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

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

基本概念

了解数据上报要求（格式、数量限制等）

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

[
  {
    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'}",
      ……,
    },
  },
]

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

• 嵌套JSON类型的数据如何上报？示例1：嵌套JSON类型属性如何上报并用于过滤、分组
• 事件属性数据类型传输错误，需要修改怎么办？Q1：事件属性数据类型传输错误，需要修改怎么办？
• 各端数据类型传输不一致，系统如何处理？如何修改？Q2： 各端数据类型传输不一致，系统如何处理？如何修改？

了解用户标识逻辑

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

• device_id、web_id、anonymous_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逻辑和更多关于用户标识的介绍详情请参见支持的用户唯一标识。

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

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

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

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

• 如何梳理需求
• 如何设计埋点采集方案
• 指标体系demo
• 埋点方案模板

步骤1（可选）：创建埋点需求/录入自定义埋点

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

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

步骤2：获取APPID

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

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

步骤3：获取上报地址

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

获取数据上报地址

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

私有化环境

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

（可选）下载示例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 发布日志及升级指南。

• 操作录屏
  

私有化版本

私有化版本引入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

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,
});

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

设置自定义用户

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

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

  说明

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

• 更多场景实践参考：
  • 采集上报匿名ID：匿名ID、自定义webid
  • 获取用户ID信息：getToken
  • 多用户口径类型处理

上报预置事件

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

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

上报自定义事件

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

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

• 操作要点：不要将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的版本号。例如：
   
2. SDK初始化完成后，会自动上报一条predefine_pageview事件的埋点。
3. 您可在浏览器控制台的network里看到list请求。例如：
   
4. 点开请求可看到完整的埋点数据。例如：
   
5. 此网络请求成功后示例：
   
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分钟内，您可以在增长分析平台中的用户细查页面查看具体用户行为流数据，即能看到测试事件及事件属性数据，用于验证埋点数据是否可正常采集上报。

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

  • 初始化完成后是否有正常上报数据。

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

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

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

    
    

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

控制台云控配置

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

常见问题