SDK 接入文档

Appearance

落地页SDK API 说明 ​

LandingSDK.init(options) ​

初始化 SDK 实例。

javascript
LandingSDK.init({
  appId: "demo_app",
  domain: "当前落地页域名",
  channel: "demo_channel",
});

参数 ​

参数类型必填默认值说明
appIdstring是-应用 ID
domainstring否当前页面域名上报域名
endpointstring否-直接指定完整上报地址，优先级高于 domain
channelstring是-渠道码
batchboolean否false是否批量上报，默认 false
deviceIdstring否-自定义设备 ID，传入后覆盖本地生成的值

环境说明 ​

接入文档中的配置服务环境如下：

环境域名
测试环境https://dcapi.dc-dev.cc
正式环境https://api.dc-server.cc

以上域名用于 /sdk/getAvailableDomainList 密文配置接口。落地页SDK当前不走密文配置接口，它只负责事件上报，最终地址由 endpoint 或 domain 决定。

接入方式上报地址规则说明
domaindomain + /dcserv/api/eventTracking/report.json推荐用于落地页同域代理接入；页面域名需将 /dcserv 代理到 https://ap.dc-report.cc
endpoint直接使用 endpoint 完整地址优先级高于 domain

使用 domain 时，上线前需要确认 /dcserv 已正确代理到 https://ap.dc-report.cc，最终请求能够到达 https://ap.dc-report.cc/api/eventTracking/report.json。

batch 参数说明 ​

batch 决定调用哪个上报接口，两种模式的接口路径和请求格式不同：

batch: false（默认）batch: true
上报接口/api/eventTracking/report.json/api/eventTracking/batchReport.json
请求格式application/x-www-form-urlencodedapplication/json
发送时机每次调用立即发送队列积累后批量发送
适用场景事件少、关键事件（如页面展示）短时间高频点击追踪

WARNING

使用 batch: true 时，若通过 /dcserv 代理，需确认 /api/eventTracking/batchReport.json 路径也已代理，否则请求会 404。

事件方法 ​

SDK 提供两个专用上报方法，event 字段由 SDK 内部自动设置，调用时只需传入业务参数。

LandingSDK.track.landingPageView(payload) ​

上报落地页展示事件，event 自动设为 "landing_page_view"，返回 Promise。

javascript
LandingSDK.track.landingPageView({
  landing_page_id: "123",
});

参数 ​

字段类型必填说明
landing_page_idstring是当前落地页ID

LandingSDK.track.landingPageClick(payload) ​

上报落地页点击事件，event 自动设为 "landing_page_click"，返回 Promise。

javascript
LandingSDK.track.landingPageClick({
  landing_page_id: "123",
  tab_key: "tab_001",
  tab_name: "登录",
  click_coordinates_x: 100,
  click_coordinates_y: 200,
  click_x_percent: 50,
  click_y_percent: 60,
  screen_width: 1920,
  screen_height: 1080,
  trace_id: "trace123",
});

参数 ​

字段类型必填说明
landing_page_idstring是当前落地页ID
tab_keystring是标签键
tab_namestring是标签名称
click_coordinates_xint是点击位置X坐标
click_coordinates_yint是点击位置Y坐标
click_x_percentint是点击X百分比
click_y_percentint是点击Y百分比
screen_widthint是屏幕宽度
screen_heightint是屏幕高度
trace_idstring是追踪记录ID

地址优先级 ​

最终上报地址按以下优先级确定：

  1. options.endpoint（初始化时指定的完整地址）
  2. options.domain（初始化时指定的域名）
  3. 当前页面域名（兜底）

接入建议 ​

  • 推荐通过占位队列统一调用，不要在页面多处直接调用 LandingSDK.track，参见 快速开始
  • 上线前验证 /dcserv 代理是否正确转发到 https://ap.dc-report.cc/api/eventTracking/report.json

公共上报字段 ​

每次事件上报时，SDK 自动携带以下公共字段，无需手动传入：

字段说明
app_id应用 ID，来自 init 配置
channel渠道码，来自 init 配置
uid用户 ID，默认 0
sid会话 ID，每日一会话，本地持久化
client_ts客户端时间戳（10 位秒级）
device设备类型：PC / Android / iOS
device_id设备 ID，本地持久化；可通过 init 覆盖
device_fingerprint设备指纹
user_agent浏览器 UA
sdk_version当前 SDK 版本号，自动填入
app_version应用版本号
event_id事件唯一 ID，由 SDK 自动生成（MD5）