怎么安装 Android SDK？

简短回答

在 应用统计 › 配置 › SDK 代码 登记应用的 applicationId，在 App 模块里加 implementation("com.tapcub:android:0.1.1")，在 Application.onCreate 里调用 TapCub.preInit(this, TapCubConfig(siteKey = "YOUR_SITE_KEY"))，用户同意隐私政策后再调用 TapCub.init()。之后启动、Activity 页面、点击和崩溃都会自动采集。到 应用统计 › 概览 › 实时 看头一条 $app_start。

SDK 用 Kotlin 编写，Java 也能调用；最低 minSdk 21，只声明 INTERNET 权限，不依赖 AndroidX。

1. 登记应用标识

打开 应用统计 › 配置 › SDK 代码，点「添加应用标识」，填入 Android 的 applicationId，比如 com.example.shop。SDK 每次上报都会带上它，未登记的标识发来的数据会被静默拒收。这个页面还会给出填好站点 Key 的安装代码。

2. 添加依赖

在 app/build.gradle.kts 里：

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

包发布在 Maven Central。控制台安装代码里的坐标如果不同，以控制台为准。ProGuard / R8 规则已打包在 AAR 里，不用另外添加。

3. 初始化

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

// 用户同意隐私政策之后
TapCub.init()

• preInit 只保存配置、绑定生命周期：不采集、不读设备信息、不联网。它必须在 Application.onCreate 里调用，否则冷启动和头一个页面会丢。
• init 开始采集。在用户同意后调用；如果你的 App 不需要同意这一步，紧接着 preInit 调用即可。
• appId、appVersion、appBuild 默认取包名、versionName 和 versionCode。appId 必须和登记的标识一致。
• 国内模式设 region = "cn"，同意后调用 init，再调用 TapCub.grantConsent(listOf("analytics"))。

所有调用在任意线程都会立即返回，实际工作在 SDK 自己的工作线程上执行。

4. 自动采集的内容

Fragment、Jetpack Compose 页面和对话框不会自动采集：出现时调用 TapCub.trackScreen("Home")。见追踪屏幕浏览。

5. 发送事件和识别用户

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

TapCub.login("USER_ID")            // 登录后
TapCub.setProps(mapOf("plan" to "pro"))
TapCub.logout()                    // 退出登录时

项目不是实名模式时 login 会被忽略，事件照常上报。见识别用户。

6. 验证

在真机或模拟器上运行 App，打开 应用统计 › 概览 › 实时，几秒内应能看到启动事件。没有数据时，按下面几点排查。

隐私和存储

事件队列存在 SQLite 里（默认 8 MB、1 万条或 7 天），重启后保留，失败按退避重试。设备 ID 基于 ANDROID_ID；不读取 IMEI、MAC、OAID 或广告 ID。填写 Google Play 数据安全表单时，声明设备或其他 ID、应用互动、崩溃日志和诊断数据。

排查

• 完全没有数据： applicationId 没登记，或者从没调用 init（比如用户还没同意）。
• 缺冷启动： preInit 晚于 Application.onCreate 调用。
• 缺页面： Fragment 或 Compose 页面需要调用 trackScreen。
• 启动时报 siteKey required 崩溃： 站点 Key 为空。
• 对某个用户停止采集： 调用 TapCub.optOut()，optIn() 恢复。

相关

• 安装 iOS SDK
• 无崩溃率
• 追踪 App 版本
• SDK 是什么？含义、SDK 和 API 的区别，以及统计 SDK 怎么工作
• 设备 ID
• 在 Flutter 上安装
• 在 React Native 上安装
• 在鸿蒙上安装