Skip to main content

数据采集API

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

您可在页面头部进行解构获取gdp方法。
const { gdp } = global;(阿里(支付宝)小程序和淘宝小程序为 const { gdp } = $global;)

动态修改配置接口(setOption)

由于多样的动态修改配置的需求,我们在3.8.0版本开始提供了统一的接口,以降低接口使用难度。设值成功返回true,设值失败返回false。

gdp('setOption', optionKey, optionValue);  // return true | false

1、开启/关闭无埋点数据采集(autotrack)

当加载了无埋点插件时,默认开启无埋点数据采集。当设置为 false 时,将不再采集 VIEW_CLICK , VIEW_CHANGE , FORM_SUBMIT 无埋点事件。未加载插件时无论 autotrack 是否开启都不会进行采集。

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

// <3.8.0版本的写法仍兼容,但不建议您再这么使用
// gdp('setAutotrack', true | false);

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

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

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

// <3.8.0版本的写法仍兼容,但不建议您再这么使用
// gdp('setDataCollect', true | false);

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

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

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

// <3.8.0版本的写法仍兼容,但不建议您再这么使用
// gdp('enableDebug', true | false);

4、修改上报地址(host)

请设置准确的host地址,支持 IP域名 格式,无需携带协议头

gdp('setOption', 'host', 'your serverHost');

// <3.8.0版本的写法仍兼容,但不建议您再这么使用
// gdp('setTrackerHost', 'xxxxxxxx');

5、修改请求协议(scheme)

默认为https,您可以在开发过程中设置为 http 方便与服务端进行调试。注意上生产环境前修改回 https

gdp('setOption', 'scheme', 'http' | 'https');

// <3.8.0版本的写法仍兼容,但不建议您再这么使用
// gdp('setTrackerScheme', 'http' | 'https');

功能接口

1、注册插件(registerPlugins)

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

示例

gdp('registerPlugins', [xxxx, xxxxx]);

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

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

示例

gdp('identify', openId);

注意:
1)若使用此接口需要在初始化时将 forceLogin 设置为 true。 参考文档
2)使用多项目集成插件集成时,该方法只能在主包中调用,在分包中(即开启subpackage)会自动失效。 3)该方法仅可合法地调用一次,多次调用无效。

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

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

示例

gdp('getDeviceId');

注意:
1)SDK版本 >=3.8.0-rc.7 支持。
2)开启forceLogin的小程序无需调用此方法,因为您在identify的时候已经获取了openId做为访问用户Id。如果您一定要使用它,请在identify之后调用。

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

当用户登录之后调用setUserId,设置登录用户ID

若您的小程序每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在监测到用户为登录用户后即调用此方法。

参数说明

参数参数类型说明
userIdstring / number必填;字符长度小于等于 1000,长度超限将会被截断。
userKeystring / number可选;适用于 ID-MAPPING,可设置 userId 的类型;长度限制同 userId

示例

gdp('setUserId', '112333445');
gdp('setUserId', '112333445', 'phone');

注意:
1)SDK版本 >=3.3.0 支持 ID-MAPPING,且需初始化时设置 enableIdMappingtrue
2)该方法可多次调用,设同一值时无效。

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

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

示例

gdp('clearUserId');

6、埋点事件(track)

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

参数说明

参数参数类型说明
eventIdString必填;事件名,事件标识符。
propertiesObject选填;事件属性,当事件属性关联有维度表时,属性值为对应的维度表模型ID(记录ID)参数限制
itemObject选填;事件发生关联的物品模型。
item.idStringitem 中必填;物品模型 id。
item.keyStringitem 中必填;物品模型唯一标识。
item.attributesObjectitem 中选填;物品模型属性。参数限制同properties

示例

// gdp('track', eventId, properties[, item]);

gdp('track', 'order'); // 无properties,无item
gdp('track', 'order', { type: 'hjh' }); // 有properties,无item
gdp('track', 'order', {}, { key: 'order_id', id: '12345' }); // 无properties,有item
gdp('track', 'order', { type: 'hjh' }, { key: 'order_id', id: '12345' }); // 有properties,有item

注意:
properties中的属性值为数组格式上报时会被自动转换为以||间隔的字符串(例:names: ['tony', 'mike', 'lily'] => names: 'tony||mike||lily')

7、登录用户属性(setUserAttributes)

以登录用户的身份定义登录用户属性,用于用户信息相关分析。用户属性事件示例

参数说明

参数参数类型说明
userAttributesObject包含登录用户属性的 Object 对象。参数限制

示例

gdp('setUserAttributes', { name: 'hjh' });

微信用户属性设置

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

名称标识符
微信 openid$wechat_openId
微信 unionid$wechat_unionId
微信昵称$wechat_nickName
微信头像$wechat_avatarUrl
微信用户性别$wechat_gender
微信用户所在国家$wechat_country
微信用户所在省份$wechat_province
微信用户所在城市$wechat_city
微信语言$wechat_language
关注公众号$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_avatar
支付宝用户所在省份$alipay_province
支付宝用户所在城市$alipay_city
支付宝用户昵称$alipay_nickName
支付宝学生认证$alipay_isStudentCertified
支付宝用户类型$alipay_userType
支付宝用户状态$alipay_userStatus
支付宝实名认证$alipay_isCertified
支付宝用户性别$alipay_gender

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

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

注意:
1)用户属性中的属性值为数组格式上报时会被自动转换为以||间隔的字符串(例:names: ['tony', 'mike', 'lily'] => names: 'tony||mike||lily')
2)该方法可多次调用,已有相同属性名的值会被覆盖,多次结果在服务端进行合并。

8、地理位置(setLocation)

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

2022年4月18日起,微信官方对getLocation进行了权限限制,因此SDK废弃了与getLocation有关的逻辑,并新增setLocation来代替此功能。

参数说明

参数参数类型说明
latitudenumber必填;纬度,范围为 -90~90,负数表示南纬
longitudenumber必填;经度,范围为 -180~180,负数表示西经

示例

wx.getLocation({
type: 'wgs84',
success: ({ latitude, longitude }) => {
gdp('setLocation', latitude, longitude);
// 调用后会自动补发带位置信息的VISIT事件
}
});

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

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

giou              访问用户Id(deviceId)
gios sessionId
giocs1 登录用户Id
gioid 最近的非空登录用户Id
giouserkey 用户Key
gioprojectid 项目Id
gioappid 小程序appId
gioplatform 小程序平台
giodatasourceid dataSourceId
giodatacollect 小程序是否采集数据

示例

gdp('getGioInfo');

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

注意:
1)gdp('getGioInfo') 返回的是一个 search 字符串,需要您在字符串前手动拼接 ? 或 & 符号。如果您将该字符串拼接在了hash参数中,请在web sdk(>=3.3.10支持)中开启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#锚点'
// 小程序WebView加载H5时的拼接示例为
`https://www.growingio.com/?foo=1&${gdp('getGioInfo')}#锚点`

3)3.8.0版本开始,打通数据中会增加giodatacollect字段,数据打通后,打通H5页面的 dataCollect 数据采集开关由小程序SDK初始化配置项 dataCollect 控制。此项功能使用需H5 页面集成的 Web JS SDK 版本>=3.3.9。

H5页面集成SDK参考小程序内嵌页使用集成

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

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

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

示例

gdp('setGeneralProps', { 'currency': 'RMB' });

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

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

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

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

示例

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

注意:SDK版本>=3.8.2支持。

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

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

示例

gdp('getOption', 配置项名称);

gdp('getOption', 'dataCollect'); // 返回dataCollect当前在SDK中的值
gdp('getOption'); // 返回所有支持查看的配置项值(即原来的vdsConfig对象)

13、获取SDK当前版本

在代码或开发者工具中直接调用 global.gioSDKVersion 即可获取。

采集标记

1、采集标记

有时我们表单页面中可能需要获取用户选择框、单/多选框的值进行上报以准确分析用户行为。此时,我们可以通过数值采集标记 data-growing-track 来获取值。例:

<checkbox-group bindchange='checkboxChange' data-growing-track>
<label class='checkbox'>
<checkbox value='GrowingIO' checked='true' /> GrowingIO
</label>
<label class='checkbox'>
<checkbox value='CDP' checked='false' /> GrowingIO CDP
</label>
</checkbox-group>
免责声明警告:

请勿尝试在密码框上标记 data-growing-track 采集数据,会明文暴露用户填写的密码信息。GrowingIO不承担由此直接或间接产生的数据风险和法律风险。

提示

3.8.0版本开始,SDK会自动忽略带有 autoplay 属性且值为 true 组件的 change 事件(例如swiper、video)。如果您期望采集它,请添加 data-growing-track 标记。

2、补充数据标记

1)data-title

有时SDK自动采集的节点数据并不能完全满足上报分析需要。此时,我们可以通过额外信息的标记 data-title 来补充SDK采集的内容。例:

<button data-title="额外的上报信息">节点</button>

2)data-index

有时我们页面中可能存在类似列表类的Dom结构相似或一致使得SDK上报数据出现无法区分的情况。此时,我们可以通过索引标记 data-index 来准确描述节点信息。例:

<view>
<button data-index="1">节点1</button>
<button data-index="2">节点2</button>
<button data-index="3">节点3</button>
</view>

3)data-src

有时页面中有需要跳转的链接(尤其是navigator组件)时,为了上报完整的用户目标去向。此时,我们可以通过链接标记 data-src 来上报点击链接的目标去向。例:

<navigator url="/pages/h5/h5?from=navigate" data-src="/pages/h5/h5?from=navigate" bindtap="onNavigatorTap">
<view >
...
</view>
</navigator>

<view data-src="/pages/h5/h5?from=navigate" bindtap="onLinkTap">
模拟一个链接
</view>

注意:
在有上述3种额外采集标记的节点上,必须绑定一个点击事件,SDK才能实现点击的额外数据采集。如果没有,需要您手动绑定一个空的点击事件。

4)gioPageTitle

默认情况下SDK会自动采集页面title,但当SDK可能无法识别时或您需要自定义时,可以通过在页面的data对象中设置gioPageTitle字段来指定SDK上报事件时的title值。例:

Page({
data: {
gioPageTitle: 'New Title',
...other data
}
});

注意: 指定title仅支持 String 格式。SDK版本>=3.8.0-rc.9支持。

3、忽略采集标记

有时我们会根据业务中不同的需要使用一些自己开发的组件或第三方组件,可能会触发SDK的 VIEW_CHANGE 事件,但我们并不期望它发生。

此时,我们可以通过忽略采集标记 data-growing-ignore 来让SDK忽略对该组件的数据采集。注意标记在事件绑定的节点上,没事件绑定的节点默认不会采集。例:

<view data-growing-ignore bindtap="onLinkTap">要忽略的节点</view>

半自动埋点浏览事件

用户标记一个元素并提供埋点事件,SDK 负责监控指定元素,当此元素出现在屏幕可视区域中时发送用户配置的埋点事件。因此您同样需要参考埋点事件在平台上进行事件类型和变量的预定义。

曝光逻辑

always:只要从屏幕不可见区域到可见区域即可计为一次曝光并上报。(默认值)

once:屏幕不可见区域到可见区域曝光只上报一次。

支持范围

微信小程序、阿里(支付宝)小程序(基础库>=2.7.0)、百度小程序、字节跳动小程序、QQ小程序、淘宝小程序。

快应用不支持。

使用方法

1、在需要标记的元素上添加 growing_collect_imp 样式名。

2、在节点上添加 data-gio-imp-trackdata-gio-imp-attrsdata-gio-imp-items 属性,并分别对应 track 方法中的三个参数进行设置,参数规则参考埋点事件

1)传值方式一:使用变量传值

Page({
data: {
impAttrs: JSON.stringify({ type: 'hjh', name: 'yue' }),
impItems: { key: 'order_id', id: '12345' }
}
})
<view
class="growing_collect_imp"
data-gio-imp-track="imp_picture_var"
data-gio-imp-attrs="{{ impAttrs }}"
data-gio-imp-items="{{ impItems }}"
>
监听的元素,必须有内容或额外样式来让节点有实际大小
</view>

2)传值方式二:直接手动编写Object字符串(部分框架如uniapp编译时可能会将单引号编译成双引号导致编译失败)

<view
class="growing_collect_imp"
data-gio-imp-track="imp_picture_var"
data-gio-imp-attrs='{ "type": "hjh", "name": "yue" }'
data-gio-imp-items='{ "key": "order_id", "id": "12345" }'
>
监听的元素,必须有内容或额外样式来让节点有实际大小
</view>

对应产生的CUSTOM事件相当于: ↓↓↓

gdp('track', 'imp_picture_var', { type: 'hjh', name: 'yue' }, { key: 'order_id', id: '12345' });

3、如果您的曝光事件只需要统计一次或触发过于频繁导致曝光事件量过大,可以在节点上添加data-gio-imp-type="once"并设置唯一的节点id,来使得曝光逻辑变为单次上报。

<view
class="growing_collect_imp"
id="imp_1"
data-gio-imp-type="once"
data-gio-imp-track="imp_picture_var"
...
>
监听的元素,必须有内容或额外样式来让节点有实际大小
</view>

注意:
1)此功能需要注册半自动埋点浏览插件使用。参考半自动埋点浏览插件

2)data-gio-imp-attrsdata-gio-imp-items 允许接受一个Object或者JSON.stringify后的Object字符串,SDK会自动尝试进行格式化

3)被标记的节点必须有实际的大小,一个没有内容和样式的节点标记可能不会触发事件。

4)请勿在同一页面中大量标记半自动埋点浏览事件(如商品列表),可能会严重影响页面性能导致卡顿。

5)快手小程序在同一个页面中只能监听相同大小节点的第一个,即如果在同一个页面中需要监听多个节点时,要保证节点大小不一致,否则曝光事件会全部匹配到第一个相同大小的节点。

6)data-gio-imp-type配置项SDK版本>=3.8.5支持。

其他

Object参数限制

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

key: String,length <=50;

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