Android SDK quickstart

From a fresh Crossdeck account to your first Android event landing in the dashboard in under ten minutes. One Gradle dependency, two values to paste, one Crossdeck.start(...) call inside your Application.

Before you start

You'll need:

• A Crossdeck account with a project created (if you don't have one, start free — no credit card).
• Android Studio Hedgehog (2023.1) or later. Check via Android Studio menu → About Android Studio.
• An Android app project with minSdk 21 or higher (Android 5.0 Lollipop, ~99% of active devices). Check via app/build.gradle.kts → android { defaultConfig { minSdk = 21 } }. The SDK uses no API-version-conditional code; one binary serves every supported device.
• Kotlin 1.9+ and Java 17 toolchains. Check Kotlin via top-level build.gradle.kts → plugins block → id("org.jetbrains.kotlin.android") version "…". AGP 8.x ships both as defaults.
• About 10 minutes.

You don't need a Google Play Console account or a published listing to send your first event — the emulator or a USB-connected device works fine. Google Play rail connection comes later, in rail-webhooks.

Step 1 · Find your appId and publishable key

Crossdeck identifies your Android app with two values:

Where to find them

1. Open the Crossdeck dashboard and select your project from the workspace switcher (top-left).
2. From the left sidebar, click Developers, then API keys. The direct path is /dashboard/developers/api-keys/.
3. The page lists your apps. If you haven't added an Android app yet, click + Add app and pick Android. Each app card shows the appId at the top and two publishable keys below — one test, one live. Click the copy icon next to either to copy it to your clipboard.

Step 2 · Find your Android applicationId

When you add an Android app in the Crossdeck dashboard, you'll be asked for its applicationId — the globally-unique reverse-DNS name that identifies your app on Google Play (com.acme.notes, com.spotify.music). Crossdeck uses it to attribute Google Play purchases and developer notifications to the right app inside your project.

How to find it in Android Studio

1. Open your project in Android Studio.
2. In the Project view (left sidebar, switch the dropdown to Android if it isn't already), open Gradle Scripts → build.gradle.kts (Module: app). If you're on Groovy DSL, it's build.gradle (Module: app).
3. Inside the android { defaultConfig { } } block, find the applicationId line — usually shaped like applicationId = "com.yourcompany.yourapp".

If you have product flavors or build variants (debug, release, paid, free)

Flavors and the debug suffix can produce different applicationIds at install time — e.g. com.acme.notes.debug for debug builds, com.acme.notes for release. Use the release applicationId (no suffix) for the Crossdeck app entry. If you want telemetry from debug and release routed to separate Crossdeck apps, create two Crossdeck app entries and pick the right key in your build script with BuildConfig.DEBUG.

If you can't find Android Studio (or want the answer from the command line)

grep applicationId app/build.gradle.kts
# or, on Groovy DSL:
grep applicationId app/build.gradle

Step 3 · Add the Gradle dependency

The SDK ships from Maven Central as com.crossdeck:crossdeck:1.+ — a single AAR with one import.

Kotlin DSL (build.gradle.kts)

// settings.gradle.kts — confirm mavenCentral is in the resolution list
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.crossdeck:crossdeck:1.+")
}

Groovy DSL (build.gradle)

// app/build.gradle
dependencies {
    implementation 'com.crossdeck:crossdeck:1.+'
}

Sync Gradle (Android Studio offers a "Sync Now" banner the moment you save). After sync, import com.crossdeck.Crossdeck resolves and brings the entire public API into scope.

Step 4 · Create the Application class

The SDK should start exactly once per process, before any UI code runs. The standard Android idiom is a subclass of android.app.Application overriding onCreate.

If you already have an Application subclass, skip to Step 5 — you just need to add the Crossdeck.start(...) call. If you don't, create one now:

1. In Project → app → java → com.yourcompany.yourapp (or wherever your package root is), right-click → New → Kotlin Class/File.
2. Name it MyApplication and pick Class.
3. Make it extend Application:

   package com.yourcompany.yourapp
   
   import android.app.Application
   
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           // Crossdeck.start goes here — Step 5.
       }
   }

4. Wire it into your AndroidManifest.xml by adding the android:name attribute to the <application> tag:

   <!-- app/src/main/AndroidManifest.xml -->
   <application
       android:name=".MyApplication"
       android:label="@string/app_name"
       …>
       …
   </application>

Step 5 · Initialise the SDK

Call Crossdeck.start(context, options) exactly once inside Application.onCreate. Wrap the call in try/catch and store the client as nullable — a typo'd key should log + degrade telemetry, never crash a customer's launch.

package com.yourcompany.yourapp

import android.app.Application
import android.util.Log
import com.crossdeck.Crossdeck
import com.crossdeck.CrossdeckError
import com.crossdeck.CrossdeckOptions
import com.crossdeck.Environment

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Build-configuration switch — Debug never embeds a live key,
        // Release never routes events into the sandbox.
        val publicKey = if (BuildConfig.DEBUG) "cd_pub_test_…" else "cd_pub_live_…"
        val env = if (BuildConfig.DEBUG) Environment.SANDBOX else Environment.PRODUCTION

        crossdeck = try {
            Crossdeck.start(
                this,
                CrossdeckOptions(
                    appId = "app_android_92b2d6a5728a4d",
                    publicKey = publicKey,
                    environment = env,
                ),
            )
        } catch (e: CrossdeckError) {
            // invalid_secret_key / env_mismatch / missing_app_id —
            // recoverable misconfig. Log + carry on without telemetry.
            Log.e("Crossdeck", "start failed (${e.code}): ${e.message}", e)
            null
        } catch (e: Throwable) {
            Log.e("Crossdeck", "start failed", e)
            null
        }
    }

    companion object {
        // Process-singleton accessor. Reach from anywhere as
        // \`MyApplication.crossdeck?.…\` — no
        // \`(applicationContext as MyApplication).cd\` boilerplate.
        var crossdeck: Crossdeck? = null
            private set
    }
}

Reach the client from anywhere as MyApplication.crossdeck?.…:

// Track an event
MyApplication.crossdeck?.track("paywall_seen", mapOf("variant" to "annual"))

// Synchronous paywall gate (safe from the UI thread)
if (MyApplication.crossdeck?.isEntitled("pro") == true) {
    showProUI()
} else {
    showPaywall()
}

android {
    buildFeatures {
        buildConfig = true
    }
}

Step 6 · Identify your user

Until you call identify(...), every event carries an anonymous ID minted on first launch and persisted via SharedPreferences. The moment you know who the user is — after sign-in — call identify with your app's user ID. The SDK rotates the anonymous events onto the identified person automatically.

MyApplication.crossdeck?.identify("user_847")

// When the user signs out
MyApplication.crossdeck?.reset()

The userId is whatever your app uses — the database primary key, the Firebase Auth UID, the Google account ID. Stable for the lifetime of the account.

Want the People feed to show real names instead of anon_xxx? identify also takes optional email and traits — see Identify users for the full signature.

Step 7 · Verify the heartbeat

Build and run your app on an emulator or USB-connected device. The SDK fires its boot heartbeat the moment start returns. Open Developers → Heartbeat in the dashboard to confirm.

The page shows a per-app SDK signal audit:

• Last seen — should show "a few seconds ago" after you launch the app.
• SDK version — the version string the SDK stamped on its events. Confirms which build is live.
• Recent events — live tail of the last events received. You should see session.started within a few seconds, then screen.viewed events as you navigate through Activities and Fragments.

If nothing shows up after 30 seconds

What's next

Heartbeat green? The SDK is live. From here:

• Identify users — pass traits (email, plan, signup date) so the People feed renders real names instead of anon_xxx.
• Track custom events — cd.track("paywall_seen", mapOf("variant" to "annual")) for the conversion events that matter to you.
• Entitlements & gating — gate pro features with one line: if (cd.isEntitled("pro")) { … }.
• Connect Google Play — start verifying Play Billing purchases and computing MRR from Google Play subscriptions.
• Full Android SDK reference — every method, every option, every event the SDK fires automatically.