Flutter 应用分析：在 iOS 与 Android 追踪真实用户旅程

Flutter 可以让 iOS 与 Android 应用共用代码，但团队想从数据中回答的问题通常更具体：用户在获得产品价值前到达了哪些页面？他们是完成了新手引导，还是只打开了引导页面？回访用户有没有再次使用团队投入最多的功能？Flutter 应用分析应该依据应用实际发生的流程回答这些问题。

Talivia Flutter SDK把应用页面浏览、产品事件、会话和已知用户身份发送到与网站活动相同的接收端。应用和网站使用相同的 Website ID 与域名时，团队可以在同一个 Talivia 工作区查看两类数据。应用仍需明确调用追踪方法；移动端获客来源和付款事实也需要独立证据。本文介绍如何接入，以及怎样正确理解报表边界。

从团队用得上的事件计划开始

添加追踪代码前，先选出少量业务问题。订阅应用可能想了解新用户是否打开引导、完成设置、使用主要功能，并在之后的会话中回来。交易平台可能更关心搜索、查看商品、收藏以及提交咨询。这些都是产品本来就需要回答的问题，事件计划应采用团队熟悉的业务语言。

把页面、成功操作和已知身份分开。页面浏览说明用户真正看到了哪个目的地；自定义事件说明重要的业务节点确实发生；账户 ID 说明应用已经确认这位登录客户是谁。打开 Checkout 不等于付款成功，点击创建按钮也不等于对象已经保存。

为每个事件维护一份简短说明，写明触发条件、预期属性和定义负责人。还应决定重复点击、请求重试与后台完成是否会增加计数。稳定的事件名称应该能经受按钮文案和界面组件的修改。移动应用分析总览介绍这些信号如何在不同平台上配合使用。

安装并配置原生 Flutter 包

talivia_flutter 可用于 iOS 和 Android 上的 Flutter 应用。安装它，并明确添加示例所用的本地状态依赖 shared_preferences：

flutter pub add talivia_flutter
flutter pub add shared_preferences

配置时需要 Talivia Website ID、网站追踪器使用的域名、当前原生平台，以及 SharedPreferences 实例。只有在应用的同意与隐私设置允许采集时才初始化。在原生应用的异步设置函数中，可以这样创建实例：

import 'dart:io';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:talivia_flutter/talivia_flutter.dart';

Future<Talivia> createAnalytics() async {
  final preferences = await SharedPreferences.getInstance();
  return Talivia(
    websiteId: 'YOUR_WEBSITE_UUID',
    platform: Platform.isIOS ? 'ios' : 'android',
    hostname: 'your-site.com',
    preferences: preferences,
  );
}

请将占位值换成自己工作区的 ID 和域名。hostname 只填写域名，不包含协议或路径。这个包默认向 https://talivia.com 发送数据，应用里不需要放私有 API 密钥。如果项目还提供 Flutter Web，请单独规划浏览器端分析；此 SDK 及使用 dart:io 的示例面向原生 iOS 与 Android。Flutter 接入文档提供当前的安装说明。

在 Navigator 或 Router 中记录可见页面

SDK 不会自动观察 Flutter 导航。请根据产品决定 Navigator、Router 或所用路由包的哪些变化代表有意义的新页面，并在目的地真正可见时调用 screen()：

await analytics.screen('Home');
await analytics.screen('Workspace/Detail');

明确调用有实际价值，因为弹窗、嵌套路由、标签切换和完整页面在不同产品里含义不同。页面名称应描述稳定的目的地。不要把电子邮箱、搜索词或不断变化的记录 ID 填进路径。像 Workspace/Detail 这样的模板既便于跨记录比较，也不会让页面维度充满私人或只出现一次的值。

SDK 会把名称编码成移动端路径，并附上 iOS 或 Android 平台信息。这些路径与网站浏览共用 Talivia 接收端，但描述的是应用页面。请检查导航回调，避免组件重建、焦点变化或嵌套状态更新造成重复页面浏览。可以在会话活动视图中抽查一条真实测试路径，确认顺序与用户看到的一致。

在业务操作完成后记录事件

应用确认结果后再调用 track()。例如，账户真正创建成功后发送 signup_completed；服务端确实保存工作区后发送 first_workspace_created：

await analytics.track('signup_completed', {'method': 'email'});
await analytics.track('first_workspace_created', {'template': 'blank'});

如果请求失败，就不应发送成功事件。如果操作在后台完成，应在应用可以确认结果的时刻记录。这样分析会顺应已有业务流程，而不会反过来要求业务流程迁就 SDK。转化报表也因此更有意义：点击率很高但完成率很低，与用户一开始就没有意愿，是两个不同的问题。

事件属性要认真筛选。功能类别或套餐层级可能帮助团队分析使用情况；访问令牌、用户自由输入的内容、电子邮箱和付款凭据通常不适合进入普通事件。如果网站和应用中存在同一个业务结果，最好约定一致的命名方式。事件追踪指南说明自定义事件如何用于 Talivia 报表。

关联已知账户，同时避免误读跨设备漏斗

认证流程确认客户后，用稳定的内部账户 ID 调用 identify()。如果同一位客户还登录网站，请在那里使用相同的 ID。退出登录后调用 reset()，在另一位用户使用设备前更换匿名访客与会话身份：

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

这个包通过 SharedPreferences 保存访客、会话、已知用户和当前页面状态。超过 30 分钟不活动后，会开始一个新会话。这有助于观察回访，但不会让手机和浏览器变成同一个匿名访客。相同的已知账户 ID 可以建立身份关联；当前漏斗仍按访客标识统计，不会把登录前的所有网站和应用操作自动合并成一条跨设备漏斗。

展示转化率时尤其需要说明这一点。客户可能先在笔记本上浏览网站，再安装应用，最后在手机上登录。账户关联提供了有用的上下文，但获客路径仍可能不完整。报表应明确标注统计对象是访客、会话、已知账户还是成功操作。移动分析文档解释了当前共享工作区的实际工作方式。

了解离线发送与获客归因的边界

网络不可用导致发送失败时，Flutter SDK 可以在下一次事件或调用 flush() 时重试。待发送队列最多在内存中保存 100 个事件。应用进程退出后它会丢失，因此无法保证长时间离线后的投递。如果服务端明确拒绝一个事件，该事件也可能从队列中移除。正式依赖离线报表前，最好断网完成一小段测试旅程，重新联网后刷新队列，再比较实际到达的数据与预期。

SDK 不会自动采集应用商店安装来源、深度链接活动或广告网络转化证据。网站的活动参数可以解释一次网页访问，却不能单独证明后来原生应用安装的来源。如果这类归因对业务重要，请接入合适的安装或活动数据源，并定义它如何与应用旅程关联。不要用猜测填补证据缺口。

同样，客户端事件不能证明款项已收取。应用内购买可能验证失败、延迟或退款。设备发出的 purchase_completed 也可能重复或被伪造。应通过可信后端或受支持的付款服务集成记录权威付款结果，再用 Talivia 收入归因查看已确认收入与符合条件的行为证据如何连接。

增加事件前先验证一条短旅程

使用测试账户打开应用，进入 Home，创建一个真实对象，然后登录、退出登录，并在超过非活跃时间窗口后回来。确认页面和事件顺序正确、每个页面只记录一次、失败操作不会产生成功事件，而且账户 ID 只在认证后出现。如果应用同时发布 iOS 和 Android，请分别测试两个平台。共享工作区里没有看到预期活动时，应先核对 Website ID 与域名。

接着测试飞行模式与网络恢复，并在 Talivia 中查看结果。最初的事件计划应足够小，便于逐条人工核对。只有团队能解释每个信号的含义和来源时，增加追踪范围才有价值。比较不同框架时，可以阅读 React Native 应用分析指南，了解同样的衡量原则如何应用于另一个移动技术栈。

Flutter 应用分析应跟随产品真实发生的结果：导航提供页面，已完成的操作提供事件，认证提供已知身份，可信服务端提供付款事实。可以从 Talivia Flutter 概览开始，按照 SDK 安装指南接入，并在第一条旅程从头到尾都清晰可靠后再扩大追踪范围。