You need to enable JavaScript to run this app.
导航
Web/JS SDK 集成
最近更新时间:2025.07.15 19:38:53首次发布时间:2025.05.29 16:08:31
我的收藏
有用
有用
无用
无用

说明

这是Web/JS SDK新版集成文档,包含:

如果想继续查看旧版文档,请点击这些链接:Web/JS SDK 集成Web/JS SDK 埋点与属性

文档导读

以下为您概要介绍Web端SDK集成相关文档的组织思路,您可参考以下导读示意图了解文档结构,查阅对应文档完成SDK集成操作。
Image

埋点规划

在进行SDK集成前,您需结合您的业务分析情况先进行埋点规划,明确出待分析的业务指标中可能需要埋点的事件有哪些、属性有哪些等。进行埋点规划时,您需了解一些基本概念和DataFinder为您预置提供的埋点事件和属性、DataFinder的用户标识逻辑等前置信息,结合DataFinder为您提供的能力进行埋点规划。

基本概念

基本概念

概念说明

埋点规划与SDK集成要点

详细指导文档

事件、事件属性、事件公共属性、用户属性

DataFinder的用户行为数据分析是基于事件+用户模型的分析模型。

  • 事件&事件属性:用户的某一种或一类行为称之为“事件”,事件属性即事件触发时同步采集的事件发生的形式、位置等用来描述事件的信息。例如,某个用户购买了某个商品,则该用户的行为事件为“购买”,事件属性为“商品名称”、“商品分类”、“支付金额”等。
  • 事件公共属性:指不与某个事件强关联、在多个或所有事件中都共同存在的属性,例如,应用的版本号、设备信息等。
  • 用户&用户属性:用户指的是事件行为的发生主体人。用户属性指的是用户自身状态的属性(与行为无关,例如年龄、性别等)或与行为有关但不常变化的用户相关属性(如VIP等级、注册时间等)。

您需根据业务分析需要,规划好待采集的事件、事件属性、用户属性有哪些、类型是什么,进行SDK集成时

详细概念介绍请参见数据模型

埋点、全埋点、自定义埋点

  • 埋点:通过SDK的开发,将事件逻辑写入代码的过程,称之为埋点。DataFinder为您提供了预置事件及事件属性,这类事件及事件属性无需您手动埋点,只需打开采集开关即可。
  • 全埋点:是DataFinder提供的预置事件和事件属性的一种,在DataFinder中,采集的全埋点事件为bav2b_click按钮点击, bav2b_page页面浏览。不需要研发额外投入,但会以上报大量数据为代价,并且只可以采集简单的PV、UV,对于丰富业务数据的采集显得有些‘力不从心’。
  • 代码埋点:代码埋点指的是开发工程师,按照业务个性化需求,人工写入代码中以实现数据采集逻辑。采集范围广、应用灵活。但需要研发投入,且需要一定的技术能力。

通常建议您结合DataFinder提供的预置事件/属性和自定义埋点进行埋点规划。

埋点、全埋点

了解数据上报要求(格式、数量限制等)

进行埋点规划时,您需明确清楚需采集上报的事件、属性的数据格式要求,以及采集上报的一些限制要求,避免后续因为数据格式等不满足要求,进而导致数据采集后无法入库、后续无法查询分析。
SDK上报的数据通常有固定的格式,主要包括userheaderevents三个部分。

字段

作用

Web端数据示例

user

存放用户属性数据,比如web_id、user_unique_id这些重要属性。

[
  {
    events: [
      {
        event: 'predefine_pageview',
        params: '{"url":"https://www.xxxx.com",……}',
        local_time_ms: 1745897787756,
        session_id: 'd8b28410-6079-42da-9f91-5a49d6ffb01f',
      },
    ],
    user: {
      web_id: '7498573*****',
      user_unique_id: 'zhangsan',
    },
    header: {
      app_id: *******,
      browser: 'Chrome',
      browser_verison:'135.0.0.0',
      os_name: 'windows',
      os_version: '10.0.1',
      ……
      custom: "{aaaa: 'bbbb'}",
      ……,
    },
  },
]

header

存放事件公共属性。
app_id、os_name这些都是预置的,会直接放在header下,如果是您自定义设置的事件公共属性,会放到header.custom下。

events

存放事件及事件属性。
本身是一个数组,支持携带多个事件。
每个事件都有event、params、local_time_ms、session_id几个字段,其中local_time_ms、session_id是SDK自动产生的,而event、params是业务设置的,event是事件名,params存放的是事件属性(值是JSON对象进行了序列化操作)。

其中,需要上报自定义事件、自定义属性时,您需确保事件和属性的数据格式符合要求,当前DataFinder支持的数据格式要求和数据上报的限制请参见支持的数据格式与事件/属性分类
常见问题:

了解用户标识逻辑

进行埋点规划时,您需要了解DataFinder的用户标识逻辑,用于结合自身业务的用户标识逻辑进而最终统一用户的标识数据来源。DataFinder默认以用户作为统计分析的对象,默认使用ssid作为用户唯一标识ID来计算指标,此时用户的SSID就是默认的统计口径。当您的分析对象为用户时,建议保持默认统计口径ssid,DataFinder可通过ID_Mapping将用户的device_id/web_id、user_unique_id等进行mapping后,尽量通过一个ssid还原一个真实的用户个体。

  • device_idweb_idanonymous_id:均可作为设备的唯一id,多为无法获取用户实名id的场景下使用。
  • user_unique_id:为登录态用户标识,多为在能获取用户实名ID场景下使用,一般情况直接使用产品业务中使用的用户标识,比如登录账号。当 user_unique_id 未设定时,在SaaS版本中,系统会自动使用 device_id/web_id 替代。
  • ssid:为DataFinder的用户统计口径ID,与设备标识device_id/web_id、登录态用户标识user_unique_id 互相Mapping,能保证用户匿名和实名状态下的ID统一。

三类ID的mapping逻辑和更多关于用户标识的介绍详情请参见支持的用户唯一标识

说明

  • 如果您的业务中用户实名ID有多种ID类型,例如,可通过账号ID、用户手机号等多种ID类型来标注用户的实名信息,您也可以使用多ID类型功能,详情请参见使用多ID类型

了解Web端支持的预置事件和属性

如上文所述,大部分业务分析场景中,您需要结合自身业务特性进行自定义埋点的规划和集成,在此之前,您可以先了解下当前DataFinder已为您提供的预置事件、预置属性有哪些,结合已有的预置事件和属性能力,进一步规划自定义代码埋点的需求。

  • Web端支持的预置事件和属性列表请参见Web预置事件及属性
  • 同时您还需关注当前禁用的预置属性列表,后续规划自定义埋点及属性时需避免与禁用属性同名,否则会导致数据无法正常上报,详情请参见禁用属性列表

梳理埋点需求设计埋点方案

说明

准备工作

步骤1(可选):创建埋点需求/录入自定义埋点

完成埋点规划后,建议您根据规划将埋点需求创建再DataFinder的需求管理页面,并将自定义埋点先录入DataFinder完成自定义埋点在DataFinder元数据的入库。

  • 埋点需求管理:您可以通过DataFinder的埋点需求管理功能来管理埋点需求,后续可在埋点需求管理页面中持续维护和管理需求,提高管理效率。创建埋点需求管理的操作请参见需求管理
  • 自定义埋点录入:您可以根据埋点规划,先将自定义埋点创建录入至DataFinder的元数据,操作详情请参见新增事件新增事件属性新增用户属性

步骤2:获取APPID

在开始集成前,首先需要在集团中拥有一个应用,进行 SDK 集成前,您需要获取对应应用的 appid 信息。

  • SaaS-云原生场景下,您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid,详情请参见项目管理
    Image
  • SaaS-非云原生场景下,您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid,详情请参见应用列表
    Image

步骤3:获取上报地址

进行数据接入上报时,您需要根据当前的环境类型和端类型确认您的数据上报地址,如果上报地址设置错误,后续会导致您无法正常上报、查询到数据。

获取数据上报地址

注意

  • 请在上报数据前,务必确认您当前使用的环境类型,根据环境类型配置上报地址。查看当前的环境类型请参见SaaS云原生/非云原生&私有化环境
  • 如果您使用的是SaaS-云原生环境,您也需确认您的服务所在的地域,根据所在地域配置上报地址(通常您的服务会在华北2-北京地域,部分用户可能会使用其他地域)。SaaS-云原生用户查看服务所在地域请参见支持的地域

SaaS-云原生 & SaaS-非云原生

地址类型

SaaS-云原生环境
(国内:华北2-北京&华南1-广州)

SaaS-云原生
(海外:亚太东南-柔佛)

SaaS-非云原生环境 国内环境

SaaS-非云原生 海外BytePlus环境
(以下 SG 指新加坡)

数据上报地址
(channel_domain)

  • SaaS-云原生(华北):
  • channel_domain: https://gator.volces.com
  • SaaS-云原生(华南):
  • channel_domain: https://gator.uba.cn-guangzhou.volces.com
  • channel_domain: https://gator.uba.ap-southeast-1.volces.com
  • channel_domain: https://gator.uba.ap-southeast-1.volces.com
  • channel: 'cn'
  • 不需要设置channel_domain
  • channel: 'sg'
  • 不需要设置channel_domain

分流地址
(ab_channel_domain,仅开启A/B实验时需配置)

  • ab_channel_domain: https://tab.volces.com
  • ab_channel_domain: https://tab.ab.ap-southeast-1.volces.com

无需手动配置

无需手动配置

私有化环境

私有化部署场景下,您需要获取部署私有化环境时,自行规划配置的数据上送地址,如您不清楚此地址,请联系您的项目经理或客户成功经理。

集成SDK

(可选)下载示例demo

以下为您提供了一个简单的示例demo,下文的SDK集成操作指导也基于此demo,您可先下载demo文件用于学习了解WebSDK的集成操作。

注意:使用demo时请将其中的app_id和channel_domain更换成自己的。

demo.zip
未知大小

step1:引入SDK

引入方式1:使用script标签引入

您可以使用script标签引入的方式引入Web端SDK,下面所有的示例均以script标签形式引入的方式进行演示。

SaaS版本

  • 操作指导
    复制对应的代码片段,放到标签内尽可能靠前的位置。这段代码的作用是:

    • 定义了一个全局函数window.collectEvent,可以用来配置和发送事件。(为了避免与其他全局变量名冲突,collectEvent可以被替换为任意自定义的变量名)
    • 引入一段 SDK 的脚本文件。

    说明

    以下安装SDK的代码,为面向主流较新版本浏览器适用的代码示例,当前Web JS支持的浏览器版本,及低版本的IE、Google浏览器的安装要点可基于以下代码示例和FAQ文档进行修改调整:Web SDK支持哪些浏览器?web sdk是否兼容旧版IE浏览器?web sdk是否兼容低版本Google浏览器?

    <script>    
    //此段代码的作用是将SDK主文件未加载完成时,业务代码中调用的API依次进行放到数组q中缓存,等待SDK主文件加载完成后,再取出,并执行。
    (function(win, export_obj) {
        win['LogAnalyticsObject'] = export_obj;
        if (!win[export_obj]) {
            var _collect = function() {
                _collect.q.push(arguments);
            }
            _collect.q = _collect.q || [];
            win[export_obj] = _collect;                
        }
        win[export_obj].l = +new Date();
    })(window, 'collectEvent');
    </script>
    <script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.2.9.js"></script>
    

    注意

    • 第一段script标签请放到页面结构尽量靠前的位置
    • 第二段script标签可以放在其他位置,但一定要在第一段之后。
    • 引入时,其中SDK的版本号为示例版本号,建议您在引入时使用最新版本的SDK。web SDK的发布日志请参见参考:Web/JS SDK 发布日志及升级指南
  • 操作录屏
    Image

私有化版本

私有化版本引入SDK的方式是一样的,区别在于SDK的地址不同:

  • 私有化版本需要获取js文件的私部地址,一般在{{domain}}/minio.byterangers.onpremise.docor.static/collect-privity-v5.2.9.js,如您不清楚此地址,请联系您的项目经理或客户成功经理。
  • 如果您的私有化环境可以访问外网,您也可使用火山引擎提供的私部地址:
    <script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-privity-v5.2.9.js"></script>
    

引入方式2:使用npm包引入

您也可以选择使用npm包的方式集成,npm包不区分saas和私有化版本,默认为saas版本。

操作指导

操作录屏

npm i @datarangers/sdk-javascript

Image

step2:初始化SDK

初始化SDK时,通常您需要调用SDK的核心API(init、config等接口),用来实现采集上报预置事件和属性数据、采集上报自定义事件和数据、定义用户的ID标识字段等。

初始化基础结构

以下为一个简单的集成SDK代码示例,您可通过此示例来快速了解SDK集成时的代码结构、涉及的核心接口、典型的配置参数等,后续步骤中会为您逐步介绍SDK集成的详细操作要点。

window.collectEvent('init', { // 调用初始化接口init,下方配置初始化接口的参数
    app_id: {{APPID}}, // 通过APPID指定数据上报到哪个应用,注意类型是数字而非字符串,详情参见 步骤2:获取APPID
    channel: 'cn', // 仅SaaS-非云原生环境需手动修改,详情请参考上述的准备工作步骤三:获取上报地址
    channel_domain: 'https://****.****.****.****', // 详情请参考上述的准备工作步骤三:获取上报地址
    log: true, // true:开启本地调试日志打印,false:关闭本地调试日志打印
});
// 如果需要设置uuid、设置公共属性等,可以在start方法前嵌入设置代码
window.collectEvent('start'); // start方法调用后,SDK才会开始上报事件
  • 涉及核心API:
    • init:对SDK实例进行初始化配,init接口中需要指明数据上报的appid信息,并配置是否开启日志等初始化参数。全量init接口的参数介绍请参见init
    • start:当init初始化调用之后,需要调用start方法,SDK才开始上报事件。在调用start方法之前,不会有事件上报。

      说明

      start方法调用前,同样可以上报事件,这些事件被缓存在内存中,没有真正的发送给服务端;直到start调用后,缓存的事件才会与设置的用户属性等参数合并成完整的事件结构,然后通过网络请求发送给服务端。start方法调用后发送的事件,则直接合并参数后发给服务端。

      更多关于start方法的介绍请参见start

设置上报域名

如果您当前的环境是SaaS-云原生环境或者私有化环境,您需要设置对应环境的数据上报域名,即在初始化时设置channel_domain。如果设置不正确后续会导致数据无法正常查询分析。

操作指导

操作录屏

window.collectEvent('init', {
    app_id: 1338, // demo appid
    channel_domain: 'https://gator.volces.com',
    log: true,
});

Image

  • 操作要点:设置数据上报域名前,您需要先明确您使用的环境和所在的地域,根据实际情况设置上报域名。确认您当前使用的环境类型请参见:SaaS云原生/非云原生&私有化环境

设置自定义用户

如您的产品中有账户体系,请在用户登录后立即设置uuid,以保证用户登录前后口径一致性。

操作指导

操作录屏

  • 用户登录
    如您的产品中有账户体系,请在用户登录后立即设置uuid,以保证用户登录前后口径一致性。

    window.collectEvent('config', {
        user_unique_id: "zhangsan"
    });
    
  • 用户退出登录
    如果您希望用户退出回复匿名状态时,则在退出登录时调用。

    window.collectEvent('config', {
        user_unique_id: null
    });
    

Image

  • 涉及核心API:您可以通过config方法来设置用户的业务标识ID——user_unique_id,设置前您需要先了解DataFinder的用户标识逻辑(详情请参见支持的用户唯一标识),更多config接口的介绍和参数说明请参见config

    说明

    此处介绍的config方法主要用来设置用户的实名ID——user_unique_id,如果您希望上报用户属性,则可调用用户属性相关的API进行上报,详情请参见用户ID模块及API

  • 更多场景实践参考:

上报预置事件

DataFinder为您提供了页面访问相关、页面时长相关等预置事件,其中页面访问(predefine_pageview)事件默认采集,其他事件默认不采集。如果您需要采集上报默认不采集的预置事件和预置属性数据,则您需要在初始化SDK时打开对应预置事件的采集开关。

说明

当前支持的预置事件和属性列表请参见Web预置事件及属性

  • 操作指导:
    • 开启/关闭采集页面浏览事件:此预置事件默认采集,详细说明请参见:页面浏览事件
    • 开启/关闭采集页面时长事件:此预置事件默认不采集,详细说明请参见: 停留时长模块及API
    • 开启/关闭采集全埋点事件:此预置事件默认不采集,详细说明请参见:全埋点事件介绍
  • 涉及核心API:
    • init:如果您需要采集上报DataFinder为您提供的预置事件和属性,您需要在init接口中配置对应事件的采集开关为true。全量init接口的参数介绍请参见init
  • 更多场景实践参考:

上报自定义事件

根据埋点规划,如果需要采集上报自定义事件,您可以调用“collectEvent”方法设置自定义事件名和事件属性。

操作指导

操作录屏

自定义事件的数据采集采用事件event+事件属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性,配置示例:

window.collectEvent('test_event', {
   key_string: 'value_string',
   key_int: 10
});

说明

建议事件名和属性统一使用小写。

  • 事件命名仅支持字母、数字和下划线,不要使用init、start等SDK内部api名。
  • 事件属性值的数据类型请参考1.属性数据类型;不要在事件属性中使用嵌套object,即属性值暂不支持object类型,可转为string后进行上报。

Image

  • 操作要点:不要将window.collectEvent赋值给一个临时变量,赋值操作可能会导致无法上报或者报错**。**
  • 涉及核心API:
    • 上报埋点相关API:调用“collectEvent”方法设置自定义事件名和事件属性,该方法支持单个事件方式和批量事件方式上报,以上为一个单个事件上报的示例,更多参数说明和使用示例请参见 上报埋点
  • 更多场景实践参考:
    • 事件过滤:过滤事件
    • 上报自定义事件公共属性:调用“collectEvent”方法上报自定义事件时,也支持调用config接口设置自定义事件公共属性,详情请参见设置事件公共属性
    • 页面跳转前上报埋点:页面跳转上报

step3:初始化验证结果

使用DataFinder Web DevTools

5.1.4以上的版本支持本地/线上直接调试埋点,以下为操作的核心流程步骤。,详细请查看Web DevTools

  1. 开启调试参数

    window.collectEvent('init', {
       enable_debug: true
    });
    
  2. 需要验证的页面URL后增加如下参数:

    https://www.aaa.com?open_dev_tool=true&app_id=${appid}
    

使用浏览器控制台

  1. SDK顺利完成初始化后,并且初始化设置log:true后,会打印如下信息:您的appid、当前的用户信息、当前SDK的版本号。例如:
    Image
  2. SDK初始化完成后,会自动上报一条predefine_pageview事件的埋点。
  3. 您可在浏览器控制台的network里看到list请求。例如:
    Image
  4. 点开请求可看到完整的埋点数据。例如:
    Image
  5. 此网络请求成功后示例:
    Image
  6. 如您按照本文档完整接入SDK后,没有上述的控制台日志,或者网络请求,或者网络请求的返回码不是0(常见错误码有-2、-100等),请联系技术支持。

更多场景实践

采集上报自定义用户属性

如果您需要采集上报自定义用户属性数据,可以调用用户属性模块API进行设置,详情请参见Web/JS SDK API 说明

自动采集点击/元素曝光事件

如果您希望自动采集元素的点击事件或者曝光事件数据,您需要在SDK初始化设置时,在init接口中开启全埋点采集(autotrack),详情请参见 Web/JS SDK API 说明

内嵌H5页打通原生

APP打通H5上报

设置请求加密

私有化版本支持使用国密方式加密请求(SaaS版本不支持),详情请参见Web/JS SDK API 说明

更多场景实践

更多场景实践请参见Web/JS SDK 集成场景实践

埋点数据验证

完成初始化验证后,您可以在小程序端进行测试操作,触发一些待采集上报的事件,测试事件上报后,大约15分钟内,您可以在增长分析平台中的用户细查页面查看具体用户行为流数据,即能看到测试事件及事件属性数据,用于验证埋点数据是否可正常采集上报。

  • 用户细查页面中展示的用户行为流数据通常有固定的格式,主要包括userheaderevents三个部分,分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据,上报的数据包含了开启采集的预置和自定义的数据。
  • 如果在用户细查处能看到对应事件,表明事件上报成功,通过观察事件的属性,可以确认相应属性是否也成功上报上来了。
  • 如果数据没有正常在用户细查中查询到,您可检查一下:
    • 初始化完成后是否有正常上报数据。

    • 上报数据的数据格式等是否符合要求:支持的数据格式与事件/属性分类

    • 检查下查询的user_unique_id是否正确。

    • SaaS-云原生环境和私有化环境的话,需检查下集成代码中的上报域名是否配置正确。

Web SDK API 列表

DataFinder为您提供了丰富的API接口,除了上述通用流程中介绍的核心接口和典型场景的使用示例外,您也可以了解当前Web支持的主要API接口和其作用,根据业务需求可灵活调用对应接口完成业务数据埋点,具体请查看:Web/JS SDK API 说明

分类

API列表

API说明

核心API

init

对SDK实例进行初始化配置的API。

start

当init初始化调用之后,需要调用start方法,SDK才开始上报事件。在调用start方法之前,不会有事件上报。

config

调用config对事件进行一些设置,比如设置公共属性、设置user_unique_id等。可以调用多次,后面设置会覆盖之前相同设置项。

上报埋点

使用CollectEvent方法可以上报自定义事件。

模块API

页面浏览事件

此模块提供页面浏览事件(predefinePageView)的采集开关和属性配置能力。

停留时长模块及API

此模块提供了页面时长相关事件的采集开关和属性配置能力。

用户ID模块及API

此模块提供设置用户属性能力,并提供了一系列的方法:setAnonymousIdgetTokenprofileSetprofileSetOnceprofileUnsetprofileIncrementprofileAppend等。

全埋点模块

此模块提供了全埋点预置事件和预置属性的采集开关和属性配置能力。

AB实验模块及API

此模块提供AB实验能力,并提供了一系列的方法:getVargetAllVarsgetAbSdkVersionsetExternalAbVersion

加密上报模块

此模块提供了对上报数据进行加密的功能开关。

生命周期模块

此模块提供了监听某个SDK生命周期的广播的能力,适用于SDK运行时的消息用来获取SDK状态。

追踪事件模块

此模块提供了追踪某个事件的能力。
例如追踪视频播放耗时相关数据,但不希望每次视频的操作都触发数据上报,仅需要在视频完播时上报视频播放过程中的数据,此时可以用追踪事件模块,在视频点击时标注Start完播时标注End,在end时上报所有中间过程的数据。

非核心API

stop

暂停SDK上报事件。调用该方法后,SDK会处于暂停状态,后续不再会上报事件。

reStart

取消暂停SDK上报,一般是在调用disableSDK后又打算取消暂停,即重新启动SDK上报,后续会恢复上报事件。

相关文档

控制台云控配置

SaaS云原生版本或私有化V4.4.0以上版本,DataFinder支持通过服务端下发 SDK 设置,包括上报时机、全埋点开关等,详细介绍文档请查阅:项目管理-SDK设置

常见问题

上报逻辑与存储策略

Web SDK能力与使用咨询

故障/报错排查处理

更多FAQ请参见参考:Web/JS SDK FAQ