小程序 SDK（预览）

16 days ago
5000cbc

小程序 SDK（预览）

预览状态：微信、支付宝、抖音适配源码已公开，但 @entmesh/miniapp-sdk 尚未发布到 npm Registry。不要执行不存在的 Registry 安装命令，也不要把未固定的 main 分支作为稳定生产依赖。

源码：cnb.cool/mliev/entmesh/sdk-miniapp

构建预览制品

git clone --depth 1 https://cnb.cool/mliev/entmesh/sdk-miniapp
cd sdk-miniapp
npm ci
npm test
npm run lint
npm run build

把构建后的对应平台入口作为本地依赖接入测试项目；正式 npm 版本发布后，再替换成带精确版本号的 Registry 依赖。

控制台和平台准备

  1. 在当前环境登记微信、支付宝或抖音小程序 AppID。
  2. 保存当前环境的 ck_… Client Key。
  3. 在小程序平台配置合法请求域名：
https://collector.entmesh.mliev.com

初始化

以微信为例，在 App 和 Page 注册之前创建客户端：

import { createClient } from '@entmesh/miniapp-sdk/wechat'

const entmesh = createClient({
  endpoint: 'https://collector.entmesh.mliev.com',
  clientKey: 'ck_替换为当前环境的ClientKey',
  applicationId: '替换为微信小程序AppID',
  consent: 'pending',
  autocapture: true,
})

await entmesh.consent('grant')
await entmesh.track('signup_completed', { plan: 'team' })

支付宝使用 @entmesh/miniapp-sdk/alipay，抖音使用 @entmesh/miniapp-sdk/douyin；applicationId 必须与控制台登记的平台和 AppID 一致。

生命周期与页面

SDK 在启用自动采集时包装平台 App/Page 生命周期，记录启动、前后台、页面访问、可见性和退出。必须在宿主调用 App()、Page() 前初始化，避免漏掉生命周期。

手动页面与事件：

await entmesh.page('/pages/checkout/index')
await entmesh.track('order_submitted', { order_id: 'order-1001' })

登录、退出与同意

await entmesh.identify('user-42', { account_type: 'team' })
await entmesh.reset()

await entmesh.consent('grant')
await entmesh.consent('deny')
await entmesh.consent('revoke')

退出页面或应用前可调用 flush()，停止计时器并刷新时调用 shutdown()。

SDK 使用平台安全随机数、存储和请求 API，不回退到 Math.random，不读取宿主设备广告标识，客户端批次必须加密后发送。网络或加密失败时保留有限持久队列等待重试。