Install Userpilot on Your Android App

Introduction

Userpilot Android SDK enables you to capture user insights and deliver personalized in-app experiences in real time. With just a one-time setup, you can immediately begin leveraging Userpilot’s analytics and engagement features to understand user behaviors and guide their journeys in-app.

This document provides a step-by-step walkthrough of the installation and initialization process, as well as instructions on using the SDK’s public methods.

Prerequisites

Before you begin, ensure your Android project meets the following requirements:

• Android Gradle Plugin: 8.0 or higher.
• minSdkVersion: 21 or higher.
• compileSdkVersion: 34 or higher.
• Kotlin Compatibility: Apply the kotlin-android plugin in your app module’s build.gradle or ensure your Android Gradle Plugin is on 8.4.0 or higher.

Installation

1. Add Maven Central Repository

   Userpilot is hosted on Maven Central. Make sure Maven Central is included in your project’s root-level build.gradle file:

allprojects {
    repositories {
        mavenCentral()
    }
}

2. Add the Userpilot Dependency

   In your app module’s build.gradle , add the Userpilot dependency. Replace <SDK_VERSION> with the latest version available. You can fetch the latest version from here.

Groovy

dependencies {
    implementation 'com.userpilot:userpilot-android:<SDK_VERSION>'
}

Kotlin

dependencies {
    implementation("com.userpilot:userpilot:<SDK_VERSION>")
}

Once synced, the Userpilot SDK is available to import throughout your application.

Initialization

To use Userpilot, initialize it once in your Application class. This ensures the SDK is ready as soon as your app starts. Update your Application class. Replace <APP_TOKEN> with your Application Token, which can be fetched from your Environments Page.

class YourApplication : Application() {
    lateinit var userpilot: Userpilot

    override fun onCreate() {
        super.onCreate()
        userpilot = Userpilot(this, "<APP_TOKEN>")
    }
}

Using the SDK

Once initialized, the SDK provides straightforward methods for identifying users, tracking events, and screen views.

Identifying Users (Required)

This method is required to identify unique users and companies (groups of users) alongside their properties. Once identified, all subsequent tracked events and screens will be attributed to that user.

Recommended Usage:

• On user authentication (login): Immediately call identify when a user signs in to establish their identity for all future events.
• On app launch for authenticated users: If the user has a valid authenticated session, call identify at app launch.
• Upon property updates: Whenever user or company properties change.

Example

userpilot.identify(
  "<USER_ID>", 
  mapOf("name" to "John Doe", "email" to "user@example.com", "created_at" to "2019-10-17", "role" to "Admin"), 
  mapOf("id" to "<COMPANY_ID>", "name": "Acme Labs", "created_at": "2019-10-17", "plan" to "Free")
)

Properties Guidelines

• Key id is required in company properties, to identify a unique company.
• Userpilot supports String, Numeric, and Date types.
• Make sure you’re sending date values in ISO8601 format.
• If you are planning to use Userpilot’s localization features, make sure you are passing user property locale_code with a value that adheres to ISO 639-1 format.
• Userpilot’s reserved properties’ have pre-determined types and improve profiles interface in the dashboard:
  • Use key email to pass the user’s email.
  • Use key name to pass the user’s or company’s name.
  • Use key created_at to pass the user’s or company’s signed up date.

Tracking Screens (Required)

Calling screen is crucial for unlocking Userpilot’s core engagement and analytics capabilities. When a user navigates to a particular screen, invoking screen records that view and triggers any eligible in-app experiences. Subsequent events are also attributed to the most recently tracked screen, providing context for richer analytical insights. For these reasons, we strongly recommend tracking all of your app’s screen views.

Example

userpilot.screen("Profile")

Tracking Events

Log any meaningful action the user performs. Events can be button clicks, form submissions, or any custom activity you want to analyze. Optionally, you can pass metadata with the event to provide specific context.

Example

userpilot.track("Added to Cart", mapOf("itemId" to "sku_456", "price" to 29.99))

Logging Out

When a user logs out, call logout() to clear the current user context. This ensures subsequent events are no longer associated with the previous user.

Example

userpilot.logout()

Anonymous Users

If a user is not authenticated, call anonymous() to track events without a user ID. This is useful for pre-signup flows or guest user sessions.

Example

userpilot.anonymous()

Configurations (Optional)

If you have additional configuration needs, you can pass a custom configuration to Userpilot’s constructor. Userpilot provides interfaces for implementing listeners or handlers to Userpilot events. Implement these interfaces and pass them in your config on initialization if you need to.

userpilot = Userpilot(context, "<APP_TOKEN>"), {
    // Configuration options here
    loggingLevel = LoggingLevel.DEBUG
    navigationHandler = NavigationHandlerObject
    analyticsListener = AnalyticsListenerObject
    experienceListener = ExperienceListenerObject
}

Navigation Handler

Defines how your app handles deep link route triggers configured in Userpilot experiences, requiring you to route the user to the appropriate location.

Interface

public interface UserpilotNavigationHandler {
    public suspend fun navigateTo(uri: Uri): Boolean
}

The UserPilot SDK automatically handles navigation if you haven't implemented the UserPilotNavigationHandler . When a deep link with a defined schema and host is present in the manifest file, the SDK will open the corresponding activity. If the link is external, the SDK will handle it appropriately. For complete control over link handling, you can override the UserPilotNavigationHandler interface. This allows you to customize the behavior for all types of links as per your requirements.

Analytics Listener

Receives callbacks whenever the SDK tracks an event, screen, or identifies a user. Use this if you want to integrate with another analytics tool.

public interface UserpilotAnalyticsListener {
    public fun didTrack(
	    type: UserpilotAnalytic,
	    value: String,
	    properties: Payload
	  )
}

Experience Listener

Receives callbacks when Userpilot experiences start, complete, or are dismissed, as well as changes in their step-by-step progression. Implement this if you want to pipe this data to a destination, or react to user action.

Interface

public interface UserpilotExperienceListener {
    public fun onExperienceStateChanged(
	    id: Int,
	    state: UserpilotExperienceState
    )
    
    public fun onExperienceStepStateChanged(
        id: Int,
        state: UserpilotExperienceState,
        experienceId: Int,
        step: Int,
        totalSteps: Int
    )
}