Android SDK

Install and use FantasmaSDK for Android.

Fantasma Android SDK

FantasmaSDK for Android is the Android-first Kotlin client for Fantasma’s event ingest API.

Android parity is at the event-contract and runtime-behavior level, not the exact public API shape. The iOS SDK exposes a static Fantasma facade; Android uses an instance-based FantasmaClient API because that fits Android and Kotlin usage better.

Shared ingest and queue behavior lives on the SDK behavior page.

Install

The Android build lives under:

sdks/android

The library module is:

:fantasma-sdk

Current build requirements:

• Android minSdk 26
• Java 17
• Kotlin 2.0.21

Usage

import android.app.Application
import com.fantasma.sdk.FantasmaClient
import com.fantasma.sdk.FantasmaConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class DemoApplication : Application() {
    private lateinit var fantasma: FantasmaClient

    override fun onCreate() {
        super.onCreate()
        fantasma = FantasmaClient(
            context = this,
            config = FantasmaConfig(
                serverUrl = "http://10.0.2.2:8081",
                writeKey = "<ingest-key-from-provision-project>",
            ),
        )

        CoroutineScope(Dispatchers.Main).launch {
            fantasma.track("app_open")
        }
    }
}

Public API

• FantasmaClient(context, FantasmaConfig(serverUrl, writeKey))
• track(eventName)
• flush()
• clear()
• close()

track() and flush() are suspend functions and throw typed FantasmaException failures. close() is idempotent, and any later track(), flush(), or clear() call on that closed client throws FantasmaException.ClosedClient.

Android-Specific Notes

• Android uses an instance-based FantasmaClient API rather than a static facade.
• The SDK auto-populates platform = "android", device, app_version, os_version, and locale.
• device emits phone, tablet, or unknown from the Android runtime form-factor snapshot.
• track() and flush() are suspend functions and throw typed FantasmaException failures.
• close() is idempotent, and any later track(), flush(), or clear() call on that closed client throws FantasmaException.ClosedClient.
• In addition to the shared upload triggers, the SDK also attempts uploads when the app enters background.
• The SDK persists one app-local install identifier, reuses it across destinations, and rotates it on clear() without mutating already queued rows.
• Clients created with the same normalized destination share one process-local runtime.
• Creating a client with a different normalized destination supersedes the previously active destination for the process after the current upload boundary, matching the Swift SDK’s single-destination behavior.
• Older Android client handles should be treated as replaced once a different destination is created; future track(), flush(), and clear() calls on a superseded handle throw FantasmaException.ClosedClient, and the superseded runtime retires itself without requiring an explicit close() on the old handle.