1.1 安装SDK

使用npm方式安装

npm install @datarangers/sdk-qg

1.2 域名配置准备

在 「小程序后台-开发-开发设置-服务器域名」 中进行配置，具体可以参考小游戏相应的官方文档，如微信小游戏文档 https://developers.weixin.qq.com/minigame/dev/guide/base-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.1 获取appid

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

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

2.2 初始化SDK示例

2.2.1 SaaS业务

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

$$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();

2.2.2 私有化业务

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

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

$$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();

2.2.3 SaaS云原生业务

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

$$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();

3.1 init

支持的初始化参数

示例

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

3.2 config

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

示例

// 参数：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: '...'
});

3.5 获取相关信息API

3.5.1 getToken

获取SDK的相关id，包含web_id、user_unique_id、ssid等
getToken(callback: (value: Record<string, string | number>) => void): void
getToken(): Promise<Record<string, string | number>>
示例

// 方式1
// 参数：(value: Record<string, string | number>) => void
// 返回值：void
$$Rangers.getToken((value) => {
    // value值大概如下：
    /* 
    {
        web_id: '1234567',
        user_unique_id: 'abcdefg',
        ssid: 'xxx-yyy-zzz',
        // ...
    }
    */
});

// 方式2
// 参数：无
// 返回值：Promise<Record<string, string | number>>
$$Rangers.getToken().then((value) => {
    // value值大概如下：
    /* 
    {
        web_id: '1234567',
        user_unique_id: 'abcdefg',
        ssid: 'xxx-yyy-zzz',
        // ...
    }
    */
});

3.5.2 getConfig

获取已设置的公共属性，包含SDK自动获取的属性等
getConfig(key?: string): Record<string, any>
示例

// 参数：string 可选
// 返回值：Record<string, any>
const allConfig = $$Rangers.getConfig();
// allConfig值大概如下
/*
{
    device_brand: 'xxx',
    device_model: 'yyy',
    // ...
    city: 'nanjing',
    custom: {
        current_name: 'mini',
        // ...
    }
}
*/

const deviceBrand = $$Rangers.getConfig('device_brand');
// deviceBrand可能有值，也可能为undefined

3.6 AB实验API

需要开启enable_ab_test后，下面几个ab相关的方法才有效

3.6.1 getAllVars

获取ab实验所有配置信息
getAllVars(callback: (value: any) => void): void
getAllVars(): Promise
示例

// 方式1
// 参数：(value: any) => void
// 返回值：void
$$Rangers.getAllVars((value) => {
    // value值大概如下：
    /* 
    {
      aa: { val: 'aa-value', vid: '11' },
      test_before_6d: { val: 'test_before_6d-value', vid: '22' },
      bb: { val: 'bb-value', vid: '33' },
    }
    */
});

// 方式2
// 参数：无
// 返回值：Promise<any>
$$Rangers.getAllVars().then((value) => { 
    // value值大概如下：
    /* 
    {
      aa: { val: 'aa-value', vid: '11' },
      test_before_6d: { val: 'test_before_6d-value', vid: '22' },
      bb: { val: 'bb-value', vid: '33' },
    }
    */ 
});

3.6.2 getVar

获取ab实验配置中的实验对应的值
getVar(name: string, defaultValue: any, callback: (value: any) => void): void
getVar(name: string, defaultValue: any): Promise
示例

// 方式1
// 参数：string, any, (value: any) => void
// 返回值：void
$$Rangers.getVar('color', 'red', (value) => {
    // 当配置中存在color实验，value值为配置中的color对应的值，否则值为red
});

// 方式2
// 参数：string, any
// 返回值：Promise<any>
$$Rangers.getVar('color', 'red').then((value) => { 
    // 当配置中存在color实验，value值为配置中的color对应的值，否则值为red
});

3.7 Profile相关API

用户属性设置，需要开启enable_profile后，下面几个profile相关的方法才有效

3.7.1 profileSet

将属性字段用新的值覆盖，一次可以设置一个或多个属性，支持数组类型属性值
profileSet(params: Record<string, string | number | Array>): void
示例

// 参数：Record<string, string | number | Array<string>>
// 返回值：void
$$Rangers.profileSet({
    trade: '篮球',
    interests: ['篮球', '跑步', '摄影'],
});

3.7.2 profileSetOnce

按属性字段，只设置一次，如果已经有值，则不再更新
profileSetOnce(params: Record<string, string | number | Array>): void
示例

// 参数：Record<string, string | number | Array<string>>
// 返回值：void
$$Rangers.profileSetOnce({
    trade: '篮球',
});

3.7.3 profileUnset

删除某个属性的值
profileUnset(key: string): void
示例

// 参数：string
// 返回值：void
$$Rangers.profileUnset('trade');

3.7.4 profileIncrement

将数值型属性增加指定的值，可以为负数
profileIncrement(params: Record<string, number>): void
示例

// 参数：Record<string, number>
// 返回值：void
$$Rangers.profileIncrement({
    age: 10,
    money: -10000,
});

3.7.5 profileAppend

当属性不存在时候，创建属性，并set，如果是数组类型属性的，会把值追加进数组
profileAppend(params: Record<string, string | number | Array>): void
示例

// 参数：Record<string, string | number | Array<string>>
// 返回值：void
$$Rangers.profileAppend({
    trade: '篮球',
    interests: ['钓鱼'],
});