# Native Android / Kotlin

Download [Submetry.kt](https://submetry.com/sdk/Submetry.kt) into your app under package `com.submetry` (or adjust the package locally). This source adapter uses Android SharedPreferences, `org.json`, a single background executor and `HttpURLConnection`. There is no Maven artifact and no third-party networking/storage dependency.

## Configure

Declare `android.permission.INTERNET` in the app manifest, then initialize once from your application setup:

```kotlin
import com.submetry.Submetry
import org.json.JSONObject

val telemetry = Submetry(
    context = applicationContext,
    appId = "YOUR_APP_ID",
    publicKey = "YOUR_PUBLIC_SUB_PK_KEY",
    userId = actualFinancialProviderUserId,
    environment = if (BuildConfig.DEBUG) "debug" else "production",
    extraContext = mapOf("app_version" to appVersion, "build" to buildNumber),
    onError = { message -> Log.w("Submetry", message) }
)
telemetry.onboardingStep(1, "goal")
telemetry.onboardingCompleted()
telemetry.track("activation_completed")
telemetry.paywallShown("onboarding")
telemetry.track("generation_completed", JSONObject().put("style", "kinetic"))
```

The anonymous installation identity and first-open marker persist in app-private preferences. Configuration emits `first_open` once plus the initial `session_start` / `app_open`. Call `startSession()` for later application foreground transitions and `flush()` when backgrounding. Avoid reconfiguring in each Activity. Calls return Futures; disk commits and uploads run on the background executor. Error callbacks run there too; dispatch any UI changes to the main thread.

## Identity and purchase events

If RevenueCat or Superwall is installed, configure it first and pass its actual app-user identity to Submetry. Call `identify(newId)` after successful identity changes. Record `trial_started` and `purchase_completed` only from a confirmed transaction, with product/plan properties. Use the separate provider webhook for revenue, refunds and lifecycle metrics.

## Persistence and retry

The adapter persists events before upload using `SharedPreferences.commit()` on its executor. Batches contain up to 20 events with stable IDs. Failures retain queued events, with exponential delays up to five minutes and eight consecutive automatic retries. `flush()` or a new launch retries again. Permanently invalid payloads are archived in the same private preferences under `rejected`; they are not silently discarded. Corrupt queues abort initialization so saved data can be recovered. Keep one active instance per app; call `stop()` when retiring it.

The adapter attaches the actual Android model, OS, locale and timezone. No advertising ID is collected. Its Kotlin source compiled with Kotlin 2.0.21 against Android API 35 in this workspace. Emulator and physical-device runtime behavior remains unverified. Build it with your application, verify lifecycle transitions and HTTP 202, then inspect Events/Journeys in the matching environment. Financial data needs [RevenueCat](https://submetry.com/docs/revenuecat.md) or [Superwall](https://submetry.com/docs/superwall.md).
