Skip to main content

​
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.