Skip to main content
The Android SDK is a Kotlin library distributed through JitPack. Add the JitPack repo, pull the dependency, then initialise the singleton from your Application subclass.

​
Requirements

  • Android SDK 23+ (Android 6.0 Marshmallow and later)
  • Java 17 toolchain
  • Kotlin (Java consumers work, but the API uses Kotlin’s suspend and default arguments)

​
Install

In your project’s settings.gradle, add the JitPack repo to dependencyResolutionManagement:
In your app module’s build.gradle, add the dependency:
Pin to the version range that suits your stability appetite. Check the JitPack page for the latest release tag.

​
Initialise

Subclass Application and call Spotzee.initialize from onCreate. Use a publishable key (pk_…); read Manage API keys for how to mint one.
Wire the subclass in your AndroidManifest.xml:
initialize returns the Spotzee instance. Stash it as a companion object (or inject through your DI framework) so other layers can call analytics.track(…), analytics.identify(…), and so on. To wire in-app notifications and deeplinks, also pass an InAppDelegate:
Read In-app notifications and deeplinks for the delegate contract.

​
What every request carries

The SDK adds these headers to every API call. You don’t set them yourself. The SDK’s Gson serialiser converts Kotlin camelCase property names to snake_case before sending, so Identity(externalId = …) lands as external_id on the wire.

​
Identity persistence

The SDK persists three values in SharedPreferences:
  • anonymousId: minted on first call, kept across app launches.
  • externalId: cached on the singleton after identify succeeds.
  • deviceId: a per-install UUID, used when registering for push.
Call analytics.reset() on sign-out to clear externalId and the persisted anonymous ID.

​
Errors

Failed requests return Result.failure(IOException(...)) with a one-line summary that includes the HTTP status, the API error code (when present), the message, and the request_id. The legacy { error: string } shape and the new RFC 7807 envelope are both parsed; quote request_id to support. track and register are fire-and-forget and don’t return failures to your code; check Logcat under the Spotzee tag for transient issues. identify, alias, getNotifications, and consume are suspend and surface results explicitly.

​
Debugging

Pass isDebug = true (or isDebug = BuildConfig.DEBUG) to Spotzee.initialize to flip the SDK’s HTTP logging to body level. Every request and response prints to Logcat under tag OkHttp so you can inspect payloads. Leave isDebug = false (the default) for production builds.

​
Next steps

Identify users

Link anonymous activity to a known user.

Track events

Send custom events with properties.

Push notifications

Register for FCM and route incoming pushes through the SDK.

In-app notifications and deeplinks

Render in-app dialogs and unwrap App Links.