You need to enable JavaScript to run this app.
导航
支付宝小程序SDK
最近更新时间:2024.05.15 17:29:30首次发布时间:2021.03.11 16:09:24

1. 集成

1.1 安装SDK

使用npm方式安装

npm install @datarangers/sdk-mp

1.2 域名配置准备

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

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

1.3 老版本升级

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

1.4 旧版本说明

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

2. 初始化

2.1 获取appid

在开始集成前,首先需要在集团中拥有一个应用。
「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid。
图片

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而非字符串
    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.2 私有化业务

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

// 在入口页面初始化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',
});
$$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',
        });
    }
});

3. 用户与用户属性

3.1 登录态变化调用

3.1.1 账户登录

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

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

3.2 设置用户属性

3.2.1 profileSet

设置用户属性,存在则覆盖,不存在则创建。

// 示例:设置用户属性,属性名为key,属性值为value
$$Rangers.profileSet({
    key: 'value' // 值支持字符串,数字,数组
});

3.2.2 profileSetOnce

设置用户属性,存在则不设置,不存在则创建,适合首次相关的用户属性,比如首次访问时间等。

// 示例:设置用户属性,属性名为key_once,属性值为value_once
$$Rangers.profileSetOnce({
    key_once: 'value_once' // 值支持字符串,数字,数组
});

3.2.3 profileIncrement

设置数值类型的属性,可进行累加。

// 示例:设置用户属性,属性名为key,属性值为1
$$Rangers.profileIncrement({
    key: 1
});

3.2.4 profileAppend

设置List类型的用户属性,可持续向List内添加。

// 示例:设置用户属性,属性名为key,原本已有属性值,现添加属性值为value_append
$$Rangers.profileAppend({
    key: 'value_append'
});

3.2.5 profileUnset

删除用户的属性。

// 示例:删除用户属性,属性名为key
$$Rangers.profileUnset('key');

4. 获取实验参数

版本1.0.9开始,sdk增加了ab实验能力,提供了getVar、getAllVars等方法,这些方法在开启ab实验时才有效,即enable_ab_test: true。「A/B 测试」通常在SDK 初始化后会向分流服务发送一个分流请求(request),在获取到分流服务的响应(response)后,客户端开发可以根据分流的结果参数完成代码分支。

  • 请注意此步骤的前置条件:已经根据实验的需求方创建好了实验及相关的参数,具体见“创建实验”。

4.1 getVar

获取ab实验元信息中的变量对应的值。 一个变量name是和一个vid绑定的,获取成功之后,会把对应的vid设置到sdk上报的公共属性里。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app,以便其他页面调用。
    //experiment-key 为实验参数的key ,用户开发做代码分支,default-value 为网络异常时的兜底方案,建议和对照组value一致
    this.$$Rangers.getVar('experiment-key', 'defaulte-value', function(value) {
        console.log(value);
    });
    //示例
    this.$$Rangers.getVar('size', '1', function(value) {
        console.log(value);
    });
  }
});

当调用getVar 的方法会自动上报曝光事件(ab_exposure),用于内部处理进组用户的相关统计。

4.2 getAllVars

如果需要获取所有ab实验的进组信息可使用getAllVars方法,但是此方法不会上报曝光事件,因此调用此方法系统不会有数据显示,只做获取进组信息接口使用。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app,以便其他页面调用。
    this.$$Rangers.getAllVars(function(data) {
        //data数据格式如下:
        // {
        //   "aa": {"vid": "1183", "val": true},
        //   "test_before_6d": {"vid": "2446", "val": "fail"}
        // }
    });
  }
});

参数

必选

说明

示例

callback

(data: { [key: string]: { val: any,
vid: string } }) => void
获取所有实验数据时候的回调函数。

{
"aa": {"vid": "1183", "val": true},
"test_before_6d": {"vid": "2446", "val": "fail"}
}

5. 事件与事件属性(实验指标)

5.1 上报代码埋点

用户行为日志采用事件event+属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。
仅上报事件的代码埋点,示例如下:

// 示例:上报事件event,该事件不包含属性
// 置于业务逻辑对应位置
app.$$Rangers.event('event');

上报事件和对应属性的代码埋点,示例如下:

// 示例:上报事件event,该事件包含两个属性
//      一个string类型的属性,属性名为key_string,属性值为value_string
//.     一个int类型的属性,属性名为key_int,属性值为10
// 置于业务逻辑对应位置
app.$$Rangers.event('event', {
   key_string: 'value_string',
   key_int: 10
});

5.2 事件公共属性

如需在每个事件中都包括某属性,可通过公共属性设置,无需在每个事件中重复设置。公共属性只需设置一次,即可包括在所有代码埋点事件、预置事件和全埋点事件中。

5.2.1 设置公共属性

// 示例:设置自定义的公共属性,属性名为key_public,属性值为value_public
$$Rangers.config({
   key_public: 'value_public'
});

6. API说明

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

6.2 config

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

字段

类型

说明

示例

用户

user_unique_id

string

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

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

自定义

自定义属性

string/number

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

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

示例

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

6.3 send

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

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

6.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: '...'
});

6.5 SDK预设公共属性字段

SDK 会在 config({}) 中默认给一些字段赋值,这些SDK 默认设置的字段可以被覆盖。
请注意,增长分析产品中“分享用户”功能的昵称、头像、地域信息需您主动上报。

字段

类型

说明

是否自动设置

举例

platform

string

平台类型

自动采集

mp

device_brand

string

设备品牌

自动

"iPhone"

device_model

string

设备型号

自动

"iPhone 7"

os_name

string

客户端系统

自动

"ios"

os_version

string

客户端/操作系统版本

自动

"iOS 10.0.1"

screen_width

number

屏幕宽度

自动

375

screen_height

number

屏幕高度

自动

812

resolution

string

屏幕分辨率

自动

"375x812"

access

string

网络类型

自动

"wifi"

language

string

系统语言

自动

"zh_CN"

device_id

number

设备id

业务方设置

67834512

app_name

string

应用名称

业务方设置

"xxx"

app_version

string

应用版本

业务方设置

"2.5.0"

region

string

地区

业务方设置

"cn"

province

string

省份

业务方设置

"江苏"

city

string

城市

业务方设置

"南京"

nick_name

string

昵称

业务方设置

"张三"

gender

string

性别

业务方设置

"male"

avatar_url

string

头像

业务方设置

"https://xxx"

timezone

number

时区

业务方设置

8

tz_offset

number

时区偏移

业务方设置

-28800

6.6 获取平台生成的各种ID

获取SDK的token信息,里面包含web_id、ssid、user_unique_id信息。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app,以便其他页面调用。
    this.$$Rangers.getToken(function(token) { 
        //token数据内容例如:
        // {
        //    "web_id":"6748002161499735560",
        //    "ssid":"579bc89a-bd45-4021-8314-669c35f38e3d",
        //    "user_unique_id":"xxx",
        // }
    });
  }
});

6.7 获取实验版本ID

注意

开展AB实验必须调用获取实验参数的api(详情请参见 获取实验参数 章节)。如需获取用户所有曝光或命中实验的版本ID(vid)时,可使用此API,此API不会上报abtest_exposure曝光事件。

$$Rangers.getAbSdkVersion();

6.8 自定义webid

如需更改SDK默认的webid,首先初始化时开启enable_custom_webid: true,然后再通过config设置web_id。

$$Rangers.init({
    // 其他初始化配置
    enable_custom_webid: true, // 初始化时开启enable_custom_webid
});

开启后,可在其他时机config设置web_id。

$$Rangers.config({
    web_id: '11111111111111', // webid的值要求纯数字或全是数字的字符串类型
});

需要注意的是,当开启了自定义webid后,必须主动设置webid,SDK才会真正初始化并继续执行后续的流程。此场景适合H5页面在微信小程序中打开,需要传递微信的unionID或者openID给H5页面。

6.9 预置事件自动上报

使用预置事件自动上报,需要在初始化时配置auto_report参数为true。建议您开启此事件。
请注意:自定义事件的事件名请勿与预置事件重名。
小程序预置事件请参考:小程序预置事件及属性

7.小程序第三方框架适配

针对自动上报事件(app_launch、app_terminate等),SDK针对tarouni-app第三方框架进行了兼容处理。此兼容需保证 SDK 版本高于 1.1.1。

7.1 taro框架使用方式

  • 在 app.jsx 中通过 import 引入 SDK
  • 在 App 类前初始化完成 SDK

7.2 uni-app框架使用方式

  • 在 main.js 中通过 import 引入 SDK
  • 在 App 类前初始化完成 SDK

7.3 预置事件上报排查

如果发现有部分自动事件未上报情况,可以按照下面几种情况排查:

  • SDK版本需要1.1.1+,并且尽可能的将SDK的初始化放在工程入口最前面;
  • 第三方框架需要当前比较新的版本,taro:、uni-app: (其他第三方框架目前还未做特别兼容处理,有可能不支持);
  • 同时引入了其他类似功能的SDK,这种情况下尽量将我们的SDK放在其他SDK后面进行初始化(但是依然需要在App类前)。

三、调试试验

1. 为什么要调试实验

实验上线前需要保证前面的集成过程无误,上线后才能保证实验结果的科学和有效 !

2. 开启调试状态

参照“创建实验”章节,使实验处于“调试中” 状态,如下图所示:

  • 实验状态有:运行中、调试中、已冻结、已暂停、已结束、待审批。
    图片

3. 通过接口获取调试设备的统计口径

分别在微信小程序SDK init和config中打开日志和A/B Test开关,并完成初始化:

  • 通过6.6中getToken方法获取对应的ssid

图片

4. 添加至白名单

将您的测试设备 ssid 到白名单中,并在右下角点击"保存"按钮。
图片

5. 微信小程序参数调试

设置完上述步骤后,清空缓存并编译,观察ab数据包(即abtest_config接口返回的实验数据),是否获取到了Tester 中的配置。下图中是成功获取到了实验参数:
图片
如果您的微信小程序没有发出实验请求,或实验请求为空, 请按下面步骤排查:

  • 初始化时是否正确设置 enable_ab_test: true;
  • 微信小程序是否将“A/B Test域名”和“事件上报域名”添加到 微信开发者后台/开发/开发者设置/服务器域名 "request合法域名" 中,具体域名参考1.2~1.4章节。

触发实验事件后,您可以在事件数据包头观察到 ab_sdk_version 字段和内容(下图以ab_exposed事件举例,其他事件以此类推):
图片

6. 真机或模拟器实验场景调试

在实验参数调试正常的情况下,开发或者是QA/PM/运营 同学需要观察实验所在的页面是否符合之前实验设计的预期。

  • 关于实验设计和准备,请参照“创建实验”章节。