怎么在 React Native 应用里接入 TapCub？

简短回答

在 应用统计 › 配置 › SDK 代码 登记 Android 的 applicationId 和 iOS 的 Bundle ID，安装 @tapcub/react-native 和 @react-native-async-storage/async-storage，启动时调用 TapCub.preInit(config, host) 和 await TapCub.init()，再把 TapCub.navigationHook 传给 NavigationContainer，让屏幕切换被发送。SDK 在 JavaScript 里运行（React Native 0.72 及以上）；iOS 上仍需要加一行 Podfile。

1. 登记两个应用标识

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

2. 安装

npm install @tapcub/react-native @react-native-async-storage/async-storage

iOS 上，自动链接会加入这个包的 pod，而它依赖 TapCub pod。这个 pod 不在 CocoaPods trunk 上，所以要在 ios/Podfile 的 App target 里加上它，再运行 pod install：

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

3. 初始化

import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState, Dimensions, Platform } from 'react-native';
import { TapCub } from '@tapcub/react-native';

TapCub.preInit(
  { siteKey: 'YOUR_SITE_KEY', appId: 'com.example.app' },
  { asyncStorage: AsyncStorage, appState: AppState, platform: Platform, dimensions: Dimensions },
);
// 用户同意隐私政策之后：
await TapCub.init();

第二个参数是宿主对象；SDK 自己不引入 react-native，所以要把它该用的东西传进去：

• asyncStorage 让事件队列在重启后保留。不传时队列只在内存里。
• appState 记录前后台切换。不传就不记录。
• platform 正确上报 iOS 或 Android。不传时事件都会报成 Android。

appId 必须和登记的标识一致。国内模式传 region: 'cn'，同意后调用 init，再调用 TapCub.grantConsent(['analytics'])。在 preInit 之前调用 track 会抛出 TapCub.preInit() first。

4. 追踪屏幕

<NavigationContainer onStateChange={TapCub.navigationHook}>
  {/* 导航器 */}
</NavigationContainer>

最内层路由名变化时发送一次 $screen_view；连续两次相同的名字不会重复发送。不用 React Navigation 时，自己调用 TapCub.trackScreen('Home')。

5. 事件和身份

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

TapCub.login(userId, { plan: 'pro' }, { type: 'login' });
TapCub.logout();

type 可以是 login、email、mobile、openid、unionid 或 custom；邮箱和手机号发送前会先哈希。见识别用户。

6. 可选：原生崩溃

JavaScript SDK 只能看到 JavaScript 异常。要同时拿到原生崩溃、ANR（Android 11+）和卡顿（iOS），需要安装原生 SDK 和这个包里的 TapCubCrash 模块：

1. Android： 在 android/app/build.gradle 里加 com.tapcub:android 依赖，并在 Application.onCreate 里调用 TapCubCrash.install(this)。
2. iOS： 加好上面那行 Podfile 后，在 didFinishLaunchingWithOptions: 里调用 [TapCubCrash install]。
3. JavaScript： 在宿主对象里加 nativeCrash: NativeModules.TapCubCrash。

原生记录的崩溃会在下次启动时交给 JavaScript SDK，并保留原始崩溃时间。不要在原生侧再调用 preInit：那会启动第二个原生 SDK，每个事件都会发两次。

7. 验证

运行 App，打开 应用统计 › 概览 › 实时，几秒内应能看到启动事件和头一个屏幕。

排查

• 没有数据： 标识没登记，或者从没调用 init。
• 没有屏幕： navigationHook 没加到 NavigationContainer 上，或者状态里没有路由名。
• 重启后事件丢了： 没传 asyncStorage。
• 事件全显示为 Android： 没传 platform。
• pod install 找不到 TapCub： 缺那一行 Podfile。

相关

• 追踪屏幕浏览
• 安装 iOS SDK
• 无崩溃率