帮助文档
搜索文档…
自定义数据上传API
自定义数据常用作打通业务逻辑
您的APP或网页在集成了 GrowingIO 的 SDK 之后,它将会自动地为您采集一系列用户行为数据,进行数据分析。除自动收集的用户行为数据(或称为无埋点数据)之外,GrowingIO 还提供了多种 API 接口,供您上传一些自定义事件和变量,下面介绍自定义事件和变量 API 使用方法,后文简称埋点事件API。
GrowingIO所有运营时API需要在主线程调用。

API概览

1
// 发送自定义事件 API
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.track(String eventId);
4
gio.track(String eventId, JSONObject eventLevelVariables);
5
6
// 发送页面级变量 API
7
GrowingIO gio = GrowingIO.getInstance();
8
gio.setPageVariable(Activity activity, String key, String value);
9
gio.setPageVariable(Activity activity, String key, Number value);
10
gio.setPageVariable(Activity activity, String key, Boolean value);
11
gio.setPageVariable(Activity activity, JSONObject pageLevelVariables);
12
13
gio.setPageVariable(Fragment fragment, String key, String value);
14
gio.setPageVariable(Fragment fragment, String key, Number value);
15
gio.setPageVariable(Fragment fragment, String key, Boolean value);
16
gio.setPageVariable(Fragment fragment, JSONObject pageLevelVariables);
17
18
// 发送转化变量 API
19
GrowingIO gio = GrowingIO.getInstance();
20
gio.setEvar(String key, String value);
21
gio.setEvar(String key, Number value);
22
gio.setEvar(String key, Boolean value);
23
gio.setEvar(JSONObject conversionVariables);
24
25
// 发送用户变量 API
26
GrowingIO gio = GrowingIO.getInstance();
27
gio.setPeopleVariable(String key, String value);
28
gio.setPeopleVariable(String key, Number value);
29
gio.setPeopleVariable(String key, Boolean value);
30
gio.setPeopleVariable(JSONObject peopleVariables);
31
32
// 设置登录用户ID API
33
GrowingIO.getInstance().setUserId(String userId);
34
35
// 清除登录用户ID API
36
GrowingIO.getInstance().clearUserId();
37
38
// 设置访问用户变量,或者设置 A/B 测试标签
39
GrowingIO.getInstance().setVisitor(JSONObject visitorVariable);
Copied!

接口定义

1. 设置登录用户ID(setUserId)

当用户登录之后调用setUserId API,设置登录用户ID。
1
//setuserid API原型
2
GrowingIO.getInstance().setUserId(String userId);
Copied!
参数说明
参数名称
类型
是否必须
说明
userId
string
登录用户Id,长度限制小于等于1000;
如果值为空则清空了登录用户变量,不建议这么用,
请使用 clearUserId 清除登录用户变量。
1
//setUserId API调用示例
2
GrowingIO.getInstance().setUserId("1234567890");
Copied!
如果您的App每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级App版本后初次访问时重新调用上述setUserId方法。

2. 清除登录用户ID(clearUserId)

当用户登出之后调用clearUserId,清除已经设置的登录用户ID。
示例代码
1
//clearUserId API原型和调用示例
2
GrowingIO.getInstance().clearUserId();
Copied!

3. 设置登录用户变量(setPeopleVariable)

发送用户信息用于用户信息相关分析,在添加代码之前必须在打点管理界面上声明用户变量。
1
// setPeopleVariable API原型
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.setPeopleVariable(String key, String value);
4
gio.setPeopleVariable(String key, Number value);
5
gio.setPeopleVariable(String key, Boolean value);
6
gio.setPeopleVariable(JSONObject peopleVariables);
Copied!
参数名称
类型
是否必须
说明
key
string
用户变量的标识符。
限制:非空,长度限制小于等于50。
value
string
用户变量的值。
限制:非空,长度限制小于等于1000。
peopleVariables
JSONObject
用户变量用于用户信息相关的分析。
限制:非空,长度限制小于等于100(peopleVariables.length()<=100);
peopleVariables 内部不允许含有JSONObject或者JSONArray
key长度限制小于等于50,value长度限制小等于1000,值不能为空串,也就是""。
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>ppl(用户变量)事件
示例代码
1
// setPeopleVariable API调用示例一
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.setPeopleVariable("gender", "male");
Copied!
1
// setPeopleVariable API调用示例二
2
GrowingIO gio = GrowingIO.getInstance();
3
jsonObject.put("gender", "male");
4
jsonObject.put("age", "21");
5
gio.setPeopleVariable(jsonObject);
Copied!
检验数据发送日志示例:
注意 t 等于ppl字段,表示用户变量发送成功,只需注意 var字段,其它字段无需仔细验证。
1
{
2
"s":"a35872af-13df-4479-90bc-25558d12328e",
3
// t 为事件类型, pvar 为发送用户变量事件
4
"t":"ppl",
5
"tm":1532339208991,
6
"d":"com.growingio.android.test",
7
"cs1":"GrowingIO",
8
// 用户变量
9
"var":{
10
"gender":"male",
11
"age":"21"
12
},
13
"gesid":311,
14
"esid":0
15
}
Copied!

4. 设置访问用户变量(setVisitor)

当用户未登录时,定义用户属性变量,也可用于A/B测试上传标签。
版本支持:>=2.4.0
1
//setVisitor API原型
2
GrowingIO.getInstance().setVisitor(JSONObject visitorVar)
Copied!
参数说明
参数说明
类型
是否必填
说明
visitorVar
JSONObject
不可使用嵌套的JSONObject对象,即为JSONObject中不可以放入JSONObject或者JSONArray
key 长度限制小于等于50,value长度限制小等于1000,值不能为空串,也就是""。
Java
Kotlin
1
//setVisitor API调用示例
2
GrowingIO gio = GrowingIO.getInstance();
3
jsonObject.put("gender", "male");
4
jsonObject.put("age", "21");
5
gio.setVisitor(jsonObject);
Copied!
1
//setVisitor API调用示例
2
val gio = GrowingIO.getInstance()
3
jsonObject.put("gender", "male")
4
jsonObject.put("age", "21")
5
gio.setVisitor(jsonObject)
Copied!
检验数据发送日志示例
注意 t 等于vstr字段,表示访问用户变量发送成功,其它字段无需仔细验证
1
{
2
"s":"d334b4a1-57eb-4bf4-b426-64c1cce5a5c0",
3
// t 为事件类型, vstr 为发送访问用户变量事件
4
"t":"vstr",
5
"tm":1532341259134,
6
"d":"com.growingio.android.test",
7
"cs1":"GrowingIO",
8
//访问用户变量
9
"var":{
10
"gender":"male",
11
"age":"21"
12
},
13
"gesid":322,
14
"esid":0
15
}
Copied!

5. 设置页面级变量(setPageVariable)

使用限制:适用于无埋点SDK。
发送页面级别的信息,在添加代码之前必须在打点管理界面上声明页面级变量。
1
// setPageVariable API原型
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.setPageVariable(Activity activity, String key, String value);
4
gio.setPageVariable(Activity activity, String key, Number value);
5
gio.setPageVariable(Activity activity, String key, Boolean value);
6
gio.setPageVariable(Activity activity, JSONObject pageLevelVariables);
7
8
gio.setPageVariable(Fragment fragment, String key, String value);
9
gio.setPageVariable(Fragment fragment, String key, Number value);
10
gio.setPageVariable(Fragment fragment, String key, Boolean value);
11
gio.setPageVariable(Fragment fragment, JSONObject pageLevelVariables);
12
13
// SDK 2.6.6 以上支持 androidx, 增加接口:
14
gio.setPageVariableX(Fragment fragment, String key, String value);
15
gio.setPageVariableX(Fragment fragment, String key, Number value);
16
gio.setPageVariableX(Fragment fragment, String key, Boolean value);
17
gio.setPageVariableX(Fragment fragment, JSONObject pageLevelVariables);
Copied!
注意确认当前页面,通过圈选方式最快定位当前页面,在当前页面埋点最稳定可靠,如果页面未确认,可能在Activity和Fragment嵌套的场景下埋点失败。如未能成功发送自定义页面变量,请参考”Android SDK集成FAQ > 无埋点API使用问题
参数选择是当前被识别的页面对象,可能是 Activity 或 Fragment,可以使用 Mobile Debugger 或debug日志确认。
参数名称
类型
是否必须
说明
activity
Activity
当前页面访问事件(page事件)发送的页面
fragment
Fragment
当前页面访问事件(page事件)发送的页面
key
string
页面级变量的标识符
限制:非空,长度限制小于等于50
value
string
页面级变量的值
限制:非空,长度限制小于等于1000
pageLevelvariables
JSONObject
页面级变的信息
限制:非null,长度限制小于等于100(pageLevelVariable.length()<=100);
pageLevelVariable 内部不允许含有JSONObject或者JSONArray
key 长度限制小于等于50,value长度限制小等于1000,值不能为空串,也就是""。
SDK 2.4.0 以上能够在 Log 日志中查看对应报错,之下版本无提示信息。调用后请关注日志,查看数据发送是否成功,事件类型tpvar
SDK 2.6.7 将页面级变量pageLevelVariables与该页面对象绑定,设置不同的值将会合并,如果想要清空,需要传 null 。
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>pvar(页面级变量)事件
示例代码
Java
Kotlin
1
// setPageVariable API调用示例
2
GrowingIO gio = GrowingIO.getInstance();
3
JSONObject jsonObject = new JSONObject();
4
jsonObject.put("gender", "male");
5
jsonObject.put("age", "21");
6
gio.setPageVariable(myActivity, jsonObject);
Copied!
1
// setPageVariable API调用示例
2
val gio = GrowingIO.getInstance()
3
val jsonObject = JSONObject()
4
jsonObject.put("gender", "male")
5
jsonObject.put("age", "21")
6
gio.setPageVariable(myActivity, jsonObject)
Copied!
检验数据发送日志示例:
注意 t 等于pvar字段,表示自定义事件发送成功,只需注意 var字段,其它字段无需仔细验证
1
{
2
"s":"0a7e8150-c409-45d4-96ed-b5781fe652cb",
3
// t 为事件类型,pvar 页面级事件
4
"t":"pvar",
5
"tm":1532337448255,
6
"d":"com.growingio.android.test",
7
"cs1":"GrowingIO",
8
"p":"SetUserIdFragment1",
9
"ptm":1532337448255,
10
//页面级变量
11
"var":{
12
"gender":"male",
13
"age":"21"
14
},
15
"gesid":292,
16
"esid":0
17
}
Copied!

6. 设置转化变量(setEvar)

发送一个转化信息用于高级归因分析,在添加代码之前必须在打点管理界面上声明转化变量。
1
// setEvar API原型
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.setEvar(String key, String value);
4
gio.setEvar(String key, Number value);
5
gio.setEvar(String key, Boolean value);
6
gio.setEvar(JSONObject conversionVariables);
Copied!
参数说明
参数名称
类型
是否必须
说明
key
string
转化变量的标识符
限制:非空,长度限制小于等于50
value
string
转化变量的值
限制:非空,长度限制小于等于1000
conversionVariables
JSONObject
转化变量用于高级归因分析
限制:非空,长度限制小于等于100(conversionVariables.length()<=100);
conversionVariables 内部不允许含有JSONObject或者JSONArray
key 长度限制小于等于50,value长度限制小等于1000,值不能为空串,也就是""。
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>evar(转化变量)事件
Java
Kotlin
1
// setEvar API调用示例一
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.setEvar("campaignId", "1234567890");
Copied!
1
// setEvar API调用示例一
2
val gio = GrowingIO.getInstance()
3
gio.setEvar("campaignId", "1234567890")
Copied!
Java
Kotlin
1
// setEvar API调用示例二
2
GrowingIO gio = GrowingIO.getInstance();
3
JSONObject jsonObject = new JSONObject();
4
jsonObject.put("campaignId", "1234567890");
5
jsonObject.put("campaignOwner", "Li Si");
6
gio.setEvar(jsonObject);
Copied!
1
// setEvar API调用示例二
2
val gio = GrowingIO.getInstance()
3
val jsonObject = JSONObject()
4
jsonObject.put("campaignId", "1234567890")
5
jsonObject.put("campaignOwner", "Li Si")
6
gio.setEvar(jsonObject)
Copied!
检验数据发送日志示例:
注意 t 等于evar字段,表示转化事件发送成功,只需注意 var字段,其它字段无需仔细验证。
1
{
2
"s":"e1c48845-dd60-4cf2-b1a5-a8e529d2188d",
3
// t 为事件类型, evar 为转化事件
4
"t":"evar",
5
"tm":1532338526083,
6
"d":"com.growingio.android.test",
7
"cs1":"GrowingIO",
8
// 转化变量
9
"var":{
10
"evarTest":111,
11
"campaignId":"1234567890",
12
"campaignOwner":"Li Si"
13
},
14
"gesid":300,
15
"esid":22
16
}
Copied!

7. 设置自定义事件和事件级变量(track)

发送一个自定义事件。在添加所需要发送的事件代码之前,需要在打点管理用户界面配置事件以及事件级变量。
1
// track API原型
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.track(String eventId);
4
gio.track(String eventId, JSONObject eventLevelVariables);
Copied!
参数名称
类型
是否必须
说明
eventId
string
事件标识符。
eventLevelVariable
JSONObject
事件发生时所伴随的维度信息。
限制:非空,键值对个数限制小于等于100(eventLevelVariable.length()<=100);eventLevelVariable内部不允许含有JSONObject或者JSONArray;
key长度限制小于等于50,value长度限制小于等于1000,值不能为空字符串,也就是“”。
SDK 2.4.0以上能够在Log日志中查看对应报错,之下版本无提示信息。调用后请关注日志,查看数据发送是否成功,事件类型t为cstm。
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>cstm(事件以及关联的事件级变量)事件
示例代码
Java
Kotlin
1
// track API调用示例一
2
GrowingIO gio = GrowingIO.getInstance();
3
gio.track("registerSuccess");
Copied!
1
// track API调用示例一
2
val gio = GrowingIO.getInstance()
3
gio.track("registerSuccess")
Copied!
Java
Kotlin
1
// track API调用示例二
2
GrowingIO gio = GrowingIO.getInstance();
3
JSONObject jsonObject = new JSONObject();
4
jsonObject.put("gender", "male");
5
jsonObject.put("age", "21");
6
gio.track("registerSuccess", jsonObject);
Copied!
1
val gio = GrowingIO.getInstance()
2
val jsonObject = JSONObject()
3
jsonObject.put("gender", "male")
4
jsonObject.put("age", "21")
5
gio.track("registerSuccess", jsonObject)
Copied!
检验数据发送日志示例
注意 t 等于 cstm 字段,表示自定义事件发送成功,只需注意 varn 字段,其它字段无需仔细验证
1
//展示 track 接口调用示例三日志内容
2
{
3
"s":"31e3aa14-5241-490c-821c-a741e9bf0f87",
4
// t 为事件类型, track 接口调用发送的事件类型为 cstm
5
"t":"cstm",
6
"tm":1532085495251,
7
"d":"com.growingio.android.test",
8
// n 为 eventId 参数携带的值
9
"n":"loanAmount",
10
// var 为 eventLevelVariable 参数携带的值
11
"var":{
12
"gender":"male",
13
"age":"21"
14
},
15
"ptm":0,
16
"gesid":18,
17
"esid":0,
18
"u":"b6247b01-a31a-3bc6-a391-4c456888c1ee"
19
}
Copied!
最近更新 5mo ago