说明
这是Web/JS SDK新版集成文档,包含:
如果想继续查看旧版文档,请点击这些链接:Web/JS SDK 集成、Web/JS SDK 埋点与属性
以下为您概要介绍Web端SDK集成相关文档的组织思路,您可参考以下导读示意图了解文档结构,查阅对应文档完成SDK集成操作。
在进行SDK集成前,您需结合您的业务分析情况先进行埋点规划,明确出待分析的业务指标中可能需要埋点的事件有哪些、属性有哪些等。进行埋点规划时,您需了解一些基本概念和DataFinder为您预置提供的埋点事件和属性、DataFinder的用户标识逻辑等前置信息,结合DataFinder为您提供的能力进行埋点规划。
基本概念 | 概念说明 | 埋点规划与SDK集成要点 | 详细指导文档 |
---|---|---|---|
事件、事件属性、事件公共属性、用户属性 | DataFinder的用户行为数据分析是基于事件+用户模型的分析模型。
| 您需根据业务分析需要,规划好待采集的事件、事件属性、用户属性有哪些、类型是什么,进行SDK集成时 | 详细概念介绍请参见数据模型。 |
埋点、全埋点、自定义埋点 |
| 通常建议您结合DataFinder提供的预置事件/属性和自定义埋点进行埋点规划。 |
进行埋点规划时,您需明确清楚需采集上报的事件、属性的数据格式要求,以及采集上报的一些限制要求,避免后续因为数据格式等不满足要求,进而导致数据采集后无法入库、后续无法查询分析。
SDK上报的数据通常有固定的格式,主要包括user
、header
、events
三个部分。
字段 | 作用 | Web端数据示例 |
---|---|---|
| 存放用户属性数据,比如web_id、user_unique_id这些重要属性。 |
|
| 存放事件公共属性。 | |
| 存放事件及事件属性。 |
其中,需要上报自定义事件、自定义属性时,您需确保事件和属性的数据格式符合要求,当前DataFinder支持的数据格式要求和数据上报的限制请参见支持的数据格式与事件/属性分类。
常见问题:
进行埋点规划时,您需要了解DataFinder的用户标识逻辑,用于结合自身业务的用户标识逻辑进而最终统一用户的标识数据来源。DataFinder默认以用户作为统计分析的对象,默认使用ssid作为用户唯一标识ID来计算指标,此时用户的SSID就是默认的统计口径。当您的分析对象为用户时,建议保持默认统计口径ssid,DataFinder可通过ID_Mapping将用户的device_id/web_id、user_unique_id等进行mapping后,尽量通过一个ssid还原一个真实的用户个体。
三类ID的mapping逻辑和更多关于用户标识的介绍详情请参见支持的用户唯一标识。
说明
如上文所述,大部分业务分析场景中,您需要结合自身业务特性进行自定义埋点的规划和集成,在此之前,您可以先了解下当前DataFinder已为您提供的预置事件、预置属性有哪些,结合已有的预置事件和属性能力,进一步规划自定义代码埋点的需求。
完成埋点规划后,建议您根据规划将埋点需求创建再DataFinder的需求管理页面,并将自定义埋点先录入DataFinder完成自定义埋点在DataFinder元数据的入库。
在开始集成前,首先需要在集团中拥有一个应用,进行 SDK 集成前,您需要获取对应应用的 appid 信息。
进行数据接入上报时,您需要根据当前的环境类型和端类型确认您的数据上报地址,如果上报地址设置错误,后续会导致您无法正常上报、查询到数据。
注意
地址类型 | SaaS-云原生环境 | SaaS-云原生 | SaaS-非云原生环境 国内环境 | SaaS-非云原生 海外BytePlus环境 |
---|---|---|---|---|
数据上报地址 |
|
|
|
|
分流地址 |
|
| 无需手动配置 | 无需手动配置 |
私有化部署场景下,您需要获取部署私有化环境时,自行规划配置的数据上送地址,如您不清楚此地址,请联系您的项目经理或客户成功经理。
以下为您提供了一个简单的示例demo,下文的SDK集成操作指导也基于此demo,您可先下载demo文件用于学习了解WebSDK的集成操作。
注意:使用demo时请将其中的app_id和channel_domain更换成自己的。
您可以使用script标签引入的方式引入Web端SDK,下面所有的示例均以script标签形式引入的方式进行演示。
操作指导
复制对应的代码片段,放到标签内尽可能靠前的位置。这段代码的作用是:
window.collectEvent
,可以用来配置和发送事件。(为了避免与其他全局变量名冲突,collectEvent
可以被替换为任意自定义的变量名)说明
以下安装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>
注意
操作录屏
私有化版本引入SDK的方式是一样的,区别在于SDK的地址不同:
{{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>
您也可以选择使用npm包的方式集成,npm包不区分saas和私有化版本,默认为saas版本。
操作指导 | 操作录屏 |
---|---|
|
初始化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才会开始上报事件
如果您当前的环境是SaaS-云原生环境或者私有化环境,您需要设置对应环境的数据上报域名,即在初始化时设置channel_domain。如果设置不正确后续会导致数据无法正常查询分析。
操作指导 | 操作录屏 |
---|---|
|
如您的产品中有账户体系,请在用户登录后立即设置uuid,以保证用户登录前后口径一致性。
操作指导 | 操作录屏 |
---|---|
|
说明
此处介绍的config方法主要用来设置用户的实名ID——user_unique_id,如果您希望上报用户属性,则可调用用户属性相关的API进行上报,详情请参见用户ID模块及API。
DataFinder为您提供了页面访问相关、页面时长相关等预置事件,其中页面访问(predefine_pageview)事件默认采集,其他事件默认不采集。如果您需要采集上报默认不采集的预置事件和预置属性数据,则您需要在初始化SDK时打开对应预置事件的采集开关。
说明
当前支持的预置事件和属性列表请参见Web预置事件及属性。
true
。全量init接口的参数介绍请参见init。根据埋点规划,如果需要采集上报自定义事件,您可以调用“collectEvent”方法设置自定义事件名和事件属性。
操作指导 | 操作录屏 |
---|---|
自定义事件的数据采集采用事件event+事件属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性,配置示例:
说明 建议事件名和属性统一使用小写。
|
5.1.4以上的版本支持本地/线上直接调试埋点,以下为操作的核心流程步骤。,详细请查看Web DevTools。
开启调试参数
window.collectEvent('init', { enable_debug: true });
需要验证的页面URL后增加如下参数:
https://www.aaa.com?open_dev_tool=true&app_id=${appid}
network
里看到list
请求。例如:如果您需要采集上报自定义用户属性数据,可以调用用户属性模块API进行设置,详情请参见Web/JS SDK API 说明。
如果您希望自动采集元素的点击事件或者曝光事件数据,您需要在SDK初始化设置时,在init接口中开启全埋点采集(autotrack),详情请参见 Web/JS SDK API 说明。
私有化版本支持使用国密方式加密请求(SaaS版本不支持),详情请参见Web/JS SDK API 说明。
更多场景实践请参见Web/JS SDK 集成场景实践。
完成初始化验证后,您可以在小程序端进行测试操作,触发一些待采集上报的事件,测试事件上报后,大约15分钟内,您可以在增长分析平台
中的用户细查
页面查看具体用户行为流数据,即能看到测试事件及事件属性数据,用于验证埋点数据是否可正常采集上报。
user
、header
、events
三个部分,分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据,上报的数据包含了开启采集的预置和自定义的数据。初始化完成后是否有正常上报数据。
上报数据的数据格式等是否符合要求:支持的数据格式与事件/属性分类。
检查下查询的user_unique_id是否正确。
SaaS-云原生环境和私有化环境的话,需检查下集成代码中的上报域名是否配置正确。
DataFinder为您提供了丰富的API接口,除了上述通用流程中介绍的核心接口和典型场景的使用示例外,您也可以了解当前Web支持的主要API接口和其作用,根据业务需求可灵活调用对应接口完成业务数据埋点,具体请查看:Web/JS SDK API 说明。
分类 | API列表 | API说明 |
---|---|---|
核心API | 对SDK实例进行初始化配置的API。 | |
当init初始化调用之后,需要调用start方法,SDK才开始上报事件。在调用start方法之前,不会有事件上报。 | ||
调用config对事件进行一些设置,比如设置公共属性、设置user_unique_id等。可以调用多次,后面设置会覆盖之前相同设置项。 | ||
使用CollectEvent方法可以上报自定义事件。 | ||
模块API | 此模块提供页面浏览事件(predefinePageView)的采集开关和属性配置能力。 | |
此模块提供了页面时长相关事件的采集开关和属性配置能力。 | ||
此模块提供设置用户属性能力,并提供了一系列的方法: | ||
此模块提供了全埋点预置事件和预置属性的采集开关和属性配置能力。 | ||
此模块提供AB实验能力,并提供了一系列的方法: | ||
此模块提供了对上报数据进行加密的功能开关。 | ||
此模块提供了监听某个SDK生命周期的广播的能力,适用于SDK运行时的消息用来获取SDK状态。 | ||
此模块提供了追踪某个事件的能力。 | ||
非核心API | 暂停SDK上报事件。调用该方法后,SDK会处于暂停状态,后续不再会上报事件。 | |
取消暂停SDK上报,一般是在调用disableSDK后又打算取消暂停,即重新启动SDK上报,后续会恢复上报事件。 |
SaaS云原生版本或私有化V4.4.0以上版本,DataFinder支持通过服务端下发 SDK 设置,包括上报时机、全埋点开关等,详细介绍文档请查阅:项目管理-SDK设置。
上报逻辑与存储策略 | Web SDK能力与使用咨询 | 故障/报错排查处理 |
---|---|---|
更多FAQ请参见参考:Web/JS SDK FAQ |