Mobile - iOS
Sprig iOS SDK: installation, implementation, and updates.
Installation
Official Releases of the Sprig iOS SDK (Releases)
This SDK is designed to work with iOS 10.3 and above.
Versioning
This SDK uses Semantic Versioning 2.0.0.
You can find the latest release version here.
Installation Methods
There are three ways you can include Sprig in your application:
SPM
In order to install using SPM, please star the release repository.
Then please install the package from main branch like so


CocoaPods
The recommended way to acquire this Framework is via CocoaPods. Simply add the following statement to your Podfile, then run pod install
:
pod 'UserLeapKit'
Then run this command in the same directory that contains your Podfile.
pod install
Carthage
If you're using Carthage, add the following statement to your Cartfile.
binary "https://raw.githubusercontent.com/UserLeap/userleap-ios-sdk-releases/main/UserLeapKit.json"
Follow the instructions to finish the installation.
Installing manually
If youâre unable to use Cocoapods or Carthage, you can also install Sprig manually. Download the latest framework as a zip from our Releases. Unzip the downloaded file and drag the UserLeap.framework folder into your project directory.
Open Xcode and select your project in the âProject Navigatorâ pane, select your app under âTARGETSâ. In the âFrameworks, Libraries, and Embedded Contentâ section, press â+â, âAdd OtherâŚâ, âAdd FilesâŚâ and select the UserLeap.framework folder.
Be sure that UserLeap.framework is in your project settings âFramework Search Pathsâ or you Xcode will throw the âno such module UserLeapâ error.
App size impact
Sprig only uses Foundation
, UIKit
, SystemConfiguration
, and CoreGraphics
with no third-party frameworks to provide the smallest disk footprint on your app binary.
The SDK size is 234 KB compressed and 592 KB uncompressed
Note: Compressed is equivalent to the additional size downloaded from the App Store, and uncompressed is the additional size on an iPhone after installation
Methodology: Created a fresh Xcode project with and without UserLeapKit.framework and used the App Size Report tool (Apple docs)
Initializing the SDK
Usage is simple and revolves around a singleton, conveniently named Sprig
. The singleton must be configured before it can be used. The most obvious place for this is in your ApplicationDelegate
, but do what's appropriate for your application.
import UserLeapKit
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
//your app setup
Sprig.shared.configure(withEnvironment: "ENVIRONMENT_ID")
return true
}
}
The ENVIRONMENT_ID
for your deployment can be found under the iOS section of your Connect page, in the Sprig dashboard.
Note: configure
will only accept 1 environment id, calling it multiple times with different IDs will have no effect.
Verifying your SDK Installation
You can verify youâve set up the installation and environment ID correctly by adding the following line:
Sprig.shared.presentDebugSurvey(from: self)
This presents a test study, assuming everything has been configured correctly.
Identifying users
User ID
Sprig allows you to identify users by supplying a userId
. While tracking USER_IDs is optional, it helps to provide a consistent experience across platforms and prevents users from seeing the same study multiple times.
The user identifier should be unique and mappable to your internal user id in some way.
Once a user has logged in to the app, you can set their userId
:
Sprig.shared.setUserIdentifier("USER_ID")
This user identifier is stored locally and this method can be called multiple times without issue. We recommend you set the user identifier every time you configure Sprig, and anytime your customers log in.
ď¸ Warning
Sprig enforces recontact windows and study eligibility based on the user ID associated with the current user and tracks this user ID across multiple sessions and devices. If no user ID is provided, Sprig will only enforce recontact windows against the current anonymous visitor ID.
Email address
You can also provide Sprig with the user's email address. It is not required for Web and Mobile studies but is required to enable Email-based studies.
Sprig.shared.setEmailAddress("EMAIL_ADDRESS")
Segmenting your users with attributes
Sprig allows you to associate attributes to each user. These attributes are surfaced as study filter options in the Sprig dashboard, and allow you to send studies to users with certain attributes.
//Example of setting a single attribute
Sprig.shared.setVisitorAttribute(key: "KEY", value: "VALUE")
//Example of setting multiple attributes
//TIP: This avoids multiple requests, rounds trips and reduces data usage
Sprig.shared.setVisitorAttributes([
"KEY1": "VALUE1",
"KEY2": "VALUE2"
])
//Remove attributes, if they no longer apply to the user
Sprig.shared.removeVisitorAttributes(["KEY1", "KEY2"])
Sprig automatically tracks and attaches the following attributes to each user:
- App version
- iOS version
- SDK version
- Device type
- System Language
Some common attributes your team might want to consider setting:
- Location
- Referral channel
- A/B test group
- Network connectivity status
- Battery level
Tracking user events
Sprig can track events inside your mobile app by calling the trackEvent()
function and passing the event name as an argument.
ď¸ Info
Your engineering team will want to place
trackEvent()
code after any action or context, denoting to Sprig that the event has occurred. If your colleague used the UI to add a No Code event to be used with your Mobile deployment, you will want to name it identically. To locate visit the Events tab, locate the event and then select the event. Once there, you will see the snippet by toggling.
Sprig.shared.trackEvent(eventName: "EVENT_NAME")
These events can be used as part of your filters for triggering a study, but will not display a study to your users.
Displaying studies to users
Instead of strictly tracking when user events occur, you can send events to Sprig and also display a study, should the user qualify for one. We can do this by modifying the prior track()
call, and adding in a switch
statement as follows:
Info
Sprig will automatically check if a user is eligible based on your study's filter constraints, and determine study eligibility for you. Your team does not need to code additional logic that validates a user's attribute criteria, before sending events to us.
Sprig.shared.trackEvent(eventName: "EVENT_NAME") { state in
switch state {
case .ready:
Sprig.shared.presentSurvey(from: viewController)
case .noSurvey, .disabled:
break
}
}


Example Microsurvey
Verifying your Event-based Studies
There are checks in place to make sure we show studies at the right time, see Recontact Waiting Period. To test that your studies show with the right attributes and events set, be sure to set up the SDK with your development ENVIRONMENT_ID
. This will bypass throttling and the recontact window.
ď¸ Warning
While studies can be configured to trigger and display from multiple events, only one of those events needs to occur to display a study (assuming a user also meets your study's filter criteria).
User logout
When a user logs out of your app, make sure to log that user out of the Sprig SDK. This will prevent any new activity from being associated with the wrong user.
Sprig.shared.logout()
Set Locale
Sprig has the ability to set the locale of a study with the set.Local() function. The following locales are supported:
- de
- en
- es-es
- fr
- hi
- ja
- ko
- pt-br
- ru
- zh
To set the local to Switzerland, for iOS:
Sprig.shared.setLocale('zh')
Info
Setting the locale will only set the static texts. This function does NOT exist in React Native, only iOS and Android.
iOS SDK Updates
We adhere to Semver for versioning our SDKs so upgrading between major versions (e.g. 2.0.0 -> 2.1.0 or 3.1.0 > 3.2.1) should not present any breaking changes.
Upgrading from 3.1.1 to 3.2.0/4.x.x
Note: 3.2.0 is the same as 4.0.0, we've bumped the major version to signify that versions below 3.2.0 will be disabled/deprecated by Feb 12, 2021
Changes:
Sprig.shared.visitorIdentifier
which returnsNSNumber?
will always returnnil
for new visitors. Please use the newSprig.shared.visitorIdentifierString
which returnsString?
Upgrading from 2.x.x to 3.1.1
Please be aware of 2 breaking changes in this upgrade:
Visitor Identifier Getter
To better support the Objective-C runtime, we have changed the return type of Sprig.shared.visitorIdentifier
from Int?
to NSNumber?
. If you are using visitorIdentifier
in your codebase and expect it to be an Int
, please be sure to call intValue
on that value if it is non-nil.
UserLeap init() calls are officially deprecated
As with all versions of this SDK, please use the provided single Sprig.shared
instead.
How to upgrade
Cocoapods
Locate your Podfile
that has declared UserLeapKit
as a dependency and update the version number to the latest release listed (e.g. pod 'UserLeapKit', '~> 3.2.0'
) and then run pod install
Carthage
Simply run carthage update
in the same directory as your Cartfile
Manual
If you linked the UserLeapKit
framework manually through Xcode, please download the latest release listed and follow the instructions for Installing Manually
Updated 13 days ago