> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cordova plugin

> Install Userpilot on Cordova Application

UUserpilot Cordova 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.

## **Prerequisites**

#### **Cordova**

Your application should use Cordova version 10+ with cordova-cli installed globally.

#### **Android**

Your application's `build.gradle` must have a `compileSdk` of 35+ and `minSdk` of 21+, and use Android Gradle Plugin (AGP) 8.6+.

```xml theme={null}
<platform name="android">
    <preference name="android-minSdkVersion" value="21" />
    <preference name="android-compileSdkVersion" value="35" />
    <preference name="android-targetSdkVersion" value="35" />
    <preference name="GradlePluginKotlinEnabled" value="true" />
</platform>
```

#### **iOS**

Your application must target iOS 13+ to install the SDK, Update the iOS project xcodeproj to set the deployment target. Update your `config.xml` to set the deployment target.

```xml theme={null}
<platform name="ios">
    <preference name="deployment-target" value="13.0" />
    <preference name="SwiftVersion" value="5.0" />
</platform>
```

***

## Installation

Add the Userpilot Cordova Plugin dependency to your application.

1. In your app's root directory, install the Userpilot Cordova Plugin. You can fetch the latest version from [here](https://www.npmjs.com/package/@userpilot/cordova).

```bash theme={null}
cordova plugin add @userpilot/cordova
or 
cordova plugin add @userpilot/cordova --variable DEPLOYMENT-TARGET=13.0
```

1. Prepare your platforms:

```bash theme={null}
cordova prepare
```

***

## 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](https://run.userpilot.io/environment).

```javascript theme={null}
// API
setup(token, options, onSuccess, onError)

// Example
document.addEventListener('deviceready', function() {
	const options = {
        logging: true,         // Enable/disable SDK logging
        useInAppBrowser: true  // Enable/disable in-app browser for links - Works for Android
    };

    window.userpilot.setup('<APP_TOKEN>', options,
        function(success) {
            console.log('Userpilot initialized successfully');
        },
        function(error) {
            console.error('Failed to initialize Userpilot:', error);
        }
    );
}, false);
```

## **Configurations (Optional)**

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

***

## Using the SDK

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

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

<Warning>
  **Important**

  It’s crucial to call the Userpilot identify function; without it, Userpilot won’t be able to recognize your users, and mobile content won’t be displayed to them.
</Warning>

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

```javascript theme={null}
// API
identify(userID, properties, company, onSuccess, onError)

// Example
window.userpilot.identify(
    '<USER_ID>',
    {
        'name': 'John Doe', 
        'email': 'user@example.com', 
        'created_at': '2019-10-17', 
        'role': 'Admin'
    },
    {
        'id': 'company123', 
        'name': 'Acme Labs', 
        'created_at': '2019-10-17', 
        'plan': 'Free'
    },
    function(success) {
        console.log('User identified successfully');
    },
    function(error) {
        console.error('Failed to identify user:', error);
    }
);
```

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

<Tip>
  Notes

  * Ensure the User ID source is consistent across Web, Android, and iOS.
  * While properties are optional, setting them enhances Userpilot’s segmentation capabilities.
</Tip>

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

```javascript theme={null}
// API
screen(screenName, onSuccess, onError)

// Example
window.userpilot.screen('Profile',
    function(success) {
        console.log('Screen tracked successfully');
    },
    function(error) {
        console.error('Failed to track screen:', error);
    }
);
```

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

```javascript theme={null}
// API
track(name, properties, onSuccess, onError)

// Example
window.userpilot.track('Added to Cart', 
    { 
        itemId: 'sku_456', 
        price: 29.99 
    },
    function(success) {
        console.log('Event tracked successfully');
    },
    function(error) {
        console.error('Failed to track event:', error);
    }
);
```

### **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.

```javascript theme={null}
// API
logout(onSuccess, onError)

// Example
window.userpilot.logout(
    function(success) {
        console.log('User logged out successfully');
    },
    function(error) {
        console.error('Failed to logout user:', error);
    }
);
```

### **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.

```javascript theme={null}
// API
anonymous(onSuccess, onError)

// Example
window.userpilot.anonymous(
    function(success) {
        console.log('Anonymous user set successfully');
    },
    function(error) {
        console.error('Failed to set anonymous user:', error);
    }
);
```

<Warning>
  Anonymous users count towards your Monthly Active Users usage. Consider your MAU limits before using this API.
</Warning>

***

## Experience

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

```javascript theme={null}
// API
triggerExperience(experienceId, onSuccess, onError)

// Example
window.userpilot.triggerExperience('<EXPERIENCE_ID>',
    function(success) {
        console.log('Experience triggered successfully');
    },
    function(error) {
        console.error('Failed to trigger experience:', error);
    }
);
```

To end current active experience

```javascript theme={null}
// API
endExperience(onSuccess, onError)

// Example
window.userpilot.endExperience(
    function(success) {
        console.log('Experience ended successfully');  
    },
    function(error) {
        console.error('Failed to end experience:', error);
    }
);
```

## Configuration (Optional)

| **Parameter**                             | **Type** | **Description**                                                                                                                         |
| ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| logging                                   | Boolean  | Enable or disable logs for the SDK.<br /><br />**Default: false**                                                                       |
| disableRequestPushNotificationsPermission | Boolean  | Disable push notifications permission request by the SDK.<br /><br />**Default: false**                                                 |
| useInAppBrowser                           | Boolean  | Determines whether to open URLs inside CustomTabsIntent/SFSafariViewController or use the system browser.<br /><br />**Default: false** |

<Frame>
  [**For any questions or concerns please reach out to support@userpilot.com**](mailto:support@userpilot.com)
</Frame>