UserLeap

The UserLeap Developer Hub

Welcome to the UserLeap developer hub. You'll find comprehensive guides and documentation to help you start working with UserLeap as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

Mobile - iOS

Installation, Implementation, and Updates.

Installation

Official Releases of the UserLeap iOS SDK (Releases)

This SDK is designed to work with iOS 10.3 and above. As part of that design decision, you will need to explicitly exclude that architecture in your Build Settings.

If you encounter an error that reads

could not find module 'UserLeapKit' for target 'armv7-apple-ios'; found: i386, x86_64-apple-ios-simulator, arm64, x86_64, i386-apple-ios-simulator, arm64-apple-ios

or in part reads

missing required architecture armv7 in file

To explicity remove the package from your XCode build by electing your Target (usually your app) -> click Build Setting -> search for “Excluded Architecture”

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 UserLeap in your application:

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', '~>4.3.0'

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 UserLeap 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

UserLeap 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 UserLeap. 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
        UserLeap.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 UserLeap 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:

UserLeap.shared.presentDebugSurvey(from: self)

This presents a test survey, assuming everything has been configured correctly.

Identifying users

User ID

UserLeap 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 survey 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:

UserLeap.shared.setUserIdentifier("myUserId")

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 UserLeap, and anytime your customers log in.

️ Warning

UserLeap enforces resurvey windows and survey 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, UserLeap will only enforce resurvey windows against the current anonymous visitor ID.

Email address

You can also provide UserLeap with the user's email address. It is not required for Web and Mobile surveys but is required to enable Email-based surveys.

UserLeap.shared.setEmailAddress("[email protected]")

Segmenting your users with attributes

UserLeap allows you to associate attributes to each user. These attributes are surfaced as survey filter options in the UserLeap dashboard, and allow you to send surveys to users with certain attributes.

//Example of setting a single attribute
UserLeap.shared.setVisitorAttribute(key: "key", value: "value")

//Example of setting multiple attributes
//TIP: This avoids  multiple requests, rounds trips and reduces data usage
UserLeap.shared.setVisitorAttributes([
    "key1": "value1",
    "key2": "value2"
])

//Remove attributes, if they no longer apply to the user
UserLeap.shared.removeVisitorAttributes(["key1", "key2"])

UserLeap 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

Let’s track the event that you created in Setting up your first survey. You can track UserLeap events, inside your mobile app, by calling the trackEvent() function and passing the event name as a function argument.

️ Info

Your engineering team will want to placetrackEvent()code after any action or context, denoting to UserLeap that the event has occurred.

UserLeap.shared.trackEvent(eventName: "[TEST] My first event")

These events can be used as part of your filters for triggering a survey, but will not display a survey to your users.

Displaying surveys to users

Instead of strictly tracking when user events occur, you can send events to UserLeap and also display a survey, should the user qualify for one. We can do this by modifying the prior trackEvent call, and adding in a switch statement as follows:

📘

Info

UserLeap will automatically check if a user is eligible based on your survey's filter constraints, and determine survey eligibility for you. Your team does not need to code additional logic that validates a user's attribute criteria, before sending events to us.

UserLeap.shared.trackEvent(eventName: "[TEST] My first event") { state in
    switch state {
        case .ready:
            UserLeap.shared.presentSurvey(from: viewController)
        case .noSurvey, .disabled:
            break
    }
}
Example MicrosurveyExample Microsurvey

Example Microsurvey

Verifying your Event-based Surveys

We have checks in place to make sure we show surveys at the right time (See Survey Eligibility). To test that your surveys show with the right attributes and events set, be sure to setup the SDK with your development ENVIRONMENT_ID. This will bypass throttling and the re-survey window.

️ Warning

While surveys can be configured to trigger and display from multiple events, only one of those events needs to occur to display a survey (assuming a user also meets your survey's filter criteria).

User logout

When a user logs out of your app, make sure to log that user out of the UserLeap SDK. This will prevent any new activity being associated with the wrong user.

UserLeap.shared.logout()

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:

  • UserLeap.shared.visitorIdentifier which returns NSNumber? will always return nil for new visitors. Please use the new UserLeap.shared.visitorIdentifierString which returns String?

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 UserLeap.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 UserLeap.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 3 days ago

Mobile - iOS


Installation, Implementation, and Updates.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.