Android SDK

16 days ago

f4649f7

Android SDK

适用版本：公开标签 v0.1.1，Android API 23+，Java/Kotlin 目标版本 17。当前文档按公开源码构建 AAR，不依赖 Release 页面。

从固定标签构建 AAR

git clone --branch v0.1.1 --depth 1 \
  https://cnb.cool/mliev/entmesh/sdk-android
cd sdk-android

export ANDROID_HOME=/path/to/Android/sdk
sh scripts/package-release.sh v0.1.1

成功后 dist/ 包含：

entmesh-android-core-v0.1.1.aar：必选核心库；
entmesh-android-google-identifiers-v0.1.1.aar：可选 App Set ID / GAID；
entmesh-android-fragment-v0.1.1.aar：可选 Fragment 页面采集；
entmesh-android-compose-v0.1.1.aar：可选 Compose Navigation 页面采集；
SHA256SUMS：制品校验值。

先校验 SHA-256，再把所需 AAR 复制到应用模块的 libs/。核心库必须始终引入，其他模块按需添加：

dependencies {
    implementation(files("libs/entmesh-android-core-v0.1.1.aar"))

    // 使用 Fragment 适配时同时添加：
    // implementation(files("libs/entmesh-android-fragment-v0.1.1.aar"))
    // implementation("androidx.fragment:fragment-ktx:1.8.9")

    // 使用 Compose Navigation 适配时同时添加：
    // implementation(files("libs/entmesh-android-compose-v0.1.1.aar"))
    // implementation(platform("androidx.compose:compose-bom:2025.06.01"))
    // implementation("androidx.compose.runtime:runtime")
    // implementation("androidx.navigation:navigation-compose:2.9.1")

    // 使用 Google 标识适配时同时添加：
    // implementation(files("libs/entmesh-android-google-identifiers-v0.1.1.aar"))
    // implementation("com.google.android.gms:play-services-appset:16.1.0")
    // implementation("com.google.android.gms:play-services-ads-identifier:18.2.0")
}

控制台准备

在目标环境的接入指南中登记 Android 应用包名，例如 com.example.shop，并保存 ck_… Client Key。

初始化

建议在 Application.onCreate 中初始化一次：

Entmesh.init(
  application = this,
  config = EntmeshConfig(
    endpoint = "https://collector.entmesh.mliev.com",
    clientKey = "ck_替换为当前环境的ClientKey",
    applicationId = packageName,
    consent = Consent.PENDING,
  )
)

Entmesh.consent(Consent.GRANT)
Entmesh.track("signup_completed", mapOf("plan" to "team"))

默认 consent 为 PENDING，autocapture 为 true，每 5 秒刷新、每批 20 条。SDK 自动使用安全随机数、持久化匿名 ID/会话和有限队列，并加密客户端批次；加密失败不会降级成明文。

页面与身份

Entmesh.screen("Checkout")
Entmesh.identify("user-42", mapOf("account_type" to "team"))

// 用户退出登录
Entmesh.reset()

Activity 生命周期在开启自动采集时自动记录前后台和页面。
Fragment 在 FragmentActivity 中调用 EntmeshFragmentTracker.install(this)。
Compose 页面可使用 EntmeshScreen("Checkout") 或 EntmeshNavigationEffect(navController)。
应用结束或测试清理时调用 Entmesh.shutdown()；需要主动尝试发送队列时调用 Entmesh.flush()。

设备标识

核心库不依赖 Google Play Services，默认不采集广告标识。需要 App Set ID 或用户授权后的 GAID 时，引入可选 Google 标识模块并通过 identifierProviders 配置。

OAID、VAID、AAID 需要宿主应用自行集成 MSA SDK，并提供 DeviceIdentifierProvider；Entmesh 不分发 MSA SDK。授权或标识状态变化后调用 Entmesh.refreshDeviceIdentifiers()。