Jitsu iOS SDK

Jitsu iOS SDK allows you to send data to Jitsu from iOS applications.

Installation#

You can install with Cocoapods, Carthage, or Swift Package Manager.

Cocoapods#

Add the pod to your Podfile: pod 'Jitsu'

And then run: pod install

After installing the cocoa pod into your project, import Jitsu into your project.

Carthage#

Create a file named Cartfile in your projects folder. Add Jitsu to your Cartfile: github "jitsucom/jitsu-ios" "main".

And then run: carthage update --use-xcframeworks

Open Carthage/Build directory, and drag Jitsu.framework to your application targets “General” tab under the “Linked Frameworks and Libraries” section.

If your app can't find Jitsu, go to your target's build settings, and add $(SRCROOT) recursive to your Framework search path .

Then import Jitsu into your project.

Swift Package Manager#

1. Go to File > Swift Packages > Add Package Dependency
2. Paste the project URL: https://github.com/jitsucom/jitsu-ios.git
3. Click on next and select the project target
4. Don't forget to set DEAD_CODE_STRIPPING = NO in your Build Settings(https://bugs.swift.org/plugins/servlet/mobile#issue/SR-11564)

After successfully retrieved the package and added it to your project, import Jitsu.

Importing Jitsu#

import Jitsu

Initialization#

SDK is configured with JitsuOptions. You should provide your Client secret token and Tracking url.

let options = JitsuOptions(apiKey: "CLIENT_SECRET_KEY", trackingHost: "TRACKING_URL")
Jitsu.setupClient(with: options)

Sending events#

Sending events#

There are two ways of sending events:

a) client can send an event as something conforming to Event protocol

let event = JitsuBasicEvent(name: "hi")
Jitsu.shared.trackEvent(event)

b) or pass it as a name of event and Dict of event params.

Jitsu.shared.trackEvent(_ name: "user pressed like", params: ["to_user_id: "NEW_VALUE"])

Identifying user#

Information about the user is passed with events.

Use Jitsu.userProperties to manage user info. UserProperties consist of an anonymous user id and custom identifiers that you can set to the user.

anonymous user id: Jitsu automatically sets a UUID to any user that is stored between launches. You can get it by Jitsu.userProperties.anonymousUserId.

user identifier: You can set your own identifier to user. You can access it by Jitsu.userProperties.userIdentifier. You can set new identifier with:

Jitsu.userProperties.updateUserIdentifier("NEW_ID", sendIdentificationEvent: true)

email: You can set email. You can access it by Jitsu.userProperties.email. You can update it with:

Jitsu.userProperties.updateEmail("new@new.com", sendIdentificationEvent: true)

other identifiers: You can set additional user identifiers. You can access it by Jitsu.userProperties.otherIdentifiers. You can update it with:

Jitsu.userProperties.updateOtherIdentifier(forKey: "my_key", with: "new_value", sendIdentificationEvent: true)

You can set multiple user properties:

Jitsu.userProperties.identify(
	userIdentifier: "my_id",
	email: "foo@bar.com",
	otherIds: ["name": "Foo", "surname": "Johnson"],
	sendIdentificationEvent: true
)

You can reset all users properties. All the properties set before will be reset, and new anonymous_id will be generated.

Jitsu.userProperties.resetUserProperties()

Context#

You can set properties that will always be added to events of certain types. You can add, change and remove context values. You can either add properties to certain event types or do not specify event type - then it will be added to all the event types. You can also set if you want context values persisted between launches. By default, context events are not persisted.

Jitsu.context.addValues(
	["age": 32, "codes": "Swift"], 
	for: ["event sign up"],
	persist: true
)

You can remove context values by calling

Jitsu.context.removeValue(for key: "language", for eventTypes: nil)
Jitsu.context.removeValue(for key: "language", for eventTypes: ["hi"]])

You can clear context when needed. It will not clear automatically gathered values (only update them).

Jitsu.context.clear()

SDK automatically gathers some context values.

Automatically gathered context values

• device info: model, screen size, OS version
• app version, app name, sdk version
• system language
• voice_over: true if the user has VoiceOver on.

Send screen event#

You can send an event from a screen in one line. This event will contain screen title and screen class as well as event data.

Jitsu.shared.trackScreenEvent(screen: self, event: JitsuBasicEvent(name: "screen opened"))

Out-of-the-box Trackings#

Jitsu can do some tracking for you. You can set what to track when initializing SDK with JitsuOptions.

• Main app lifecycle events: shouldCaptureAppLifecycleEvents
• When the app was updated or installed
• User opens a push notification: shouldCapturePushEvents
• The app was opened from a deeplink. shouldCaptureDeeplinks. We pass the link in payload. Note: this method will not work if your app uses SceneDelegate. If so, you will have to track opening from deeplink manually in scene(_ scene: , willConnectTo session: , options connectionOptions: )

Location#

SDK can gather info about location. There are two modes which you can set in options. SDK uses the permissions that your app has and would never ask the user for permission by itself.

• trackPermissionChanges - SDK tracks location permission changes. We add current location permission status to the context, and send events when it changes.
• addLocationOnAppLaunch - If user granted access to location, we gather a new location every time the app launches and add it to the context.

options.locationTrackingOptions = [.addLocationOnAppLaunch, .trackPermissionChanges]

Also there is a special event type method that allows to send location events easily:

let event = LocationEvent(location: location, name: "left bike", payload: [:])

Privacy Settings#

Jitsu SDK doesn't collect any persistent device identifiers.

You can allow your users to disable/enable data collection.

Jitsu.shared.turnOff()
Jitsu.shared.turnOn()

That will generate Jitsu turned off and Jitsu turned on events

Logging#

You can set log level when initializing SDK with JitsuOptions .

options.logLevel = .critical

where JitsuLogLevel has values debug, info, warnings, errors, critical, none

UnitTestMode#

1. You can set up your own mock of Jitsu by calling Jitsu.setupMock:. If you pass nil, we will create our own empty mock
2. Jitsu automatically tracks if your app is in Unit Testing mode. If so, it disables sending data to the backend and saving it to the database.

Advanced Settings#

• Jitsu uses an internal queue to make calls fast and non-blocking.
• Jitsu doesn't send each event immediately. Instead, it sends events in batches. SDK sends a new batch either when it reaches eventsQueueSize, or every sendingBatchesPeriod. Also, Jitsu sents all unsent events when an application enters the background state. If the app gets closed or crashes, events are sent on the next launch. You can manually set the number of events in the queue and time period.

Jitsu.shared.eventsQueueSize = 20
Jitsu.shared.sendingBatchesPeriod = TimeInterval(10)

Also, you can force SDK to send batch immediately by calling sendBatch method.