Kotlin Android 应用分析：如何追踪页面、事件与用户

Android 应用有了下载量，并不代表用户已经用到了产品的核心功能。崩溃报告可以告诉你哪里坏了，却无法说明新用户是否完成了设置、是否再次打开主要功能、是否真正办成了一件事。要让应用分析帮助产品决策，就需要把用户走过的页面与已经确认的结果联系起来，同时区分这两种信号。

Talivia 的原生 Kotlin Android SDK 仍在准备中。目前的源码已经实现页面浏览、业务事件、会话和已登录用户识别，并把数据发送到 Talivia 现有的采集接口。但是，它的 Maven Central 包尚未发布，请不要把 com.talivia:talivia-android 当成已经可以下载的远程 Gradle 依赖。本文帮助你提前设计埋点，也展示当前源码的 API；它并不表示生产应用现在就能通过 Maven 安装该 SDK。接入前请查看 Android SDK 文档 中的最新发布状态。

先确定产品问题，再决定记录什么

从一个会影响决策的问题开始。购物应用可能想知道，打开商品详情的用户是否完成了真实订单；学习应用可能关心，新学员是否学完第一课，并在下周回来；企业应用则可能关注，新建工作区后是否生成了第一份有用的报告。把每一次触摸都记录下来，通常不能自动回答这些问题。

先写一份简短的衡量方案，把信号分成三类：用户看到了哪个页面、应用确认了哪项业务结果、当时是否知道用户属于哪个账号。只有真正显示了重要目的地时，才记录页面；只有底层操作成功时，才记录完成事件；只有登录流程确认账号后，才识别用户。团队以后查看会话时间线时，每个信号才能有明确含义。

在上线前，让产品和工程团队一起确定事件名称、触发时机和允许的属性。如果网络重试或连续点击会重复执行操作，要先决定事件代表一次尝试，还是一次已确认的结果。界面改版后，事件名称也应该保持稳定。更完整的跨平台规划可以参考 移动应用分析总览。

看清 Android SDK 目前能否安装

Kotlin 源码位于 Talivia 独立的 Android 包目录中，目前仍是草稿 SDK。com.talivia 发布命名空间已经准备好，但 Maven Central 上没有正式版本。命名空间得到验证只是发布流程的一步；构建、真机验证、签名、上传和发布检查仍需完成。因此，不要把预计使用的 Gradle 坐标复制进应用后，就认为依赖一定能够解析。

当前源码要求提供 Android Context、UUID 格式的 Talivia Website ID，以及不包含协议和路径的网站域名。默认情况下，它会向 https://talivia.com/api/send 发送数据。应用页面会被表示为 /__app/android/ 下的路径，方便同一个采集端区分原生页面和网站页面。应用也应当遵守自己的隐私与同意设置，只在允许采集时初始化客户端。

以下代码是当前源码的 API 预览，可用于规划接入方式，或者在本地模块中试验；它不是已经发布的安装命令：

val analytics = Talivia(
    context = applicationContext,
    websiteId = "YOUR_WEBSITE_UUID",
    hostname = "your-site.com",
)

analytics.screen("Home")
analytics.track("onboarding_completed", mapOf("path" to "guided"))
analytics.identify(account.id)
// 退出登录成功后调用 analytics.reset()

如果希望网站与应用的数据进入同一个 Talivia 工作区，Website ID 和域名应与网站追踪器保持一致。如果不希望测试应用污染正式报表，就为预发布环境使用单独的 Website ID。正式发布后的安装说明应以 Android 分析产品页 和文档为准。若你现在需要已经发布的移动端方案，可以分别查看 React Native 指南、Flutter 指南 或 Swift 指南，不要把这些 SDK 的发布状态套用到 Android 包上。

在真正的导航边界记录页面

在 Jetpack Compose 中，界面可能频繁重新组合，但这不等于用户每次都进入了新页面。使用 Navigation Component 时，目的地也可能因为恢复状态或返回操作再次出现。应当在团队认定的导航边界调用 screen()，不要把它随意写进可组合函数的主体，让每次重组都产生新的页面浏览。对于 Fragment 或 Activity，也需要选择合适的生命周期位置，并验证重新打开页面时不会意外重复记录。

可以用一个小型导航监听逻辑，把路由映射成稳定的分析名称，例如 Home、Product/Detail 和 Checkout/Review。不要把客户 ID、搜索词、邮箱地址或动态路由原文直接放进页面名称。Talivia 会将页面名称转换成 /__app/android/ 下的应用路径；名称稳定，报表才不会因为大量商品记录而变得难读。SDK 会对路径片段进行编码，但编码并不能让敏感信息变得适合采集。

analytics.screen("Product/Detail")
analytics.screen("Checkout/Review")

当前 SDK 会记住最近的页面，为之后的业务事件提供上下文；前提是应用在正确的导航时机记录了页面。应在真机上测试标签页切换、深层链接、返回导航和进程恢复。通过 会话活动视图 检查 Talivia 实际收到的顺序。如果一次导航产生了两次页面浏览，应修正埋点位置，而不是把重复数据解释成第二次访问。

等业务操作成功之后再记录事件

Android API 提供 track(name, data) 来记录自定义事件。应该在应用确认业务操作完成的时刻调用它。比如创建工作区的服务端请求成功后，再发送 workspace_created。如果用户按下“支付”按钮，但请求随后失败，就不应该发送 purchase_completed。事件必须描述已经观察到的结果，而不是点击按钮时期待发生的结果。

analytics.track(
    "first_report_created",
    mapOf("report_type" to "weekly"),
)

目前的源码要求事件名称长度为 1 到 50 个字符，并把可选属性序列化成 JSON。属性应保持简洁，并与具体决策相关：功能类别、实验分组或不敏感的套餐名称通常已经足够。不要发送访问令牌、支付资料、邮箱地址、用户输入的自由文本或任何密钥。如果网站也记录相同的业务里程碑，最好在两个端使用同一个业务事件名称。有关命名事件的设计，可以参考 事件追踪文档。

客户端购买事件尤其容易被误读。Android 应用可以记录结账页面打开，或者应用中的购买流程返回成功，但手机本身不是订阅或收入的可信权威来源。购买验证、退款、续费和权益状态应由服务端集成确认。阅读 收入归因指南 时也要保留这一区别：客户端事件可以解释用户意图与使用路径，却不能单独证明已经入账的收入。

识别已登录用户，并在退出时重置

移动端安装最初对应一个匿名访客标识。登录成功后，用应用自己控制的稳定内部账号 ID 调用 identify()。如果同一用户也使用网站，一致的 ID 可以帮助 Talivia 关联已知用户记录。能使用不透明的稳定账号 ID 时，不建议直接用邮箱地址。SDK 会在 Android SharedPreferences 中保存用户 ID、访客 ID、会话 ID 和最近的页面。

analytics.identify(account.id)
// 确认退出账号之后：
analytics.reset()

退出登录后调用 reset()，这样共用一台手机的下一位用户不会继承上一位用户的匿名访客与会话。重置会轮换两个标识、清除已知用户、清空内存中的待发送队列，并重新开始会话状态。要把这一步放进真正的退出路径；由账号删除触发的登出也不能遗漏。如果产品支持直接切换账号，也应先隔离旧身份，再识别新账号。

当前 Android SDK 会在 30 分钟无活动后轮换会话。因此，会话只是对一段相近活动的分组，不意味着应用一直保持打开。更关键的是，Talivia 当前的漏斗报表仍按访客标识分组。相同账号 ID 可以帮助关联网站和应用的已知用户记录，但不会自动把浏览器访客与 Android 访客合并成一条跨设备漏斗。分析图表前，要先说明它统计的是访客、会话、已识别账号，还是完成的事件。当前身份边界可见 移动分析文档。

理解发送、隐私与归因限制

Android SDK 会在工作线程安排网络发送，调用 track() 不需要让界面线程等待一次网络往返。它的队列最多保存 100 条消息；临时发送失败后，会在后续事件或显式调用 flush() 时再次尝试。但是，这个队列只存在于内存中。如果应用在离线期间结束进程，未发送的消息可能丢失。因此，它不是持久化离线事件仓库，也不能保证每条事件都送达。被服务端永久拒绝的请求同样可能被丢弃。

请同时测试正常路径和故障路径：断开网络后记录页面与操作，重新联网，调用 flush()，再检查实际到达的数据。也要在终止进程后冷启动一次，让团队了解哪些离线事件不会恢复。解释活动量突然下跌时，这些测试很重要，因为发送缺口与真实的产品行为变化，在图表上可能十分相似。要求财务数据完整的场景，应使用可信的服务端记录，而不是依赖客户端队列。

Android 应用分析也不会自动提供安装归因、广告网络的可信活动信息，或者经过验证的 Google Play 购买记录。这些能力需要另外的可信集成，并遵守相应的用户同意要求。团队应确认各地区允许采集什么数据，以及这些选择如何与应用的隐私控制配合。衡量方案保持适度，往往不需要收集个人内容或每一次触摸，也能回答关键的产品问题。

先验证一条完整路径，再扩展埋点

SDK 发布后，请按照届时的 Android 安装文档 加入依赖，而不是复制本文中尚未验证的坐标。先在测试应用中使用专门的 Website ID：打开 Home，前往 Product/Detail，完成一项真实操作，登录账号，再退出。去 Talivia 会话视图核对顺序和属性。接着让操作失败一次，确认没有错误发送成功事件。最后在同一设备换一个账号，检查 reset() 后的活动是否使用了新的访客标识。

然后分别看清每种报表统计的对象。页面浏览描述导航，事件描述已经确认的应用操作，会话把相近的活动放在一起，已识别用户则提供账号关联。这些问题彼此相关，但答案并不相同。为每个事件保存一份简短的责任清单：由哪段代码发送，它在业务上究竟意味着什么。功能流程变化时，同步更新清单。如果产品同时有网站和应用，应先分别验证两个端，再解释同一工作区里的合并视图。

这种循序渐进的上线方式，比第一天就记录所有动作更有用。它先给团队一条可信的用户路径，也让重复导航事件和离线缺口尽早暴露，然后再有根据地增加事件。原生包正式发布后，Talivia 可以通过共用采集接口接收这些 Android 信号。在此之前，请把 Kotlin 源码与本文视为接入准备资料，并通过 移动应用分析总览 比较当前可用的平台方案。