# Android SDK Source: https://usefantasma.mintlify.app/mintlify/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](/mintlify/sdk-behavior) page. ## Install The Android build lives under: ```text theme={null} sdks/android ``` The library module is: ```text theme={null} :fantasma-sdk ``` Current build requirements: * Android `minSdk 26` * Java 17 * Kotlin 2.0.21 ## Usage ```kotlin theme={null} 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 = "", ), ) 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. # Flutter SDK Source: https://usefantasma.mintlify.app/mintlify/flutter-sdk Install and use the Fantasma Flutter SDK. # Fantasma Flutter SDK The Flutter SDK lives under `sdks/flutter/fantasma_flutter`. Shared ingest and queue behavior lives on the [SDK behavior](/mintlify/sdk-behavior) page. ## Public API * `FantasmaConfig(serverUrl, writeKey, storageNamespace, {localeProvider})` * `FantasmaClient(config)` * `track(eventName)` * `flush()` * `clear()` * `close()` ## Usage ```dart theme={null} import 'dart:ui'; import 'package:fantasma_flutter/fantasma_flutter.dart'; import 'package:flutter/widgets.dart'; final client = FantasmaClient( FantasmaConfig( serverUrl: 'http://10.0.2.2:8081', writeKey: '', storageNamespace: 'primary', localeProvider: () => WidgetsBinding.instance.platformDispatcher.locale, ), ); await client.track('app_open'); await client.flush(); await client.clear(); await client.close(); ``` ## Install The package name is: ```text theme={null} fantasma_flutter ``` The current package constraints are: * Dart `>=3.4.0 <4.0.0` * Flutter `>=3.22.0` The package is currently source-first in this repository rather than published to `pub.dev`. ## Flutter-Specific Notes * The package currently supports iOS and Android only. * Tracked events auto-populate `platform`, `device`, `app_version`, `os_version`, and `locale`. * `storageNamespace` is required and defines the client-local persistence boundary for the queue, install identity, and blocked-destination state. * Only one live `FantasmaClient` may use a given `storageNamespace` inside a process at a time. Reusing a namespace concurrently is rejected. * `localeProvider` is resolved when `track()` enqueues the event; queued rows keep that snapshot even if the app locale changes later. * In addition to the shared upload triggers, the SDK also attempts best-effort flushes when the app pauses or backgrounds. * Lifecycle-triggered and threshold-triggered flushes are best-effort background work and do not make `track()` surface upload failures. # Intro Source: https://usefantasma.mintlify.app/mintlify/index Privacy-first mobile analytics SDKs for iOS, Android, Flutter, and React Native. # Fantasma SDK Docs Fantasma is a self-hosted, privacy-first mobile analytics platform with a small, legible product surface. These docs cover the shipped client SDKs for iOS, Android, Flutter, and React Native. The SDKs share the same core ingest model: * events are queued durably before upload * uploads target `POST /v1/events` * write keys must be project-scoped `ingest` keys * runtime metadata such as platform, device, and locale is added automatically Choose your platform: * [Shared SDK behavior](/mintlify/sdk-behavior) * [iOS SDK](/mintlify/ios-sdk) * [Android SDK](/mintlify/android-sdk) * [Flutter SDK](/mintlify/flutter-sdk) * [React Native SDK](/mintlify/react-native-sdk) Fantasma keeps the public product surface narrow on purpose. This docs site is SDK-first for now; operator, deployment, and API reference docs remain in the repository until a later phase. # iOS SDK Source: https://usefantasma.mintlify.app/mintlify/ios-sdk Install and use FantasmaSDK for iOS and macOS. # Fantasma iOS SDK The iOS SDK sources live in `sdks/ios/FantasmaSDK`, and the repo root publishes them as the `FantasmaSDK` Swift package. ## Public API * `configure(serverURL:writeKey:) async throws` * `track(_:) async throws` * `flush() async throws` * `clear() async` ## Usage ```swift theme={null} import Foundation import FantasmaSDK let serverURL = URL(string: "http://localhost:8081")! Task { do { try await Fantasma.configure( serverURL: serverURL, writeKey: "" ) try await Fantasma.track("app_open") try await Fantasma.track("screen_view") try await Fantasma.flush() await Fantasma.clear() } catch { print("Fantasma SDK error: \(error)") } } ``` The SDK auto-populates `platform`, `device`, `app_version`, `os_version`, and `locale` for each event. Shared ingest and queue behavior lives on the [SDK behavior](/mintlify/sdk-behavior) page. ## Install Add `FantasmaSDK` from the repo root package URL: ```text theme={null} https://github.com/RuiAAPeres/fantasma.git ``` Then use: * Package: `FantasmaSDK` * Minimum version: your tagged release, for example `0.4.0` ```swift theme={null} dependencies: [ .package(url: "https://github.com/RuiAAPeres/fantasma.git", from: "0.4.0"), ] ``` For local development, you can also use an explicit path to this repository until you have tags available. ```swift theme={null} .package(path: "../fantasma"), ``` Supported platforms: * iOS 17.0+ * macOS 14.0+ ## iOS-Specific Notes * The SDK exposes a static `Fantasma` facade instead of an instance-based client. * iPhone emits `platform = "ios"`, `device = "phone"`. * iPad emits `platform = "ios"`, `device = "tablet"`. * Native macOS, Mac Catalyst, and iOS-on-Mac desktop-class runs emit `platform = "macos"`, `device = "desktop"`. * `track(_:)` throws when the SDK has not been configured. * `flush()` throws when the SDK has not been configured. * Reconfiguring to a different server URL or write key discards any still-queued rows after the current upload boundary, even across app relaunches, then switches future uploads to the new destination. * In addition to the shared upload triggers, the SDK also attempts uploads when the app enters background. # React Native SDK Source: https://usefantasma.mintlify.app/mintlify/react-native-sdk Install and use the Fantasma React Native SDK. # Fantasma React Native SDK The React Native SDK lives under `sdks/react-native/fantasma-react-native`. Shared ingest and queue behavior lives on the [SDK behavior](/mintlify/sdk-behavior) page. ## Public API * `new FantasmaClient({ serverUrl, writeKey })` * `track(eventName)` * `flush()` * `clear()` * `close()` ## Usage ```ts theme={null} import { FantasmaClient } from "fantasma-react-native"; const client = new FantasmaClient({ serverUrl: "https://api.usefantasma.com", writeKey: "", }); await client.track("app_open"); await client.flush(); await client.clear(); await client.close(); ``` ## Install The package name is: ```text theme={null} fantasma-react-native ``` Current packaging shape: * bare React Native support through native module files under `ios/` and `android/` * Expo-managed support through prebuild/dev-client only * no Expo Go support in v1 ## React Native-Specific Notes * The JS layer allows one live `FantasmaClient` per process at a time. * Config validation happens synchronously at construction time, while native configure/acquire happens on first use. * If first native acquire fails, that JS instance auto-closes and frees the slot immediately. * Destination switching remains supported by closing the current client and creating a new one with a different destination. * The native iOS and Android SDKs still own queue durability, built-in metadata, blocked-destination handling, and identity rotation. * React Native inherits the native `platform` and `device` mappings, including Apple desktop-class `platform = "macos"`, `device = "desktop"`. # SDK Behavior Source: https://usefantasma.mintlify.app/mintlify/sdk-behavior Shared ingest and runtime behavior across Fantasma mobile SDKs. # Shared SDK Behavior Fantasma's iOS, Android, Flutter, and React Native SDKs share one ingest contract and one core runtime model. The platform pages cover install and API shape; this page covers the behavior they have in common. ## Common Ingest Model * Events are queued durably before upload rather than sent inline. * Uploads target `POST /v1/events`. * Client apps must use project-scoped `ingest` write keys. * SDKs upload in JSON batches and treat `202 Accepted` as the success case. * Malformed successful responses are treated as invalid and leave queued rows in place. ## Upload Triggers All shipped SDKs attempt uploads: * every 30 seconds * when the queue reaches 100 events * when `flush()` is called Lifecycle-driven flush attempts are platform-specific in implementation, but the intent is the same: opportunistic background delivery rather than a delivery guarantee. ## Queue And Identity Semantics * Accepted events are deleted from the durable queue. * Failed or retryable uploads keep rows in the queue for later replay. * `clear()` rotates the future install identity without rewriting already queued rows. * Each SDK auto-populates built-in metadata such as timestamp, install id, platform, device, app version, OS version, and locale. * `platform` is the coarse OS family. `device` is the coarse form factor. * Apple SDKs emit `platform=macos`, `device=desktop` for native macOS, Mac Catalyst, and iOS-on-Mac desktop-class runs. * Android-class mobile SDKs emit `platform=android` with `device=phone` or `device=tablet`, and fall back to `device=unknown` when the runtime cannot classify device form factor. ## Blocked And Retryable Destinations The shared destination model is: * `401`, `422`, and `409 project_pending_deletion` block the current destination * transport failures, `500`, and unrelated `409` responses remain retryable Once a destination is blocked, the SDK requires a different destination configuration before it resumes sending events there. ## Platform-Specific Notes See each platform page for the details that differ by client: * [iOS SDK](/mintlify/ios-sdk) * [Android SDK](/mintlify/android-sdk) * [Flutter SDK](/mintlify/flutter-sdk) * [React Native SDK](/mintlify/react-native-sdk) # useFantasma Source: https://usefantasma.mintlify.app/mintlify/usefantasma Hosted Fantasma setup and managed endpoint guidance. # Intro [useFantasma](https://usefantasma.com) is the hosted Fantasma product. It gives you the Fantasma API and dashboard without running the stack yourself. You can see it in the [live demo](https://usefantasma.com/demo). ## How To Use It When setting up your SDK, use the hosted API base URL and the project-scoped ingest key: ```swift Swift theme={null} import Foundation import FantasmaSDK let serverURL = URL(string: "https://api.usefantasma.com")! try await Fantasma.configure( serverURL: serverURL, writeKey: "" ) ``` ```kotlin Android theme={null} import com.fantasma.sdk.FantasmaClient import com.fantasma.sdk.FantasmaConfig val client = FantasmaClient( context = applicationContext, config = FantasmaConfig( serverUrl = "https://api.usefantasma.com", writeKey = "", ), ) ``` ```dart Flutter theme={null} import 'package:fantasma_flutter/fantasma_flutter.dart'; final client = FantasmaClient( FantasmaConfig( serverUrl: 'https://api.usefantasma.com', writeKey: '', storageNamespace: 'primary', ), ); ```