Android SDK

Getting Started

Overview

The Sprig Android SDK, when installed in your native Android app, allows you to track your customer’s in-product behavior and display Sprig studies when they perform certain actions.

Requirements

• Join your teammates on Sprig (check with your Sprig admin whether team discovery is on, or simply have a team member invite you via your email address). This will give you access to your team’s environment IDs, as well as the interactive Installation Guide.
• Ensure you have access to your Android codebase, and can deploy to a development and/or production environment
• The Sprig Android 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="http://schemas.android.com/apk/res/android"
  package="com.myapp"
    xmlns:tools="http://schemas.android.com/tools">

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

To see all official releases of the Sprig Android SDK, visit the repository.

Install SDK

Install via Gradle

You can install the Sprig SDK via maven central:

dependencies {
    implementation "com.userleap:userleap-android-sdk:2.17.8"
}

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"
  }
}

If you experience build issues like “Failed to find the generated class”, try adding this to your proguard rules:

-keep class com.userleap.** { *; }
-keep class sprig.** { *; }

Your app will also need to maintain the following dependencies:

• Kotlin (1.5.31)
• Gradle (7.2.0)
• Android X
• Material Components (1.5.0-alpha04) (used for bottom sheet dialog for surveys)
• ConstraintLayout (1.1.3) (used for flat view hierarchies for surveys)

Obtain an Environment ID

After you’ve installed, you must obtain an environment ID from Sprig. Sprig provides two environments, Development and Production, each with its own corresponding ENVIRONMENT_ID (which can be found in Integrations > Android SDK).

The Development environment is recommended for initially setting up and verifying your installation. Then, you can use the Production environment to deploy studies to real users.

Initialize the SDK

Initializing and using the SDK revolves around a singleton named Sprig. The singleton must be configured before it can be used; a common pattern is to configure Sprig in your class that extends Application, but follow the best practices for your team and application.

Make sure to check the OS system version before calling Sprig:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    Sprig.configure(context, "ENVIRONMENT_ID")
}

/**
 * You can test your study easily (bypass all filters and resurvey windows) by
 * using Sprig's new testing feature. This requires installing Sprig v2.15.0 and
 * adding the following code to pass the study's unique previewKey to the Sprig
 * instance.
**/
class DeepLinkActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        intent?.data?.getQueryParameter("sprigPreviewKey")?.let { previewKey ->
            Sprig.setPreviewKey(previewKey)
        }
        finish()
    }

}

Be sure to swap in the correct ENVIRONMENT_ID. Note that configure will only accept 1 environment ID, and calling it multiple times with different IDs will have no effect.

Warning: Additional action recommended for customers that completed SDK install before October 2023 to enable in app testing feature

In order to test your study directly in your production application, you must first update your application’s install code to include additional snippet below ⬇️

Study Previews

/**
 * You can test your study easily (bypass all filters and resurvey windows) by
 * using Sprig's new testing feature. This requires installing Sprig v2.15.0 and
 * adding the following code to pass the study's unique previewKey to the Sprig
 * instance.
**/
class DeepLinkActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        intent?.data?.getQueryParameter("sprigPreviewKey")?.let { previewKey ->
            Sprig.setPreviewKey(previewKey)
        }
        finish()
    }
}

Alternatively, you can overwrite the previously added install code with the version here that includes the required changes. Be sure to swap in the correct ENVIRONMENT_ID

Identify Users

Identifying users ensures that a user’s actions are all associated with the same profile so they can be targeted.

Properly identifying users helps ensure:

• Your users have a consistent experience across platforms, and do not see the same study multiple times
• You can accurately target the right users
• You are billed for the correct number of Monthly Unique Users (MUUs)

Set User ID

Sprig allows you to differentiate users by setting a unique USER_ID. You may want to ensure consistency between the User IDs sent to Sprig and the ones in your internal database, product analytics/CDP, or data warehouse. You can also use an anonymizing function or hash.

A good User ID is…

• Unique: Two users should not share the same User ID.
• Mappable: User IDs sent to Sprig should map back to your internal User IDs, either directly or anonymously.
• Static: Once assigned, a User ID should not change.

Users that do not have a User ID set are considered unauthenticated.

You can use setUserIdentifier to identify a user with any string less than 256 characters. This function can be called multiple times safely, and stores the identifier locally. We recommend you set the User ID whenever the user logs in to your app, as well as after configuring Sprig (if the user is already logged in).

Sprig.setUserIdentifier("USER_ID")

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. Note that if you call logout() on an unauthenticated user, Sprig will assign them a new profile and count this new user separately toward your MTU limit.

Sprig.logout()

Track Events

Sprig uses events to trigger (display) studies after the user performs a specific action. They can also be used as a filter to target users who have previously performed an action.

Once you’ve installed the Sprig SDK, the next step is to configure the tracking of events that you would like to use to trigger or filter a study. For mobile SDKs, you must configure Code events. (Sprig also offers No-Code events, but these are only available on web platforms.)

To track a Code event, use:

val payload = EventPayload(event = "EVENT_NAME", properties = mapOf("key" to "value"))
Sprig.trackAndPresent(payload, YOUR_FRAGMENT_ACTIVITY)

After sending a new Code event to Sprig, you must approve the new event request on the Events page before it can be used to trigger or filter surveys.

Alternatively, 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 will be presented on a modal bottom sheet.

val payload = EventPayload(event = "EVENT_NAME", properties = mapOf("key" to "value")) { surveyState ->
    when (surveyState) {
        SurveyState.READY -> {
            // We received a survey for the event, present it to the user
            Sprig.presentSurvey(activity)
        }
        SurveyState.NO_SURVEY -> {
            // No survey available based on event
        }
        SurveyState.DISABLED -> {
            // Sprig has been disabled remotely
        }
    }
}
Sprig.track(payload) 

These events will also be available as filters for your studies. For example, you may want to only display a study to users who have performed the “checkout” event at least 3 times.

Track Attributes

Sprig allows you to track attributes, which can provide more context about the user to help you better understand their feedback. You can also use these attributes to filter your audience and target specific kinds of users. Some example attributes that can be tracked are:

• Plan type
• Super users / power users
• Company

A user’s attributes can be seen on their profile in the Users page, and are recorded and attached to any surveys response they submit. For more information, see Attributes.

To set a user’s attribute, provide key-values pairs where:

• ATTRIBUTE_NAME must be a string less than 256 characters, and cannot start with an ! (these names are reserved for use by Sprig)
• ATTRIBUTE_VALUE must be a number, boolean, or string less than 256 characters

Sprig.setVisitorAttributes(mapOf("key" to "value", "plan" to "enterprise"))

Set Email Address

Setting the user’s email address is optional. Setting emails is not required for web or mobile studies, but can be used to target users or create a Group of users based on their email. Check your organization’s guidelines around personally-identifiable information before sending email addresses to Sprig.

Sprig.setEmailAddress("EMAIL_ADDRESS")

Test & Deploy

To verify your SDK is configured properly, we recommend testing with your development ENVIRONMENT_ID.

1. Create a survey in your Sprig Development Environment
2. Choose an approved event as a trigger for your study
3. [For testing purposes only] Allow users to retake the survey and set the recontact waiting period to 0 days

4. Track the approved event from your app and confirm that the survey appears

Congratulations! Your installation is complete and you can begin deploying.

Advanced Customization

Study Lifecycle Notifications

Sprig exposes updates throughout the study lifecycle. Here is a sample code block for listening to SDK events in real time:

kotlin

val listener = EventListener {
	Log.d("Sprig Event Tracking", it.toString())
}

Sprig.addEventListener(eventName, listener)

Set Locale

Sprig supports setting the locale for default caption and button text. The following locales are supported:

• de
• en
• es-es
• fr
• hi
• ja
• ko
• pt-br
• ru
• zh

To set the locale to Chinese:

Sprig.setLocale('zh')

Info

Setting the locale will only affect static text, and is only available for the iOS and Android SDKs (not React Native).

App size impact

The Sprig SDK AAR size is 211 KB.

The impact to an Android App Bundle is around 650 KB. Note: The Sprig 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 Sprig SDK.