Web Event SDK 接入指南

在客户网站中安装一次 SDK，在关键业务行为成功发生时，使用统一的 eid + data 格式发送事件。

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

1. 安装 SDK

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

<script type="text/javascript" src="https://pwa.suncentads.com/event.js?v=20260110" data-token="token"></script>
请将示例中的 token 替换成服务方提供的实际值。v=20260110 是当前发布版本，请勿自行删除或修改，也不要修改 SDK 文件或采集接口地址。
安装参数是否必填说明
data-token是当前网站的公开接入标识，不是密码或服务端密钥

3. 调用事件

SDK 的运行文件异步加载。每次调用都先保留下面的初始化行，事件会在运行文件就绪后自动发送：

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

页面浏览

首次加载 SDK 时会自动发送基础页面浏览。下面的事件用于 SPA 路由切换或需要单独记录的页面内容展示。

window.EventRelay = window.EventRelay || [];
window.EventRelay.push({
  eid: "page_view",
  data: {}
});

搜索

window.EventRelay = window.EventRelay || [];
window.EventRelay.push({
  eid: "search",
  data: {
    query: "running shoes"
  }
});

加入购物车

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

购买成功

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

多商品购买

window.EventRelay = window.EventRelay || [];
window.EventRelay.push({
  eid: "purchase",
  data: {
    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 会把当前完整页面 URL 作为环境字段自动发送，因此 URL 查询参数也会随请求上传。

6. 点击归因参数

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

https://customer.example/landing?pixel_click_id=OPAQUE_TOKEN&utm_source=oks

客户网站的 301/302 跳转、登录跳转、语言切换和 URL 规范化必须原样保留广告系统附加的查询参数，包括 pixel_click_id、_oks_ft、_oks_ext 和 utm_source。SDK 会自动读取并保存归因信息，后续事件不需要手工传入。

7. SDK 发出的请求

客户业务代码只调用 EventRelay，不要直接请求采集接口。SDK 加载时会使用 GET 自动发送基础页面浏览；业务事件优先使用 Beacon POST：

GET  https://event.suncentads.com/collect?...pageview fields...
POST https://event.suncentads.com/collect

事件请求体会包含事件数据、点击归因、浏览器标识和页面环境；以下仅展示常见字段：

{
  "v": 1,
  "token": "token",
  "_cid": "browser-identifier",
  "ft": "opaque-click-token",
  "type": "event",
  "dl": "https://customer.example/landing",
  "dh": "customer.example",
  "dt": "Page title",
  "ua": "Browser User-Agent",
  "eid": "purchase",
  "data": {
    "value": 19.8,
    "currency": "USD"
  }
}
  • HTTP 2xx：事件已被采集服务接收。
  • HTTP 4xx：token、事件名称或请求格式不合法。
  • HTTP 5xx：采集服务暂时不可用。

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

script-src https://pwa.suncentads.com
connect-src https://event.suncentads.com https://m1.openfpcdn.io
img-src https://event.suncentads.com

8. 联调与验收

  1. 使用服务方提供的测试 token 和带 pixel_click_id 的测试链接打开客户页面。
  2. 在浏览器开发者工具 Network 面板确认 https://pwa.suncentads.com/event.js?v=20260110 返回 HTTP 200。
  3. 确认异步运行文件和自动 pageview 请求加载成功，并完成一次真实测试动作。
  4. 确认 https://event.suncentads.com/collect 请求返回 HTTP 2xx，事件请求中存在对应的 ft 归因值。
  5. 确认请求中的事件名、金额、币种和商品 ID 与实际业务一致。
  6. 由服务方确认事件已进入后台并完成最终验收。

单页应用需要在每次路由页面真正展示后调用一次 page_view。同一业务结果不要重复调用。