Web Event SDK 接入指南

在客户网站中安装一次 SDK，在关键业务行为成功发生时调用事件。SDK 会负责生成事件 ID、保存待发送事件、批量请求和失败重试。

客户页面→Web Event SDK→统一事件服务

1. 安装 SDK

把下面代码放进所有页面的 <head>。服务方会为每个网站分配一个 token，请勿在不同网站之间混用。

<script>
  window.EventRelay = window.EventRelay || [];
</script>
<script
  async
  src="https://pwa.qqqmob.com/event.js?v=20260110"
  data-token="token"
  data-require-consent="true">
</script>
请将示例中的 token 替换成服务方提供的实际值。v=20260110 是当前发布版本，请勿自行删除或修改，也不要修改 SDK 文件或采集接口地址。
安装参数是否必填说明
data-token是当前网站的公开接入标识，不是密码或服务端密钥
data-require-consent否true 表示获得授权前不保存或发送事件
data-click-param否归因参数名，默认是 cid
data-debug否联调时可设为 true，正式环境请删除

3. 调用事件

统一调用格式如下。该写法在 SDK 加载完成前后都可以使用：

window.EventRelay.push(["track", "事件名称", {
  参数名: "参数值"
}]);

页面浏览

window.EventRelay.push(["track", "page_view"]);

搜索

window.EventRelay.push(["track", "search", {
  query: "running shoes"
}]);

加入购物车

window.EventRelay.push(["track", "add_to_cart", {
  content_id: "sku_123",
  content_type: "product",
  content_name: "Running shoes",
  price: 9.9,
  quantity: 2,
  currency: "USD"
}]);

购买成功

window.EventRelay.push(["track", "purchase", {
  content_id: "sku_123",
  content_type: "product",
  content_name: "Annual membership",
  value: 19.8,
  currency: "USD",
  price: 9.9,
  quantity: 2
}]);

多商品购买

window.EventRelay.push(["track", "purchase", {
  value: 29.8,
  currency: "USD",
  items: [
    {content_id: "sku_123", price: 9.9, quantity: 1},
    {content_id: "sku_456", price: 19.9, quantity: 1}
  ]
}]);
purchase 必须在支付真正成功后触发。点击支付按钮、进入收银台或创建订单，都不能代替支付成功事件。

4. 支持的事件名称

只使用下表中的固定事件名，不要自行创建事件名。

事件名触发时机必填参数
page_view页面或 SPA 路由展示完成无
content_view商品或内容详情展示无
button_click关键按钮被点击无
form_submit表单成功提交无
search用户完成搜索query
add_to_cart商品成功加入购物车无
add_payment_info支付信息添加成功无
checkout_started结账流程开始无
order_placed订单创建成功value
purchase支付或购买成功value
registration_completed注册完成无
wishlist_added成功加入收藏无
subscription_completed订阅完成无
first_deposit首次入金完成无
contact联系或咨询成功无
download下载开始无
credit_approval授信审批完成无
loan_application贷款申请提交无
loan_credit贷款审批通过无
loan_disbursal贷款放款完成无
credit_card_application信用卡申请提交无
key_event业务关键事件无
key_event_1业务关键事件 1无
key_event_2业务关键事件 2无
key_event_3业务关键事件 3无
ad_view页面内广告展示无
ad_click页面内广告点击无

5. 事件参数

参数类型说明
content_idString商品或内容 ID
content_typeString单商品传 product，商品组传 product_group
content_categoryString页面、商品或内容分类
content_nameString页面、商品或内容名称
currencyString大写币种代码；当前支持 BRL、IDR、USD
valueNumber订单总金额；purchase、order_placed 必填
priceNumber单件商品价格
quantityNumber商品数量
queryString搜索关键词，供 search 使用
itemsArray<Object>多商品列表；每项可包含商品 ID、单价、数量等参数

金额规则

所有金额使用数字，不要加币种符号或千位分隔符。例如 2 件商品、单价 10 美元，应传 price: 10、quantity: 2、value: 20、currency: "USD"。

数据安全

不要通过事件参数发送姓名、手机号、邮箱、身份证、银行卡、密码或其他个人敏感信息。页面 URL 的查询参数不会被 SDK 自动上传。

6. 点击归因参数

广告或跳转链接可能在落地页上携带 cid：

https://customer.example/landing?cid=OPAQUE_TOKEN

客户网站的 301/302 跳转、登录跳转、语言切换和 URL 规范化必须保留 cid。获得用户授权后，SDK 会保存该令牌 30 天，后续事件不需要手工传入。

7. SDK 发出的请求

客户业务代码只调用 EventRelay，不要直接请求采集接口。SDK 会自动发送：

POST https://event.qqqmob.com/collect
Content-Type: text/plain;charset=UTF-8

请求体示例：

{
  "version": 1,
  "token": "token",
  "sent_at": "2026-08-26T08:00:00.000Z",
  "events": [{
    "event_id": "generated-event-id",
    "name": "purchase",
    "occurred_at": "2026-08-26T07:59:59.000Z",
    "data": {"value": 19.8, "currency": "USD"},
    "page": {"origin": "https://customer.example", "path": "/success"},
    "attribution": {"click_id": "opaque-token"}
  }]
}
  • HTTP 2xx：事件已被采集服务接收。
  • HTTP 4xx：token、域名、事件或参数不合法。
  • HTTP 408、429 或 5xx：SDK 会保留事件并延迟重试。

如果网站启用了严格 CSP，需要放行：

script-src https://pwa.qqqmob.com
connect-src https://event.qqqmob.com

8. 联调与验收

  1. 使用服务方提供的测试 token 和带 cid 的测试链接打开客户页面。
  2. 在浏览器开发者工具 Network 面板确认 https://pwa.qqqmob.com/event.js?v=20260110 返回 HTTP 200。
  3. 完成一次真实测试动作，确认 https://event.qqqmob.com/collect 返回 HTTP 202 或其他 2xx。
  4. 确认请求中的事件名、金额、币种和商品 ID 与实际业务一致。
  5. 由服务方确认事件已进入后台并完成最终验收。

单页应用需要在每次路由页面真正展示后调用一次 page_view。同一业务结果不要重复调用；SDK 会生成事件 ID，服务端也会进行重复事件检查。