How do I install the Android SDK?

Short answer

Register your app's applicationId under App analytics › Configuration › SDK code, add implementation("com.tapcub:android:0.1.1") to your app module, call TapCub.preInit(this, TapCubConfig(siteKey = "YOUR_SITE_KEY")) in Application.onCreate, and call TapCub.init() once the user has accepted your privacy policy. Launches, Activity screens, clicks and crashes are then collected automatically. Check App analytics › Overview › Realtime for the first $app_start.

The SDK is written in Kotlin and callable from Java, needs minSdk 21, declares only the INTERNET permission and has no AndroidX dependency.

1. Register the app identifier

Open App analytics › Configuration › SDK code and click Add app identifier. Enter your Android applicationId, for example com.example.shop. The SDK sends it with every upload, and data from an identifier that is not registered is dropped silently. The page also prints an install snippet with your site key filled in.

2. Add the dependency

In app/build.gradle.kts:

dependencies {
    implementation("com.tapcub:android:0.1.1")
}

The package is on Maven Central. If the snippet in the console prints different coordinates, use those. ProGuard / R8 rules ship inside the AAR, so you do not need to add any.

3. Initialize

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        TapCub.preInit(this, TapCubConfig(siteKey = "YOUR_SITE_KEY"))
    }
}

// after the user accepts the privacy policy
TapCub.init()

• preInit only stores the config and binds the lifecycle: no collection, no device reads, no network. It must run in Application.onCreate, otherwise the cold start and the first screen are lost.
• init starts collection. Call it after consent; if your app does not need a consent step, call it right after preInit.
• appId, appVersion and appBuild default to the package name, versionName and versionCode. appId must match the identifier you registered.
• For China mode, set region = "cn", call init after consent and then TapCub.grantConsent(listOf("analytics")).

All calls return immediately from any thread; work runs on the SDK's own worker thread.

4. What is collected automatically

Fragments, Jetpack Compose screens and dialogs are not captured automatically: call TapCub.trackScreen("Home") when they appear. See Track screen views.

5. Send events and identify users

TapCub.track("purchase", mapOf("revenue" to 19.9, "currency" to "USD"))

TapCub.login("USER_ID")            // after sign-in
TapCub.setProps(mapOf("plan" to "pro"))
TapCub.logout()                    // on sign-out

login is ignored when the project is not in identified mode; events still flow. See Identify users.

6. Verify

Run the app on a device or emulator and open App analytics › Overview › Realtime. A start event should appear within seconds. If nothing arrives, check the points below.

Privacy and storage

The event queue is stored in SQLite (8 MB, 10,000 events or 7 days by default), survives restarts and retries with backoff. The device ID is based on ANDROID_ID; no IMEI, MAC, OAID or advertising ID is read. For the Google Play data safety form, declare device or other IDs, app interactions, crash logs and diagnostics.

Troubleshooting

• No data at all: the applicationId is not registered, or init was never called (for example, consent was not given).
• Cold start missing: preInit runs later than Application.onCreate.
• Screens missing: Fragment or Compose screens need trackScreen.
• App crashes at start with siteKey required: the site key is empty.
• Stop collection for a user: call TapCub.optOut(); optIn() resumes.

Related

• Install the iOS SDK
• Crash-free rate
• Track app versions
• What is an SDK? Meaning, SDK vs API, and how analytics SDKs work
• Device ID
• Install on Flutter
• Install on React Native
• Install on HarmonyOS