SDK 接入文档

Appearance

Web SDK 更新日志 ​

v1.2.0 · 2026-09-18 ​

相对 v1.1.9：运行时 sdk_version 更新为 1.2.0；帖子创建时间字段改名。其余帖子 / 剧集客户端范围、指纹 3.0.1、关键词与剧集播放取值沿用 v1.1.9。

变更 ​

  • postEvent.create_time → post_create_time：帖子创建时间字段改名，业务需改传 post_create_time（不要再传 create_time）。
  • uid 长度约束：未登录可传空字符串；非空时长度必须 ≥ 4（init / setUid / setContext 均适用）。
  • novelEvent.page_no：普通小说从 1 开始；仅有声小说允许上报 0，其他类型不得为 0。

升级须知 ​

  1. postEvent 请传 post_create_time，不要再传 create_time。
  2. 登录态 uid 长度须 ≥ 4。
  3. 有声小说以外的小说事件不要上报 page_no = 0。
  4. 服务端 eventCodes 仍需包含 post_event、drama_event、drama_status_change；继续接受 fp_version = 3.0.1。

v1.1.9 · 2026-09-17 ​

新增（2026-09-09） ​

  • 帖子分析日志（客户端）：postEvent（post_event）。点赞 / 评论 / 收藏 / 解锁为服务端上报。
  • 剧集分析日志（客户端）：dramaEvent（drama_event）、dramaStatusChange（drama_status_change）。点赞 / 评论 / 收藏 / 解锁为服务端上报。
  • videoEvent 字段：新增必填 play_speed（播放倍速 × 100，例如 1.25 倍传 125）；新增 post_id（仅 video_content_type 为 post_video 时必填）；video_content_type 增加 post_video。视频帖播放仍走 videoEvent，不走 postEvent。

变更（2026-09-16） ​

  • 设备指纹 fp_version → 3.0.1：指纹因子去掉 language、timezone（二者仍可作为环境字段上报）；canonical 前缀仍为 fp_v3。
  • 指纹持久化：首次生成后写入 localStorage['__web_sdk_device_fp__']，之后优先读取已有值，不因语言 / 时区变化重算；清除站点存储后才会重新生成。

变更（2026-09-17） ​

  • 帖子 / 剧集客户端范围收敛：Web SDK 仅保留客户端方法 postEvent、dramaEvent、dramaStatusChange；移除 postLike / postComment / postCollect / postUnlock / dramaLike / dramaComment / dramaCollect / dramaPurchase（改由服务端上报）。
  • dramaEvent 播放行为：play_behavior_key 新增 ep_complete（播放完成）、ep_share（分享）。
  • 关键词事件枚举：keywordSearch.search_content_type / search_id、keywordClick.click_item_type_key 新增 post、short_drama。

升级须知 ​

  1. 服务端 eventCodes 需同步加入帖子 / 剧集客户端 3 个 event 字符串（post_event、drama_event、drama_status_change），否则 SDK 会拦截上报。
  2. 服务端应接受 fp_version = 3.0.1；升级后首次访问可能生成新指纹值。
  3. 若业务曾调用已移除的点赞 / 评论 / 收藏 / 解锁客户端方法，请改为服务端上报。

v1.1.8 · 2026-08-06 ​

新增 ​

  • disableAutoEvents：init 新增自动上报禁用名单（默认 []）。写入名单的事件关闭 SDK 自动上报，未列出的保持默认开启；不影响手动 WebSDK.track.*。合法值：sdk_init、app_lifecycle、network_state_change、app_session_summary、app_page_view、page_click；未知值忽略并 warn。
  • adError.ad_id：广告错误事件新增 ad_id（必填，允许空字符串）；有创意 ID 则传，没有传 ''。
  • adFill / adImpressionSdk 跳过与关闭标记：新增必填 is_skippable、is_closable（int，1/0），分别映射后端 show_skip_button / show_close_button。

变更 ​

  • 关闭自动 app_page_view（disableAutoEvents: ['app_page_view']）时：SDK 不再自动发送该事件，也不写入自动 PV 预记指标；页面上下文跟踪与自动 page_click 不受影响。手动 WebSDK.track.appPageView(...) 仍走严格字段校验，并由 SDK 补全 page_id、page_enter_ts、page_url、viewport_width、viewport_height。
  • page_click 坐标口径：click_page_x/y 改为视口坐标（与 click_viewport_* / clientX/Y 一致）；文档坐标仅保留在 click_document_*。自动点击的 click_x/y_percent 继续按 viewport 计算；手动上报请按视口口径传入。

修复 ​

  • page_click 滚动字段：scroll_top / scroll_left 上报前 Math.round，避免出现小数。
  • page_click 坐标夹取：异常负值与越界值夹到合法区间；不可用仍为 -1。

升级须知 ​

关闭自动 PV 示例：

javascript
WebSDK.init({
  appId: "1",
  channel: "organic",
  encryptedConfig: "...",
  disableAutoEvents: ["app_page_view"],
});

v1.1.7 · 2026-07-22 ​

本次为 bug 修复版本，零破坏性变更，现有接入代码无需修改。

修复 ​

  • network_state_change 网络状态一致性：修正 Network Information API 与 navigator.onLine 不一致时的上报值——connection_type 为 none 但实际在线时改为 unknown；已识别到具体连接类型却被标为离线时，将 is_online 纠正为在线。
  • 批量上报接口路径修正：事件批量上报地址由 /api/eventTracking/batchReport 改为 /api/eventTracking/batchReport.json，与服务端实际路径对齐，避免上报 404。
  • page_load_time 默认值修正：页面加载耗时无法从 Performance API 获取时，默认值由 -1 改为 0，避免异常默认值进入上报。
  • 会话存储收敛到 sessionStorage：sid / 会话元数据不再写入 localStorage 与 Cookie，仅保存在 sessionStorage，避免跨标签页会话串扰与 Cookie 残留。
  • 清理历史会话残留：首次访问时自动删除旧版写入的 localStorage 会话键，并将历史会话 Cookie 置为过期（max-age=0），防止沿用失效会话数据。

v1.1.6 · 2026-07-10 ​

新增 ​

  • 自动采集事件：init() 成功后 SDK 自动启动采集，无需额外配置，覆盖以下事件：
    • app_page_view — 页面浏览（首屏加载、SPA 路由变化）
    • page_click — 页面点击
    • app_lifecycle — 应用生命周期（cold_start / web_load / warm_start / foreground / background / web_unload 等）
    • sdk_init — SDK 初始化完成
    • network_state_change — 网络状态变化
    • app_session_summary — 会话结束摘要（停留时长、页面数、点击数、滚动行为等）
  • notifyPageLoad()：SPA 客户端路由跳转完成后调用，通知 SDK 开始新页面统计。

优化 ​

  • 设备指纹增强：采集维度扩展（操作系统、浏览器内核、屏幕参数、Canvas / WebGL / Audio 指纹、字体哈希等），用于生成 device_fingerprint。
  • 上报签名升级：签名算法升级至 sig_v2。

v1.1.5 · 2026-06-08 ​

新增 ​

  • 广告 SDK 事件：新增 8 个广告 SDK 侧事件，覆盖广告请求、填充、展示、点击、关闭、错误等生命周期：
    • adRequest — 广告请求
    • adFill — 广告填充成功
    • adNoFill — 广告无填充
    • adLoadSuccess — 广告加载成功
    • adImpressionSdk — 广告展示（SDK 侧）
    • adClickSdk — 广告点击（SDK 侧）
    • adClose — 广告关闭
    • adError — 广告错误
  • appPageitemExposure / appPageitemClick 字段扩展：新增 recommend_id、recommend_trace_info 字段。
  • IM 事件：新增 4 个 IM 即时通讯事件：
    • imEvent — IM 行为事件
    • imConversationView — IM 会话列表曝光
    • imConnectionSuccess — IM 连接成功
    • imMessageContent — IM 消息内容

v1.1.4 · 2026-06-05 ​

新增 ​

  • appPageitemExposure 事件：新增应用内容项曝光事件，支持上报内容项曝光数据，包含 item_id、item_type、item_name、parent_item_id、page_key、page_name 等字段。
  • appPageitemClick 事件：新增应用内容项点击事件，支持上报内容项点击数据，包含 item_id、item_type、item_name、parent_item_id、position、page_key、page_name 等字段。

v1.1.3 · 2026-04-18 ​

优化 ​

  • 去重策略优化：优化 event_id 算法，提高去重效率。

v1.1.2 · 2026-04-17 ​

修复 ​

  • event_id 重复使用问题：修复同一 event_id 在不同批次中被重复上报的缺陷。

新增 ​

  • appVersion 支持外部传入：init 可传入自定义应用版本号，默认值为 1.0.0。

优化 ​

  • 去重策略升级：改为基于 event_id 队列实现跨批次去重，提升事件去重准确性。

v1.1.1 · 2026-04-16 ​

新增 ​

  • init 新增 deviceId 可选配置：业务侧可在初始化时传入自定义设备 ID，不传则由 SDK 自动生成并持久化。
  • 公共字段 sdk_version：自动注入，来自 SDK 内部版本常量，业务无需传入。
  • 公共字段 app_version：业务应用版本号，init 传入全局默认，可通过 setContext 动态覆盖。

v1.0.9 · 2026-04-14 ​

暂无更新说明。