Android SDK (Kotlin)

The Datafly Signal Android SDK is a native Kotlin library that captures events on-device and delivers them to your Signal pipeline. It has zero external dependencies and uses only Android framework APIs.

Requirements

Android API 21+ (Lollipop)
Kotlin 1.9+ or Java 11+
Android Gradle Plugin 8.0+

Installation

Gradle (recommended)

Add the dependency to your app’s build.gradle.kts:

dependencies {
    implementation("com.datafly:signal:1.0.0")
}

Or in Groovy (build.gradle):

dependencies {
    implementation 'com.datafly:signal:1.0.0'
}

Maven

<dependency>
    <groupId>com.datafly</groupId>
    <artifactId>signal</artifactId>
    <version>1.0.0</version>
</dependency>

Initialisation

Initialise the SDK in your Application class:

import android.app.Application
import com.datafly.signal.Datafly
import com.datafly.signal.DataflyConfig
 
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
 
        val config = DataflyConfig(
            pipelineKey = "dk_live_abc123",
            endpoint = "https://data.example.com"
        )
        Datafly.initialize(this, config)
    }
}

Make sure your Application class is registered in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ...>

Quick start

// Track a screen view
Datafly.screen("Home")
 
// Track a custom event
Datafly.track("add_to_cart", mapOf(
    "item_id" to "SKU-001",
    "item_name" to "Running Shoes",
    "price" to 79.99,
    "currency" to "GBP"
))
 
// Identify a user after login
Datafly.identify("user-123", mapOf(
    "email" to "[email protected]",
    "name" to "Jane Doe",
    "plan" to "professional"
))
 
// Associate with a company
Datafly.group("company-456", mapOf(
    "name" to "Acme Corp",
    "plan" to "enterprise"
))
 
// Handle a deep link (extracts UTM params and click IDs)
Datafly.handleDeepLink(intent.data!!)
 
// Set Google Advertising ID after consent
Datafly.setAdvertisingId(advertisingId, enabled = true)
 
// Force flush
Datafly.flush()
 
// Logout -- generates new anonymous ID
Datafly.reset()

Device identifiers

The Android SDK automatically collects:

Identifier	Source	Persistence	Permission required
Anonymous ID	UUID v4, SDK-generated	SharedPreferences	None
Android ID	`Settings.Secure.ANDROID_ID`	System-managed	None
Device model	`Build.MODEL`	N/A	None
AAID	Set via `setAdvertisingId()`	Memory	User consent

ANDROID_ID is scoped per app signing key since Android 8.0 (Oreo). It persists across app reinstalls as long as the app is signed with the same key, providing stable device identity without requiring additional permissions.

⚠️

Unlike iOS, SharedPreferences data is lost on app reinstall. However, the server-side device recognition system can re-identify the device using a fingerprint hash (IP + User Agent + screen + locale + timezone), linking the new anonymous ID back to the existing canonical identity.

App lifecycle events

When trackAppLifecycle is enabled (default), the SDK automatically tracks:

Event	When	Properties
`Application Installed`	First launch after install	`version`, `build`
`Application Updated`	First launch after app update	`version`, `build`, `previous_version`, `previous_build`
`Application Opened`	App enters foreground	`version`, `build`, `from_background`
`Application Backgrounded`	App enters background	—

The SDK uses ActivityLifecycleCallbacks to detect foreground/background transitions without requiring AndroidX Lifecycle dependencies.

ProGuard / R8

The SDK ships with consumer ProGuard rules that are automatically applied when your app enables code shrinking. No additional configuration is needed.

Configuration reference

Property	Type	Default	Description
`pipelineKey`	`String`	Required	Your source pipeline key
`endpoint`	`String`	Required	Your Ingestion Gateway URL
`flushIntervalSeconds`	`Int`	`30`	Seconds between automatic flushes
`flushThreshold`	`Int`	`20`	Events queued before automatic flush
`maxQueueSize`	`Int`	`1000`	Maximum events stored locally
`sessionTimeoutSeconds`	`Int`	`1800`	Seconds of inactivity before new session (30 min)
`trackAppLifecycle`	`Boolean`	`true`	Automatically track install/update/open/background
`debug`	`Boolean`	`false`	Enable debug logging to Logcat

Debug mode

Enable debug logging to see SDK activity in Logcat (tag: DataflySignal):

val config = DataflyConfig(
    pipelineKey = "dk_live_abc123",
    endpoint = "https://data.example.com",
    debug = true
)

You can also attach an event inspector callback:

Datafly.onEvent = { eventMap ->
    Log.d("Datafly", "Event queued: $eventMap")
}

Next steps

track() — record custom events
screen() — record screen views
identify() — link anonymous users to known identities
Identity & Device IDs — understand how identity works on Android
Offline & Batching — how events are queued and delivered

iOS (Swift)React Native