1.2.1.7 小程序 SDK使用说明

优质

小牛编辑

128浏览

2023-12-01

1.1. 当前支持的小程序类型

当前支持四类小程序：微信小程序(miniType: 'wx')、字节跳动小程序(miniType: 'tt')、支付宝小程序(miniType: 'my')、百度小程序(miniType: swan)，这四类小程序共用一套sdk。

1.1.1. 显示指明小程序类型

小程序对应的类型名: 微信小程序(miniType: 'wx')、字节跳动小程序(miniType: 'tt')、支付宝小程序(miniType: 'my')、百度小程序(miniType: swan)。

初始化采集器时，需要显示指明当前小程序类型如: miniType: 'tt' ;

详细使用请看下面初始化配置说明，若初始化时不显示申明，默认为"微信小程序"。

这四类小程序对应的类型说明:

const SDKTYPE = {
  'wx': 'MiniProgram',
  'tt': 'toutiaoMiniProgram',
  'my': 'alipayMiniProgram',
  'swan': 'baiduMiniProgram'
};

采集的日志里对应的字段：sdkType。比如当前配置的是字节跳动小程序：miniType: 'tt'，那么日志中sdkType: 'toutiaoMiniProgram'。

1.2. 获取和引入 HubbleData SDK

获取到 DATracker.js 文件后，把该文件放到小程序根目录 utils 目录下, 然后在 app.js 第一行引入 import DATracker from './utils/DATracker';(注意：下载下来的文件名改成DATracker.js即可)

1.2.1. 使用

sdk初始化配置（必须）编辑 app.js

//在app.js 第一行引入sdk
import DATracker from './utils/DATracker'
//sdk 初始化配置, 其中 88888 替换对应的 appkey
DATracker.init('88888');

如果初始化的时候需要设置其它配置，如下

//一下配置为选填
DATracker.init('88888', {
    // 指明小程序类型: (微信: wx) | (字节跳动: tt) | (支付宝: my) | (百度: swan)
    miniType: 'wx', 
    //appVersion 为应用版本号属性
    appVersion: 'v1.0.1',
    //设置false，关闭调试模式，默认为false
    debug: false,
    //重写路由变动时触发的函数
    onPageShow: function(datracker, router, page) {
        //注意，如果要发送 PV事件，必须调用以下方法
        datracker.track_pageview({data: page['xxName']});
    }
});

现在其它Page 里就可以通过 getApp 来使用 sdk 的API了

// Page 模块
var app = getApp();
Page({
  data: {
    motto: '新梦想兔家庭智能管理平台',
    array:[{title:'我的购物',icon:'success'}]
  },
  tapName: function(event) {
     //触发自定义事件 
     app.DATracker.track('eventList', {
       title: event.target.dataset.title
     });
  }
})

1.3. 微信小程序HTTPS域名配置

登录公众平台-设置-开发者设置-安全域名配置中增加Hubble域名: https://hubble.netease.com(埋点日志上报需要)、wss://hubble.netease.com(A/B实验实时调试需要)

1.4. 如何标识用户

1.4.1. 在登录和注册成功后，调用 DATracker.login(userId) 来标识真实用户

sdk 会自动生成一个 deviceUdid 并永久保存到小程序的 localStorage 中，作为匿名用户唯一标识。如果你已知了真实的用户 id, 你可以通过 DATracker.login(userId) 设置用户 userId。

//在某个 Page 中
var app = getApp();
Page({
    data: {},
    loginOK: function(userId){
        app.DATracker.login(userId);
    }
})

1.4.2. 使用 DATracker.logout 切换到之前的匿名 id

//在某个 Page 中
var app = getApp();
Page({
    data: {},
    loginOut: function(){
        app.DATracker.logout();
    }
})

1.5. 自定义事件追踪

HubbleData SDK 初始化成功后，即可以通过 DATracker.track() 记录事件

//在某个 Page 中
var app = getApp();
Page({
    data: {},
    viewProduct: function(){
        // 追踪浏览商品事件。
        app.DATracker.track('ViewProduct', {
            ProductId: '123456'，
            ProductCatalog: "Laptop Computer",
            ProductName: "MacBook Pro",
            ProductPrice: 123.45
        });
    }
})

1.6. PV事件

SDK已经自动追踪了微信小程序中 Page onShow，这个会在每次打开页面都会调用一次（即PV）。手动调用接口: track_pageview(properties)


//在某个 Page 中
var app = getApp();
Page({
    data: {},
    onShow: function(){
        // 触发PV事件
        app.DATracker.track_pageview();
    }
})

注：若手动调用API，建议配置 onPageShow，这样关闭自动追踪PV事件。

1.7. 转发分享事件

SDK已经自动追踪了微信小程序中 onShareAppMessage，每次触发转发行为都会上报一次转发分享事件。手动调用接口： track_share(properties)


//在某个 Page 中
var app = getApp();
Page({
    data: {},
    onShareAppMessage: function(){
        // 触发转发分享事件
        app.DATracker.track_share();
    }
})

注：若手动调用API，建议关闭sdk自动追踪转发分享事件。

1.7.1. 转发分享事件sdk配置项介绍

sdk开启自动追踪了微信小程序中 onShareAppMessage方法，该配置项是sdk默认开启的。
```
// 开启追踪onShareAppMessage
DATracker.init('88888', {
 share: true
});
```
sdk开启分享后续追踪,开启后sdk在自定义分享的path上添加追踪标志。
```
//开启分享后续追踪
DATracker.init('88888', {
 allowAmendSharePath: true
});
```

允许所有页面都可分享

// 允许所有页面都可分享配置
DATracker.init('88888', {
shareAll: true,
share: false,
allowAmendSharePath: false
});

1.8. 预置属性

所有事件都会有的预置属性：

字段名称	类型	说明
deviceOs	string	操作系统
deviceOsVersion	string	操作系统版本
devicePlatform	string	平台
screenWidth	int	分辨率（宽）
screenHeight	int	分辨率（高）
deviceModel	string	设备型号
networkType	string	网络
localeLanguage	string	本地语言
appVersion	string	应用版本
currentUrl	string	当前页url
urlPath	string	当前页路径
referrer	string	表示：当小程序内部页面互相切换时，记住上一页的currentUrl
scene	string	表示：场景值 ,如: '1001'

1.9. 设置用户属性

1.9.1. DATracker.people.set(properties)

直接设置用户的属性，如果存在则覆盖。

properties：object，必选。

//在某个 Page 中
var app = getApp();
Page({
    data: {},
    viewProduct: function(){
        app.DATracker.people.set({height:'188cm'});
    }
})

1.9.2. 内置用户属性列表

字段名称	类型	说明
$realName	string	姓名
$age	int	用户年龄
$account	string	用户登录账号
$birthday	date	用户出生日期格式 yyyy-MM-dd
$gender	string	用户性别
$country	string	国家
$region	string	省份
$city	string	城市
persistedTime	date	首次使用时间
lastUseTime	date	最近使用时间

1.9.3. 内置属性设置方法

设置用户名

DATracker.people.set_realname(realname)

设置国家

DATracker.people.set_country(country)

设置省份

DATracker.people.set_province(province)

设置城市

DATracker.people.set_city(city)

设置性别

DATracker.people.set_gender(gender)

设置出生日期

DATracker.people.set_birthday(birthday)

设置账户 + 姓名 + 生日 + 性别

DATracker.people.set_populationWithAccount(account, realname, birthday, gender)

设置国家 + 省份 + 城市

DATracker.people.set_location(country, region, city)

1.10. 其它配置

1.10.1. 应用版本号 appVersion

在 app.js 中编辑

import DATracker from './utils/DATracker'
DATracker.init('88888', {
    //appVersion 为应用版本号属性
    appVersion: 'v1.0.1'
});

1.10.2. onPageShow {Function}

重写路由变动时触发的函数，此时不再自动触发 PV事件，如果要发送 PV事件，必须调用 datracker.track_pageview()方法

import DATracker from './utils/DATracker'
//一下配置为选填
DATracker.init('88888', {
    //重写路由变动时触发的函数
    /**
     * @param {Object} datracker sdk实例 == DATracker
     * @param {String} router 路由地址
     * @param {Object} page 当前页Page对象
     */
    onPageShow: function(datracker, router, page) {
        //注意，如果要发送 PV事件，必须调用以下方法
        datracker.track_pageview({data: page['xxName']});
        //其它事件
        datracker.track('pageR', {
            pageName: 'ss'
        });
    }
});

1.10.3. share {Boolen}

是否自动上报转发分享事件，默认 true

import DATracker from './utils/DATracker'
// 关闭自动追踪转发分享事件
DATracker.init('88888', {
    share: false
});

1.10.4. debug {String}

调试配置，默认为 false, 不启动。配置为 true后，控制台打印出发送的埋点数据

import DATracker from './utils/DATracker'
//一下配置为选填
DATracker.init('88888', {
    debug: true
});

1.10.5. sendConfig {Object}

小程序中 request 的最大并发数是有限制的，当应用中并发数过多的时候，可以通过配置 sendConfig，接管sdk的数据发送。

sendConfig.fn( params ) 数据发送函数，接管sdk的数据发送方法写入此函数中 -- params ==> params.url 数据发送的url -- params ==> params.method 数据发送类型 -- params ==> params.success 数据发送成功后执行方法 -- params ==> params.fail 数据发送失败后执行方法
sendConfig.start 默认为 false , 设置为 true 后表示启动接管 sdk的数据发送，设置为 false 后启动默认内置sdk数据发送

import DATracker from './utils/DATracker'

//接管sdk的数据发送函数实现
function send(params) {
    wx.request({
      url: params.url,
      method: params.method,
      success: params.success,
      fail: params.fail
    }); 
}

DATracker.init('88888', {
  appVersion: 'v0.0.1',
  //重新定义数据发送方式
  sendConfig: {
    start: true,
    fn: function(params) {
      send(params);
    }
  }
});

1.11. 其它 API

1.11.1. time_event

统计事件耗时(ms)，参数为事件名称。触发一次后移除该事件的耗时监听。

// Page 模块
var app = getApp();
//统计clickBuy事件的耗时
app.DATracker.time_event('clickBuy');
Page({
  data: {
    motto: '新梦想兔家庭智能管理平台',
    array:[{title:'我的购物',icon:'success'}]
  },
  buy: function(event) {
     //触发自定义事件 
     app.DATracker.track("clickBuy");
  }
})

1.12. 实际案例

获取到 DATracker.js 文件后，把该文件放到小程序根目录 utils 目录下。

1.12.1. 在根目录的 app.js 中引入

//在app.js 第一行引入sdk
import DATracker from './utils/DATracker'
DATracker.init('88888', {
    // 指明小程序类型: (微信: wx) | (字节跳动: tt) | (支付宝: my) | (百度: swan)
    miniType: 'wx', 
    //appVersion 为应用版本号属性
    appVersion: 'v1.0.1',
    //设置false，关闭调试模式，默认为false
    debug: false,
    //重写路由变动时触发的函数
    onPageShow: function(datracker, router, page) {
        //注意，如果要发送 PV事件，必须调用以下方法
        datracker.track_pageview({data: page['xxName']});
    }
});

1.12.2. 在 Page 里的 js中通过 getApp() 来调用 Hubble的sdk

// Page 模块
var app = getApp();
Page({
  data: {
    motto: '新梦想兔家庭智能管理平台',
    array:[{title:'我的购物',icon:'success'}]
  },
  tapName: function(event) {
     //触发自定义事件 
     app.DATracker.track('eventList', {
       title: event.target.dataset.title
     });
  }
})

当前版本支持编程实验

2.1. 小程序WSS域名配置

登录公众平台-设置-开发者设置-安全域名配置中增加Hubble域名: wss://hubble.netease.com

2.2. 引入 DATracker_ABtest.js

获取到和引入 DATracker_ABtest.js后(注意：下载下来的文件名改成 DATracker_ABtest.js 即可)，把该文件放到小程序根目录 utils 目录下,然后在 app.js 中添加如下代码（必须先引入DATracker.js）：

//app.js
import DATracker from './utils/DATracker';
import ABtest from './utils/DATracker_ABtest';

2.3. 初始化

DATracker初始化后，再初始化ABtest。

DATracker.init('88888', {
  // 指明小程序类型: (微信: wx) | (字节跳动: tt) | (支付宝: my) | (百度: swan)
  miniType: 'wx', 
  appVersion: 'v0.0.1',
  debug: true
});

// 将ABtest实例注册到 DATracker 中，方便后面使用
DATracker['abtest'] = new ABtest(DATracker);

2.4. 获取实验变量


// 调用 DATracker.abtest.get_variation 方法
DATracker.abtest.get_variation((flgs) => {
    // 获取变量`aColor`的值，默认值设置为'red'；
    const aColor = flgs.get('aColor', 'red');
    this.setData({
       aColor: aColor
    });
});

<view>
    <label style="background-color:">该label背景颜色通过获取实验变量来设置</label>
</view>

当需要某个变量时，首先调用 DATracker.abtest.get_variation 方法，参数是一个回调函数。回调函数参数是abtest对象，比如命名为 flgs ，再调用 flgs.get 方法，获取变量值。其中 get 方法接受两个变量：变量名称和变量默认值。

2.5. 主动拉取实验配置方法

DATracker.abtest.async_get_variable();

2.6. 开启实验（非必须）

默认开启实验，若需关闭: enable_abtest : false


// 实验sdk初始化时配置，内置默认开启
DATracker['abtest'] = new ABtest(DATracker, { enable_abtest: true });

2.7. 自定义拉取实验配置频率（非必须）

默认拉取实验配置频率60分钟一次，即本地缓存为60分钟。

自定义配置（单位分钟）: interval_mins_abtest : 60


// 实验sdk初始化时配置，内置默认60分钟；
DATracker['abtest'] = new ABtest(DATracker, { interval_mins_abtest: 60 });

2.8. 预定义变量（全局配置）（非必须）

预定义变量配置: default_variables : { aColor: 'red' }


// 实验sdk初始化时配置，预定义变量 aColor，默认值 red
DATracker['abtest'] = new ABtest(DATracker, default_variables : { aColor: 'red' });

2.9. A/B实验示例

2.9.1. 在app.js 第一行引入sdk


import DATracker from './utils/DATracker';
import ABtest from './utils/DATracker_ABtest';

DATracker.init('88888', {
  // 指明小程序类型: (微信: wx) | (字节跳动: tt) | (支付宝: my) | (百度: swan)
  miniType: 'wx', 
  appVersion: 'v0.0.1',
  debug: true
});

// 将ABtest实例注册到 DATracker 中，方便后面使用
DATracker['abtest'] = new ABtest(DATracker);

2.9.2. 在 Page 里调用

改变颜色


// Page 模块

var app = getApp();
// 获取A/B实验实例
var ABTest = app.DATracker['abtest'];

Page({
  data: {
    motto: '新梦想兔家庭智能管理平台',
    aColor: ''
  },
  onLoad: function(event) {
    // 调用 ABTest.get_variation 方法
    ABTest.get_variation((flgs) => {
        // 获取变量`aColor`的值，默认值设置为'red'；
        const aColor = flgs.get('aColor', 'red');
        // 重新赋值
        this.setData({
          aColor: aColor
        });
    });
  }
})

模板


<view>
    <label style="background-color:">该label背景颜色通过获取实验变量来设置</label>
</view>