当前主流小程序均可参考本文进行SDK集成，接入并上报对应小程序的数据，主要包括：

• 微信小程序
• 字节跳动小程序
• 支付宝小程序
• 百度小程序
• 钉钉小程序

1.1 安装SDK

使用npm方式安装

# 当前最新版本为 2.12.2
npm install @datarangers/sdk-mp

1.2 域名配置准备

1.2 获取上报地址并配置小程序白名单

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，将数据上报地址添加到小程序后台的“request合法域名”中，如果上报地址设置错误，后续会导致您无法正常上报、查询到数据。

获取数据上报地址

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

私有化环境

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址，将私有化部署的数据上报域名添加到小程序后台的“request合法域名”中。如您不清楚此地址，请联系您的项目经理或客户成功经理。

配置小程序白名单

在 「小程序后台-开发-开发设置-服务器域名」 中进行配置，具体可以参考小程序相应的官方文档，如 微信小程序文档。
，各环境各地域的上送地址请参见上文的 获取数据上送地址 章节。

1.3 老版本升级

请注意，如果是SaaS-非云原生业务，升级SDK到最新版（2.x.x版本）时，需要补充将https://mcs.volceapplog.com和https://abtest.volceapplog.com添加到小程序后台的“request合法域名”中，已添加过https://mcs.ctobsnssdk.com和https://toblog.ctobsnssdk.com不要立即移除。

1.4 旧版本说明

如果集成旧版本SDK(2.0以下版本)，需要将https://mcs.ctobsnssdk.com和https://toblog.ctobsnssdk.com 添加到微信开放平台的请求白名单中。

2.1 获取appid

在开始集成前，首先需要在集团中拥有一个应用，请参考：如何创建应用。

• SaaS-云原生
  
• SaaS-非云原生
  

2.2 初始化SDK

2.2.1 SaaS-云原生

// 在入口页面初始化SDK
// app.js
import $$Rangers from '@datarangers/sdk-mp';
$$Rangers.init({
    app_id: 0000, // 替换成申请的app_id，参考2.1节获取，注意类型是number而非字符串
    channel_domain: "https://gator.volces.com", // 设置数据上送域名，各环境各地域的上送地址请参见上文的 获取数据上送地址 章节。
    log: true, // 开启后会控制台会打印日志，开发阶段有助于查看埋点上报过程
    auto_report: true, // 开启后会上报一些预定义事件，如app_launch、app_terminate等
    enable_ab_test: true, // 开启ab实验
    ab_channel_domain: "https://tab.volces.com", // 分流请求域名
});
$$Rangers.config({
    mp_name: 'xyz小程序', // 一些预定义属性，可以通过config进行设置mp_version: '1.1.1',
    mp_version: '1.1.1',
});
$$Rangers.send();

App({
    onLaunch: function () {
        this.$$Rangers = $$Rangers;
    
        // 如果想设置用户标识，比如想使用open_id来标识用户，可以在获取到open_id后把值设置给user_unique_id
        this.$$Rangers.config({
            user_unique_id: '获取到的open_id', //可以是open_id，也可以union_id等其他业务觉的可以用来标识用户唯一性的值
        });
        // 调用event方法上报具体事件
        this.$$Rangers.event('test_event', {
            from: 'launch', // 支持任意属性，值支持数字、字符串等
        });
    }
});

// 其他页面上报事件，如：
// pages/index/index.js
Page({
    onLoad() {
        getApp().$$Rangers.event('bind_view_tap', {
            'title': 'chart',
        });
    }
});

2.2.2 SaaS-非云原生

// 在入口页面初始化SDK
// app.js
import $$Rangers from '@datarangers/sdk-mp';

$$Rangers.init({
    app_id: 0000, // 替换成申请的app_id，参考2.1节获取，注意类型是number而非字符串
    log: true, // 开启后会控制台会打印日志，开发阶段有助于查看埋点上报过程
    auto_report: true, // 开启后会上报一些预定义事件，如app_launch、app_terminate等
    enable_ab_test: true, // 开启ab实验
});
$$Rangers.config({
    mp_name: 'xyz小程序', // 一些预定义属性，可以通过config进行设置
    mp_version: '1.1.1',
});
$$Rangers.send();

App({
    onLaunch: function () {
        this.$$Rangers = $$Rangers;
    
        // 如果想设置用户标识，比如想使用open_id来标识用户，可以在获取到open_id后把值设置给user_unique_id
        this.$$Rangers.config({
            user_unique_id: '获取到的open_id', //可以是open_id，也可以union_id等其他业务觉的可以用来标识用户唯一性的值
        });

        // 调用event方法上报具体事件
        this.$$Rangers.event('test_event', {
            from: 'launch', // 支持任意属性，值支持数字、字符串等
        });
    }
});

// 其他页面上报事件，如：
// pages/index/index.js
Page({
    onLoad() {
        getApp().$$Rangers.event('bind_view_tap', {
            'title': 'chart',
        });
    }
});

2.2.3 私有化

私有化业务需要明确设置数据上报域名，如您不清楚此域名，请联系您的项目经理或客户成功经理。

// 在入口页面初始化SDK
// app.js
import $$Rangers from '@datarangers/sdk-mp';
$$Rangers.init({
    app_id: 0000, // 替换成申请的app_id，参考2.1节获取，注意类型是number而非字符串
    channel_domain: "{{DOMAIN}}", // 设置私有化部署数据上送域名，如您不清楚此地址，请联系您的项目经理或客户成功经理
    log: true, // 开启后会控制台会打印日志，开发阶段有助于查看埋点上报过程
    auto_report: true, // 开启后会上报一些预定义事件，如app_launch、app_terminate等
    enable_ab_test: true, // 开启ab实验
    ab_channel_domain: "{{ABTEST_DOMAIN}}", // 设置ab分流接口域名，默认为channel_domain的设置
});
$$Rangers.config({
    mp_name: 'xyz小程序', // 一些预定义属性，可以通过config进行设置mp_version: '1.1.1',
    mp_version: '1.1.1',
});
$$Rangers.send();

App({
    onLaunch: function () {
        this.$$Rangers = $$Rangers;
    
        // 如果想设置用户标识，比如想使用open_id来标识用户，可以在获取到open_id后把值设置给user_unique_id
        this.$$Rangers.config({
            user_unique_id: '获取到的open_id', //可以是open_id，也可以union_id等其他业务觉的可以用来标识用户唯一性的值
        });
        // 调用event方法上报具体事件
        this.$$Rangers.event('test_event', {
            from: 'launch', // 支持任意属性，值支持数字、字符串等
        });
    }
});
 
// 其他页面上报事件，如：
// pages/index/index.js
Page({
    onLoad() {
        getApp().$$Rangers.event('bind_view_tap', {
            'title': 'chart',
        });
    }
});

2.2.4 多实例初始化（可选）

// 导入sdk的类（构造器）
import SDK from '@datarangers/sdk-mp/esm/sdk';

// 对构造器使用new操作产生实例1
const $$sdk1 = new SDK();
// 其他api调用完全一样
$$sdk1.init({
    app_id: 1338,
});
$$sdk1.config({});
$$sdk1.send();

// 对构造器使用new操作产生实例2
const $$sdk2 = new SDK();
// 其他api调用完全一样
$$sdk2.init({
    app_id: 1339, // app_id不能与其他实例相同
});
$$sdk2.config({});
$$sdk2.send();

2.3 引入调试工具 - DevTools组件(可选)

DevTools是Debug环境下辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件。详细接入文档请查阅：小程序埋点开发工具。