更新时间:2023.04.24 19:12:09
上报事件和属性前,请先阅读数据格式介绍。
如您的产品中有账户体系,请在用户登录后立即设置uuid,以保证用户登录前后口径一致性。
$$Rangers.config({ user_unique_id: '{{USER_UNIQUE_ID}}' });
2.6.0+版本,可以使用setUserUniqueID方法进行设置uuid
// 设置uuid $$Rangers.setUserUniqueID('{{USER_UNIQUE_ID}}'); // 清空uuid $$Rangers.setUserUniqueID(null);
说明
注意:使用 profile api 之前,需要在 init 中配置 enable_profile = true
。
设置用户属性,存在则覆盖,不存在则创建。
// 示例:设置用户属性,属性名为key,属性值为value $$Rangers.profileSet({ key: 'value' // 值支持字符串,数字,数组 });
设置用户属性,存在则不设置,不存在则创建,适合首次相关的用户属性,比如首次访问时间等。
// 示例:设置用户属性,属性名为key_once,属性值为value_once $$Rangers.profileSetOnce({ key_once: 'value_once' // 值支持字符串,数字,数组 });
设置数值类型的属性,可进行累加。
// 示例:设置用户属性,属性名为key,属性值为1 $$Rangers.profileIncrement({ key: 1 });
设置List类型的用户属性,可持续向List内添加。
// 示例:设置用户属性,属性名为key,原本已有属性值,现添加属性值为value_append $$Rangers.profileAppend({ key: 'value_append' });
删除用户的属性。
// 示例:删除用户属性,属性名为key $$Rangers.profileUnset('key');
用户行为日志采用事件event+属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。 仅上报事件的代码埋点,示例如下:
// 示例:上报事件event,该事件不包含属性 // 置于业务逻辑对应位置 $$Rangers.event('event');
上报事件和对应属性的代码埋点,示例如下:
// 示例:上报事件event,该事件包含两个属性 // 一个string类型的属性,属性名为key_string,属性值为value_string // 一个int类型的属性,属性名为key_int,属性值为10 // 置于业务逻辑对应位置 $$Rangers.event('event', { key_string: 'value_string', key_int: 10 });
如需在每个事件中都包括某属性,可通过公共属性设置,无需在每个事件中重复设置。公共属性只需设置一次,即可包括在所有代码埋点事件、预置事件和全埋点事件中。
// 示例:设置自定义的公共属性,属性名为key_public,属性值为value_public $$Rangers.config({ key_public: 'value_public' });
2.6.0+版本,可以使用setHeaderInfo方法进行设置公共属性
// 示例:设置自定义的公共属性,属性名为key_public,属性值为value_public $$Rangers.setHeaderInfo('key_public', 'value_public');
2.6.0+版本,可以使用removeHeaderInfo方法进行移除公共属性
// 示例:移除自定义的公共属性,属性名为key_public $$Rangers.removeHeaderInfo('key_public');
SDK 会在 config({})
中默认给一些字段赋值,这些SDK 默认设置的字段可以被覆盖。 请注意,增长分析产品中“分享用户”功能的昵称、头像、地域信息需您主动上报。
字段 | 类型 | 说明 | 是否自动设置 | 举例 |
---|---|---|---|---|
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 |
获取SDK的token信息,里面包含web_id、ssid、user_unique_id信息。
App({ onLaunch: function () { this.$$Rangers = $$Rangers; // 绑定到全局的app,以便其他页面调用。 this.$$Rangers.getToken((token) => { // token数据内容例如: // { // "web_id":"6748002161499735560", // "ssid":"579bc89a-bd45-4021-8314-669c35f38e3d", // "user_unique_id":"xxx", // } }) // ... } });
如需更改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页面。
使用预置事件自动上报,需要在初始化时配置auto_report
参数为true。建议您开启此事件。 请注意:自定义事件的事件名请勿与预置事件重名。 小程序预置事件请参考:小程序预置事件及属性。
通过init方法设置auto_report参数来开启功能
参数 | 参数值类型 | 说明 |
---|---|---|
auto_report | boolean | 默认值为false |
const $$Rangers = require('@datarangers/sdk-mp'); $$Rangers.init({ // ... 其他初始化配置 // 或者 auto_report: {} auto_report: true }); $$Rangers.send();
const $$Rangers = require('@datarangers/sdk-mp'); $$Rangers.init({ // ... 其他初始化配置 auto_report: { click: true } }); $$Rangers.send();
const $$Rangers = require('@datarangers/sdk-mp'); $$Rangers.init({ // ... 其他初始化配置 auto_report: { click: true, appError: false } }); $$Rangers.send();
当click设为true时,SDK将在那些绑定了一些事件函数的组件被点击时上报bav2b_click事件(目前只支持bindtap类型),该事件会采集组件上的dataset数据集中的内容作为参数上报。 假设如下组件,设置了id="diandian"以及data-hi="hello"
<view id="diandian" data-hi="hello" bindtap="tapMethod">点我</view>
当该组件被点击时,上报bav2b_click事件以及采集的参数大概如下
{ event: 'bav2b_click', params: { path: 'pages/index/index', query_id: 'diandian', query_hi: 'hello' } }
需要注意的是,不同实例的app_id需要不同。
// 导入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();
注意在飞书小组件场景下,不支持预置事件上报(即auto_report参数设置无效)。版本要求:2.9.0+
import Sdk from '@datarangers/sdk-mp/esm/block'; // 如果需要ab插件等功能,则需要手动加载插件 import AbPlguin from '@datarangers/sdk-mp/esm/plugin/ab'; Sdk.usePlugin(AbPlugin); // 需要其他插件的功能的话,与上面ab插件的使用方式相同 const $$sdk = new Sdk(); $$sdk.init({ //... }); $$sdk.config({}); $$sdk.send(); // ....
针对自动上报事件(app_launch、app_terminate等),SDK针对taro
、uni-app
第三方框架进行了兼容处理。此兼容需保证 SDK 版本高于 1.1.1。
在 app.jsx 中通过 import 引入 SDK
在 App 类前初始化完成 SDK
在 main.js 中通过 import 引入 SDK
在 App 类前初始化完成 SDK
如果发现有部分自动事件未上报情况,可以按照下面几种情况排查:
尽可能的将SDK的初始化放在工程入口最前面;
第三方框架需要当前比较新的版本,taro、uni-app (其他第三方框架目前还未做特别兼容处理,有可能不支持);
同时引入了其他类似功能的SDK,这种情况下尽量将我们的SDK放在其他SDK后面进行初始化(但是依然需要在App类前)。