Getting started with iOS SDK

Detailed technical documentation on RudderStack’s iOS SDK using XCode to send events from your iOS device to various destinations.

What is the RudderStack iOS SDK?

The RudderStack iOS SDK allows you to integrate RudderStack to your iOS application in order to track event data from your app. After integrating this SDK, you will also be able to send this data to your preferred analytics destination/s such as Google Analytics, Amplitude, and more.

You can check the codebase if you want to get more hands on or keen to know the SDK architecture.

SDK Setup Requirements

To set up the RudderStack iOS SDK, there are a few prerequisites as mentioned below:

  • You will need to set up a RudderStack Account

  • Once signed up, your iOS source writeKey will appear in the Dashboard, as shown:

iOS source writeKey on the RudderStack Dashboard
  • Your Data-plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

Data Plane URL
  • A Mac with the latest version of Xcode.

Installing the SDK

We distribute our iOS SDK through Cocoapods. The recommended and easiest way to add the SDK to your project is through Podfile. Follow these steps:

Add the RudderStack SDK to your Podfile

pod 'RudderSDKCore'

Then, run the following command:

$ pod install

Important: Remember to include the following code in all .m and .h files where you want to refer to or use RudderStack SDK classes.

#import "RudderSDKCore.h"

Initializing the Client

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

Objective-C
Swift
Objective-C
RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
[builder withEndPointUrl:YOUR_DATA_PLANE_URL];
[RudderClient getInstance:YOUR_WRITE_KEY config:[builder build]];

A shared instance of RudderClient is accessible after the initialization by [RudderClient sharedInstance]

Swift
let builder: RudderConfigBuilder = RudderConfigBuilder()
builder.withEndPointUrl(YOUR_DATA_PLANE_URL)
RudderClient.getInstance(WRITE_KEY, config: builder.build())

A shared instance of RudderClient is accesible after the initialization by RudderClient.sharedInstance()

We automatically track the following optional events:

  1. Application Installed

  2. Application Updated

  3. Application Opened

  4. Application Backgrounded

You can disable these events using withTrackLifecycleEvents method of RudderConfigBuilder and passing false. However, it is highly recommended to keep them enabled.

iOS SDK APIs

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

track

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

An example track event is as shown:

Objective-C
Swift
Objective-C
// create properties for the event you want to track
NSMutableDictionary *property = [[NSMutableDictionary alloc] init];
[property setValue:@"test_value_1" forKey:@"test_key_1"];
[property setValue:@"test_value_2" forKey:@"test_key_2"];
// track event
[[RudderClient sharedInstance] track:@"test_track_event" properties:property];
Swift
// create properties for the event you want to track
var properties: [String: NSObject] = [:]
properties["test_key_1"] = "test_value_1" as NSObject
properties["test_key_2"] = "test_value_2" as NSObject
// track event
RudderClient.sharedInstance()?.track("test_track_event", properties: properties);

The track method can be used in two ways.

Firstly, you can use TrackPropertyBuilder to create the property object and pass the RudderMessage object with the property to trackMessage method.

Alternatively you can follow the method signature as below:

Name

Data Type

Required

Description

eventName

NSString

YES

Name of the event you want to track

properties

NSDictionary

NO

Extra data properties you want to send along with the event

options

RudderOption

NO

Extra event options

identify

We capture deviceId and use that as anonymousId for identifying the user. To attach more information to the user, you can use the identify method. Once you set the identify information to the user, those will be passed to the successive track or screen calls. To reset the user identification, you can use the reset method.

An example identify event is as shown:

Objective-C
Swift
Objective-C
RudderTraits *traits = [[RudderTraits alloc] init];
[traits putBirthday:[[NSDate alloc] init]];
[traits putEmail:@"abc@123.com"];
[traits putFirstName:@"First"];
[traits putLastName:@"Last"];
[traits putGender:@"m"];
[traits putPhone:@"5555555555"];
[[RudderClient sharedInstance] identify:@"test_user_id" traits:[traits dict]];
Swift
let traits : RudderTraits = RudderTraits()
traits.putBirthday(NSDate() as Date)
traits.putEmail("abc@123.com")
traits.putFirstName("First")
traits.putLastName("Last")
traits.putGender("m")
traits.putPhone("5555555555")
RudderClient.sharedInstance()?.identify("test_user_id", traits: traits.dict())

The identify method can be used in two ways. Firstly, you can use RudderTraitsBuilder to create the traits object and pass RudderMessage object with the property to the identifyMessage method.

Alternatively, you can follow the method signatures below:

Name

Data Type

Required

Description

userId

NSString

YES

Developer identity for the user

traits

NSDictionary

NO

Traits information for user. Use dict method of RudderTraits to convert to NSDictionary easily

options

RudderOption

NO

Extra options for identify event

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:

Objective-C
Swift
Objective-C
[[RudderClient sharedInstance] screen:@"ViewController"];
Swift
RudderClient.sharedInstance()?.screen("ViewController")

The screen method can be used in two ways. Firstly, you can use ScreenPropertyBuilder and pass the property in the RudderMessage, and use the screenMessage method to track a screen view action.

Alternatively, you can use the following method signature:

Name

Data Type

Required

Description

screenName

NSString

YES

Name of the screen viewed

properties

NSDictionary

NO

Extra property object that you want to pass along with the screen call

options

RudderOption

NO

Extra options to be passed along with screen event

reset

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

Objective-C
Swift
Objective-C
[[RudderClient sharedInstance] reset];
Swift
RudderClient.sharedInstance()?.reset()

Configuring RudderStack Client

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

Parameter

Type

Description

Default Value

logLevel

int

Controls how much of the log you want to see from the SDK.

RudderLogger.RudderLogLevel.NONE

endPointUri

String

URL of your data-plane.

https://api.rudderlabs.com

flushQueueSize

int

Number of events in a batch request sent to the server

30

dbThresholdCount

int

Number of events to be saved in the SQLite database. Once the limit is reached, older events are deleted from the DB

10000

sleepTimeout

int

Minimum waiting time to flush the events to the server

10 seconds

configRefreshInterval

int

Fetches the config from dashboard after the specified time (in hours)

2

trackLifecycleEvents

boolean

Specify whether SDK will capture Application Life Cycle Events automatically

true

recordScreenViews

boolean

Specify whether the SDK will capture Screen View events automatically

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:

Objective-C
Swift
Objective-C
RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
[builder withEndPointUrl:endPointUrl];
[builder withLoglevel:RudderLogLevelDebug];
[RudderClient getInstance:writeKey config:[builder build]];
Swift
let builder: RudderConfigBuilder = RudderConfigBuilder()
builder.withEndPointUrl(YOUR_DATA_PLANE_URL)
builder.withLoglevel(RudderLogLevelDebug)
RudderClient.getInstance(WRITE_KEY, config: builder.build())

Contact Us

In case of any queries, you can always reach out to us, or feel free to open an issue here in case of any discrepancy.