怎么在 Flutter 应用里接入 TapCub？

简短回答

在 应用统计 › 配置 › SDK 代码 分别登记 Android 的 applicationId 和 iOS 的 Bundle ID，运行 flutter pub add tapcub_flutter，启动时调用 TapCub.preInit 和 TapCub.init，并在 MaterialApp 上加 TapCub.navigatorObserver，让有名字的路由作为屏幕发送。插件把每次调用转给 Android 和 iOS 原生 SDK，启动、会话和崩溃都由原生 SDK 采集。

环境要求

• tapcub_flutter 0.2.0 需要 Flutter 3.44 和 Dart 3.12 及以上。较老的 Flutter 用 tapcub_flutter: ^0.1.0。
• iOS 默认用 Swift Package Manager，插件会自动拉取 tapcub-ios。
• Android 依赖 Maven Central 上的 com.tapcub:android（0.1.1 及以上），不用额外配置。

1. 登记两个应用标识

打开 应用统计 › 配置 › SDK 代码，点两次「添加应用标识」：一次填 Android 的 applicationId，一次填 iOS 的 Bundle ID。未登记的标识发来的数据会被静默丢弃。

2. 安装

flutter pub add tapcub_flutter

如果 iOS 工程关掉了 Swift Package Manager、改用 CocoaPods，在 ios/Podfile 的 target 'Runner' do 里加上这一行，再运行 pod install：

pod 'TapCub', :git => 'https://github.com/tapcub/tapcub-ios.git', :tag => '0.1.0'

3. 初始化

import 'package:tapcub_flutter/tapcub_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await TapCub.preInit(TapCubConfig(
    siteKey: 'YOUR_SITE_KEY',
    appId: 'com.example.app',
  ));
  // 用户同意隐私政策之后：
  await TapCub.init();
  runApp(const MyApp());
}

appId 必须和为原生 App 登记的标识一致。国内模式传 region: 'cn'，同意后调用 init，再调用 TapCub.grantConsent(['analytics'])。

原生 SDK 会自己记录启动和前后台切换。Android 上插件会把当前 Activity 交给原生 SDK，所以冷启动也能上报。

4. 追踪屏幕

MaterialApp(
  navigatorObservers: [TapCub.navigatorObserver],
  // ...
);

在 push、replace 和 pop 时，观察者读取路由的 settings.name 并发送一次屏幕浏览。没有名字的路由会被跳过，和上一次相同的名字也不会重复发送。给路由起名（RouteSettings(name: 'Checkout') 或命名路由），或者自己调用 TapCub.trackScreen('Home')。

5. 事件和身份

await TapCub.track('purchase', {'revenue': 19.9, 'currency': 'CNY'});

await TapCub.login('USER_ID');       // type 默认 'login'
await TapCub.login('a@example.com', type: 'email');
await TapCub.logout();

这个版本里 setProps 存为事件公共属性。调用 TapCub.flush() 可以让原生 SDK 立即发送队列里的事件。

6. 验证

分别在 Android 模拟器和 iOS 模拟器上运行，打开 应用统计 › 概览 › 实时。两个平台的启动事件几秒内都应出现；用页头的平台筛选把它们分开。

排查

• 头一次调用就报 PlatformException： 构建里缺少原生库。完整重新构建（flutter clean 后再构建）；CocoaPods 工程检查 Podfile 那一行。
• 某个平台没有数据： 这个平台的标识没有登记。
• 没有屏幕： 观察者没加到 MaterialApp 上，或者路由没有 settings.name。
• 队列和重试 跟随原生 SDK（Android 用 SQLite，iOS 用文件）。

相关

• 安装 Android SDK
• 安装 iOS SDK
• 追踪屏幕浏览