怎么在鸿蒙应用里接入 TapCub？

简短回答

在 应用统计 › 配置 › SDK 代码 登记应用的 bundleName，把 @tapcub/harmony 加进工程，在 EntryAbility.onCreate（或 AbilityStage.onCreate）里调用 TapCub.preInit(this.context, { siteKey: 'YOUR_SITE_KEY' })，用户同意隐私政策后调用 await TapCub.init()。之后启动、会话、router 和 Navigation 页面浏览以及崩溃会自动采集。点击用 TapCub.trackClick 上报。

SDK 支持 HarmonyOS NEXT（API 12 及以上，Stage 模型），以 HAR 形式提供。

1. 登记 bundleName

打开 应用统计 › 配置 › SDK 代码，点「添加应用标识」，填入应用的 bundleName。未登记的 bundleName 发来的数据会被采集端丢弃。

2. 添加依赖包

包名是 @tapcub/harmony，目前还没有发布到 OHPM 中心仓。在那之前，克隆公开的 tapcub-sdk 仓库，在工程的 oh-package.json5 里用本地路径引用：

"dependencies": {
  "@tapcub/harmony": "file:../path/to/tapcub-sdk/packages/harmony"
}

然后运行 ohpm install。包发布之后，用 ohpm install @tapcub/harmony 替换本地路径即可；控制台安装代码里的命令如果不同，以控制台为准。

如果 App 开启了属性混淆，在 obfuscation-rules.txt 里加上：

-keep ./oh_modules/@tapcub/harmony

3. 初始化

import { TapCub } from '@tapcub/harmony';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    TapCub.preInit(this.context, { siteKey: 'YOUR_SITE_KEY' });
  }
}

// 用户同意隐私政策之后
await TapCub.init();

• preInit 只保存配置、绑定生命周期：不采集、不读设备信息、不联网。必须在 AbilityStage.onCreate 或 EntryAbility.onCreate 里调用，否则冷启动和头一个页面会丢。
• 如果 App 不需要同意这一步，紧接着 preInit 调用 init。
• appId、appVersion、appBuild 默认取 bundleName、versionName 和 versionCode。
• 国内模式传 region: 'cn'，同意后调用 init，再调用 TapCub.grantConsent(['analytics'])。

4. 自动采集的内容

ArkUI 没有公开的全局点击拦截，所以点击不会自动采集，要在组件里上报：

Button('立即购买').onClick(() => {
  TapCub.trackClick('buy', '立即购买');
});

TapCub.ignoreScreen('Splash') 跳过某个页面。HarmonyOS 上暂不支持帧率和内存采样。

5. 事件和身份

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

TapCub.login('USER_ID');
TapCub.setProps({ plan: 'pro' });
TapCub.logout();

login 的第三个参数是标识类型（默认 'login'）；'email' 和 'mobile' 会先哈希。项目不是实名模式时 login 会被忽略。见识别用户。

6. 验证

在真机或模拟器上运行 App，打开 应用统计 › 概览 › 实时，几秒内应能看到启动事件。

隐私和存储

SDK 只声明 ohos.permission.INTERNET，只有 App 自己声明了 GET_NETWORK_INFO 才读取网络类型。不访问位置、通讯录或剪贴板。设备 ID 基于 ODID（同一开发者的应用共享，恢复出厂设置后重置）。待发送事件以文件形式存在沙箱里（默认 8 MB、1 万条或 7 天）。

排查

• 报 TapCub.preInit(context, config) first： 有调用发生在 preInit 之前。
• 报 siteKey required： 站点 Key 为空。
• 没有数据： bundleName 没登记，或者从没调用 init。
• 没有点击： 在 onClick 里加 trackClick。
• 对某个用户停止采集： TapCub.optOut()，optIn() 恢复。

相关

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