Kotlin / Android

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

The Helion Kotlin SDK allows you to track user behavior in your Kotlin applications.

Looking for a step-by-step tutorial? Check out the Kotlin analytics guide.

Installation

This package is not yet published and cannot be installed via a package manager.

Step 1: Add Dependency

Add the Helion SDK to your project's dependencies:

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

Step 2: Initialize

Import and initialize the SDK with your client credentials:

import dev.helion.Helion

val hl = Helion.create(
    context,
    Helion.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 helion 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 called before each event. Return false to suppress the event.
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 hl = Helion.create(
    context,
    Helion.Options(
        clientId = "YOUR_CLIENT_ID",
        filter = { payload ->
            // Return false to suppress the event
            true
        }
    )
)

Usage

Tracking Events

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

Identifying Users

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

Setting Global Properties

Properties set here are merged into every subsequent track() call.

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

Incrementing Properties

Increment a numeric property on a user profile:

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

Decrementing Properties

Decrement a numeric property on a user profile:

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

Clearing User Data

clear() resets the current user profile, device identity, and session:

hl.clear()

Advanced Usage

Custom Event Filtering

val hl = Helion.create(
    context,
    Helion.Options(
        clientId = "YOUR_CLIENT_ID",
        filter = { payload ->
            // Return false to suppress the event
            true
        }
    )
)

Disabling Tracking

Disable all tracking for local development or testing — no HTTP calls are made:

val hl = Helion.create(
    context,
    Helion.Options(
        clientId = "YOUR_CLIENT_ID",
        disabled = true
    )
)

Automatic Tracking

When automaticTracking is enabled, the SDK automatically tracks app_opened and app_closed lifecycle events:

val hl = Helion.create(
    context,
    Helion.Options(
        clientId = "YOUR_CLIENT_ID",
        automaticTracking = true
    )
)

System Information

The SDK automatically captures and attaches system metadata to every event:

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

Thread Safety

The Helion SDK is designed to be thread-safe. Its methods can be called from any thread without additional synchronization.

Support

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

Common options

On this page