The RudderStack iOS SDK lets you track your customer event data from your iOS applications and send it to your specified destinations via RudderStack.

Refer to the GitHub codebase to get a more hands-on understanding of the SDK.

SDK setup requirements

To set up the RudderStack iOS SDK, the following prerequisites must be met:

• You need to set up a RudderStack account.
• Once signed up, set up an iOS source in the dashboard. You should be able to see a Write Key for this source, as shown below:

• You also need a data plane URL. Refer to the Glossary for more information on the data plane URL and where to find it.

• Finally, you need a Mac with the latest version of Xcode.

Installing the RudderStack iOS SDK

You can install the iOS SDK through Cocoapods and Carthage. The recommended and easiest way to add the SDK to your project is through Podfile. To do so, follow these steps:

Copy
#import <Rudder/Rudder.h>

Copy
import Rudder

Swift Package Manager

You can also install the iOS SDK through Swift Package Manager (SPM) via one of the following methods:

Copy
// swift-tools-version:5.5
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "RudderStack",
    products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "RudderStack",
            targets: ["RudderStack"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(url: "git@github.com:rudderlabs/rudder-sdk-ios.git", from: "1.8.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "RudderStack",
            dependencies: [
                .product(name: "Rudder", package: "rudder-sdk-ios")
            ]),
        .testTarget(
            name: "RudderStackTests",
            dependencies: ["RudderStack"]),
    ]
)

Initializing the RudderStack client

Put this code in your AppDelegate.m file under the method didFinishLaunchingWithOptions:

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[RSClient getInstance:WRITE_KEY config:[builder build]];

Copy
let builder: RSConfigBuilder = RSConfigBuilder()
    .withDataPlaneUrl(DATA_PLANE_URL)
RSClient.getInstance(WRITE_KEY, config: builder.build())

RudderStack supports all the major API calls across all iOS devices via the SDK. These include the track, identify, and screen calls.

Enabling/disabling user tracking via the optOut API (GDPR support)

RudderStack gives the users (e.g., an EU user) the ability to opt out of tracking any user activity until the user gives their consent. You can do this by leveraging RudderStack's optOut API.

The optOut API takes YES or NO as a Boolean value to enable or disable tracking user activities. This flag persists across device reboots.

The following snippet highlights the use of the optOut API to disable user tracking:

Copy
[[RSClient sharedInstance] optOut:YES];

Copy
RSClient.sharedInstance()?.optOut(true)

Once the user grants their consent, you can enable user tracking once again by using the optOut API with NO or false as a parameter sent to it, as shown:

Copy
[[RSClient sharedInstance] optOut:NO];

Copy
RSClient.sharedInstance()?.optOut(false)

Chromecast

Google Chromecast is a device that plugs into your TV or monitor with an HDMI port, and can be used to stream content from your phone or computer.

Track

You can record the users' activity through the track method. Every user action is called as an event.

A sample track event is as shown:

Copy
[[RSClient sharedInstance] track:@"simple_track_with_props" properties:@{
    @"key_1" : @"value_1",
    @"key_2" : @"value_2"
}];

Copy
RSClient.sharedInstance()?.track("test_user_id", properties: [
    "key_1": "value_1",
    "key_2": "value_2"
])

The track method accepts the following parameters:

Identify

We capture deviceId and use that as anonymousId for identifying the user. This helps in tracking the users across the application installation.

To attach more information to the user, you can use the identify method. Once you identify the user, the SDK persists all the user information and passes it to the subsequent track or screen calls. To reset the user identification, you can use the reset method.

An example identify event is as shown:

Copy
[[RSClient sharedInstance] identify:@"test_user_id"
traits:@{@"foo": @"bar",
        @"foo1": @"bar1",
        @"email": @"test@gmail.com",
        @"key_1" : @"value_1",
        @"key_2" : @"value_2"
}
];

Copy
RSClient.sharedInstance()?.identify("test_user_id", traits: [
    "key_1": "value_1",
    "key_2": "value_2",
    "email": "test@gmail.com"
])

The identify method accepts the following parameters:

Screen

You can use the screen call to record whenever the user sees a screen on the mobile device. You can also send some extra properties along with this event.

An example of the screen event is as shown:

Copy
[[RSClient sharedInstance] screen:@"ViewController"];

Copy
RSClient.sharedInstance()?.screen("ViewController")

The screen method accepts the following parameters:

Automatically capturing screen views

To automatically capture the screen views, you can enable the recordScreenViews parameter while initializing the SDK, as shown:

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withRecordScreenViews:YES];
[RSClient getInstance:WRITE_KEY config:[builder build]];

Copy
let builder: RSConfigBuilder = RSConfigBuilder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withRecordScreenViews(true)
RSClient.getInstance(WRITE_KEY, config: builder.build())

Note that if automatic screen recording is enabled, RudderStack removes every instance of ViewController in the screen event.

For example, if automatic screen recording is enabled and you set the ViewController class name to HomeViewController, then the SDK sets the screen event name to Home.

Group

The group call associates a user to a specific organization. A sample group call for the API is below:

Copy
[[RSClient sharedInstance] group:@"sample_group_id"
  traits:@{@"foo": @"bar",
            @"foo1": @"bar1",
            @"email": @"ruchira@gmail.com"}
];

Copy
RSClient.sharedInstance()?.group("test_group_id", traits: [
    "key_1": "value_1",
    "key_2": "value_2"
])

Alternatively, you can use the following method signature

Alias

The alias call associates the user with a new identification. A sample alias call for the API is below:

Copy
[[RSClient sharedInstance] alias:@"new_user_id"];

Copy
RSClient.sharedInstance()?.alias("new_user_id")

Alternatively, you can use the following method signature

We replace the old userId with the newUserId and we persist that identification across the sessions.

Reset

You can use the reset method to clear the persisted traits for the identify call. This is required for the Logout operations.

Copy
[[RSClient sharedInstance] reset];

Copy
RSClient.sharedInstance()?.reset()

Configuring the RudderStack client

You can configure your client based on the following parameters using RudderConfigBuilder:

Self-hosted control plane

If you are using a device mode destination like Adjust, Firebase, etc., the iOS SDK needs to fetch the required configuration from the control plane. If you are using the Control Plane Lite utility to host your own control plane, then follow the steps in this section and specify controlPlaneUrl in RudderConfigBuilder that points to your hosted source configuration file.

Setting the device token

You can pass your device-token for Push Notifications to be passed to the destinations which support Push Notification. We set the token under context.device.token.

Follow the instructions below:

Copy
[RSClient putDeviceToken:@"your_device_token"];

Advertisement ID

We have kept IDFA collection completely separate from the Core library so that the developer has better control over the same. You can pass the IDFA to putAdvertisementId method to set it under context.device.advertisingId

Follow the instructions below:

Copy
#import <AdSupport/ASIdentifierManager.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Override point for customization after application launch.
    RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
    [builder withDataPlaneURL:[[NSURL alloc] initWithString:DATA_PLANE_URL]];
    [RSClient getInstance:WRITE_KEY config:[builder build]];

    [[[RSClient sharedInstance] getContext] putAdvertisementId:[self getIDFA]];

    return YES;
}

- (NSString*) getIDFA {
    return [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
}

ATTrackingManager authorization consent

You can pass the ATTrackingManager.trackingAuthorizationStatus to RudderStack and we'll pass it along to the relevant destinations wherever needed. For example AppsFlyer accepts this parameter for the attribution to work in their S2S mode.

Follow the instructions below:

Copy
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Override point for customization after application launch.
    RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
    [builder withDataPlaneURL:[[NSURL alloc] initWithString:DATA_PLANE_URL]];
    [RSClient getInstance:WRITE_KEY config:[builder build]];

    [[[RSClient sharedInstance] getContext] putAppTrackingConsent:RSATTAuthorize];

    return YES;
}

Following are the available options you can pass to the putAppTrackingConsent method.

• RSATTNotDetermined
• RSATTRestricted
• RSATTDenied
• RSATTAuthorize

Anonymous ID

We use the deviceId as anonymousId by default. You can use the following method to override and use your own anonymousId with the SDK.

An example of setting the anonymousId is shown below:

Copy
[RSClient putAnonymousId:<ANONYMOUS_ID>];

Filtering events

When sending events to a destination via the device mode, you can explicitly specify which events should be discarded or allowed to flow through - by allowlisting or denylisting them.

Enabling/disabling events for specific destinations

The RudderStack iOS SDK allows you to enable or disable event flow to a specific destination or all the destinations to which the source is connected. You can specify these destinations by creating a RSOption object as shown:

Copy
RSOption *option = [[RSOption alloc]init];
//default value for `All` is true
[option putIntegration:@"All" isEnabled:YES];
// specifying destination by its display name
[option putIntegration:@"Amplitude" isEnabled:YES];
[option putIntegration:@"<destination display name>" isEnabled:<BOOL>];
// specifying destination by its Factory instance
[option putIntegrationWithFactory:[RudderMoengageFactory instance] isEnabled:NO];
[option putIntegrationWithFactory:[<RudderIntegrationFactory> instance] isEnabled:<BOOL>];

Copy
let option:RSOption = RSOption();
//default value for `All` is true
option.putIntegration("All", isEnabled:true)
// specifying destination by its display name
option.putIntegration("Amplitude", isEnabled:true)
option.putIntegration(<DESTINATION DISPLAY NAME>, isEnabled:<BOOL>)
// specifying destination by its Factory instance
option.putIntegration(with: RudderMoengageFactory.instance(), isEnabled: true);
option.putIntegration(with: <RudderIntegrationFactory>.instance(), isEnabled:<BOOL>);

You can pass the destination(s) specified in the above snippet to the SDK in two ways:

1. Passing destinations while initializing the SDK

This is helpful when you want to enable/disable sending the events across all the event calls made using the SDK to the specified destinations.

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneURL:[[NSURL alloc] initWithString:DATA_PLANE_URL]];
[builder withLoglevel:RSLogLevelDebug];
[builder withTrackLifecycleEvens:YES];
[builder withRecordScreenViews:YES;
[RSClient getInstance:WRITE_KEY config:[builder build] options:option]; // passing the rudderoption object containing the list of destinations you specified

Copy
let builder: RSConfigBuilder = RSConfigBuilder()
            .withLoglevel(RSLogLevelDebug)
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withTrackLifecycleEvens(true)
            .withRecordScreenViews(true)
RSClient.getInstance(WRITE_KEY, config: builder.build(),options: option)// passing the rudderoption object containing the list of destination(s) you specified

2. Passing destinations while making event calls

This approach is helpful when you want to enable/disable sending only a particular event to the specified destination(s) or if you want to override the specified destinations passed with the SDK initialization for a particular event.

Copy
[[RSClient sharedInstance] track:@"simple_track_with_props" properties:@{
        @"key_1" : @"value_1",
        @"key_2" : @"value_2"
    } options:option]; // passing the rudderoption object containing the list of destination(s) you specified

Copy
let rudder: RSClient? = RSClient.sharedInstance()
rudder?.track("track_with_props", properties: [
            "key_1": "value_1",
            "key_2": "value_2",
        ],options:option) // passing the rudderoption object containing the list of destination(s) you specified

External ID

You can pass your custom userId along with standard userId in your identify calls. We add those values under context.externalId. The following code snippet shows a way to add externalId to your identify request.

Copy
RSOption *identifyOptions = [[RSOption alloc] init];
[identifyOptions putExternalId:@"brazeExternalId" withId:@"some_external_id_1"];
[[RSClient sharedInstance] identify:@"testUserId"
                             traits:@{@"firstname": @"First Name"}
                            options:identifyOptions];

Tracking user sessions

By default, the iOS SDK automatically tracks the user sessions. This means that RudderStack automatically determines the start and end of a user session depending on the inactivity time configured in the SDK (default time is 5 minutes).

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withAutoSessionTracking:YES];  // Set to No to disable automatic session tracking
[builder withSessionTimeoutMillis:(5*60*1000)];
[RSClient getInstance:WRITE_KEY config:[builder build]];

Copy
let builder: RSConfigBuilder = RSConfigBuilder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withAutoSessionTracking(true)  // Set to false to disable automatic session tracking
            .withSessionTimeoutMillis(5*60*1000)
RSClient.getInstance(WRITE_KEY, config: builder.build())

To disable automatic session tracking, set withAutoSessionTracking to false.

Debugging

If you run into any issues regarding the RudderStack iOS SDK, you can turn on the VERBOSE or DEBUG logging to find out what the issue is. To turn on the logging, change your RudderClient initialization to the following:

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withLoglevel:RudderLogLevelDebug];
[RSClient getInstance:WRITE_KEY config:[builder build]];

Copy
let builder: RSConfigBuilder = RSConfigBuilder()
builder.withDataPlaneUrl(<DATA_PLANE_URL>)
builder.withLoglevel(RudderLogLevelDebug)
RSClient.getInstance(<WRITE_KEY>, config: builder.build())

Developing a device mode destination

You can easily develop a device mode destination in case RudderStack doesn't support it already. Follow the steps listed in this section to do so.

• Create a CustomFactory.h file by extending RSIntegrationFactory, as shown:

Copy
#import <Foundation/Foundation.h>
#import <Rudder/Rudder.h>

NS_ASSUME_NONNULL_BEGIN

@interface CustomFactory : NSObject<RSIntegrationFactory>

+ (instancetype) instance;

@end

NS_ASSUME_NONNULL_END

• Then, create a CustomFactory.m file, as shown:

Copy
#import <Foundation/Foundation.h>
#import <Rudder/Rudder.h>
#import "CustomFactory.h"
#import "CustomIntegration.h"


@implementation CustomFactory

+ (instancetype)instance {
    static CustomFactory *sharedInstance;
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        sharedInstance = [[self alloc] init];
    });
    return sharedInstance;
}

- (instancetype)init
{
    self = [super init];
    return self;
}

- (nonnull NSString *)key {
    return @"Custom Factory";
}

- (nonnull id<RSIntegration>)initiate:(NSDictionary *)config client:(nonnull RSClient *)client rudderConfig:(nonnull RSConfig *)rudderConfig {
    return [[CustomIntegration alloc] initWithConfig:config withAnalytics:client];
}


@end

• Next, create a CustomIntegration.h file by extending RSIntegration.

Copy
#import <Foundation/Foundation.h>
#import <Rudder/Rudder.h>

NS_ASSUME_NONNULL_BEGIN

@interface CustomIntegration : NSObject<RSIntegration>

@property (nonatomic, strong) NSDictionary *config;
@property (nonatomic, strong) RSClient *client;

- (instancetype)initWithConfig:(NSDictionary *)config withAnalytics:(RSClient *)client;

@end

NS_ASSUME_NONNULL_END

• Next, create a CustomIntegration.m file.

Copy
#import <Foundation/Foundation.h>
#import <Rudder/Rudder.h>
#import "CustomIntegration.h"

@implementation CustomIntegration

- (instancetype) initWithConfig:(NSDictionary *)config withAnalytics:(RSClient *)client {
    if (self == [super init]) {
    }
    return self;
}

- (void) processRuderEvent:(nonnull RSMessage *)message {
    NSString *type = message.type;
    if ([type isEqualToString:@"identify"]) {
//        Do something
    } else if ([type isEqualToString:@"track"]) {
//        Do something
    } else if ([type isEqualToString:@"screen"]) {
//        Do something
    } else {
        [RSLogger logWarn:@"MessageType is not supported"];
    }
}

- (void) dump:(nonnull RSMessage *)message {
    [self processRuderEvent:message];
}

- (void) reset {
}

- (void) flush {
}

@end

• Register the CustomFactory with the RudderStack iOS SDK during its initialization, as shown:

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
    [builder withDataPlaneURL:[[NSURL alloc] initWithString:DATA_PLANE_URL]];
    [builder withLoglevel:RSLogLevelDebug];
    [builder withTrackLifecycleEvens:NO];
    [builder withRecordScreenViews:NO];
    [builder withCustomFactory:[CustomFactory instance]];
    [RSClient getInstance:WRITE_KEY config:[builder build]];

Some pointers to keep in mind:

• RudderStack's iOS SDK dumps every event it receives to the dump() method of the CustomFIntegration class. From here, you can process the event and hand it over to the native SDK of the device mode destination.
• The SDK also triggers the reset() method of the CustomFactory class on every reset() call made via the SDK. You can use this to handle the destination-specific reset logic.
• Make sure you do not duplicate the value of KEY present inside CustomFactory, across multiple CustomFactory that you develop.

flush API

The iOS SDK supports the flush() API. RudderStack retrieves all the messages present in the database, divides them into individual batches based on the specified queue size, and flushes them to the RudderStack server/backend.

For example, if the flushQueueSize is 30 and there are 180 events in the database when the flush() API is called, the SDK will retrieve all those events and divide them into batches of 30 messages each, that is, into 6 batches.

If a batch fails for some reason, RudderStack drops the remaining batches to maintain the sequence of the messages. A batch is considered as failed if it isn’t sent to the RudderStack server after 3 retries.

In device mode, the flush() API also calls the destination SDK’s flush() API (if applicable).

For every flush() call made via the iOS SDK, the flush() method of the CustomFactory class is also triggered, which can be used to handle the destination-specific reset logic. You can make a flush call using the SDK as shown:

Copy
[[RSClient sharedInstance] flush];

FAQs

I'm facing issues building with Carthage on XCode 12. What should I do?

If you're facing an issue with Carthage and XCode 12, you can follow this workaround suggested by the Carthage team.

Does the SDK support tvOS ?

As of version 1.1.0, the iOS SDK supports the tvOS platform.

Does the SDK support watchOS ?

As of version 1.3.0, the iOS SDK supports the watchOS platform.

How do I migrate from v1.0.2?

Update the usage of the following classes as per the table below:

How do I ensure the events tracked just before closing/backgrounding the app are sent immediately and not on the next app launch?

To ensure that the events tracked just before closing/backgrounding the app are sent to RudderStack immediately, you can set withEnableBackgroundMode to YES while creating the RSConfigBuilder object as shown below:

Copy
RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withEnableBackgroundMode:YES];
[RSClient getInstance:WRITE_KEY config:[builder build] options:defaultOption];

By doing so, your app requests iOS for some additional background run time to run the app, which in turn allows the SDK to immediately send the events tracked just before the app is closed/backgrounded, instead of waiting till the next app launch.

This SDK feature relies on the background mode capability offered by the iOS. There is no set number on the background run time the apps get, as it is completely abstracted by iOS. For more information, refer to this guide.

How can I get the user traits after making the identify call?

You can get the user traits after making an identify call in the following way:

Copy
let traits = RSClient.sharedInstance()?.getContext().traits

Copy
NSDictionary* traits = [[RSClient sharedInstance] getContext].traits;

How does the SDK handle different client/server errors?

In case of client-side errors, e.g. if the source write key passed to the SDK is incorrect, RudderStack gives you a 400 Bad Request response and aborts the operation immediately. For other types of network errors (e.g. Invalid Data Plane URL), the SDK tries to flush the events to RudderStack in an incremental manner (every 1 second, 2 seconds, 3 seconds, and so on).

Why is there a larger difference between timestamp and received_at for iOS events vs. Android events?

This scenario is most likely caused by the default behavior of iOS apps staying open in the background for a shorter period of time after a user closes them.

When a user closes an iOS or Android app, events will still continue to be sent from the queue until the app closes in the background as well. Any events still in the queue will remain there until the user reopens the app. Due to this lag, there are some scenarios where there can be significant differences between timestamp (when the event was created) and received_at (when RudderStack actually receives the events).

For Android apps, events can be sent from the background after apps close for a longer period of time than iOS apps, therefore, more of the events coming from the Android SDK have closer timestamp and received_at times.

Does RudderStack integrate with SKAdNetwork?

RudderStack does not integrate with SKAdNetwork. However, SKAdNetwork can be directly integrated into an iOS application alongside RudderStack.

Can I disable event tracking until the user gives their consent?

Yes, you can.

RudderStack gives you the ability to disable tracking any user activity until the user gives their consent, by leveraging the optOut API. This is required in cases where your app is audience-dependent (e.g. minors) or where you're using the app to track the user events (e.g. EU users) to meet the data protection and privacy regulations.

The optOut API takes true / false (in case of Swift) or YES / NO (in case of Objective-C) as a value to enable or disable tracking user activities. So, to disable user tracking, you can use the optOut API as shown:

Copy
[[RSClient sharedInstance] optOut:YES];

Copy
RSClient.sharedInstance()?.optOut(true)

Once the user gives their consent, you can enable user tracking again, as shown:

Copy
[[RSClient sharedInstance] optOut:NO];

Copy
RSClient.sharedInstance()?.optOut(false)