Like Jitsu? Give us a star on ⭐ GitHub!

📜 Configuration

Configuration UI

Jitsu Internals

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

Swift
Objective-C
import Jitsu

Initialization

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

ParameterDescription
CLIENT_SECRET_KEYClient secret key can be obtained from Jitsu UI Events API section or from Configuration
TRACKING_URLFull URL of /api/v1/event endpoint of your deployment, e.g.: https://example.com/api/v1/event. For cloud version of Jitsu pass nil value
Swift
Objective-C
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

Swift
Objective-C
let event = JitsuBasicEvent(name: "hi")
Jitsu.shared.trackEvent(event)

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

Swift
Objective-C
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:

Swift
Objective-C
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:

Swift
Objective-C
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:

Swift
Objective-C
Jitsu.userProperties.updateOtherIdentifier(forKey: "my_key", with: "new_value", sendIdentificationEvent: true)

You can set multiple user properties:

Swift
Objective-C
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.

Swift
Objective-C
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.

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

You can remove context values by calling

Swift
Objective-C
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).

Swift
Objective-C
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.

Swift
Objective-C
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.
Swift
Objective-C
options.locationTrackingOptions = [.addLocationOnAppLaunch, .trackPermissionChanges]

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

Swift
Objective-C
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.

Swift
Objective-C
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 .

Swift
Objective-C
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.
Swift
Objective-C
Jitsu.shared.eventsQueueSize = 20
Jitsu.shared.sendingBatchesPeriod = TimeInterval(10)

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