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

Installation, Implementation, and Updates.


Official Android SDK for UserLeap (Releases)

This SDK is designed to work with Android SDK 21 (Android Lollipop, OS 5.0) and above.

If using minSdk below 21, you can override the library in your main AndroidManifest.

<manifest xmlns:android=""

    <uses-sdk tools:overrideLibrary="com.userleap" />

Make sure to check the OS system version before calling UserLeap.

    UserLeap.configure(context, "YOUR_ENVIRONMENT_ID")


You can install the UserLeap SDK via maven central.

dependencies {
    implementation 'com.userleap:userleap-android-sdk:2.3.0'

Add Java 8 support to your project (if not added already)

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"



These permissions are automatically merged into your app Manifest.

  • INTERNET - send and receive events and surveys

App size impact

The UserLeap SDK AAR size is 373 KB.

The impact to an Android App Bundle is 1.2 MB. Note: The UserLeap SDK uses the common dependencies listed above. The actual size impact will be smaller if these dependencies are already used by the app.

Methodology: Build a ProGuarded release Android App Bundle in Android Studio with an Empty Activity project. Then compare size after adding the UserLeap SDK.


Initializing the SDK

In order to use the SDK, you need to configure the SDK for your app. Do this before calling any other UserLeap functions. A convenient place to configure UserLeap is in your class that extends Application.

UserLeap.configure(context, "YOUR_ENVIRONMENT_ID")

The ENVIRONMENT_ID for your deployment can be found in the Connect page of the UserLeap Dashboard.

Verifying your SDK Installation

You can verify you’ve set up the installation and environment ID correctly by adding the following line:


This survey always displays a debug survey and the results are submitted to UserLeap.

Identifying users

User ID

UserLeap allows you to identify users by supplying a userId. While tracking userIds 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.

Set the userId after configuring if they are already logged in or after the user logs in to your app:


This user identifier is stored locally and this method can be called multiple times safely. We recommend you set the user identifier every time you configure UserLeap and anytime your customer's login to be safe.

️ 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.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.

UserLeap.setVisitorAttribute("key", "value")

UserLeap automatically tracks and attaches the following attributes:

  • App version
  • Android version
  • SDK version

Some common attributes you can set are:

  • 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 track() function and passing the event name as a function argument.

️ Info

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


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, we can send events to UserLeap and also display a survey, should the user qualify for one. We can do this by modifying the prior track() call, and adding in a when statement as follows:

UserLeap.track("YOUR_TRACKING_EVENT") { surveyState ->
    when (surveyState) {
        SurveyState.READY -> {
            // We received a survey for the event, present it to the user
        SurveyState.NO_SURVEY -> {
            // No survey available based on event
        SurveyState.DISABLED -> {
            // UserLeap has been disabled remotely

After sending each tracking event, you can check if a new survey is ready for the user. If a survey is ready, you can decide to present the survey to the user. The survey is presented on a modal bottom sheet.

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 set up the SDK with your development ENVIRONMENT_ID. This will bypass throttling and the re-survey window.



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 from being associated with the wrong user.



We adhere to Semver for versioning our SDKs so upgrading between major versions (e.g. 1.0.1-> 1.1.0) should not present any breaking changes.

Note: 1.2.1 is the same as 2.0.0, we've bumped the major version to signify that versions below 1.2.1 will be disabled/deprecated by Feb 12, 2021

Upgrading from 1.x.x to 2.x.x

  • UserLeap.visitorIdentifier which returns Int? will always return null for new visitors. Use the new UserLeap.visitorIdentifierString which returns String?

The latest UserLeap SDK release is shown here.

Updated about a month ago

Mobile - Android

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.