Web SDK

具体的事件上报参数说明，参考文档：Lark 链接　密码：@8228T56

下载 SDK

不同框架引入方式

1）`import` 引入（适合 Vue / React 工程化项目）

当前产物是 UMD 文件，import 方式建议做"副作用引入"，然后通过 window.WebSDK 使用：

javascript

// main.js / App.tsx
import "/web-sdk-v1.2.0.js";

window.WebSDK.init({
  appId: "1",
  uid: "",
  channel: "test",
  encryptedConfig: "jzzemX+UqICBr9/PIK62ENqIEXIaxKInHEYHeKcGXv1M...",
});

2）`script` 直引

html

<script src="./web-sdk-latest.js"></script>
<script>
  window.WebSDK.init({
    appId: "1",
    uid: "",
    channel: "test",
    encryptedConfig: "jzzemX+UqICBr9/PIK62ENqIEXIaxKInHEYHeKcGXv1M...",
  });
</script>

3）JS 注入

原生页面推荐使用脚本注入（GA 风格队列），可保证 SDK 未加载完成前事件先入队，不丢首屏事件：

html

<script>
  (function (i, s, o, g, r) {
    i[r] =
      i[r] ||
      function () {
        var args = Array.prototype.slice.call(arguments);
        return new Promise(function (resolve, reject) {
          (i[r].q = i[r].q || []).push({
            args: args,
            resolve: resolve,
            reject: reject,
          });
        });
      };
    var a = s.createElement(o);
    var m = s.getElementsByTagName(o)[0];
    a.async = 1;
    a.src = g;
    m.parentNode.insertBefore(a, m);
  })(window, document, "script", "./web-sdk-latest.js", "tracker");

  (function () {
    var timer = setInterval(function () {
      if (!window.WebSDK) return;
      clearInterval(timer);
      window.WebSDK.init({
        appId: "1",
        uid: "",
        channel: "test",
        encryptedConfig: "jzzemX+UqICBr9/PIK62ENqIEXIaxKInHEYHeKcGXv1M...",
      });
      var queued = (window.tracker && window.tracker.q) || [];
      var real = function () {
        return window.WebSDK.track.apply(window.WebSDK, arguments);
      };
      window.tracker = real;
      queued.forEach(function (item) {
        real.apply(null, item.args).then(item.resolve).catch(item.reject);
      });
    }, 30);
  })();
</script>

初始化

javascript

WebSDK.init({
  appId: "1",
  uid: "",
  channel: "organic",
  encryptedConfig: "jzzemX+UqICBr9/PIK62ENqIEXIa...", // 加密配置串（必传）
  appVersion: "1.0.0",  // 可选，业务应用版本号
  deviceId: "custom_device_id", // 可选，自定义设备 ID；不传则 SDK 自动生成
  disableAutoEvents: [], // 可选，自动上报禁用名单
  batchIntervalMs: 5000, // 可选，默认 5000ms
  batchMaxSize: 20, // 可选，默认 10 条
  pingTimeoutMs: 1500, // 可选，测速超时毫秒
});

参数	类型	必填	默认值	说明
`appId`	`string`	是	-	平台分配的应用 ID
`uid`	`string`	否	`""`	用户 ID；未登录传空字符串。非空时长度必须 ≥ 4
`channel`	`string`	是	-	渠道标识
`encryptedConfig`	`string`	是	-	AES-GCM 加密配置串，包含域名列表和事件白名单
`appVersion`	`string`	否	`"1.0.0"`	业务应用版本号，随每条事件上报
`deviceId`	`string`	否	-	自定义设备 ID，不传则 SDK 自动生成并持久化
`disableAutoEvents`	`string[]`	否	`[]`	自动上报禁用名单。命中则关闭对应事件的 SDK 自动上报；未命中保持默认。合法值：`sdk_init` / `app_lifecycle` / `network_state_change` / `app_session_summary` / `app_page_view` / `page_click`。不影响手动 `WebSDK.track.*`
`batchIntervalMs`	`number`	否	`5000`	批量上报间隔（毫秒）
`batchMaxSize`	`number`	否	`10`	触发立即上报的队列阈值（条数）
`pingTimeoutMs`	`number`	否	`1500`	域名测速超时（毫秒）

动态更新 UID / Channel

javascript

// 登录后设置 uid
WebSDK.setUid("user_123");

// 切换渠道
WebSDK.setChannel("ad_abc");

// 批量更新
WebSDK.setContext({ uid: "user_123", channel: "ad_abc" });

// 动态更新 app_version
WebSDK.setContext({ app_version: "2.0.0" });

// 登出清空 uid
WebSDK.setUid("");

也可以统一使用 setContext：

javascript

WebSDK.init({ appId: "1", uid: "", channel: "organic" });

// 注册/登录后更新 uid
WebSDK.setContext({ uid: "user_123" });

// channel 变化后更新
WebSDK.setContext({ channel: "ad_abc" });

// 登出后清空 uid
WebSDK.setContext({ uid: "" });

更新后，后续事件自动带最新的 uid / channel。

uid 约束：未登录可传空字符串；登录后传入的 uid 长度必须 ≥ 4（init / setUid / setContext 均适用）。

获取公共字段

javascript

// 获取全部公共字段
const all = await WebSDK.getCommonFields();

// 获取指定字段
const part = await WebSDK.getCommonFields([
  "device_id",
  "device_fingerprint",
  "fp_version",
  "sid",
]);

// 获取单个字段
const deviceId = await WebSDK.getCommonField("device_id");

公共字段列表

每条上报事件自动携带以下公共字段（顶层）：

字段	说明
`app_id`	应用 ID（`init` 传入）
`app_version`	业务应用版本号；优先级：① `init` 传入全局默认 → ② `setContext` 动态覆盖
`channel`	渠道（`init` 传入，可动态更新）
`client_ts`	客户端时间戳（秒）
`device`	设备类型：`Android` / `iOS` / `PC`
`device_brand`	设备品牌（如 `Apple`、`Samsung`）
`device_model`	设备型号（如 `iPhone`、`SM-S9180`）
`device_id`	设备标识（`localStorage` 持久化随机 ID）
`device_fingerprint`	设备指纹（多特征哈希；首次生成后写入 `localStorage['__web_sdk_device_fp__']`，之后优先读取；失败传空）
`fp_version`	指纹算法版本号（当前 `3.0.1`；仅指纹算法变更时升级；指纹为空时该字段也为空）
`sid`	会话 ID（按天轮换）
`sdk_version`	SDK 版本号（自动注入，当前 `1.2.0`，业务无需传入）
`uid`	用户 ID（`init` 传入，可动态更新；未登录可为空，非空时长度必须 ≥ 4）
`user_agent`	浏览器 UA

业务自定义字段统一放在 payload 内。

设备指纹说明（`fp_version` 3.0.1）

参与计算的因子含操作系统、浏览器内核 / 平台、屏幕参数、Canvas / WebGL / Audio、字体 / 插件哈希等；不含 language、timezone（二者仍可出现在环境采集字段中）。
首次生成后写入 localStorage['__web_sdk_device_fp__']，之后优先读取；清除站点存储后才会重新生成。
服务端应按 fp_version 区分规则；升级到当前构建后首次访问可能得到新指纹值。

自动采集事件

init() 成功后 SDK 自动启动采集，无需额外配置。以下事件由 SDK 自动上报，业务方无需手动调用 track()：

事件名	说明	触发时机
`app_page_view`	页面浏览	首屏加载、SPA 路由变化（监听 `pushState` / `popstate` / `hashchange`）
`page_click`	页面点击	用户点击页面任意区域
`app_lifecycle`	应用生命周期	`cold_start` / `web_load` / `warm_start` / `foreground` / `background` / `web_unload` 等
`sdk_init`	SDK 初始化	`init` 成功时
`network_state_change`	网络状态变化	浏览器网络连接状态变化时
`app_session_summary`	会话摘要	会话结束时（空闲超时、页面卸载等），含停留时长、页面数、点击数、滚动行为等

如需关闭部分自动上报，在 init 传入 disableAutoEvents（例如 ['app_page_view']）。关闭自动 PV 后仍可手动调用 WebSDK.track.appPageView(...)；SDK 会继续维护页面上下文并补全内部字段。

SPA 路由页面加载通知

SPA 应用在完成客户端路由跳转后，可调用 notifyPageLoad() 通知 SDK 开始新页面统计：

javascript

// 路由跳转完成后
WebSDK.notifyPageLoad();

手动上报事件

v1.2.0 起帖子 / 剧集客户端事件 3 个。服务端 eventCodes 需同步加入对应 event 字符串，否则 SDK 会拦截上报：post_event、drama_event、drama_status_change。点赞 / 评论 / 收藏 / 解锁由服务端上报，Web SDK 不提供对应方法。postEvent 创建时间字段为 post_create_time（不再使用 create_time）。

1. 导航路径行为

示例代码:

javascript

window.WebSDK.track.navigation({
  navigation_key: "home",
  navigation_name: "首页",
});

参数说明:

字段	类型	必填	说明
navigation_key	string	是	导航键
navigation_name	string	是	导航名称

2. 应用页面展示日志

示例代码:

javascript

window.WebSDK.track.appPageView({
  page_key: "detail",
  page_name: "详情页",
});

参数说明:

字段	类型	必填	说明
user_type	string	否	用户类型
page_key	string	否	页面键
page_name	string	否	页面名称
referrer_page_key	string	否	来源页面键
referrer_page_name	string	否	来源页面名称
current_page_key	string	否	当前页面键
current_page_name	string	否	当前页面名称
page_load_time	int	否	页面加载时间
recommend_trace_id	string	否	推荐追踪ID

3. 应用点击事件

示例代码:

javascript

window.WebSDK.track.pageClick({
  page_key: "home",
  page_name: "首页",
  click_page_x: 100,
  click_page_y: 200,
  click_x_percent: 50,
  click_y_percent: 60,
  screen_width: 1920,
  screen_height: 1080,
  recommend_trace_id: "trace123",
});

参数说明:

字段	类型	必填	说明
page_key	string	是	页面键
page_name	string	是	页面名称
click_page_x	int	是	点击 X（视口坐标，与 `clientX` / `click_viewport_x` 同口径）
click_page_y	int	是	点击 Y（视口坐标，与 `clientY` / `click_viewport_y` 同口径）
click_x_percent	int	是	点击 X 百分比（0–100，相对 viewport）
click_y_percent	int	是	点击 Y 百分比（0–100，相对 viewport）
screen_width	int	是	屏幕宽度
screen_height	int	是	屏幕高度
recommend_trace_id	string	否	推荐追踪ID

手动上报时 click_page_* / percent 请按视口口径传入；文档坐标由 SDK 补 click_document_*，不要写进 click_page_*。

4. 推荐列表内容展示

示例代码:

javascript

window.WebSDK.track.recommendListView({
  page_key: "recommend",
  page_name: "推荐页",
  recommend_content_type: "video",
  recommend_trace_id: "trace123",
  recommend_id: "rec123",
  recommend_trace_info: "recommend_info",
  client_version: "1.0.0",
});

参数说明:

字段	类型	必填	说明
page_key	string	是	页面键
page_name	string	是	页面名称
recommend_content_type	string	是	推荐内容类型 (video/novel/comic)
recommend_trace_id	string	是	推荐追踪ID
recommend_id	string	是	推荐ID
recommend_trace_info	string	是	推荐追踪信息
client_version	string	是	客户端版本

5. 推荐列表内容点击

示例代码:

javascript

window.WebSDK.track.recommendListClick({
  page_key: "recommend",
  page_name: "推荐页",
  recommend_content_type: "video",
  recommend_trace_id: "trace123",
  recommend_id: "rec123",
  recommend_trace_info: "recommend_info",
  client_version: "1.0.0",
});

参数说明:

字段	类型	必填	说明
page_key	string	是	页面键
page_name	string	是	页面名称
recommend_content_type	string	是	推荐内容类型 (video/novel/comic)
recommend_trace_id	string	是	推荐追踪ID
recommend_id	string	是	推荐ID
recommend_trace_info	string	是	推荐追踪信息
client_version	string	是	客户端版本

6. 广告页面点击事件

示例代码:

javascript

window.WebSDK.track.advertising({
  event_type: "click",
  advertising_key: "ad123",
  advertising_name: "广告1",
  advertising_id: "ad_id123",
});

参数说明:

字段	类型	必填	说明
event_type	string	是	事件类型 (click/close/show)
advertising_key	string	是	广告键
advertising_name	string	是	广告名称
advertising_id	string	是	广告ID

7. 视频事件

示例代码:

javascript

window.WebSDK.track.videoEvent({
  media_id: "media123",
  video_id: "video123",
  video_title: "视频标题",
  video_type_id: "type1",
  video_type_name: "类型1",
  video_content_type: "video",
  recommend_trace_id: "trace123",
  video_tag_key: "tag1",
  video_tag_name: "标签1",
  video_duration: 120,
  play_duration: 60,
  play_progress: 50,
  play_speed: 100,
  video_behavior_key: "video_view",
  video_behavior_name: "视频播放",
});

参数说明:

字段	类型	必填	说明
media_id	string	是	媒体ID
video_id	string	是	视频ID
video_title	string	是	视频标题
video_type_id	string	是	视频类型ID
video_type_name	string	是	视频类型名称
video_content_type	string	是	视频内容类型（`video` / `short_video` / `post_video`）
recommend_trace_id	string	是	推荐追踪ID
video_tag_key	string	是	视频标签键
video_tag_name	string	是	视频标签名称
video_duration	int	是	视频时长
play_duration	int	是	播放时长
play_progress	int	是	播放进度 [0-100]
play_speed	int	是	播放倍速 × 100（如 1.25 倍传 `125`）
video_behavior_key	string	是	视频行为键
video_behavior_name	string	是	视频行为名称
post_id	string	否	帖子 ID；仅 `post_video` 时必填

帖子视频播放示例（仍走 videoEvent，不走 postEvent）：

javascript

window.WebSDK.track.videoEvent({
  media_id: "media123",
  video_id: "video123",
  video_title: "帖子视频",
  video_type_id: "default",
  video_type_name: "默认分类",
  video_content_type: "post_video",
  recommend_trace_id: "",
  video_tag_key: "default",
  video_tag_name: "默认标签",
  video_duration: 60,
  play_duration: 15,
  play_progress: 25,
  play_speed: 125,
  video_behavior_key: "video_play",
  video_behavior_name: "播放",
  post_id: "post123",
});

8. 帖子展示事件

图文帖 / 视频帖展示时上报。视频帖的播放、暂停、完播等仍走 videoEvent（video_content_type: "post_video" + 非空 post_id）。

示例代码:

javascript

window.WebSDK.track.postEvent({
  media_id: "media123",
  post_id: "post123",
  post_title: "帖子标题",
  post_create_time: 1725686400,
  post_user_id: "author123",
  post_user_nick: "作者昵称",
  post_type_id: "default",
  post_type_name: "默认分类",
  post_content_type: "video_post", // post | video_post
  recommend_trace_id: "",
  post_tag_key: "default",
  post_tag_name: "默认标签",
  post_behavior_key: "view",
  post_behavior_name: "展示",
});

参数说明:

字段	类型	必填	说明
media_id	string	否	媒体 ID
post_id	string	是	帖子 ID
post_title	string	是	帖子标题
post_create_time	int	是	帖子创建时间（10 位秒级时间戳）
post_user_id	string	是	创建人账号 ID
post_user_nick	string	是	创建人昵称
post_type_id	string	是	分类 ID
post_type_name	string	是	分类名称
post_content_type	string	是	`post`（图文）/ `video_post`（视频帖）
recommend_trace_id	string	是	推荐 trace，未对接传 `''`
post_tag_key	string	是	标签 KEY，可空
post_tag_name	string	是	标签名称，可空
post_behavior_key	string	是	行为键，展示为 `view`
post_behavior_name	string	是	行为名称，如 `展示`

帖子点赞 / 评论 / 收藏 / 解锁为服务端上报，Web SDK 不提供对应方法。

9. 剧集播放事件

示例代码:

javascript

window.WebSDK.track.dramaEvent({
  media_id: "media123",
  drama_id: "drama123",
  drama_title: "短剧标题",
  episode: 5,
  total_episode: 20,
  video_id: "video005",
  drama_type_id: "default",
  drama_type_name: "默认分类",
  drama_content_type: "short_drama",
  recommend_trace_id: "",
  drama_tag_key: "default",
  drama_tag_name: "默认标签",
  drama_duration: 300,
  play_duration: 60,
  play_progress: 20,
  play_speed: 100,
  play_behavior_key: "ep_play",
  play_behavior_name: "播放",
});

参数说明:

字段	类型	必填	说明
media_id	string	否	媒体 ID
drama_id	string	是	剧集 ID
drama_title	string	是	剧集名称
episode	int	是	当前第几集（从 1 开始）
total_episode	int	是	总集数
video_id	string	是	当前集视频 ID
drama_type_id	string	是	分类 ID
drama_type_name	string	是	分类名称
drama_content_type	string	是	如 `short_drama`
recommend_trace_id	string	是	推荐 trace，未对接传 `''`
drama_tag_key	string	是	标签 KEY，可空
drama_tag_name	string	是	标签名称，可空
drama_duration	int	是	当前集总时长（秒）
play_duration	int	是	本次播放时长（秒）
play_progress	int	是	播放进度 [0-100]
play_speed	int	是	播放倍速 × 100（如 1.25 倍传 `125`）
play_behavior_key	string	是	播放行为标识：`ep_view`（展示）/ `ep_play`（播放）/ `ep_pause`（暂停）/ `ep_forward`（快进）/ `ep_rewind`（快退）/ `ep_complete`（播放完成）/ `ep_share`（分享）
play_behavior_name	string	是	播放行为名称：展示 / 播放 / 暂停 / 快进 / 快退 / 播放完成 / 分享

剧集点赞 / 评论 / 收藏 / 解锁为服务端上报，Web SDK 不提供对应方法。

10. 剧集状态变更事件

示例代码:

javascript

window.WebSDK.track.dramaStatusChange({
  media_id: "media123",
  drama_id: "drama123",
  drama_title: "短剧标题",
  episode: 5,
  video_id: "video005",
  pre_episode: 2, // 从第 2 集切到第 5 集
  drama_behavior_key: "ep_switch",
  drama_behavior_name: "切换剧集",
});

参数说明:

字段	类型	必填	说明
media_id	string	否	媒体 ID
drama_id	string	是	剧集 ID
drama_title	string	是	剧集名称
episode	int	是	当前第几集
video_id	string	是	当前集视频 ID
pre_episode	int	是	前集序号
drama_behavior_key	string	是	`ep_auto_play` / `ep_previous` / `ep_next` / `ep_switch` / `ep_unlock`
drama_behavior_name	string	是	行为名称，如 `切换剧集`

11. 小说事件

示例代码:

javascript

window.WebSDK.track.novelEvent({
  novel_id: "novel123",
  novel_title: "小说标题",
  media_id: "media123",
  novel_type_id: "type1",
  novel_type_name: "类型1",
  recommend_trace_id: "trace123",
  novel_tag_key: "tag1",
  novel_tag_name: "标签1",
  read_progress: 50,
  page_no: 1,
  novel_behavior_key: "view",
  novel_behavior_name: "小说阅读",
  chapter_id: "chapter_001",
  chapter_name: "第一章 陨落的天才",
});

参数说明:

字段	类型	必填	说明
novel_id	string	是	小说ID
novel_title	string	是	小说标题
media_id	string	是	媒体ID
novel_type_id	string	是	小说类型ID
novel_type_name	string	是	小说类型名称
recommend_trace_id	string	是	推荐追踪ID
novel_tag_key	string	是	小说标签键
novel_tag_name	string	是	小说标签名称
read_progress	number	是	阅读进度
page_no	number	是	页码。普通小说从 `1` 开始；仅有声小说允许上报 `0`，其他类型不得为 `0`
novel_behavior_key	string	是	小说行为键
novel_behavior_name	string	是	小说行为名称
chapter_id	string	否	章节 ID，无章节或未对接推荐引擎时传 `""`
chapter_name	string	否	章节名称，无章节或未对接推荐引擎时传 `""`

12. 漫画事件

示例代码:

javascript

window.WebSDK.track.comicEvent({
  media_id: "media123",
  comic_id: "comic123",
  comic_title: "漫画标题",
  comic_type_id: "type1",
  comic_type_name: "类型1",
  recommend_trace_id: "trace123",
  comic_tag_key: "tag1",
  comic_tag_name: "标签1",
  read_progress: 50,
  page_no: 1,
  comic_behavior_key: "view",
  comic_behavior_name: "漫画阅读",
  chapter_id: "chapter_001",
  chapter_name: "第一话",
});

参数说明:

字段	类型	必填	说明
media_id	string	是	媒体ID
comic_id	string	是	漫画ID
comic_title	string	是	漫画标题
comic_type_id	string	是	漫画类型ID
comic_type_name	string	是	漫画类型名称
recommend_trace_id	string	是	推荐追踪ID
comic_tag_key	string	是	漫画标签键
comic_tag_name	string	是	漫画标签名称
read_progress	number	是	阅读进度
page_no	number	是	页码
comic_behavior_key	string	是	漫画行为键
comic_behavior_name	string	是	漫画行为名称
chapter_id	string	否	章节 ID，无章节或未对接推荐引擎时传 `""`
chapter_name	string	否	章节名称，无章节或未对接推荐引擎时传 `""`

13. 关键词搜索事件

示例代码:

javascript

window.WebSDK.track.keywordSearch({
  keyword: "搜索关键词",
  search_result_count: 100,
  search_content_type: "post", // video | novel | comic | post | short_drama
  search_trace_id: "trace123",
  search_id: "search123",
});

参数说明:

字段	类型	必填	说明
keyword	string	是	搜索关键词
search_result_count	number	是	搜索结果数量
search_content_type	string	否	搜索列表类型：`video`（视频）/ `novel`（小说）/ `comic`（漫画）/ `post`（帖子）/ `short_drama`（短剧）。未对接搜索推荐引擎上报空字符串
search_trace_id	string	否	搜索引擎 `trace_id`；未对接搜索推荐引擎上报空字符串
search_id	string	否	搜索结果列表 ID：`video_id`（视频）/ `novel_id`（小说）/ `comic_id`（漫画）/ 帖子 ID / 短剧 ID；可视窗口有多个时用英文逗号分隔。未对接搜索推荐引擎上报空字符串

14. 关键词搜索结果点击事件

示例代码:

javascript

window.WebSDK.track.keywordClick({
  keyword: "搜索关键词",
  click_item_id: "item123",
  click_item_type_key: "post", // video | novel | comic | post | short_drama
  click_item_type_name: "帖子",
  click_position: 1,
  search_trace_id: "trace123",
});

参数说明:

字段	类型	必填	说明
keyword	string	是	搜索关键词
click_item_id	string	是	点击项 ID
click_item_type_key	string	是	点击项目类型：`video`（视频）/ `novel`（小说）/ `comic`（漫画）/ `post`（帖子）/ `short_drama`（短剧）
click_item_type_name	string	是	点击项目类型名称：`视频` / `小说` / `漫画` / `帖子` / `短剧`
click_position	number	是	点击位置
search_trace_id	string	是	搜索追踪ID

15. 广告展示日志

示例代码:

javascript

window.WebSDK.track.adImpression({
  page_key: "home",
  page_name: "首页",
  ad_slot_key: "slot1",
  ad_slot_name: "广告位1",
  ad_id: "ad1,ad2",
  creative_id: "creative1,creative2",
  ad_type: "banner",
});

参数说明:

字段	类型	必填	说明
page_key	string	是	页面键
page_name	string	是	页面名称
ad_slot_key	string	是	广告位键
ad_slot_name	string	是	广告位名称
ad_id	string	是	广告ID (多个ID用逗号分隔)
creative_id	string	是	创意ID (多个ID用逗号分隔)
ad_type	string	是	广告类型

16. 广告点击日志

示例代码:

javascript

window.WebSDK.track.adClick({
  page_key: "home",
  page_name: "首页",
  ad_slot_key: "slot1",
  ad_slot_name: "广告位1",
  ad_id: "ad1,ad2",
  creative_id: "creative1,creative2",
  ad_type: "banner",
});

参数说明:

字段	类型	必填	说明
page_key	string	是	页面键
page_name	string	是	页面名称
ad_slot_key	string	是	广告位键
ad_slot_name	string	是	广告位名称
ad_id	string	是	广告ID (多个ID用逗号分隔)
creative_id	string	是	创意ID (多个ID用逗号分隔)
ad_type	string	是	广告类型

17. 客户端安装事件

示例代码:

javascript

window.WebSDK.track.appInstall({
  trace_id: "从业务侧获取的 trace 字符串",
});

参数说明:

字段	类型	必填	说明
trace_id	string	是	安装/激活归因侧下发的追踪 ID，须为字符串（勿传数字类型）

18. 应用内容项曝光事件

示例代码:

javascript

window.WebSDK.track.appPageitemExposure({
  item_id: "item123",
  item_type: "video",
  item_name: "内容项名称",
  parent_item_id: "parent123",
  page_key: "home",
  page_name: "首页",
  referrer_page_key: "recommend",
  referrer_page_name: "推荐页",
  recommend_trace_id: "trace123",
  recommend_id: "rec123",
  recommend_trace_info: "extra_info",
});

参数说明:

字段	类型	必填	说明
item_id	string	是	内容项ID
item_type	string	是	内容项类型
item_name	string	是	内容项名称
parent_item_id	string	是	父级内容项ID
page_key	string	是	页面键
page_name	string	是	页面名称
referrer_page_key	string	否	来源页面键
referrer_page_name	string	否	来源页面名称
recommend_trace_id	string	否	推荐追踪ID
recommend_id	string	是	推荐ID
recommend_trace_info	string	是	推荐追踪信息

19. 应用内容项点击事件

示例代码:

javascript

window.WebSDK.track.appPageitemClick({
  item_id: "item123",
  item_type: "video",
  item_name: "内容项名称",
  parent_item_id: "parent123",
  position: 1,
  page_key: "home",
  page_name: "首页",
  recommend_trace_id: "trace123",
  recommend_id: "rec123",
  recommend_trace_info: "extra_info",
});

参数说明:

字段	类型	必填	说明
item_id	string	是	内容项ID
item_type	string	是	内容项类型
item_name	string	是	内容项名称
parent_item_id	string	是	父级内容项ID
position	int	是	点击位置
page_key	string	是	页面键
page_name	string	是	页面名称
recommend_trace_id	string	否	推荐追踪ID
recommend_id	string	是	推荐ID
recommend_trace_info	string	是	推荐追踪信息

20. 广告请求

示例代码:

javascript

window.WebSDK.track.adRequest({
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
});

参数说明:

字段	类型	必填	说明
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键

21. 广告填充成功

示例代码:

javascript

window.WebSDK.track.adFill({
  trace_id: "trace123",
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_id: "ad001",
  ad_type: "banner",
  fill_count: 3,
  is_skippable: 1,
  is_closable: 0,
});

参数说明:

字段	类型	必填	说明
trace_id	string	是	追踪ID
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_id	string	是	广告ID
ad_type	string	是	广告类型
fill_count	int	是	填充数量
is_skippable	int	是	是否支持跳过（`1`/`0`，映射 `show_skip_button`）
is_closable	int	是	是否支持关闭（`1`/`0`，映射 `show_close_button`）

22. 广告无填充

示例代码:

javascript

window.WebSDK.track.adNoFill({
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_type: "banner",
  reason: "no_ad_available",
});

参数说明:

字段	类型	必填	说明
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_type	string	是	广告类型
reason	string	是	无填充原因

23. 广告加载成功

示例代码:

javascript

window.WebSDK.track.adLoadSuccess({
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_id: "ad001",
  ad_type: "banner",
  load_duration: 350,
});

参数说明:

字段	类型	必填	说明
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_id	string	是	广告ID
ad_type	string	是	广告类型
load_duration	int	是	加载耗时(ms)

24. 广告展示（SDK 侧）

示例代码:

javascript

window.WebSDK.track.adImpressionSdk({
  trace_id: "trace123",
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_id: "ad001",
  ad_type: "banner",
  material_size: "320x50",
  is_skippable: 1,
  is_closable: 0,
});

参数说明:

字段	类型	必填	说明
trace_id	string	是	追踪ID
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_id	string	是	广告ID
ad_type	string	是	广告类型
material_size	string	是	素材尺寸
is_skippable	int	是	是否支持跳过（`1`/`0`，映射 `show_skip_button`）
is_closable	int	是	是否支持关闭（`1`/`0`，映射 `show_close_button`）

25. 广告点击（SDK 侧）

示例代码:

javascript

window.WebSDK.track.adClickSdk({
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_id: "ad001",
  ad_type: "banner",
});

参数说明:

字段	类型	必填	说明
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_id	string	是	广告ID
ad_type	string	是	广告类型

26. 广告关闭

示例代码:

javascript

window.WebSDK.track.adClose({
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_id: "ad001",
  ad_type: "banner",
  close_type: "manual",
});

参数说明:

字段	类型	必填	说明
request_id	string	是	请求ID
ad_slot_key	string	是	广告位键
ad_id	string	是	广告ID
ad_type	string	是	广告类型
close_type	string	是	关闭方式

27. 广告错误

示例代码:

javascript

window.WebSDK.track.adError({
  trace_id: "trace123",
  request_id: "req123",
  ad_slot_key: "slot_banner_home",
  ad_type: "banner",
  ad_id: "ad001", // 无创意 ID 时传 ''
  error_code: "E001",
  error_msg: "广告加载超时",
  error_stage: "load",
});

参数说明:

字段	类型	必填	说明
trace_id	string	是	追踪ID
request_id	string	否	请求ID
ad_slot_key	string	是	广告位键
ad_type	string	是	广告类型
ad_id	string	是	广告ID（允许空字符串；有创意 ID 则传，没有传 `''`）
error_code	string	是	错误码
error_msg	string	是	错误信息
error_stage	string	是	错误阶段

Web SDK ​

下载 SDK ​

不同框架引入方式 ​

1）import 引入（适合 Vue / React 工程化项目） ​

2）script 直引 ​

3）JS 注入 ​

初始化 ​

动态更新 UID / Channel ​

获取公共字段 ​

公共字段列表 ​

设备指纹说明（fp_version 3.0.1） ​

自动采集事件 ​

SPA 路由页面加载通知 ​

手动上报事件 ​

1. 导航路径行为 ​

2. 应用页面展示日志 ​

3. 应用点击事件 ​

4. 推荐列表内容展示 ​

5. 推荐列表内容点击 ​

6. 广告页面点击事件 ​

7. 视频事件 ​

8. 帖子展示事件 ​

9. 剧集播放事件 ​

10. 剧集状态变更事件 ​

11. 小说事件 ​

12. 漫画事件 ​

13. 关键词搜索事件 ​

14. 关键词搜索结果点击事件 ​

15. 广告展示日志 ​

16. 广告点击日志 ​

17. 客户端安装事件 ​

18. 应用内容项曝光事件 ​

19. 应用内容项点击事件 ​

20. 广告请求 ​

21. 广告填充成功 ​

22. 广告无填充 ​

23. 广告加载成功 ​

24. 广告展示（SDK 侧） ​

25. 广告点击（SDK 侧） ​

26. 广告关闭 ​

27. 广告错误 ​

Web SDK

下载 SDK

不同框架引入方式

1）`import` 引入（适合 Vue / React 工程化项目）

2）`script` 直引

3）JS 注入

初始化

动态更新 UID / Channel

获取公共字段

公共字段列表

设备指纹说明（`fp_version` 3.0.1）

自动采集事件

SPA 路由页面加载通知

手动上报事件

1. 导航路径行为

2. 应用页面展示日志

3. 应用点击事件

4. 推荐列表内容展示

5. 推荐列表内容点击

6. 广告页面点击事件

7. 视频事件

8. 帖子展示事件

9. 剧集播放事件

10. 剧集状态变更事件

11. 小说事件

12. 漫画事件

13. 关键词搜索事件

14. 关键词搜索结果点击事件

15. 广告展示日志

16. 广告点击日志

17. 客户端安装事件

18. 应用内容项曝光事件

19. 应用内容项点击事件

20. 广告请求

21. 广告填充成功

22. 广告无填充

23. 广告加载成功

24. 广告展示（SDK 侧）

25. 广告点击（SDK 侧）

26. 广告关闭

27. 广告错误