Userpilot Capacitor Plugin

Userpilot Capacitor Plugin 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 APIs.

• Userpilot Capacitor Plugin
  • 🚀 Getting Started
    • Prerequisites
      • Android
      • iOS
    • Installation
    • Initializing
    • Identifying Users
    • Tracking Screens
    • Tracking Events
    • Trigger Experience
    • Push Notifications
    • SDK Callbacks
  • 📝 Documentation
  • 🎬 Examples
  • 📄 License

🚀 Getting Started

Prerequisites

Android

Your application's build.gradle must have a compileSdk of 35+ and minSdk of 23+. Your project should use the Android Gradle Plugin (AGP) version 8.6+.

android {
    compileSdk 35

    defaultConfig {
        minSdk 23
    }
}

Due to the SDK usage of Jetpack Compose, it is required to either:

1. apply kotlin-android plugin in app's build.gradle file.

plugins {
  id 'com.android.application' 
  id 'kotlin-android' 
}

2. OR Update Android Gradle Plugin 8.4.0+

Related Google issue regarding usage of the Jetpack Compose dependency versions 1.6+

If your project fails to build with similar error:

(25, 39): Class 'kotlin.Unit' was compiled with an incompatible version of Kotlin. 
The binary version of its metadata is 1.9.0, expected version is 1.7.1.

Make sure to set the appropriate kotlin_version on your project build.gradle file

ext.kotlin_version = ‘1.7.20’

iOS

Your application must target iOS 13+ to install the SDK. Update the iOS project xcodeproj to set the deployment target, if needed. In the application's Podfile, include at least this minimum version.

# Podfile
platform :ios, '14.0'

Installation

In your app's root directory, run:

npm install @userpilot/capacitor

npx cap sync

Note: You do not need to manually update your Podfile to add Userpilot.

Initializing

An instance of the Userpilot SDK should be initialized when your app launches.

import { Userpilot } from '@userpilot/capacitor';

Userpilot.initialize({ token: 'ACCOUNT_TOKEN', config: { logging: true } })

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.

SDK Configurations

| Parameter | Type | Description | | ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | logging | Boolean | Enable or Disable logs for SDKDefault: false | | disableRequestPushNotificationsPermission | Boolean | Disable request push notifications permission by SDK.Default: false | | useInAppBrowser | Boolean | configuration to indicate when to open the URL inside CustomTabsIntent or not.Default: false |

Identifying Users

This API is used to identify unique users and companies (groups of users) and set 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.

    API:

// Identify a user
identify(options: IdentifyOptions)

export interface IdentifyOptions {
    /**
     * identified user id
     */
    userId: string;
    /**
     * extra properties
     */
    properties?: object;
    /**
     * extra company
     */
    company?: object;
}

    Example:

Userpilot.identify({
            userId: '<USER_ID>',
            properties: {'name' : 'John Doe', 'email' : '[email protected]', 'created_at' : '2019-10-17', 'role' : 'Admin'},
            company: {'id' : '<COMPANY_ID>', 'name': 'Acme Labs', 'created_at': '2019-10-17', 'plan' : '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.

Notes

• Make sure your User ID source is consistent across all of your platform installations (Web, Android, and iOS).
• While properties are optional, they are essential in Userpilot’s segmentation capabilities. We encourage you to set the properties with the people who are responsible for Userpilot integration.

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.

    API:

screen(options: ScreenOptions)

export interface ScreenOptions {
  /**
   * name of the screen
   */
  title: string;
}

    Example:

Userpilot.screen({ title: '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.

    API:

track(options: TrackOptions)

export interface TrackOptions {
  /**
   * name of the event
   */
  name: string;
  /**
   * extra properties
   */
  properties?: object;
}

    Example:

Userpilot.track({ name: 'Added to Cart', properties: {'itemId' : 'sku_456', 'price' : 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.

    API:

logout()

    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.

    API:

anonymous()

    Example:

Userpilot.anonymous()

Notes

• Anonymous users are counted towards your Monthly Active Users usage. You should take your account’s MAU limit into consideration before applying this API.

Trigger Experience

Triggers a specific experience programmatically using it's ID. This API allows you to manually initiate an experience within your application.

triggerExperience(options: ShowOptions)

export interface ShowOptions {
  /**
   * experience id
   */
  experienceId: string;
}

    Example:

userpilot.triggerExperience({ experienceId: '<EXPERIENCE_ID>' })

To end current active experience

Userpilot.endExperience()

SDK callbacks

Userpilot SDK provides three types of callbacks:

• Navigation Listener
• Analytics Listener
• Experience Listener

Navigation Listener Called when a deep link is triggered from a Userpilot experience or notification. Use this to handle in-app routing.

url: String — The deep link URL to be handled by your app.

Analytics Listener Called when an analytics event is triggered by the Userpilot SDK. Use this to mirror or log SDK-level events into your analytics system.

Params:

analytic: "Identify" | "Screen" | "Event"

value: String — Event value, if any.

properties: Map<String, Any> — Additional metadata for the event.

Experience Listener Called when an experience or its step changes state. Includes two callback types:

onExperienceStateChanged Triggered when the overall state of an experience changes.

experienceId?: Int — Unique ID of the experience (optional)

experienceType: "Flow" | "Survey" | "NPS"

experienceState: "Started" | "Completed" | "Dismissed" | "Skipped" | "Submitted"

onExperienceStepStateChanged Triggered when the state of a specific step within an experience changes.

stepId: Int — Unique identifier of the step

experienceId: Int — ID of the parent experience

experienceType: "Flow" | "Survey" | "NPS"

stepState: "Started" | "Completed" | "Dismissed" | "Skipped" | "Submitted"

step?: Int — Step index (optional)

totalSteps?: Int — Total number of steps in the experience (optional)

Both callbacks are sent under the same event name: UserpilotExperienceEvent

useEffect(() => {
        if (Capacitor.isNativePlatform()) {
            let analyticsListener: PluginListenerHandle
            let experienceListener: PluginListenerHandle
            let navigationListener: PluginListenerHandle

            const setupListeners = async () => {
                analyticsListener = await UserpilotPlugin.addListener(
                    'UserpilotAnalyticsEvent',
                    (event: any) => console.log('Analytics Event:', JSON.stringify(event, null, 2))
                )

                experienceListener = await UserpilotPlugin.addListener(
                    'UserpilotExperienceEvent',
                    (event: any) => console.log('Experience Event:', JSON.stringify(event, null, 2))
                )

                navigationListener = await UserpilotPlugin.addListener(
                    'UserpilotNavigationEvent',
                    (event: any) => {
                        console.log('Navigation Event', JSON.stringify(event, null, 2))
                        if (event?.url) handleDeepLink(event.url)
                    }
                )
            }

            setupListeners()

            return () => {
                if (analyticsListener) analyticsListener.remove()
                if (experienceListener) experienceListener.remove()
                if (navigationListener) navigationListener.remove()
            }
        }
    }, [])

Push Notification

UserPilot SDK supports handling push notifications to help you deliver targeted messages and enhance user engagement. For setup instructions, and integration details, please refer to the Push Notifications Guide.

📝 Documentation

Full documentation is available at Userpilot

🎬 Examples

The example-app directory in this repository contains full example iOS/Android app to providing references for correct installation and usage of the Userpilot API.

📄 License

This project is licensed under the MIT License. See LICENSE for more information.