# Android SDK Official Android client SDK - Kotlin, minSdk 21, zero third-party runtime dependencies. The API mirrors the Mixpanel Android SDK, so migrating is mostly a find-and-replace of MixpanelAPI to Cohorly. ## Install Distributed via JitPack from the public `cohorly-io/cohorly-android` repository: ```kotlin // settings.gradle.kts dependencyResolutionManagement { repositories { google(); mavenCentral() maven("https://jitpack.io") } } // app/build.gradle.kts dependencies { implementation("com.github.cohorly-io.cohorly-android:cohorly-android:v0.1.0") } ``` The host app must declare the `INTERNET` permission. ## Initialize Call `Cohorly.getInstance` once, e.g. in `Application.onCreate()`. One instance per project token. ```kotlin import com.cohorly.android.Cohorly val cohorly = Cohorly.getInstance(context, "YOUR_PROJECT_TOKEN") cohorly.track("Plan Selected", mapOf("plan" to "pro")) cohorly.identify("user-123") // links the anonymous id via /alias cohorly.people.set("plan", "pro") // profile update via /engage cohorly.registerSuperProperties(mapOf("ab_test" to "variant_b")) cohorly.flush() // also auto-flushes every 5s / 20 events ``` ## API | Member | Notes | | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `Cohorly.getInstance(context, token, apiHost[, config])` | Singleton per token. `CohorlyConfig` accepts `flushIntervalMs`, `batchSize`, `maxQueueSize`, `trackAutomaticEvents`. | | `track(name[, JSONObject \| Map])` | Queue an event (persisted to SharedPreferences). | | `identify(id)` / `reset()` | Set the distinct id (sends /alias while anonymous) / new anonymous id on logout. | | `registerSuperProperties[Once] / unregisterSuperProperty / clearSuperProperties` | Super properties merged into every event. | | `people.set / setOnce / increment / unset / deleteUser` | Profile updates sent to /engage. | | `optOutTracking() / optInTracking()` | GDPR opt-out; drops queued events while opted out. | | `flush()` | Send now, bypassing any retry backoff window. | | `getFeatureFlag(key[, fallback])` / `isFeatureEnabled(key[, fallback])` | Read a flag's variant/enabled value; never hits the network. | | `getFeatureFlagDetails(key[, fallback])` | The value plus `source` (`network` / `persistence` / `fallback`) and cache metadata. | | `reloadFeatureFlags()` / `onFeatureFlags(listener)` | Re-evaluate flags on the worker thread / subscribe to updates. | ## Feature flags Flags are evaluated on `getInstance` (opt out with `CohorlyConfig(loadFeatureFlags = false)`), on `identify()` and on `reset()`, always on the worker thread, and persisted to storage scoped by distinct id; reads never hit the network. `CohorlyConfig.flagPersistence` (default `FlagPersistenceMode.persistenceUntilNetworkSuccess`) controls how reads resolve against the persisted cache: | Policy | Behavior | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `networkOnly` | Never reads nor writes the cache on the serving path (identity changes still remove it - that is hygiene, not serving). Flags come only from network responses this session; a failed evaluation serves the fallback. | | `networkFirst` | Prefers the network, but reads are synchronous, so a valid cache (inside the TTL) is served immediately like `persistenceUntilNetworkSuccess`. Strict about freshness: a cache past the TTL is dropped, never served. | | `persistenceUntilNetworkSuccess` | Serves a valid cache immediately, so startup doesn't flicker; the first network success takes over and re-persists. A failed evaluation keeps the cache serving. Trades freshness for offline availability: an expired cache still serves while inside `CohorlyCore.FLAG_CACHE_MAX_STALE_MS` (7 days). | The cache carries a `stored_at` timestamp and expires after `CohorlyConfig.flagCacheTtlMs` (default **24 hours** - the Mixpanel reference default shared by every Cohorly SDK). A legacy cache with no timestamp cannot be dated, so it is served indefinitely rather than expired - the graceful-upgrade path preserving the pre-TTL behavior - until the next successful reload rewrites it in the stamped format. `identify()` and `reset()` clear the previous identity's flags before fetching the new identity's, so values never leak across users - `onFeatureFlags` listeners are notified of the clear with an empty map, then again when the new identity's flags land. ```kotlin val variant = cohorly.getFeatureFlag("checkout-copy", fallback = "control") val details = cohorly.getFeatureFlagDetails("checkout-copy") // details.source: FlagSource.network | .persistence | .fallback // details.enabled / details.payload; a fallback result reports // enabled = truthiness of the fallback and payload = null // details.persistedAt / details.ttlMs when source == FlagSource.persistence ``` A read that resolves to the fallback reports no exposure. Reads of known flags emit `$feature_flag_called` once per (key, value) per identity, stamped with `$feature_flag_source` (`"network"` or `"persistence"`) plus `$feature_flag_persisted_at` and `$feature_flag_ttl_ms` for persistence reads; the same value served first from persistence and then from the network is reported once. ## Auto-captured properties Every event includes `$lib` = `"android"`, `$lib_version`, `$os`, `$os_version`, `$manufacturer`, `$brand`, `$model`, `$screen_dpi`, `$screen_height`, `$screen_width`, `$app_version_string`, `$app_build_number`, `$carrier`, `$has_nfc`, `$has_telephone`, `$bluetooth_version` and `$google_play_services`. `$wifi` and `$bluetooth_enabled` are only collected when the app holds the corresponding permission. Geo properties are derived server-side from the client IP. ## Automatic events Opt-in via `trackAutomaticEvents = true` (default off, matching the iOS and React Native SDKs): `$ae_first_open` (once ever), `$ae_updated` (on version change) and `$ae_session` with `$ae_session_length` when the app backgrounds after a session of 10s or more. The offline queue survives process death (SharedPreferences, capped at 1000 events, oldest dropped) and follows the shared Cohorly retry contract: exponential backoff on 429/5xx/network errors honoring `Retry-After`, batch halving on 413, permanent drop on 400.