Userpilot

https://docs.userpilot.com
Admin
Userpilot is a product growth platform that empowers non-technical teams to create and optimize user...
Tokens:173,678
Snippets:2,476
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Userpilot.setup

Source: https://docs.userpilot.com/developer/installation/mobile/mobile-react-native

Initializes the Userpilot SDK. This should be called once when the application starts.

```APIDOC
## Userpilot.setup(token, options)

### Description
Initializes the Userpilot SDK with your application token.

### Parameters
- **token** (string) - Required - Your Application Token from the Userpilot Environments Page.
- **options** (Object) - Optional - Configuration options, such as { logging: boolean }.
```

--------------------------------

### Install and Initialize Userpilot SDK via NPM

Source: https://docs.userpilot.com/developer/security/sri

Install the package and initialize the SDK with your token and SRI hash configuration.

```bash
npm install userpilot
```

```typescript
import { Userpilot } from 'userpilot';

// Initialize the Userpilot SDK with SRI
Userpilot.initialize("YOUR_TOKEN_HERE", {
  version: "YOUR_VERSION_HERE",
  sri: "YOUR_SRI_HASH_HERE"
});
```

--------------------------------

### Install Userpilot Capacitor plugin

Source: https://docs.userpilot.com/developer/installation/mobile/capacitor/installation

Install the plugin dependency and synchronize the Capacitor project.

```bash
npm install @userpilot/capacitor

npx cap sync
```

--------------------------------

### Install Userpilot Babel Plugin

Source: https://docs.userpilot.com/developer/installation/mobile/react-native/auto-capture

Install the required Babel plugin as a development dependency.

```sh
npm install --save-dev @userpilot/babel-plugin-react-native-autocapture
```

--------------------------------

### Install Userpilot MAUI SDK via NuGet

Source: https://docs.userpilot.com/developer/installation/mobile/maui/installation

Add the Userpilot.Maui package to your project file.

```xml
<PackageReference Include="Userpilot.Maui" Version="<latest_version>" />
```

--------------------------------

### Implement UserpilotExperienceDelegate in Objective-C

Source: https://docs.userpilot.com/developer/installation/mobile/ios/callbacks

Provides an example implementation of the delegate methods in Objective-C.

```objective-c
#pragma mark - UserpilotExperienceDelegate

- (void)onExperienceStateChangedWithExperienceType:(UserpilotExperienceType)experienceType
                                      experienceId:(NSNumber *)experienceId
                                   experienceState:(UserpilotExperienceState)experienceState {
    NSLog(@"Experience [%@] type: %ld changed state to: %ld",
          experienceId, (long)experienceType, (long)experienceState);
}

- (void)onExperienceStepStateChangedWithExperienceType:(UserpilotExperienceType)experienceType
                                          experienceId:(NSNumber *)experienceId
                                               stepId:(NSNumber *)stepId
                                            stepState:(UserpilotExperienceState)stepState
                                                 step:(NSNumber *)step
                                           totalSteps:(NSNumber *)totalSteps {
    NSLog(@"Step [%@] of experience [%@] (type: %ld) changed state to: %ld - step %ld/%ld",
          stepId, experienceId, (long)experienceType, (long)stepState,
          step.intValue, totalSteps.intValue);
}
```

--------------------------------

### Identify user properties

Source: https://docs.userpilot.com/developer/identify-vs-reload

Use these examples to set or update user identification and properties.

```javascript
userpilot.identify("443", // Unique user ID
  { 
    name: "James",
    created_at: "2019-10-17", // ISO8601 Date
    plan: "Trial"
    // Additional user properties
    // projectId: "1"
    // trialEnds: "2019-10-31" // ISO8601 Date
  }
);
```

```javascript
userpilot.identify("443", { color: "blue" });
```

--------------------------------

### Import API Responses

Source: https://docs.userpilot.com/api-references/import/overview

Example JSON responses for successful job queuing and error scenarios.

```json
{
  "end_time": null,
  "file_size": 2234,
  "filename": "2024-10-28.ndjson",
  "job_id": "imports:jobs:NX-51f4acf7:f681073b-21ac-4276-9af5-c662dc05fb25",
  "links": "/v1/background_jobs/imports:jobs:NX-51f4acf7:f681073b-21ac-4276-9af5-c662dc05fb25",
  "start_time": "2024-11-28T10:34:11.376662",
  "status": "queued",
  "total_rows": 0,
  "type": "import"
}
```

```json
{
  "errors": [
    {
      "details": null,
      "error": "Conflict",
      "error_code": "409",
      "message": "The request could not be completed due to a conflict with the current state of the target resource."
    }
  ]
}
```

--------------------------------

### setup(token, options, onSuccess, onError)

Source: https://docs.userpilot.com/developer/installation/mobile/cordova/installation

Initializes the Userpilot SDK. This method should be called once, typically after the 'deviceready' event, to configure the SDK with your application token and optional settings.

```APIDOC
## setup(token, options, onSuccess, onError)

### Description
Initializes the Userpilot SDK. This method should be called once, typically after the 'deviceready' event, to configure the SDK with your application token and optional settings.

### Parameters
- **token** (String) - Required - Your Application Token from the Userpilot Environments Page.
- **options** (Object) - Optional - Configuration object containing settings like logging and browser behavior.
- **onSuccess** (Function) - Optional - Callback function executed upon successful initialization.
- **onError** (Function) - Optional - Callback function executed if initialization fails.

### Request Example
```javascript
const options = {
    logging: true,
    useInAppBrowser: true
};

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

--------------------------------

### Get Job Status by ID Response

Source: https://docs.userpilot.com/api-references/import/overview

Example JSON response for a specific import job.

```json
{
  "elapsed_time": 6,
  "end_time": "2025-05-19T07:23:00.354452",
  "file_size": 757,
  "filename": "2024-10-28.ndjson",
  "job_id": "imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
  "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
  "start_time": "2025-05-19T07:22:54.409499",
  "status": "completed",
  "total_rows": 3,
  "type": "import"
}
```

--------------------------------

### Host and Vendor Multi-Instance Setup

Source: https://docs.userpilot.com/developer/installation/mobile/android/multi-instance

Demonstrates the recommended configuration where the host app retains the default role and the vendor SDK explicitly opts out.

```kotlin
// Application.onCreate (host app)
val hostUserpilot = Userpilot(context, "HOST") {
    enableScreenAutoCapture = true
    enableInteractionAutoCapture = true
    // no isDefault = true needed — defaults to true
}

// AcmeSDK (vendor SDK facade)
val acmeUserpilot = Userpilot(context, "ACME") {
    isDefault = false
    enableScreenAutoCapture = true
    enableInteractionAutoCapture = true
}
```

--------------------------------

### Get All Import Job Statuses Request

Source: https://docs.userpilot.com/api-references/import/overview

Example cURL request to fetch all import job statuses.

```bash
curl -X GET "{{ENDPOINT}}/v1/background_jobs" \
-H "Authorization: Token {{API_KEY}}"
```

--------------------------------

### Get Job Status by ID Request

Source: https://docs.userpilot.com/api-references/import/overview

Example cURL request to fetch a specific import job status.

```bash
curl -X GET "{{ENDPOINT}}/v1/background_jobs/:job_id" \
-H "Authorization: Token {{API_KEY}}"
```

--------------------------------

### Initialize Multiple Userpilot Instances

Source: https://docs.userpilot.com/developer/installation/mobile/ios/multi-instance

Demonstrates configuring a host application instance and a separate vendor SDK instance with distinct tokens and settings.

```swift
// AppDelegate.swift (host app)
let hostConfig = Userpilot.Config(token: "HOST")
    .logging(enabled: true)
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
let hostUserpilot = Userpilot(config: hostConfig)   // isDefault defaults to true → claims default

// AcmeSDK.swift (vendor SDK)
let vendorConfig = Userpilot.Config(token: "ACME")
    .defaultInstance(false)
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
    .attach(bundles: [Bundle(for: AcmeSDK.self)])
let acmeUserpilot = Userpilot(config: vendorConfig)

hostUserpilot.identify(userId: "host-42")
acmeUserpilot.identify(userId: "acme-99")
acmeUserpilot.track(eventName: "vendor_action")
```

--------------------------------

### Get All Import Job Statuses Response

Source: https://docs.userpilot.com/api-references/import/overview

Example JSON response containing a list of import job objects.

```json
[
  {
    "elapsed_time": 6,
    "end_time": "2025-05-19T07:23:00.354452",
    "file_size": 757,
    "filename": "2024-10-28.ndjson",
    "job_id": "imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
    "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:c6f91301-54c1-4df7-a077-b34715c38875",
    "start_time": "2025-05-19T07:22:54.409499",
    "status": "completed",
    "total_rows": 3,
    "type": "import"
  },
  {
    "elapsed_time": 0,
    "end_time": "2025-05-19T07:09:49.883288",
    "file_size": 416,
    "filename": "2024-10-28.ndjson",
    "job_id": "imports:jobs:NX-ac54070e:1fd8f0d4-cd97-432f-86fe-3df9effc1912",
    "links": "/v1/background_jobs/imports:jobs:NX-ac54070e:1fd8f0d4-cd97-432f-86fe-3df9effc1912",
    "reason_for_failure": [
      "Required field `user_id` not provided in the row: %{\"event_name\" => \"\", \"event_type\" => \"identify_user\", \"metadata\" => %{\"avg_resolution_time\" => \"2h\", \"customer_satisfaction\" => \"4.8\", \"escalation_count\" => \"1\", \"last_ticket_created\" => \"2025-02-01T10:20:30Z\", \"tickets_created\" => \"15\", \"tickets_pending\" => \"1\", \"tickets_resolved\" => \"14\"}}"
    ],
    "start_time": "2025-05-19T07:09:49.880967",
    "status": "failed",
    "total_rows": 0,
    "type": "import"
  }
  //... more jobs
]
```

--------------------------------

### Install Userpilot React Native Module

Source: https://docs.userpilot.com/developer/installation/mobile/mobile-react-native

Install the package via npm and run pod install for iOS dependencies.

```bash
npm install @userpilot/react-native
```

```bash
pod install
```

--------------------------------

### Userpilot.UserpilotSdk.Setup

Source: https://docs.userpilot.com/developer/installation/mobile/maui/installation

Initializes the Userpilot SDK. This method must be called during the application's launch sequence.

```APIDOC
## Userpilot.UserpilotSdk.Setup

### Description
Initializes the Userpilot SDK. This method is required to start the SDK and should be called during the app's launch sequence.

### Method
Static Method

### Parameters
- **token** (string) - Required - The Application Token from the Userpilot Environments Page.
- **context** (Android.Content.Context) - Required (Android only) - The Android application context.
- **isLoggingEnabled** (Boolean) - Optional - Enable or disable logs for the SDK. Default: false.
- **isDisableRequestPushNotificationsPermissions** (Boolean) - Optional - Disable push notifications permission request by the SDK. Default: false.
- **isUseInAppBrowserEnabled** (Boolean) - Optional (Android only) - Determines whether to open URLs inside CustomTabsIntent or use the system browser. Default: false.

### Returns
- **success** (Boolean) - Returns true if the SDK was initialized successfully.
```

--------------------------------

### Install Userpilot React Native dependencies

Source: https://docs.userpilot.com/developer/mobile-segment/mobile-segment-react-native

Install the required packages using npm or yarn before running pod install for autolinking.

```bash
npm install --save @userpilot/segment-react-native @userpilot/react-native
```

```bash
yarn add @userpilot/segment-react-native @userpilot/react-native
```

--------------------------------

### Initialize Multiple Userpilot Instances

Source: https://docs.userpilot.com/developer/installation/mobile/android/multi-instance

Demonstrates configuring a primary host instance and a secondary vendor SDK instance with distinct tokens and default claimant settings.

```kotlin
// Host Application.onCreate
val hostUserpilot = Userpilot(this, "HOST") {
    enableScreenAutoCapture = true
    enableInteractionAutoCapture = true
    // isDefault defaults to true — claims default automatically
}

// AcmeSDK (vendor SDK facade)
class AcmeSDK(context: Context) {
    val acmeUserpilot = Userpilot(context, "ACME") {
        isDefault = false
        enableScreenAutoCapture = true
        enableInteractionAutoCapture = true
    }

    fun identifyAcmeUser(id: String) = acmeUserpilot.identify(id)
}

hostUserpilot.identify("host-42")
AcmeSDK(this).identifyAcmeUser("acme-99")
hostUserpilot.track("Added to Cart")
```

--------------------------------

### Install Userpilot MAUI SDK via .NET CLI

Source: https://docs.userpilot.com/developer/installation/mobile/maui/installation

Use the .NET CLI to add the Userpilot.Maui package.

```bash
dotnet add package Userpilot.Maui
```

--------------------------------

### Install Userpilot via CDN

Source: https://docs.userpilot.com/developer/installation/SDK-APIs

Include the SDK directly in your HTML by setting the configuration object before loading the script.

```html
<script>
	window.userpilotSettings = {token: app_token}
</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>
```

--------------------------------

### Install Userpilot React Native package

Source: https://docs.userpilot.com/developer/installation/mobile/react-native/expo

Use the Expo CLI to install the required dependency for your project.

```sh
$ npx expo install @userpilot/react-native
```

--------------------------------

### Install Expo Notifications Library

Source: https://docs.userpilot.com/developer/installation/mobile/mobile-expo-push-notification

Command to install the required expo-notifications package for handling push notifications.

```javascript
npx expo install expo-notifications
```

--------------------------------

### Userpilot.initialize

Source: https://docs.userpilot.com/developer/installation/SDK-APIs

Initializes the Userpilot SDK with the provided application token and settings.

```APIDOC
## Userpilot.initialize(app_token, userpilotSettings)

### Description
Initializes the Userpilot SDK instance for your web application.

### Parameters
- **app_token** (string) - Required - The unique account application token.
- **userpilotSettings** (object) - Optional - Configuration object for SDK behavior.

### Configuration Settings (userpilotSettings)
- **token** (string) - Account App Token
- **version** (string) - Pinned SDK Version
- **connection** (string) - Enable long-polling mode (polling | websocket)
- **endpoint** (string) - API endpoint for when proxying
- **domain** (string) - JS SDK domain for CNAME
- **pageview** (string) - Specifies what to collect from a URL (pathonly | withhash | fullurl)
- **auto_props** (boolean) - Collecting auto properties
- **sri** (string) - Sub Resource Integrity value
- **auto_capture** (object) - Define autocapture privacy settings
- **callbacks** (object) - Listen to events that occur on the SDK side
- **integrations_interfaces** (object) - Define the integration interface
```

--------------------------------

### Install Userpilot Expo Config Plugin

Source: https://docs.userpilot.com/developer/installation/mobile/mobile-expo-push-notification

Install the required npm package to enable Userpilot configuration in an Expo project.

```bash
npm install @userpilot/expo-config
```

--------------------------------

### Install Staging Token via JavaScript

Source: https://docs.userpilot.com/developer/installation/production-staging

Use this snippet to initialize the Userpilot SDK with a staging token in your testing environment.

```javascript
<script>window.userpilotSettings = {token: "STG-5rx54y"};</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>
```

--------------------------------

### Initialize Userpilot SDK on iOS

Source: https://docs.userpilot.com/developer/installation/mobile/maui/installation

Call the Setup method during the iOS app launch sequence using your Application Token.

```csharp
bool success = Userpilot.UserpilotSdk.Setup(
    token: "<APP_TOKEN>",
    isLoggingEnabled: true,
    isDisableRequestPushPermission: false
);
```

--------------------------------

### Implement Navigation Callback in MAUI

Source: https://docs.userpilot.com/developer/installation/mobile/maui/callbacks

Handles deep link routes triggered by Userpilot experiences. Register after SDK setup on iOS and before SDK setup on Android.

```csharp
public class AppNavigationCallbackiOS : Userpilot.UserpilotNavigationCallback
{
    public override void OnNavigate(string url)
    {
        Console.WriteLine($"[Userpilot] Navigate to: {url}");
        // Handle navigation to the URL
    }
}

// Store in a static field to prevent GC
private static AppNavigationCallbackiOS? _navCallback;

// Register the callback (after SDK setup)
_navCallback = new AppNavigationCallbackiOS();
Userpilot.UserpilotSdk.SetNavigationCallback(_navCallback);
```

```csharp
public class AppNavigationCallback : Java.Lang.Object, Userpilot.UserpilotSdk.Companion.INavigationCallback
{
    public void OnNavigate(string url)
    {
        Android.Util.Log.Info("Userpilot", $"Navigate to: {url}");
        // Handle navigation to the URL
    }
}

// Register the callback (before SDK setup)
Userpilot.UserpilotSdk.SetNavigationCallback(new AppNavigationCallback());
```

--------------------------------

### Initialize Userpilot SDK Cross-Platform

Source: https://docs.userpilot.com/developer/installation/mobile/maui/installation

Use preprocessor directives to handle platform-specific initialization logic within a single codebase.

```csharp
var token = "<APP_TOKEN>";

#if ANDROID
    var context = Android.App.Application.Context;
    bool success = Userpilot.UserpilotSdk.Setup(
        context, token,
        isLoggingEnabled: true,
        isUseInAppBrowserEnabled: false,
        isDisableRequestPushNotificationsPermissions: false
    );
#elif IOS
    bool success = Userpilot.UserpilotSdk.Setup(
        token,
        isLoggingEnabled: true,
        isDisableRequestPushPermission: false
    );
#endif
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/spotlights

Source: https://docs.userpilot.com/api-references/endpoints/lookups/spotlights

Retrieve a list of spotlights available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/spotlights

### Description
Retrieve a list of spotlights available for export. This list includes IDs and names for filtering analytics exports by tooltip and hotspot interactions.

### Method
GET

### Endpoint
https://appex.userpilot.io/api/v1/analytics/exports/lookups/spotlights

### Parameters
#### Headers
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of spotlights.

#### Response Example
[
  {
    "id": 88,
    "title": "New Feature Spotlight"
  }
]
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/banners

Source: https://docs.userpilot.com/api-references/endpoints/lookups/banners

Retrieve a list of banners available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/banners

### Description
Retrieve a list of banners available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/banners

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of banners.

#### Response Example
[
  {
    "id": 77,
    "title": "Promo Banner"
  }
]
```

--------------------------------

### Authentication Example (cURL)

Source: https://docs.userpilot.com/api-references/endpoints/export/export-job

Demonstrates the required HTTP header format for authenticating API requests using an API key.

```bash
curl -X GET 'https://appex.userpilot.io/v1/identify' \
  -H 'Authorization: Token abcd1234efgh5678' \
  -H 'Content-Type: application/json'
```

--------------------------------

### Prebuild Expo Project

Source: https://docs.userpilot.com/developer/installation/mobile/mobile-expo-push-notification

Run the prebuild command to apply configuration changes before testing locally.

```bash
npx expo prebuild
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/events_properties

Source: https://docs.userpilot.com/api-references/export/lookups

Retrieves a paginated list of trackable events' properties.

```APIDOC
## GET /api/v1/analytics/exports/lookups/events_properties

### Description
Retrieves trackable events' properties/attributes. This endpoint is paginated.

### Method
GET

### Endpoint
https://appex.userpilot.io/api/v1/analytics/exports/lookups/events_properties

### Query Parameters
- **after_cursor** (string) - Optional - Cursor for fetching the next set of results.
- **limit** (integer) - Optional - Number of results per request.
```

--------------------------------

### Initialize Userpilot SDK

Source: https://docs.userpilot.com/developer/installation/SDK-APIs

Import the Userpilot class and initialize it with your application token and settings.

```javascript
import { Userpilot } from 'userpilot'

Userpilot.initialize(app_token, userpilotSettings);
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/surveys

Source: https://docs.userpilot.com/api-references/endpoints/lookups/surveys

Retrieve a list of surveys (with modules) available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/surveys

### Description
Retrieve a list of surveys (with modules) available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/surveys

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of surveys (with modules).

#### Response Example
[
  {
    "id": 45,
    "title": "CSAT Survey",
    "platform": "web",
    "modules": [
      {
        "id": 1,
        "order": 1,
        "type": "open_text",
        "question": "How was it?"
      }
    ]
  }
]
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/segments

Source: https://docs.userpilot.com/api-references/endpoints/lookups/segments

Retrieve a paginated list of segments available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/segments

### Description
Retrieve a paginated list of segments available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/segments

### Parameters
#### Headers
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **data** (array) - A list of segment objects.
- **metadata** (object) - Pagination metadata including cursor, limit, and total_count.

#### Response Example
{
  "data": [
    {
      "id": 101,
      "title": "Active Users",
      "usage": "all",
      "category": "user_id",
      "is_hidden": false,
      "is_protected": false,
      "status": "published"
    }
  ],
  "metadata": {
    "cursor": {
      "after": "...",
      "before": null
    },
    "limit": 50,
    "total_count": 1
  }
}
```

--------------------------------

### Initialize Userpilot SDK and Identify User

Source: https://docs.userpilot.com/developer/installation/web

Include the SDK script and identify the current user with their unique ID and properties. Replace 'appToken' with your specific account token.

```javascript
<script>
window.userpilotSettings = {token: "appToken"};
</script>
<script src = "https://js.userpilot.io/sdk/latest.js"></script>
<script>
  userpilot.identify( 
    "<UNIQUE USER ID>", 
    { 
         name: "John Doe",
         email: "customer@example.com",
         created_at: "1519205055"
         // Additional user properties 
         // projectId: "1"
         // trialEnds: '2019-10-31T09:29:33.401Z'
    }     
  );
</script>
```

--------------------------------

### OpenAPI Specification for Segments

Source: https://docs.userpilot.com/api-references/endpoints/lookups/segments

The OpenAPI definition for the GET /api/v1/analytics/exports/lookups/segments endpoint.

```yaml
openapi: 3.0.0
info:
  title: Userpilot API
  version: 1.0.0
  termsOfService: https://userpilot.io/terms-of-service/
  description: >-
    Userpilot's API suite for user identification, event tracking, data
    import/export, and user/company management.


    Authentication:
     All endpoints that require authentication expect an HTTP header in the following format:

     Authorization: Token {{API_KEY}}

    Example (cURL):
     curl -X GET 'https://appex.userpilot.io/v1/identify' \
       -H 'Authorization: Token abcd1234efgh5678' \
       -H 'Content-Type: application/json'

    Contact Support:
     Email: support@userpilot.com
  contact:
    name: Userpilot
    url: https://userpilot.io
    email: support@userpilot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://appex.userpilot.io
    description: Application endpoint
security: []
paths:
  /api/v1/analytics/exports/lookups/segments:
    get:
      summary: Get segments
      description: Retrieve a paginated list of segments available for export.
      parameters:
        - $ref: '#/components/parameters/AuthorizationHeader'
      responses:
        '200':
          description: A paginated list of segments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  metadata:
                    type: object
                    properties:
                      cursor:
                        type: object
                        properties:
                          after:
                            type: string
                            nullable: true
                          before:
                            type: string
                            nullable: true
                      limit:
                        type: integer
                      total_count:
                        type: integer
              example:
                data:
                  - id: 101
                    title: Active Users
                    usage: all
                    category: user_id
                    is_hidden: false
                    is_protected: false
                    status: published
                metadata:
                  cursor:
                    after: ...
                    before: null
                  limit: 50
                  total_count: 1
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      description: >-
        API authentication token in the format: `Token {{API_KEY}}`. Obtain your
        API key from the [Userpilot Environment
        Settings](https://run.userpilot.io/environment).
      schema:
        type: string
      example: Token abcd1234efgh5678
```

--------------------------------

### Initialize Userpilot with Auto Capture

Source: https://docs.userpilot.com/developer/installation/mobile/react-native/auto-capture

Configure auto capture settings during SDK initialization via Userpilot.setup. Interaction capture requires the Babel plugin to be installed.

```ts
import * as Userpilot from '@userpilot/react-native';

await Userpilot.setup('<APP_TOKEN>', {
  logging: true,
  enableScreenAutoCapture: true,
  enableInteractionAutoCapture: true,
  enableInteractionAccessibilityLabelCapture: true,
  enableInteractionTextCapture: true,
  enableInteractionValueCapture: false,
  enableInteractionCustomPropsCapture: true,
  navigation: {
    library: Userpilot.NavigationLibraryType.ReactNavigation,
    navigation: navigationRef,
  },
});
```

--------------------------------

### Initialize Userpilot SDK

Source: https://docs.userpilot.com/developer/installation/mobile/cordova/installation

Initialize the SDK within the deviceready event listener using your unique application token and configuration options.

```javascript
// 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);
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/features_events

Source: https://docs.userpilot.com/api-references/endpoints/lookups/features-events

Retrieve a list of features and events available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/features_events

### Description
Retrieve a list of features and events available for export.

### Method
GET

### Endpoint
https://appex.userpilot.io/api/v1/analytics/exports/lookups/features_events

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of features and events.

#### Response Example
[
  {
    "display_name": "Feature A",
    "key": "feature_a",
    "data_type": "string"
  }
]
```

--------------------------------

### Configure Userpilot SDK

Source: https://docs.userpilot.com/developer/installation/mobile/android/installation

Initialize the Userpilot SDK with optional settings for logging, auto-capture, and event listeners.

```kotlin
val userpilot = Userpilot(context, "<APP_TOKEN>") {
              loggingEnabled = true
              enableScreenAutoCapture = true
              enableInteractionAutoCapture = true
              useInAppBrowser = true
              disableRequestPushNotificationsPermissions = true

              navigationHandler = object : UserpilotNavigationHandler {
                  override fun navigateTo(uri: Uri) {

                  }
              }
              analyticsListener = object : UserpilotAnalyticsListener {
                  override fun didTrack(
                      type: UserpilotAnalytic,
                      value: String,
                      properties: Payload,
                  ) {

                  }
              }
              experienceListener = object : UserpilotExperienceListener {
                  override fun onExperienceStateChanged(
                      id: Int,
                      state: UserpilotExperienceState
                  ) {

                  }

                  override fun onExperienceStepStateChanged(
                      id: Int,
                      state: UserpilotExperienceState,
                      experienceId: Int,
                      step: Int,
                      totalSteps: Int,
                  ) {

                  }
              }
          }
```

```java
Userpilot userpilot = UserpilotKt.Userpilot(application, "<APP_TOKEN>", config -> {
              config.setLoggingEnabled(true);
              config.setEnableScreenAutoCapture(true);
              config.setEnableInteractionAutoCapture(true);
              config.setUseInAppBrowser(true);
              config.setDisableRequestPushNotificationsPermissions(true);
              
              Map<String, String> sdkMessages = new HashMap<>();
              sdkMessages.put(UserpilotMessageKeys.PUSH_NOTIFICATION_MESSAGE, "Custom app message");
              config.setSdkMessages(sdkMessages);

              config.setNavigationHandler(new UserpilotNavigationHandler() {
                  @Override
                  public void navigateTo(@NonNull Uri uri) {

                  }
              });

              config.setAnalyticsListener(new UserpilotAnalyticsListener() {
                  @Override
                  public void didTrack(@NonNull UserpilotAnalytic type, @NonNull String value, @Nullable Map<String, ?> properties) {

                  }
              });

              config.setExperienceListener(new UserpilotExperienceListener() {
                  @Override
                  public void onExperienceStepStateChanged(int id, @NonNull UserpilotExperienceState state, int experienceId, int step, int totalSteps) {

                  }

                  @Override
                  public void onExperienceStateChanged(int id, @NonNull UserpilotExperienceState state) {

                  }
              });
              return Unit.INSTANCE;
          });
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/flows

Source: https://docs.userpilot.com/api-references/endpoints/lookups/flows

Retrieve a list of flows (experiences) available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/flows

### Description
Retrieve a list of flows (experiences) available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/flows

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of flows (experiences).

#### Response Example
[
  {
    "id": 123,
    "title": "Onboarding Flow"
  }
]
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/company_properties

Source: https://docs.userpilot.com/api-references/endpoints/lookups/company-properties

Retrieve a list of company properties available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/company_properties

### Description
Retrieve a list of company properties available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/company_properties

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **List** (array) - A list of company properties.

#### Response Example
[
  {
    "id": 10,
    "type": "company_property",
    "key": "company_name",
    "display_name": "Company Name",
    "data_type": "string",
    "is_auto_property": false
  }
]
```

--------------------------------

### Implementing Userpilot Callbacks and Deep Link Handling

Source: https://docs.userpilot.com/developer/installation/mobile/flutter/callbacks

This example shows the full lifecycle of Userpilot initialization, stream subscription, and deep link processing within a StatefulWidget.

```dart
import 'dart:async';

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:userpilot_flutter/userpilot_flutter.dart';
import 'package:userpilot_flutter_example/src/utils/routes.dart';
import '../utils/app_colors.dart';

class UserpilotApp extends StatefulWidget {
  const UserpilotApp({super.key});

  @override
  State<UserpilotApp> createState() => _UserpilotAppState();
}

class _UserpilotAppState extends State<UserpilotApp> {
  final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

  StreamSubscription<UserpilotExperience>? experienceSubscription;
  StreamSubscription<UserpilotAnalytic>? analyticsSubscription;
  StreamSubscription<UserpilotNavigation>? navigationSubscription;

  // Event Channel creation
  // used for listening for deep links from platform code
  static const stream = EventChannel('com.userpilot.samples.flutter/events');

  // Method channel creation
  // used to check for initial deep link when launching app, from platform
  static const platform =
      MethodChannel('com.userpilot.samples.flutter/channel');

  bool _initialURILinkHandled = false;

  @override
  void initState() {
    super.initState();
    _initializeUserpilot();

    //Checking application start by deep link
    _startUri().then(_onRedirected);
    //Checking broadcast stream, if deep link was clicked in opened application
    stream.receiveBroadcastStream().listen((d) => _onRedirected(d));
  }

  @override
  void dispose() {
    experienceSubscription?.cancel();
    analyticsSubscription?.cancel();
    navigationSubscription?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      ...
    );
  }

  Future<void> _initializeUserpilot() async {
    UserpilotOptions options = UserpilotOptions();
    options.logging = true;

    try {
      await Userpilot.initialize('APP_TOKEN', options);
      print('Userpilot initialized successfully');

      // Subscribe to streams AFTER initialization completes
      // This ensures the native StreamHandlers are set up before subscribing
      _subscribeToUserpilotStreams();

      await _printUserpilotSettings();
    } catch (e) {
      print('Failed to initialize Userpilot: $e');
    }
  }

  void _subscribeToUserpilotStreams() {
    experienceSubscription = Userpilot.onExperienceEvent.listen(
      _handleExperienceEvent,
      onError: _handleError,
    );

    analyticsSubscription = Userpilot.onAnalyticEvent.listen(
      _handleAnalyticsEvent,
      onError: _handleError,
    );

    navigationSubscription = Userpilot.onNavigationEvent.listen(
      _handleNavigationEvent,
      onError: _handleError,
    );

    print('Subscribed to Userpilot streams');
  }

  // Detect if app was launched from a deeplink
  Future<String?> _startUri() async {
    // guard against processing initial link more than once
    if (!_initialURILinkHandled) {
      _initialURILinkHandled = true;
      return platform.invokeMethod('initialLink');
    }
    return null;
  }

  // Handle any deep link sent to the app
  Future<void> _onRedirected(String? url) async {
    if (!mounted || url == null) return;
    var uri = Uri.parse(url);
    // Pass along to Userpilot to potentially handle
    bool handled = await Userpilot.didHandleURL(uri);
    if (handled) return;
  }

  Future<void> _printUserpilotSettings() async {
    try {
      final settings = await Userpilot.settings();
      print('📋 Userpilot Settings:');
      settings.forEach((key, value) {
        print(' - $key: $value');
      });
    } catch (e) {
      print('Failed to fetch Userpilot settings: $e');
    }
  }

  void _handleExperienceEvent(UserpilotExperience event) {
    final parts = <String>[];
    parts.add('Type: ${event.experienceType}');

    if (event.experienceState != null) {
      parts.add('Experience State: ${event.experienceState}');
    }

    if (event.stepState != null) {
      parts.add('Step State: ${event.stepState}');
    }

    if (event.experienceId != null) {
      parts.add('Experience ID: ${event.experienceId}');
    }

    if (event.stepId != null) {
      parts.add('Step ID: ${event.stepId}');
    }

    if (event.step != null) {
      parts.add('Step: ${event.step}');
    }

    if (event.totalSteps != null) {
      parts.add('Total Steps: ${event.totalSteps}');
    }

    print('Experience Event: ${parts.join(', ')}');
  }

  void _handleAnalyticsEvent(UserpilotAnalytic event) {
    print('Analytics Event: ${event.analytic}, Value: ${event.value}');
  }

  void _handleNavigationEvent(UserpilotNavigation event) {
    print('Navigation Event URI: ${event.uri}');
    Uri uri = Uri.parse(event.uri);
    _processUri(uri);
  }

  // Process URI and handle navigation based on scheme and host
  void _processUri(Uri uri) {
    String scheme = uri.scheme;
    String host = uri.host;
```

--------------------------------

### GET /api/v1/analytics/exports/lookups/checklists

Source: https://docs.userpilot.com/api-references/endpoints/lookups/checklists

Retrieve a list of checklists (with tasks) available for export.

```APIDOC
## GET /api/v1/analytics/exports/lookups/checklists

### Description
Retrieve a list of checklists (with tasks) available for export.

### Method
GET

### Endpoint
/api/v1/analytics/exports/lookups/checklists

### Parameters
#### Headers
- **Authorization** (string) - Required - API authentication token in the format: `Token {{API_KEY}}`.

### Response
#### Success Response (200)
- **Array** (object) - A list of checklists (with tasks).

#### Response Example
[
  {
    "display_name": "Checklist A",
    "key": "checklist_a",
    "data_type": "string"
  }
]
```

--------------------------------

### window.userpilot.onUserpilotExperienceEvent

Source: https://docs.userpilot.com/developer/installation/mobile/cordova/callbacks

Registers a listener for experience and step lifecycle state changes.

```APIDOC
## window.userpilot.onUserpilotExperienceEvent(callback)

### Description
Triggered when an experience or a specific step within an experience changes state (e.g., Started, Completed, Dismissed).

### Parameters
- **callback** (function) - Required - Receives event data for `onExperienceStateChanged` or `onExperienceStepStateChanged`.
```

--------------------------------

### OpenAPI Specification for User Properties

Source: https://docs.userpilot.com/api-references/endpoints/lookups/user-properties

The OpenAPI definition for the GET /api/v1/analytics/exports/lookups/user_properties endpoint.

```yaml
openapi: 3.0.0
info:
  title: Userpilot API
  version: 1.0.0
  termsOfService: https://userpilot.io/terms-of-service/
  description: >-
    Userpilot's API suite for user identification, event tracking, data
    import/export, and user/company management.


    Authentication:
     All endpoints that require authentication expect an HTTP header in the following format:

     Authorization: Token {{API_KEY}}

    Example (cURL):
     curl -X GET 'https://appex.userpilot.io/v1/identify' \
       -H 'Authorization: Token abcd1234efgh5678' \
       -H 'Content-Type: application/json'

    Contact Support:
     Email: support@userpilot.com
  contact:
    name: Userpilot
    url: https://userpilot.io
    email: support@userpilot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://appex.userpilot.io
    description: Application endpoint
security: []
paths:
  /api/v1/analytics/exports/lookups/user_properties:
    get:
      summary: Get user properties
      description: Retrieve a list of user properties available for export.
      parameters:
        - $ref: '#/components/parameters/AuthorizationHeader'
      responses:
        '200':
          description: A list of user properties.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
              example:
                - id: 1
                  type: user_property
                  key: email
                  display_name: Email
                  data_type: string
                  is_auto_property: false
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      description: >-
        API authentication token in the format: `Token {{API_KEY}}`. Obtain your
        API key from the [Userpilot Environment
        Settings](https://run.userpilot.io/environment).
      schema:
        type: string
      example: Token abcd1234efgh5678
```
Tokens:
Raw