You need to enable JavaScript to run this app.
导航
微信小程序SDK集成
最近更新时间:2024.05.29 16:21:42首次发布时间:2021.02.23 10:41:48

1. 集成

1.1 安装SDK

使用npm方式安装。

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

1.2 域名配置准备

在 「小程序后台-开发-开发设置-服务器域名」 中进行配置,具体可以参考小程序相应的官方文档,如微信小程序文档 https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html。

  • SaaS业务:将https://mcs.volceapplog.com添加到小程序后台的“request合法域名”中。
  • 私有化业务:将私有化部署的数据上报域名添加到小程序后台的“request合法域名”中,如您不清楚此域名,请联系您的项目经理或客户成功经理。
  • SaaS云原生业务:将https://gator.volces.com添加到小程序后台的“request合法域名”中。

1.3 老版本升级

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

2. 初始化

2.1 获取appid

在开始集成前,首先需要在集团中拥有一个应用,进行SDK集成前,您需要获取对应应用的appid信息。
私有化场景下您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid,详情请参见项目详情与应用列表
图片

2.2 初始化SDK示例

2.2.1 私有化

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

// 在入口页面初始化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等
});
$$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.2 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等
});
$$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 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等
});
$$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.3 引入调试工具 - DevTools组件(可选)

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

3. API说明

3.1 init

支持的初始化参数如下:

字段

字段值

字段说明

基础

app_id

number

业务产品的唯一标识

log

boolean

设置true后,控制台会打印调试信息

channel
别名:report_channel

枚举值:
cn、sg

上报通道,对应内置的上报域名和ab实验域名,每个应用只能设置唯一一个channel,请根据产品的具体情况,设置合适的channel
cn表示国内、sg表示新加坡
默认值为cn
内置上报域名
cn:https://mcs.volceapplog.com
sg:https://mcs.tobsnssdk.com
内置ab实验域名
cn:https://abtest.volceapplog.com
sg:https://toblog.tobsnssdk.com
即当channel值为cn时
上报域名为 https://mcs.volceapplog.com
ab实验域名为 https://abtest.volceapplog.com

channel_domain

string

可以自定义上报域名,会覆盖channel设置,通常私有化环境下使用

自动上报

auto_report

boolean

设置true后,会自动上报预定义事件,如app_launch、app_terminate、predefine_pageview、on_share等事件

ab实验

enable_ab_test

boolean

设置true后,会开启ab实验功能,包括使用getVar、getAllVars等api

ab_channel_domain

string

可以自定义ab实验域名,会覆盖channel设置,通常私有化环境下使用

clear_ab_cache_on_user_change

boolean

默认切换用户重新获取A/B配置信息,如果要关闭则把clear_ab_cache_on_user_change配置项置为false

缓冲
(仅2.5.0及以上版本支持)

enable_buffer

boolean

设置true后,将开启缓冲

buffer_interval

number

缓冲的间隔时间,单位是毫秒,默认值 5000,含义是到达间隔时间后会上报缓冲区的所有事件

buffer_number

number

缓冲的最大数量,默认值 5,含义是缓冲数量达到该值后会立即上报缓冲区的所有事件

缓存
(仅2.5.0及以上版本支持)

enable_cache

boolean

开启后,请求失败的事件会存到storage中,并在用户下一次再进小程序时补充上报
请注意:开启缓存后,会由于补充上报策略导致产生数据重复问题,但整体概率小所以量不会多

其他

enable_profile

boolean

设置true后,可以使用profile相关api

enable_filter_crawler

boolean

设置true后,在爬虫场景下(scene: 1129)不再上报事件

enable_custom_webid

boolean

首先初始化时开启enable_custom_webid,然后再通过config设置web_id,只有设置web_id后才会初始化完成,web_id的值要求必须是数字或者全是数字的字符串类型
$$Rangers.init({
enable_custom_webid: true,
});
$$Rangers.config({
web_id: '9876543210',
});

示例

// 参数:InitParams
// 返回值:void
$$Rangers.init({
    app_id: 1338,
    log: true,
    auto_report: true,
    enable_ab_test: true,
    clear_ab_cache_on_user_change: true,
    // ...
});

3.2 config

config方法可以调用多次,后面设置会覆盖之前相同的属性字段。

字段

类型

说明

示例

用户

user_unique_id

string

使用业务自身的用户id来设置user_unique_id

$$Rangers.config({
user_unique_id: 'zhangsan',
});

自定义

自定义属性

string/number

当属性是公共属性字段时,属性将有明确的位置,放在header下
当属性不是公共属性字段时,将放在header的custom下

$$Rangers.config({
city: '南京',
custom_name: 'vikings',
});

示例:

// 参数:ConfigParams
// 返回值:void
$$Rangers.config({
    city: '南京',
    custom_name: 'vikings',
    // ...
});

3.3 send

当初始化设置完毕之后,必须调用send方法,sdk才真正初始化完毕,之前不会有数据上报。
示例:

// 参数:无
// 返回值:void
$$Rangers.send();

3.4 event

进行事件上报。
事件命名规范:

  • 事件命名仅支持字母、数字和下划线,不要使用app_launch、app_terminate等SDK内部自动上报事件名。
  • 建议事件名和属性统一使用小写。
  • 事件属性值仅接受number与string类型。
  • 不要在事件属性中再嵌套object,即属性值不接受object类型。
  • 如果想要表达事件属性值空的含义,建议用“be_null”,不建议使用""或" "。

示例:

// 参数:name: string, params: object
// 返回值:void
$$Rangers.event('start_event', {
    start_time: 1630986183813,
    path: '...'
});