Browser SDK

16 days ago

2b8f4fa

Browser SDK

适用版本：@entmesh/browser-sdk@0.7.0。Browser SDK 支持 ESM、UMD 和 TypeScript 类型，默认采集页面访问、SPA 路由、点击、出站链接、滚动深度、可见时长和退出事件。

前置条件

当前环境的 Browser Key，格式为 pk_…；
Collector：https://collector.entmesh.mliev.com；
业务站点 Origin 已加入当前环境的来源白名单。

npm / ESM 安装

在业务项目的 .npmrc 中配置公开只读 Registry：

@entmesh:registry=https://npm.cnb.cool/mliev/npmjs/-/packages/

安装固定版本：

npm install @entmesh/browser-sdk@0.7.0

初始化一次：

import { identify, init, reset, track } from '@entmesh/browser-sdk'

init({
  writeKey: 'pk_替换为当前环境的BrowserKey',
  endpoint: 'https://collector.entmesh.mliev.com',
})

if (currentUser) {
  identify(String(currentUser.id), {
    account_type: currentUser.accountType,
  })
}

track('signup_completed', { plan: 'team' })

function onLogout() {
  reset()
}

React、Vue、Next.js、Nuxt 等应用应在客户端入口或挂载后的生命周期中调用；不要在服务端渲染阶段初始化，也不要在组件重复渲染时反复调用 init 或 identify。

HTML / UMD 接入

<script src="https://static.1ms.run/entmesh/sdk-js/v0.7.0/entmesh.umd.js"></script>
<script>
  Entmesh.init({
    writeKey: 'pk_替换为当前环境的BrowserKey',
    endpoint: 'https://collector.entmesh.mliev.com',
    fingerprint: true
  })

  Entmesh.track('signup_completed', { plan: 'team' })
</script>

生产环境使用固定版本 URL，不要把 latest 地址写进页面。脚本建议放在 </body> 前或由应用入口加载。

常用 API

API	用途
`init(options)`	初始化或重新初始化
`page(properties?)`	手动发送 `$page_view`
`track(name, properties?)`	发送业务事件；名称不能以 `$` 开头
`identify(userID, properties?)`	关联已登录用户并发送 `$identify`
`reset()`	退出登录时清除用户、匿名访客和会话
`consent(state)`	更新 `pending/grant/deny/revoke` 状态
`flush()`	立即尝试发送内存队列
`identityContext()`	生成供后端透传的加密身份字符串
`decide` / `decideMany`	获取 typed Flag 决策，不产生曝光
`expose` / `decideAndExpose`	记录曝光或完成决策加曝光

初始化参数

interface InitOptions {
  writeKey: string
  endpoint?: string
  consent?: 'pending' | 'grant' | 'deny' | 'revoke'
  queryAllowlist?: string[]
  autocapture?: boolean
  fingerprint?: boolean
  flushIntervalMs?: number
  batchSize?: number
}

官方托管接入必须显式设置 HTTPS endpoint。默认 autocapture: true、fingerprint: true、每 5 秒刷新、每批 20 条。除 utm_* 外，URL 查询参数只有列入 queryAllowlist 才会保留。

登录用户与首条页面事件

SDK 不读取业务登录态。页面刷新并恢复登录用户后，应再次调用 identify。使用稳定的内部业务主键，不要用昵称、手机号、邮箱、Session ID 或访问 Token。

默认初始化会立即发送首条 $page_view。如果首条页面事件必须带 UID：

import { identify, init, page } from '@entmesh/browser-sdk'

init({
  writeKey: 'pk_替换为当前环境的BrowserKey',
  endpoint: 'https://collector.entmesh.mliev.com',
  autocapture: false,
})

identify(String(currentUser.id))
page()

关闭自动采集后，宿主应用也需要自行发送路由和交互事件。

同意管理

import { consent, init } from '@entmesh/browser-sdk'

init({
  writeKey: 'pk_替换为当前环境的BrowserKey',
  endpoint: 'https://collector.entmesh.mliev.com',
  consent: 'pending',
})

consent('grant')  // 开始采集与发送
consent('deny')   // 清空队列并停止采集
consent('revoke') // 撤回同意并清除本地身份状态

pending 或 deny 时不会计算浏览器指纹。业务系统负责把 CMP 或隐私设置的变化同步给 SDK。

向 Go 后端透传浏览器身份

import { identityContext } from '@entmesh/browser-sdk'

const value = await identityContext()
await fetch('/api/orders', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    ...order,
    ...(value ? { identity_context: value } : {}),
  }),
})

结果是不超过 4 KiB 的 emctx1… 加密字符串。生成失败时返回空字符串，业务请求必须照常发送。不要解码、修改、记录或用它鉴权；后端 UserID 仍必须来自可信登录态。

自定义事件属性

track('order_created', {
  order_id: 'order-1001',
  amount: 199,
  paid: true,
  tags: ['new-user', 'campaign-a'],
})

属性支持字符串、数字、布尔值、null、上述标量数组，以及一层标量对象。