数据采集API

通过 global.gdp 这个全局的方法可以调用到SDK中所有开放的接口。

您可在页面头部进行解构获取gdp方法。const { gdp } = global;

(阿里(支付宝)小程序和淘宝小程序为 const { gdp } = $global;)

参数限制

Object参数限制

SDK文档中指定参数值为 Object类型 时，请注意以下限制：(非指定类型值均会被替换为空字符串，长度超限均会被截断)

key: String，length <=100；

value: String | number 时 length <=1000； Array 时 length <=100

上报参数说明

调用埋点事件(track) 和登录用户属性(setUserAttributes) 时；

1、如果您的属性值是一个字符串或者数字组成的一维数组，上报时会自动转换为 Array.join('||') 的字符串便于服务端进行拆分解析。生成的字符串再经上述的Object参数限制进行过滤处理，字符串总长度大于1000时或数组长度大于100时会被截断。因此您需要控制数组中总体字符串和总体数组的长度。

示例

name: ['cola', 'milk', 'juice']
// 上报时会自动转换为↓↓↓
name: 'cola||milk||juice'

2、如果您的属性值是一个 json 格式，则可能会被强制转换为[object Object]。因此您需要调整数据格式。

动态修改配置接口(setOption)

自3.8.0版本开始我们提供了统一的接口，以降低接口使用难度。4.0版本继承了这一设定，但**< 3.8.0版本的写法不再兼容**，请注意修改。

gdp('setOption', optionKey: string, optionValue: boolean | string);

1、开启/关闭数据采集(dataCollect)

默认开启数据采集。当设置为 false 时，SDK将不会采集和上报事件。由关闭修改为开启时，自动补发VISIT和当前页面的PAGE事件。

gdp('setOption', 'dataCollect', true | false);

2、开启/关闭调试模式(debug)

默认不开启调试模式。当设置为 true 时，开启后会在开发者工具控制台输出日志。

gdp('setOption', 'debug', true | false);

3、修改数据上报请求地址(serverUrl)

默认为https://napi.growingio.com。

Saas客户请不要修改此项，会导致您没有数据上报；OP私有部署客户可以在开发过程中设置为指定地址方便与服务端进行调试。

gdp('setOption', 'serverUrl', 'http://api.growingio.com');

功能接口

1、注册插件(registerPlugins)

默认情况下基础SDK仅包含埋点功能，如果您需要额外扩展功能，请参考初始化集成和插件列表进行插件的注册。

gdp('registerPlugins', pluginItems: any[]);

2、设置访问用户Id(identify)

访问用户Id，又称为匿名用户Id/设备Id，在微信小程序调用登录开放接口 wx.login 之后，获取 openId，调用 identify 设置访问用户Id。

gdp('identify', openId / unionId / customId: string);

注意：
1）若使用此接口需要在初始化时将 forceLogin 设置为 true。参考文档
2）该方法仅可合法地调用一次，多次调用无效。

3、获取访问用户Id(getDeviceId)

访问用户Id，又称为匿名用户Id/设备Id，SDK 用来定义唯一设备。如果没有初始化SDK 或者关闭采集开关可能返回值为空。

const gioDeviceId: string = gdp('getDeviceId');

注意：开启forceLogin的小程序在identify之前获取的是SDK自动生成的值，identify之后获取的是您设置的值。

4、设置登录用户Id(setUserId)

当用户登录之后调用，设置登录用户ID

info

如果您的小程序每次用户升级版本时无需重新登录的话，为防止用户本地缓存被清除导致的无法被识别为登录用户，建议在用户每次登录小程序访问时调用setUserId方法
当需要标记用户ID类型时，请先进行规划，并在平台的数据中心，添加新的用户身份类型，再设置userkey，误设会影响数据质量。 同时在初始化 SDK 时设置idMapping为true

参数说明

参数	参数类型	说明
`userId`	String	长度限制大于0且小于等于1000，如果大于长度1000将只截取前1000长度
`userKey`	String	适用于ID-MAPPING,可设置 userId 的类型, 默认不传

gdp('setUserId', userId: string | number, userKey?: string | number);

5、清除登录用户Id(clearUserId)

当用户登出之后调用 clearUserId，清除已经设置的登录用户ID。

gdp('clearUserId');

6、登录用户属性(setUserAttributes)

以登录用户的身份定义登录用户属性，用于用户信息相关分析。

gdp('setUserAttributes', userAttributes);

示例

gdp('setUserAttributes', { name: 'Lily', age: 18 });
gdp('setUserAttributes', {
  tags: ['clever', 'brave', 'strong'], // 仅支持字符串和数字的一维数组，其他类型会被强制转为字符串
  age: 18
});

微信用户属性设置

Gio平台系统中用户属性默认预定义的微信用户属性如下表：

名称	标识符	名称	标识符
微信 openid	$wechat_openId	微信用户所在国家	$wechat_country
微信 unionid	$wechat_unionId	微信用户所在省份	$wechat_province
微信昵称	$wechat_nickName	微信用户所在城市	$wechat_city
微信头像	$wechat_avatarUrl	微信语言	$wechat_language
微信用户性别	$wechat_gender	关注公众号	$wechat_subscribeList

当小程序获取到微信用户信息后，以上属性标识符无需在 GrowingIO 平台用户属性中添加，调用 setUserAttributes 上报微信用户信息即可。注意自行添加 $wechat_ 的前缀。例：

wx.getUserInfo({
  success: (res) => {
    const user = res.userInfo;
    gdp('setUserAttributes', {
      $wechat_openId: user.openid,
      $wechat_unionId: user.unionid,
      $wechat_nickName: user.nickname
    });
  }
})

阿里(支付宝)小程序用户属性设置

Gio平台系统中用户属性默认预定义的阿里(支付宝)小程序用户属性如下表：

名称	标识符	名称	标识符
支付宝用户 ID	$alipay_userId	支付宝学生认证	$alipay_isStudentCertified
支付宝头像	$alipay_avatar	支付宝用户类型	$alipay_userType
支付宝用户所在省份	$alipay_province	支付宝用户状态	$alipay_userStatus
支付宝用户所在城市	$alipay_city	支付宝实名认证	$alipay_isCertified
支付宝用户昵称	$alipay_nickName	支付宝用户性别	$alipay_gender

当小程序获取到阿里(支付宝)小程序用户信息后，以上属性标识符无需在Gio平台用户属性中添加，调用 setUserAttributes 上报微信用户信息即可。注意自行添加 $alipay_ 的前缀。例：

my.getAuthUserInfo({
  success: (userInfo) => {
    gdp('setUserAttributes', {
      $alipay_userId: userInfo.userId,
      $alipay_avatar: userInfo.avatar,
      $alipay_province: userInfo.province,
    });
  }
});

注意：该方法可多次调用，已有相同属性名的值会被覆盖，多次结果在服务端进行合并。

7、地理位置(setLocation)

当用户访问至某一功能需要位置信息时，可以手动调用小程序Api获取地理位置接口，赋值给SDK采集位置信息，提升用户地域分布的分析准确性。同时您需要配置项目的permission字段参考文档和对应的权限申请参考文档。

gdp('setLocation', latitude: number, longitude: number);

示例

wx.getLocation({
  type: 'wgs84',
  success: ({ latitude, longitude }) => {
    gdp('setLocation', latitude, longitude);
  }
});

8、埋点事件(track)

发送一个埋点事件。在添加所需要发送的事件代码之前，需要在平台中配置事件以及事件属性。埋点事件示例

gdp('track', eventName: string, attributes?: Object);

示例

gdp('track', 'order');
gdp('track', 'order', {
  type: 'drinks',
  name: ['cola', 'milk', 'juice'], // 支持字符串和数字的一维数组，其他类型会被强制转为字符串
  currency: 'RMB',
  price: 3
});

提示：您可以使用多实例的能力将埋点同时上报给其他实例参考文档

9、设置埋点通用属性(setGeneralProps)

有时我们埋点需要大量业务属性，但需要每次调用时都进行传值，这给埋点工作带来了一定程度上的无用重复劳动。现在我们可以通过setGeneralProps来给后续产生的所有的埋点事件加上通用属性，从而免去一些不必要的重复劳动。也可以利用该方法为所有的埋点事件进行动态设置通用属性。

设置的通用属性可以是静态固定值，也可以是一个简单的方法执行结果的动态值。当属性值为方法时，SDK会自动执行尝试获取返回值，支持返回的数据类型：String、Number、一元Array、Boolean。不合法的数据类型会被强制转换为字符串。并且请勿执行复杂度过高的运算逻辑或异步运算，可能会导致报错或无法获取准确值。

gdp('setGeneralProps', properties: object);

示例

// 固定值
gdp('setGeneralProps', { 'currency': 'RMB' });

// 变量
let index = 0;
gdp('setGeneralProps', {
  'nick_name_var': 'Mike',
  'index_var': () => index++
});

注意：
1）定义的通用属性名依然需要在平台上进行事件属性的创建并与埋点事件完成关联。
2）该方法可多次调用，已有相同属性名的值会被覆盖。
3）埋点通用属性仅限小程序中共享使用，内嵌页无法共享通用属性。

10、清除埋点通用属性(clearGeneralProps)

SDK提供了清除通用属性的方法，调用该方法移除指定字段或所有通用埋点属性。

gdp('clearGeneralProps', propertyNames: string[]);

示例

gdp('clearGeneralProps', ['nick_name_var', 'index_var']);
// 或传空数组清空所有通用埋点属性
gdp('clearGeneralProps', []);

11、设置页面属性(setPageAttributes)

有时我们需要通过区分于页面参数的页面属性来进行拆分分析，这时就调用该方法设置页面属性。

gdp('setGeneralProps', properties: object);

示例

Page({
  onLoad() {
    gdp('setPageAttributes', {
      page_type: 'page type',
      page_level: 'page level'
    });
  }
});

注意：
1）该方法只能在 onLoad中调用，其他生命周期中调用无效。
2）该方法仅对页面浏览事件生效，不会对页面中发生的其他事件生效。如需对页面其他事件添加相同的页面属性，请将属性拼在页面查询参数query中上报（同样需要在页面加载前完成操作）。

12、与h5打通用户数据(getGioInfo)

当有H5页面需要获取小程序SDK采集用户数据的需求时(将H5页面采集的数据需要与小程序采集的数据做关联分析)，调用此接口可将获取以下9个字段的数据。

字段名	字段含义	字段名	字段含义	字段名	字段含义
giou	访问用户Id(deviceId)	giouserkey	用户Key	gioplatform	小程序平台
gios	sessionId	gioprojectid	项目Id	giodatasourceid	数据源Id
giocs1	登录用户Id	gioappid	小程序appId	giodatacollect	小程序采集状态

const gioInfo:string = gdp('getGioInfo');

如果以上字段仍不能满足您分析需求，可在初始化时添加 extraParams 参考文档配置字段来额外增加一些信息。

注意：
1）gdp('getGioInfo') 返回的是一个 search 字符串，需要您在字符串前手动拼接 ? 或 & 符号。如果您将该字符串拼接在了hash参数中，请在webjs sdk中开启hashtag解析。

2）gdp('getGioInfo') 获取的数据是一次性的，非动态获取，如果切换用户导致 sessionId 或 userId 等用户信息变动时，需要您销毁当前 webview 重设地址。并且使用不保留当前页面的跳转方式跳出承载 webview 的小程序页面。

示例

// js
Page({
  data: { url: '' },
  onShow() {
    // 每次onShow时设url的值，保证getGioInfo拿到的是最新值
    this.setData({ url: `https://www.growingIO.com?${gdp('getGioInfo')}` });
  },
  onHide() {
    // 退出webview承载页时要销毁webview，保证下次进入时是一个拿到最新数据的全新页面
    this.setData({ url: '' });
  },
  // 如果页面中有登录，需要在登录之后重设一次url的值
  handleLogin() {
    ...
    // 登录完成后重设一次url的值，保证先销毁webview，getGioInfo拿到的是最新值
    this.setData({ url: '' }, () => {
      this.setData({ url: `https://www.growingIO.com?${gdp('getGioInfo')}` });
    });
  }
})

<!-- wxml -->
<view>
  <web-view wx:if="{{url}}" src="{{url}}"></web-view>
</view>

gdp('getGioInfo')默认获取到的数据示例：

// H5 页面原有的 URL为 :
'https://www.growingio.com/?foo=1#hash'

// 小程序WebView加载H5时的拼接示例为
`https://www.growingio.com/?foo=1&${gdp('getGioInfo')}#hash`

3）数据打通后，打通H5页面的 dataCollect 数据采集开关由小程序SDK初始化配置项 dataCollect 控制。

H5页面集成SDK参考在小程序内嵌页面中集成

13、获取SDK当前配置(getOption)

当调试时需要获取SDK当前的配置信息或状态时，可调用此接口。配置项名称不传时获取的为全量的配置信息。

gdp('getOption', optionKey: string);

示例

gdp('getOption', 'dataCollect'); // 获取dataCollect当前在SDK中的值
gdp('getOption', 'version'); // 获取SDK版本号
gdp('getOption'); // 获取所有支持查看的配置项值(即原来的vdsConfig对象)

事件时长统计

可以统计上报某一事件的持续时长（例如页面浏览时长）。我们提供了事件计时开始、事件计时暂停、事件计时恢复、事件计时停止、事件计时销毁几个方法提供调用。

注意：小程序被切后台（即触发onAppHide）时，会自动暂停所有正在计时中的计时器，切前台（即触发onAppShow）时，会自动恢复正在计时中的计时器。切后台前手动调用暂停的计时器不会自动恢复，需要您再次手动恢复计时。

1、初始化计时器(trackTimerStart)

const timerId: string = gdp('trackTimerStart', eventName);

2、暂停事件计时器(trackTimerPause)

gdp('trackTimerPause', timerId);

3、恢复事件计时器(trackTimerResume)

gdp('trackTimerResume', timerId);

4、停止事件计时器(trackTimerEnd)

停止事件计时器。注意停止事件计时器时会自动发送事件并删除当前计时器。

gdp('trackTimerEnd', timerId, attributes?: object);

示例

gdp('trackTimerEnd', 'timerId123');
gdp('trackTimerEnd', 'timerId123', { extraVar1: 1, extraVar2: 2 });

提示：您可以使用多实例的能力将埋点计时同时上报给其他实例参考文档

注意

trackTimerEnd时发送CUSTOM事件上报数据：

eventName 埋点事件标识符（trackTimerStart传入）
attributes 用户自定义事件属性（trackTimerEnd传入）
event_duration 事件时长（SDK内部根据timerId自动计算获取）
    单位秒，小数点精度保证到毫秒
    变量及其值会自动添加在 attributes 中
    时间统计不会计算后台时间
eventName 对应的埋点事件需要在平台中绑定标识符为 event_duration 且类型为小数的事件属性

5、删除事件计时器(removeTimer)

删除事件计时器，参数为 trackTimerStart 返回的唯一标识。
该接口会将标识为 timerId 的计时器置为空。调用停止计时器接口，会自动触发该接口。注意移除时不论计时器处于什么状态，都不会发送事件。

gdp('removeTimer', timerId);

6、清除所有事件计时器(clearTrackTimer)

清除所有已经注册的事件计时器。
存在所有计时器需要清除时调用。注意移除时不论计时器处于什么状态，都不会发送事件。

gdp('clearTrackTimer', timerId);

参数限制​

Object参数限制​

上报参数说明​

示例​

动态修改配置接口(setOption)​

1、开启/关闭数据采集(dataCollect)​

2、开启/关闭调试模式(debug)​

3、修改数据上报请求地址(serverUrl)​

功能接口​

1、注册插件(registerPlugins)​

2、设置访问用户Id(identify)​

3、获取访问用户Id(getDeviceId)​

4、设置登录用户Id(setUserId)​

参数说明​

5、清除登录用户Id(clearUserId)​

6、登录用户属性(setUserAttributes)​

示例​

微信用户属性设置​

阿里(支付宝)小程序用户属性设置​

7、地理位置(setLocation)​

示例​

8、埋点事件(track)​

示例​

9、设置埋点通用属性(setGeneralProps)​

示例​

10、清除埋点通用属性(clearGeneralProps)​

示例​

11、设置页面属性(setPageAttributes)​

示例​

12、与h5打通用户数据(getGioInfo)​

示例​

13、获取SDK当前配置(getOption)​

示例​

事件时长统计​

1、初始化计时器(trackTimerStart)​

2、暂停事件计时器(trackTimerPause)​

3、恢复事件计时器(trackTimerResume)​

4、停止事件计时器(trackTimerEnd)​

示例​

5、删除事件计时器(removeTimer)​

6、清除所有事件计时器(clearTrackTimer)​