Track Business SDK

主题外观

最新
文档版本
最新文档✓2026.11.0
AI 文档索引 ↗

Android SDK ​

AI 辅助接入 Android

在应用进程中创建并复用 SDK 实例。Kotlin 与 Java 宿主均可通过公开 API 记录事件。

前置准备 ​

  • Android 6.0（API 23）及以上；
  • Android 工程使用 Java 17 字节码；
  • 宿主 AndroidManifest.xml 已声明网络访问权限；
  • 获取事件接收地址 endpoint 和项目凭据 projectKey，详见环境与项目凭据。

快速接入 ​

步骤 1：引入依赖与权限配置 ​

获取 Android SDK 预编译产物

从 Android SDK 下载页选择版本并下载离线包。包内 maven/ 包含核心、可选模块和依赖元数据。

在 AndroidManifest.xml 声明网络权限：

xml
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

将离线包解压到工程根目录的 libs/track-business-android/，然后配置包内的 Maven 仓库：

kotlin
// settings.gradle.kts：保留宿主现有的其他仓库配置
dependencyResolutionManagement {
    repositories {
        exclusiveContent {
            forRepository {
                maven { url = uri(rootDir.resolve("libs/track-business-android/maven")) }
            }
            filter { includeGroup("com.trackbusiness") }
        }
        google()
        mavenCentral()
    }
}

如果选择其他解压位置，请相应调整路径。在宿主模块声明核心依赖：

kotlin
// 宿主模块 build.gradle.kts
dependencies {
    implementation("com.trackbusiness:track-business-sdk:1.0.0")
}

NOTE

Gradle 会从仓库元数据解析 Room、Lifecycle、WorkManager、Security、Coroutines 等依赖，无需手工枚举。离线包提供 Track Business 自有制品；第三方依赖、Android SDK 和 Gradle 由宿主管理。完全断网构建前须预置其缓存或企业镜像。aar/ 与 metadata/ 保留为高级手工接入路径；单独使用 AAR 无法自动解析传递依赖。

包内 repository.json 提供 Maven 文件校验和，delivery.json 记录产物来源。

步骤 2：在 Application 中创建并持有实例 ​

在 Application.onCreate 中启动异步初始化。应用可先显示首屏，在 SDK 就绪后复用同一个实例：

kotlin
import android.app.Application
import android.util.Log
import com.trackbusiness.sdk.TrackBusinessConfig
import com.trackbusiness.sdk.TrackBusinessSDK

class TrackApplication : Application() {
    var sdk: TrackBusinessSDK? = null
        private set

    override fun onCreate() {
        super.onCreate()

        TrackBusinessSDK.createAsync(
            applicationContext,
            "https://collector.example.com/v1/events/batch",
            "android-public-project-key",
            TrackBusinessConfig.builder().build(),
        ) { client, error ->
            if (error == null) {
                sdk = client
            } else {
                Log.w("Analytics", "SDK initialization failed")
            }
        }
    }
}

若业务需要记录启动深链，请先保留宿主收到的 Intent，就绪后交给 SDK；自动监听从 SDK 注册之后开始。同步 create() 适用于已经在后台线程执行的初始化。

Android SDK 默认开启应用生命周期采集，并自行注册生命周期观察和前后台 Flush 调度。后台 Flush 是尽力调度，系统可能延迟 WorkManager 任务，不代表退后台后立即送达。可通过 TrackBusinessConfig.Builder 调整 trackAppLifecycle、flushAt、flushIntervalSeconds 与 flushOnBackground。

需要事前授权时，以 ConsentDecision.pending() 初始化，并在宿主/CMP 确认授权后调用 sdk.grantConsent("STANDARD")。需要紧接着记录事件时，请使用完成回调等待授权持久化与采集激活，见下方“授权后开始采集”。

步骤 3：记录首个事件 ​

在业务代码中调用 track() 记录事件。SDK 异步入队并调度上传；调用返回不等于已落盘或已上传。使用内存队列时，未确认事件不能跨进程恢复：

kotlin
// 日常业务埋点：调用后由 SDK 异步入队
sdk?.track(
    "quickstart_completed",
    mapOf("source" to "android-docs"),
)

验证交付结果 ​

  1. 使用测试环境的 endpoint 和 projectKey，记录上面的 quickstart_completed 事件。
  2. 检查网络权限、上传诊断和队列状态；联调时可调用 sdk.flush()。实体设备使用可达的局域网或部署服务地址，不能使用设备自身的 localhost。
  3. 核对接收端的事件名、属性与接收记录，并确认响应符合整批 ACK 契约。

SDK 会自动合批；flush() 返回或队列为空不能单独证明事件已接收。详见数据校验。

可选：检查待发事件的确认结果 ​

记录测试事件后，可用 verifyDelivery 检查当前待发范围。它不能代替接收端记录。

kotlin
sdk.verifyDelivery(3000L) { report, error ->
    if (error != null || report == null) {
        println("验证不可用")
    } else {
        when (report.status) {
            "acknowledged" -> println("当前待发范围已确认")
            "rejected" -> println("存在明确拒收，请排查配置或事件规则")
            "empty" -> println("当前没有待验证事件，不作为接收证明")
            else -> println("尚未完整确认：${report.reason}")
        }
    }
}

各状态含义见数据校验。

Android 完成回调不保证在主线程；更新 UI 时请切回主线程。

可选配置 ​

登录后关联用户 ​

业务系统确认用户登录后再关联身份；切换账号和安全退出使用不同操作：

kotlin
sdk.identify("user_10086")
sdk.track("account_page_viewed")
sdk.switchUser("user_10087") // 已知切换到另一个账号
sdk.signOut() // 安全退出并建立新的匿名代际

identify() 用于首次关联，不可用来静默覆盖另一个已登录用户。完整规则见身份与生命周期。

纯 Java 宿主 ​

SDK 以 Kotlin 实现，但公开 Facade 可从纯 Java Application 调用：

java
import android.app.Application;
import com.trackbusiness.sdk.TrackBusinessConfig;
import com.trackbusiness.sdk.TrackBusinessSDK;
import java.util.Collections;

public final class TrackApplication extends Application {
    private TrackBusinessSDK sdk;

    @Override
    public void onCreate() {
        super.onCreate();
        TrackBusinessSDK.createAsync(
            getApplicationContext(),
            "https://collector.example.com/v1/events/batch",
            "android-public-project-key",
            TrackBusinessConfig.builder().build(),
            (instance, error) -> {
                if (error != null) {
                    android.util.Log.w("Analytics", "SDK initialization failed");
                    return;
                }
                sdk = instance;
                sdk.track("quickstart_completed", Collections.singletonMap("source", "android-java-docs"));
            }
        );
    }
}

createAsync() 的 Java 完成回调在主线程执行。需要数字、布尔、嵌套 Map 或 List 时，使用 trackProperties(String, Map<String, ?>)。完整类型约束见 Android API 参考。

授权后开始采集 ​

需要用户事前授权时，可按以下方式初始化：

kotlin
import com.trackbusiness.sdk.TrackBusinessConfig
import com.trackbusiness.sdk.TrackBusinessSDK
import com.trackbusiness.sdk.models.ConsentDecision

var sdk: TrackBusinessSDK? = null
val config = TrackBusinessConfig.builder()
    .initialConsent(ConsentDecision.pending())
    .build()

TrackBusinessSDK.createAsync(
    applicationContext,
    "https://collector.example.com/v1/events/batch",
    "android-public-project-key",
    config,
) { client, error ->
    if (error == null) sdk = client
}

// 在用户同意的回调中调用；实例尚未就绪时先等待初始化完成。
fun onUserConsentGranted() {
    val client = sdk ?: return
    client.grantConsent("STANDARD") { consentError ->
        if (consentError == null) {
            client.recordDeepLink("myapp://orders/42")
        }
    }
}

授权激活和持久化是异步的；若马上记录依赖该授权的事件，请在 grantConsent 成功回调后执行。更新界面前请切回主线程。

R8 / ProGuard 混淆规则配置 ​

Track Business Android SDK AAR 通过 consumer-rules.pro 提供消费端所需的 R8 规则，Gradle 正常依赖 AAR 时会自动合并；一般不需要把 SDK 内部规则复制到宿主。若自定义混淆配置后出现 Release-only 问题，请先用最小 Release Host 复现并核对当前 Bundle 中的 POM/模块元数据，避免使用宽泛的 -keep 或 -dontwarn 规则。