---
title: Kotlin / Android
description: The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin and Android applications.
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';

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.

<Callout>
Looking for a step-by-step tutorial? Check out the [Kotlin analytics guide](/guides/kotlin-analytics).
</Callout>

## Installation

<Callout type="warn">
This package is not yet published. So you cannot install it with `` yet.
</Callout>

<Steps>
### 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:

```kotlin
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`

<CommonSdkConfig />

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

```kotlin
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
        }
    )
)
```

</Steps>

## Usage

### Tracking Events

To track an event:

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

### Identifying Users

To identify a user:

```kotlin
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:

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

### Incrementing Properties

To increment a numeric property on a user profile:

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

### Decrementing Properties

To decrement a numeric property on a user profile:

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

### Clearing User Data

To clear the current user's data:

```kotlin
op.clear()
```

## Advanced Usage

### Custom Event Filtering

You can set up custom event filtering:

```kotlin
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:

```kotlin
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:

```kotlin
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

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

## Support

For any issues or feature requests, please file an issue on our [GitHub repository](https://github.com/Openpanel-dev/openpanel/issues).