浏览器 JavaScript SDK

日志服务支持通过 Web Tracking 采集终端用户浏览器日志。本文介绍如何使用 Web Tracking JavaScript SDK 采集浏览器的用户日志。

背景信息

轻量级的埋点采集场景中，通常需要快速完成埋点设置和数据上报的工作。例如某些营销活动中，需要快捷的手段满足用户行为和浏览数据的采集和上报，包括用户的设备与浏览器信息、浏览行为记录、特定内容的停留时间等等。Web Tracking 技术也称为 Tracking Pixel，您可以在页面上嵌入一个 0 Pixel 图片，该图片默认对用户不可见，当访问该页面显示加载图片时，会顺带发起一个 Get 请求到服务端，这个时候就会把参数传给服务端。
日志服务通过 Web Tracking 功能提供轻量级的日志采集方案，通过 HTTP Get 请求将数据上传到日志服务的服务端，支持浏览器、JS、Image 等标签埋点，适用于各种无需任何验证的静态网页、广告投放、宣传资料和移动端数据采集。

注意事项

• 为日志主题开启 Web Tracking 后，通过 API 接口 WebTracks 写入数据时无需经过鉴权，相当于面向公网开放了匿名写入权限，可能产生脏数据。
• 通过 GET 请求调用 WebTrack 接口时，不支持上传 16 KiB 以上的 Body 内容。
• 通过 POST请求调用 WebTracks 接口时，每次写入的日志数量上限为 5 MiB。更多信息，请参见 WebTracks。

步骤一：开启 WebTracking

通过 JavaScript SDK 向日志主题写入日志数据前，您需要为指定日志主题开启 WebTracking 功能。

1. 登录日志服务控制台。
2. 在左侧导航栏中选择日志服务 > 日志项目管理。
3. 单击指定日志项目名称。
4. 在指定日志主题对应的操作列，单击编辑。
5. 打开 WebTracking 开关，并单击确定。

步骤二：导入 SDK

通过浏览器 JavaScript SDK 写入用户日志前，您需要先导入 SDK，完成基本的 SDK 接入操作。

1. 安装依赖包。

   npm install --save @volcengine/tls-js-sdk
   

2. 在您的代码工程中，导入依赖模块。

   import { WebTrackerBrowser } from '@volcengine/tls-js-sdk'
   

步骤三：写入日志数据

导入浏览器 JavaScript SDK 之后，您可以参考以下步骤配置日志采集的相关参数，包括存储日志数据的日志项目名称、日志主题名称和采集指标等。

1. 配置 options 参数。

   const options = {
     host: `${host}`, // 日志服务所在地域的endpoint
     projectId: `${projectId}`, // 日志项目id
     topicId: `${topicId}`, // 日志主题id
     source: `${source}`, // 日志来源
     time: 10, // 发送日志的时间间隔，默认值为 10，单位为秒
     count: 10, // 每次发送日志日志条数，默认值为 10
     protocol: `${protocol}`, // 请求的协议类型，默认值为 https
   }
   

   参数名称	是否必填	说明
   host	是	日志服务所在地域的服务地址。更多信息，请参见服务地址。
   projectId	是	日志项目 ID。
   topicId	是	日志主题 ID。
   source	否	日志来源。您可以自定义该字段值，便于识别不同来源。
   time	否	日志源发送日志的时间间隔，默认值为 10，单位为秒。
   count	否	每次发送的日志条数，默认值为 10。
   protocol	否	请求的协议类型，默认为 https。

2. 创建 WebTrackerBrowser 对象，并通过该对象向日志服务发起上传日志请求。

   const tracker = new WebTrackerBrowser(options)
   

3. 上传日志。
   通过send()等方法上传日志数据，此处为上传日志的具体业务逻辑，您可以在方法中传入键值对形式的日志数据。如果需要批量上传日志数据，可以使用 sendBatchLogs() 等方法，详细说明请参考核心 API 列表。

   tracker.send({
     name: 'wanger',
     status: 'normal',
     fee: 901,
   })
   

核心 API 列表

浏览器 JavaScript SDK 提供的核心 API 列表及示例代码如下，请根据业务需求选择合适的方法上传日志。

tracker.send({
    name: 'wanger',
    status: 'normal',
    fee: 901,
 })

tracker.sendImmediate({
    name: 'wanger',
    status: 'normal',
    fee: 901,
})

tracker.sendBatchLogs([{
    name: 'wanger',
    status: 'normal',
    fee: 901,
}, {
    name: 'zhangsan',
    status: 'normal',
    fee: 1000,
}, ])

tracker.sendBatchLogsImmediate([ {
    name: 'wanger',
    status: 'normal',
    fee: 901,
}, {
    name: 'lisi',
    status: 'normal',
    fee: 801,
}, ])