You need to enable JavaScript to run this app.
导航
小游戏SDK集成
最近更新时间:2024.09.19 10:28:39首次发布时间:2022.10.17 11:13:14

1. 集成

1.1 安装SDK

使用npm方式安装

npm install @datarangers/sdk-qg

1.2 域名配置准备

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

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

1.3 老版本升级

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

2. 初始化

2.1 获取appid

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

2.2 初始化SDK示例

私有化业务

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

// 在入口页面初始化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();

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等事件

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.1.0及以上版本支持)

enable_buffer

boolean

设置true后,将开启缓冲

buffer_interval

number

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

buffer_number

number

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

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

enable_cache

boolean

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

其他

enable_profile

boolean

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

示例

// 参数: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方法可以调用多次,后面设置会覆盖之前相同的属性字段

字段

类型

说明

示例

用户

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

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: ['钓鱼'],
});