怎么在微信小程序里接入 TapCub？

简短回答

在 小程序统计 › 配置 › SDK 代码 登记小程序的 AppID，在微信公众平台把 https://api.pathclue.com 加进小程序的 request 合法域名，安装 @tapcub/miniprogram 并在微信开发者工具里构建 npm，然后在 app.js 里调用 TapCub.preInit({ siteKey, appId }) 和 TapCub.init()。启动、页面浏览和页面停留时间会自动采集。到 小程序统计 › 概览 › 实时 看 $mp_launch。

1. 登记 AppID

打开 小程序统计 › 配置 › SDK 代码，点「添加应用标识」，填入小程序的 AppID（以 wx 开头）。未登记的 AppID 发来的数据会被采集端丢弃，小程序里不会报错。

2. 配置合法域名

在微信公众平台进入 开发 › 开发管理 › 服务器域名，把下面这个地址加进 request 合法域名：

https://api.pathclue.com

不加的话，正式环境里请求根本发不出去。（在开发者工具里可能察觉不到，因为那里可以关掉域名校验。）

3. 安装 SDK

在小程序项目根目录：

npm install @tapcub/miniprogram

然后在微信开发者工具里选 工具 › 构建 npm，把包复制进 miniprogram_npm。

4. 初始化

在 app.js 里：

import { TapCub } from '@tapcub/miniprogram/wx';

TapCub.preInit({
  siteKey: 'YOUR_SITE_KEY',
  appId: 'YOUR_APPID',
});

App({
  onLaunch() {
    TapCub.init();
  },
});

• appId 必须是登记过的 AppID。采集地址已内置；除非 TapCub 给了你专用地址，否则不要填 endpoint。
• preInit 会挂上 App 和 Page 的生命周期，不用自己转发 onLaunch 或 onShow。
• 国内模式： 传 region: 'cn'，用户同意后才调用 init，并调用 TapCub.grantConsent(['analytics'])，否则不会发送任何事件。

5. 自动采集的内容

• 冷启动： $mp_launch 和 $mp_show，带场景值。
• 页面： 页面显示时发送 $mp_view_screen；隐藏时发送 $mp_page_leave，带停留时长。
• 点击： 默认关闭；在 preInit 里传 autoTrack: true 才采集。

如果框架不能改写全局 Page，就逐个包装页面：

import { wrapPage } from '@tapcub/miniprogram/wx';
Page(wrapPage({ /* 页面配置 */ }));

自定义视图调用 TapCub.trackScreen('名称')。

6. 事件和身份

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

TapCub.login(openid, {}, { type: 'openid' });
TapCub.logout();

事件名最长 100 个字符，自定义属性最多 30 个，字符串值最长 200 个字符。登录 ID 最长 200 个字符。要在小程序、App 和网站之间打通 openid、unionid 和你自己的用户 ID，见小程序上的身份识别。

7. 验证

在手机上预览小程序（开着域名校验），打开 小程序统计 › 概览 › 实时，几秒内应能看到 $mp_launch。再到 渠道与分享 › 场景值分析 看场景值，到 页面与事件 › 页面 看页面。

隐私

SDK 不读取位置、通讯录或剪贴板，所以不会给你的《用户隐私保护指引》增加隐私接口。本地队列最多保存 1 万条事件、7 天或 1 MB。请求失败（429、5xx、网络错误）时从 1 秒起退避，最长 300 秒，期间事件留在队列里。

排查

• 开发者工具里有数据，正式环境没有： request 域名没加进合法域名。
• 完全没有数据： AppID 没登记、缺 siteKey，或者没调用 init（国内模式下是用户还没同意）。
• 部分页面没有浏览： 这些页面没走被改写的 Page，用 wrapPage 或 trackScreen。
• login 没效果： ID 超过 200 个字符或是占位值，或者项目不是实名模式。

相关

• 小程序上的身份识别
• 追踪屏幕浏览
• 检查安装