本文为您介绍集成Web JS SDK的主要流程和代码示例，您可根本文进行SDK集成测试，然后根据业务需要灵活使用当前支持的埋点与属性能力（参见Web/JS SDK 埋点与属性），此外，FAQ文档也为您汇总了关于SDK逻辑、典型场景使用咨询、故障/报错排查处理的内容，您可进行查阅参考。

复制对应的代码片段，放到标签内尽可能靠前的位置。如您使用SaaS版本，请参考1.1节；如您使用私有化版本，请参考1.2节。这段代码的作用是：

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

1.1 安装代码 (SaaS版本)

如您使用SaaS部署版本，请参照如下代码。

<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.1.js"></script>

1.2 安装代码 (私有化版本)

私有化版本需要获取js文件的私部地址，一般在{{domain}}/minio.byterangers.onpremise.docor.static/collect-privity-v5.2.1.js，如您不清楚此地址，请联系您的项目经理或客户成功经理。
如您使用私有化部署版本，请参照如下代码。

<script>    
(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="{{domain}}/minio.byterangers.onpremise.docor.static/collect-privity-v5.2.1.js"></script>

您也可使用火山提供的私部地址：

<script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-privity-v5.2.1.js"></script>

1.3 注意事项

上述引入的脚本和js文件，位置不可变更，否则可能会导致无法上报数据。

2.1 获取appid

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

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

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。
如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化SDK

2.3.1 SaaS-云原生版本

如您使用SaaS-云原生部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel_domain: 'https://gator.volces.com', // 设置数据上送地址
    log: true, // true:开启日志，false:关闭日志
    autotrack: false, // 全埋点开关，true开启，false关闭
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.3.2 SaaS-非云原生版本

如您使用SaaS-非云原生部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel: 'cn', // 设置数据上送地址
    log: true, // true:开启日志，false:关闭日志
    autotrack: false // 全埋点开关，true开启，false关闭
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.3.3 私有化版本

如您使用私有化部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel_domain: '{{REPORT_URL}}', // 设置私有化部署数据上送地址，参考2.2节获取
    log: true, // true:开启日志，false:关闭日志
    autotrack: false, // 全埋点开关，true开启，false关闭
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.4 配置完毕

初始化结束后，需要通知SDK设置完毕，可以真正开始发送事件了。

// 必须在初始化配置完成后，加入这行代码，否则SDK不会发送数据
window.collectEvent('start');

2.5 使用调试工具

5.1.4以上的版本支持本地/线上直接调试埋点，详细请查看调试工具。
需要验证的页面URL后增加如下参数：

?open_dev_tool=true&app_id=${appid}

以下为常用初始化配置。配置时需参考2.3/2.4节，添加到window.collectEvent('init', {/ ... /})中。

3.1 全埋点设置开关

全埋点开关默认关闭。更多功能与配置方式请参考Web/JS SDK分类功能中的第2节 Web/JS 全埋点。

// 开启全埋点功能
window.collectEvent('init', {
    // ...... 其他初始化配置
    autotrack: true
})

3.2 查看日志打印

日志打印默认关闭。

// 在控制台打印详细的log信息，协助排查
window.collectEvent('init', {
    // ...... 其他初始化配置
    log: true
})

3.3 关闭pv事件上报

当访问页面时，SDK会默认上报一次pv事件(事件名predefine_pageview)，此预置事件默认上报。如需关闭，请在初始化配置中禁用此事件。
有关预置pv事件的详情请参考Web预置事件及属性。

// 在控制台打印详细的log信息，协助排查
window.collectEvent('init', {
    // ...... 其他初始化配置
    disable_auto_pv: true // 开启禁用PV上报的开关
})

3.4 内嵌H5页打通原生端（客户端）

客户端开启内嵌H5页打通后，内嵌H5页上产生的事件将通过客户端SDK上报，不在js SDK上报，并复用客户端设置的user_unique_id和公共属性。此时，还需在集成js sdk的H5页上开启打通开关。

// H5内嵌到原生端并打通
window.collectEvent('init', {
    // ...... 其他初始化配置
    enable_native: true 
    // 5.1.3以下版本参数为Native，
    // 5.1.3以上版本修改为enable_native，但仍然兼容了Native的设置
})

如果客户端初始化的时候采用了多实例的方式，可能会导致打通失败。有以下两种方式来调整：

1. 客户端调用上报方式，使用默认实例初始化，不用多实例。
2. H5页面手动绑定以下多实例的appid。在init方法之后，start方法之前调用如下代码。

window.collectEvent('setNativeAppId', appid)

3.5 初始化配置一览表

4.1 初始化完成

在浏览器中运行您的页面，开启log并注意控制台信息，SDK顺利完成初始化后，会打印如下信息：您的appid、当前的用户信息、当前SDK的版本号。例如：

当您看到这些信息后，代表SDK运行正常。

4.2 埋点请求正常

SDK初始化完成后，会自动上报一条predefine_pageview事件的埋点。
您可在浏览器控制台的network里看到list请求。例如：

点开请求可看到完整的埋点数据。例如：

此网络请求成功后示例：

如您按照本文档完整接入SDK后，没有上述的控制台日志，或者网络请求，或者网络请求的返回码不是0(常见错误码有-2、-100等)，请联系技术支持。

5.1 云控能力

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