Swift 原生 iOS 应用分析：页面、事件与真实用户旅程

App Store 下载量说明有人安装了 iOS 应用，却不能说明他们是否到达核心功能、完成新手引导，或者后来为何再次打开应用。崩溃报告可以解释故障，但无法描述成功的客户旅程。有用的 iOS 应用分析应从用户实际看到的页面，以及应用能够确认的业务结果开始。

Talivia Swift 包通过现有 Talivia 接收端记录原生 iOS 页面、自定义事件、会话和已知用户身份。如果网站和应用使用相同的 Website ID 与域名，就可以在一个工作区查看两边的活动。这样的共同视图很有价值，但不意味着浏览器和手机上的所有会话自动合并为一条跨设备漏斗。本文说明怎样谨慎接入 Swift 应用，以及如何正确解读结果。

选事件之前先定义一条用户旅程

先提出一个会影响产品决策的问题。教育应用可能想知道新学员是否完成第一节课；财务应用可能关注连接账户并看到第一份报告；协作应用可能关注创建工作区和邀请队友。这些结果本来就属于产品，不是为了迎合某个分析工具而临时设计的动作。

把三类证据区分开。页面浏览说明用户导航到了哪里。产品事件说明重要操作确实完成。已知身份说明认证流程已经识别了哪个账户。不要根据结账页面推断付款成功，也不要根据按钮点击推断注册完成。只有应用自身确认结果后，才应发送成功事件。

上线前，为每个事件写明准确触发时刻和允许的属性，同时约定请求重试与重复点击如何计数。稳定的事件名称应该能在 SwiftUI 视图层级或 UIKit 控制器改版后继续使用。移动应用分析总览提供网站与应用共存产品的完整衡量框架。

在 Xcode 中添加带版本的 Swift 包

Talivia 源码可从公开的 talivia-group/swift 仓库通过 Swift Package Manager 获取。在 Xcode 中添加下面的包地址，并选择 0.1.0 版本：

https://github.com/talivia-group/swift.git

如果通过另一个 Package.swift 管理依赖，可添加 .package(url: "https://github.com/talivia-group/swift.git", from: "0.1.0")，再依赖 Talivia library product。这是带 Git 版本标签的源码包，不是 App Store 应用，也不是 npm 包。Swift 安装文档集中列出了当前依赖方式与代码示例。

创建客户端时，填写 Talivia 工作区的 Website ID 和网站追踪器使用的域名。hostname 只填写域名，不包含 https:// 或路径。SDK 默认连接 Talivia Cloud 接收端，应用中不需要私有 API 密钥：

import Talivia

let analytics = try Talivia(
    websiteId: "YOUR_WEBSITE_UUID",
    hostname: "your-site.com"
)

客户端限定在主 actor 上运行。请在应用中合适的主 actor 上创建并调用它，而且仅当用户的隐私与同意选项允许采集时才初始化。这个包面向原生 iOS，声明的最低系统版本为 iOS 15。如果产品还有网站，应在网站使用浏览器追踪器；原生包用于应用活动。

在 SwiftUI 或 UIKit 中记录可见页面

SDK 无法替产品判断哪些导航变化属于有意义的新页面。SwiftUI 导航到目的地，或 UIKit 控制器完成切换并显示内容时，可以调用 screen()：

try await analytics.screen("Home")
try await analytics.screen("Report/Detail")

标签切换、弹窗或嵌套路由在不同产品中的意义不一样，应由应用明确决定是否记录。使用稳定的页面名称，避免把原始客户 ID、电子邮箱、搜索词或其他不断变化的私密值写入路径。Report/Detail 这样的模板既方便团队比较不同报告的旅程，也不会让每份报告都成为分析里的独立页面。

Talivia 会把这些原生页面作为带有 iOS 上下文的应用路径发送。它们与网站页面浏览共用接收端，但描述的仍是应用导航。请检查调用位置：SwiftUI 的 onAppear 或 UIKit 生命周期回调可能在用户感知的一次切换中执行多次。确认用户实际看到一个目的地时，只产生一次预期的页面浏览。会话活动视图适合把事件顺序与真实设备操作进行核对。

应用确认业务结果后再记录事件

在已有业务流程确实知道操作成功时调用 track()。可以通过包提供的 JSONValue 类型附加少量有用属性：

try await analytics.track(
    "onboarding_completed",
    data: ["path": .string("guided")]
)
try await analytics.track("first_report_created")

如果创建报告的网络请求失败，就不要发送 first_report_created。如果购买或账户变更仍在等待确认，也不应提前标记为完成。这有助于团队区分用户意愿不足与执行过程失败。很多人打开结账页却很少完成付款，与很少有人打开结账页，需要调查的原因并不相同。

事件名称应简短且含义稳定，属性仅保留真实决策所需的信息。套餐名称和功能类别可能有用；访问令牌、电子邮箱、付款凭据和用户自由输入的私密内容通常不应复制到事件中。如果网站也记录相同节点，应在两个终端使用一致的业务名称。事件追踪文档介绍具名事件如何与页面和会话活动一起使用。

关联已知用户，同时避免夸大身份能力

认证流程确认账户后，使用稳定的内部 ID 调用 identify()。如果客户也使用网站，请在网站追踪中使用同一个 ID。退出登录后调用 reset()，让下一位使用共用手机的人获得新的匿名访客和会话身份：

try await analytics.identify(account.id)
// 退出登录成功后：
analytics.reset()

SDK 通过 UserDefaults 保存访客、会话、当前页面和已知用户状态。超过 30 分钟不活动后，会开始新会话。这有助于观察重复使用，却不意味着同一账户在多个设备上的所有活动天然构成一条连续旅程。Talivia 可以在 ID 相同时关联已知客户身份记录；当前漏斗仍按访客标识统计。浏览器访客与 iPhone 访客不会因为后来登录了同一个账户，就自动合并为一条跨设备漏斗。

每份报表都应写清统计单位。会话数、独立访客数、已知账户数与成功操作数回答的是不同问题。移动分析文档解释共享工作区和现阶段的身份边界。把边界展示出来，可以避免团队从方便的图表里读出实际上没有证据支持的故事。

把离线发送和获客归因视为独立工作

Swift SDK 可以在之后的事件或显式调用 flush() 时重试失败的网络发送。待发送队列最多在内存中保存 100 条消息。应用进程退出后，未发送消息会丢失；服务端永久拒绝的消息也可能被丢弃。因此它不是能够保证离线投递的事件存储。可以先在飞行模式下完成一小段旅程，重新联网并刷新队列，再核对实际到达的数据。

安装来源也需要普通页面追踪之外的证据。这个包不会自动收集 App Store 安装归因、深度链接活动历史或广告网络转化数据。网站活动参数可以描述它所在的浏览器访问，却无法证明之后某次原生安装的来源。如果业务需要这类判断，应增加可信的归因集成，并记录其标识如何连接到应用活动。

付款事实应由可信服务端提供。客户端的 purchase_completed 事件或成功页面无法证明 StoreKit 或其他服务商最终收取并保留了款项。购买可能未通过验证、延迟、退款、重复发送或被伪造。请由后端或受支持的付款集成发送权威结果，再通过收入归因检查已确认收入与符合条件的产品活动之间的证据链。

在真实设备上验证第一条旅程

使用测试账户并预先确定路径：打开应用、进入 Home、完成一次有价值的操作、登录、退出登录，再在超过非活跃时间窗口后返回。在 Talivia 中检查顺序。每个预期页面应只出现一次，失败操作不应产生成功事件，已知 ID 只能在认证后出现。还应核对 iOS 平台信息，以及配置的 Website ID 与域名。

再测试关闭与恢复网络连接，确认哪些消息真正到达 Talivia。即使 HTTP 请求成功，也不能单凭响应就断言报表保存了事件，因为采集规则可能有意忽略它。当前包已经有单元测试，但完整的真实设备验证仍是独立的发布检查。正式宣布接入完成前，应在自己的应用和设备上验证收到的活动。

iOS 应用分析最有价值的做法，是让应用只报告它确实知道的事：可见页面、已完成的产品节点和经过认证的身份。可信服务端应报告付款事实，安装归因也必须有独立证据。可以从 Talivia iOS 分析页面开始，按照 Swift 包指南接入，并在第一条旅程清晰、可重复后再扩大事件计划。