Kotlin / Android

The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin and Android applications.

The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin applications. This guide provides instructions for installing and using the Kotlin SDK in your project.

Installation

This package is not yet published. So you cannot install it with gradle yet.

Step 1: Add Dependency

Add the OpenPanel SDK to your project's dependencies:

dependencies {
    implementation 'dev.openpanel:openpanel:0.0.1'
}

Step 2: Initialize

First, import the SDK and initialize it with your client ID:

import dev.openpanel.OpenPanel
 
val op = OpenPanel.create(
    context,
    OpenPanel.Options(
        clientId = "YOUR_CLIENT_ID",
        clientSecret = "YOUR_CLIENT_SECRET"
    )
)

Configuration Options

`context`

Type: Context
Required: Yes
Description: Android Context used for initializing the SDK.

`Options`

Common options

apiUrl - The url of the openpanel API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Additional Kotlin-specific options:

filter - A function that will be called before tracking an event. If it returns false, the event will not be tracked
disabled - Set to true to disable all event tracking
automaticTracking - Set to true to automatically track app lifecycle events
verbose - Set to true to enable verbose logging

Filter Example

val op = OpenPanel.create(
    context,
    OpenPanel.Options(
        clientId = "YOUR_CLIENT_ID",
        filter = { payload ->
            // Your custom filtering logic here
            true // or false to filter out the event
        }
    )
)

Usage

Tracking Events

To track an event:

op.track("button_clicked", mapOf("button_id" to "submit_form"))

Identifying Users

To identify a user:

op.identify("user123", mapOf(
    "firstName" to "John",
    "lastName" to "Doe",
    "email" to "john@example.com",
    "customAttribute" to "value"
))

Setting Global Properties

To set properties that will be sent with every event:

op.setGlobalProperties(mapOf(
    "app_version" to "1.0.2",
    "environment" to "production"
))

Incrementing Properties

To increment a numeric property on a user profile:

op.increment("user123", "login_count", 1)

Decrementing Properties

To decrement a numeric property on a user profile:

op.decrement("user123", "credits", 5)

Clearing User Data

To clear the current user's data:

op.clear()

Advanced Usage

Custom Event Filtering

You can set up custom event filtering:

val op = OpenPanel.create(
    context,
    OpenPanel.Options(
        clientId = "YOUR_CLIENT_ID",
        filter = { payload ->
            // Your custom filtering logic here
            true // or false to filter out the event
        }
    )
)

Disabling Tracking

You can temporarily disable tracking:

val op = OpenPanel.create(
    context,
    OpenPanel.Options(
        clientId = "YOUR_CLIENT_ID",
        disabled = true
    )
)

Automatic Tracking

The SDK can automatically track app lifecycle events if automaticTracking is set to true. This will track "app_opened" and "app_closed" events:

val op = OpenPanel.create(
    context,
    OpenPanel.Options(
        clientId = "YOUR_CLIENT_ID",
        automaticTracking = true
    )
)

System Information

The SDK automatically gathers system information and adds it to the properties of every tracking event. This includes:

OS details (e.g., os, os_version)
Device manufacturer, brand, and model (e.g., manufacturer, brand, model)
Screen resolution and DPI (e.g., screen_width, screen_height, screen_dpi)
App version (e.g., app_version, app_build_number)
Network details (e.g., wifi, carrier, bluetooth_enabled)

Thread Safety

The OpenPanel SDK is designed to be thread-safe. You can call its methods from any thread without additional synchronization.

Support

For any issues or feature requests, please file an issue on our GitHub repository.

Common options

On this page