@seaart/spm-sdk

SeaArt SPM 埋点 SDK，支持自动获取规则并标记 DOM，同时采集点击、曝光、滚动、焦点、页面访问和自定义事件。

安装

npm install @seaart/spm-sdk

使用

import SpmSDK from '@seaart/spm-sdk';

SpmSDK.init({
  projectId: 'your-project-id',
  baseURL: 'https://api.example.com',
  appId: 'web_app',
  version: '1.1.8',
});

SpmSDK.setUserInfo({
  user_id: 'user-123',
});

SpmSDK.track('custom_submit', 'page|form|submit', {
  form_type: 'contact',
});

SDK 初始化后会自动监听 URL 变化、获取打点规则、标记 x-spm-code 元素并上报事件。

浏览器脚本也可以直接使用构建产物：

<script src="node_modules/@seaart/spm-sdk/dist/spm-sdk.umd.js"></script>
<script>
  window.SpmSDK.init({ projectId: 'your-project-id' });
</script>

配置

| 参数 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | projectId | 是 | - | SPM 项目 ID | | baseURL | 否 | - | 透传给 @seaart/request-seaart 的请求基础地址；配置后规则和上报请求都使用该地址 | | apiEndpoint | 否 | https://aiart-auto-capture.dev.seaart.dev | 规则接口地址 | | reportEndpoint | 否 | https://aiart-openresty.dev.seaart.dev | 事件上报地址 | | namespace | 否 | release | 规则环境 | | appId | 否 | web_app | 应用 ID | | version | 否 | 1.0.0 | 上报的 SDK/应用版本 | | lang | 否 | [] | URL 多语言前缀 | | enableLog | 否 | false | 是否输出调试日志 | | enableAutoTracking | 否 | true | 是否监听 URL 变化 | | enableDynamicTracking | 否 | true | 是否监听动态 DOM | | token | 否 | Cookie T | 请求认证 Token |

配置 baseURL 后，请求路径为 /api/auto-capture/page/rules/fetch 和 /log/v1/standard_report；未配置时继续使用 apiEndpoint 和 reportEndpoint。

规则请求和事件上报均使用 @seaart/request-seaart 的 SeaArt 请求协议。由于该依赖当前 npm 版本包含 workspace:* 元数据，本包在构建产物中内置了请求内核，消费者安装本包时无需额外安装请求依赖。

API

SpmSDK.init(options)
SpmSDK.setUserInfo(userInfo)
SpmSDK.getUserInfo()
SpmSDK.clearUserInfo()
SpmSDK.track(eventName, spm, customProperties)
SpmSDK.trackClick(spm, customProperties)
SpmSDK.trackExposure(spm, customProperties)
SpmSDK.flush()
SpmSDK.refreshCurrentPage(forceReload)
SpmSDK.notifyUrlChange(path)
SpmSDK.getVersion()
SpmSDK.destroy()

DOM 属性

<button
  x-spm-code="page|button|submit"
  data-obj-id="button-1"
  data-conan-custom='{"campaign_id":"summer"}'
>
  提交
</button>

data-conan-custom 支持任意 JSON 字段；单独的 data-* 属性会覆盖 JSON 中同名字段。

开发

pnpm --filter @seaart/spm-sdk build
pnpm --filter @seaart/spm-sdk test