您的APP或网页在集成了 GrowingIO 的 SDK 之后,它将会自动地为您采集一系列用户行为数据,进行数据分析。除自动收集的用户行为数据(或称为无埋点数据)之外,GrowingIO 还提供了多种 API 接口,供您上传一些自定义事件和变量,下面介绍自定义事件和变量 API 使用方法,后文简称埋点事件API。
GrowingIO所有运营时API需要在主线程调用。
// 发送自定义事件 APIGrowingIO gio = GrowingIO.getInstance();gio.track(String eventId);gio.track(String eventId, JSONObject eventLevelVariables);// 发送页面级变量 APIGrowingIO gio = GrowingIO.getInstance();gio.setPageVariable(Activity activity, String key, String value);gio.setPageVariable(Activity activity, String key, Number value);gio.setPageVariable(Activity activity, String key, Boolean value);gio.setPageVariable(Activity activity, JSONObject pageLevelVariables);gio.setPageVariable(Fragment fragment, String key, String value);gio.setPageVariable(Fragment fragment, String key, Number value);gio.setPageVariable(Fragment fragment, String key, Boolean value);gio.setPageVariable(Fragment fragment, JSONObject pageLevelVariables);// 发送转化变量 APIGrowingIO gio = GrowingIO.getInstance();gio.setEvar(String key, String value);gio.setEvar(String key, Number value);gio.setEvar(String key, Boolean value);gio.setEvar(JSONObject conversionVariables);// 发送用户变量 APIGrowingIO gio = GrowingIO.getInstance();gio.setPeopleVariable(String key, String value);gio.setPeopleVariable(String key, Number value);gio.setPeopleVariable(String key, Boolean value);gio.setPeopleVariable(JSONObject peopleVariables);// 设置登录用户ID APIGrowingIO.getInstance().setUserId(String userId);// 清除登录用户ID APIGrowingIO.getInstance().clearUserId();// 设置访问用户变量,或者设置 A/B 测试标签GrowingIO.getInstance().setVisitor(JSONObject visitorVariable);
当用户登录之后调用setUserId API,设置登录用户ID。
//setuserid API原型GrowingIO.getInstance().setUserId(String userId);
参数说明
参数名称 | 类型 | 是否必须 | 说明 |
userId | string | 是 | 登录用户Id,长度限制小于等于1000; 如果值为空则清空了登录用户变量,不建议这么用, 请使用 clearUserId 清除登录用户变量。 |
//setUserId API调用示例GrowingIO.getInstance().setUserId("1234567890");
如果您的App每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级App版本后初次访问时重新调用上述setUserId方法。
当用户登出之后调用clearUserId,清除已经设置的登录用户ID。
示例代码
//clearUserId API原型和调用示例GrowingIO.getInstance().clearUserId();
发送用户信息用于用户信息相关分析,在添加代码之前必须在打点管理界面上声明用户变量。
// setPeopleVariable API原型GrowingIO gio = GrowingIO.getInstance();gio.setPeopleVariable(String key, String value);gio.setPeopleVariable(String key, Number value);gio.setPeopleVariable(String key, Boolean value);gio.setPeopleVariable(JSONObject peopleVariables);
参数名称 | 类型 | 是否必须 | 说明 |
key | string | 否 | 用户变量的标识符。 限制:非空,长度限制小于等于50。 |
value | string | 否 | 用户变量的值。 限制:非空,长度限制小于等于1000。 |
peopleVariables | JSONObject | 否 | 用户变量用于用户信息相关的分析。 限制:非空,长度限制小于等于100(
|
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>ppl(用户变量)事件。
示例代码
// setPeopleVariable API调用示例一GrowingIO gio = GrowingIO.getInstance();gio.setPeopleVariable("gender", "male");
// setPeopleVariable API调用示例二GrowingIO gio = GrowingIO.getInstance();jsonObject.put("gender", "male");jsonObject.put("age", "21");gio.setPeopleVariable(jsonObject);
检验数据发送日志示例:
注意 t
等于ppl
字段,表示用户变量发送成功,只需注意 var
字段,其它字段无需仔细验证。
{"s":"a35872af-13df-4479-90bc-25558d12328e",// t 为事件类型, pvar 为发送用户变量事件"t":"ppl","tm":1532339208991,"d":"com.growingio.android.test","cs1":"GrowingIO",// 用户变量"var":{"gender":"male","age":"21"},"gesid":311,"esid":0}
当用户未登录时,定义用户属性变量,也可用于A/B测试上传标签。
版本支持:>=2.4.0
//setVisitor API原型GrowingIO.getInstance().setVisitor(JSONObject visitorVar)
参数说明
参数说明 | 类型 | 是否必填 | 说明 |
visitorVar | JSONObject | 是 | 不可使用嵌套的 key 长度限制小于等于50,value长度限制小等于1000,值不能为空串,也就是""。 |
//setVisitor API调用示例GrowingIO gio = GrowingIO.getInstance();jsonObject.put("gender", "male");jsonObject.put("age", "21");gio.setVisitor(jsonObject);
检验数据发送日志示例
注意 t
等于vstr
字段,表示访问用户变量发送成功,其它字段无需仔细验证。
{"s":"d334b4a1-57eb-4bf4-b426-64c1cce5a5c0",// t 为事件类型, vstr 为发送访问用户变量事件"t":"vstr","tm":1532341259134,"d":"com.growingio.android.test","cs1":"GrowingIO",//访问用户变量"var":{"gender":"male","age":"21"},"gesid":322,"esid":0}
使用限制:适用于无埋点SDK。
发送页面级别的信息,在添加代码之前必须在打点管理界面上声明页面级变量。
// setPageVariable API原型GrowingIO gio = GrowingIO.getInstance();gio.setPageVariable(Activity activity, String key, String value);gio.setPageVariable(Activity activity, String key, Number value);gio.setPageVariable(Activity activity, String key, Boolean value);gio.setPageVariable(Activity activity, JSONObject pageLevelVariables);gio.setPageVariable(Fragment fragment, String key, String value);gio.setPageVariable(Fragment fragment, String key, Number value);gio.setPageVariable(Fragment fragment, String key, Boolean value);gio.setPageVariable(Fragment fragment, JSONObject pageLevelVariables);// SDK 2.6.6 以上支持 androidx, 增加接口:gio.setPageVariableX(Fragment fragment, String key, String value);gio.setPageVariableX(Fragment fragment, String key, Number value);gio.setPageVariableX(Fragment fragment, String key, Boolean value);gio.setPageVariableX(Fragment fragment, JSONObject pageLevelVariables);
注意确认当前页面,通过圈选方式最快定位当前页面,在当前页面埋点最稳定可靠,如果页面未确认,可能在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(
|
SDK 2.4.0
以上能够在 Log 日志中查看对应报错,之下版本无提示信息。调用后请关注日志,查看数据发送是否成功,事件类型t
为pvar
。
SDK 2.6.7
将页面级变量pageLevelVariables
与该页面对象绑定,设置不同的值将会合并,如果想要清空,需要传 null 。
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>pvar(页面级变量)事件。
示例代码
// setPageVariable API调用示例GrowingIO gio = GrowingIO.getInstance();JSONObject jsonObject = new JSONObject();jsonObject.put("gender", "male");jsonObject.put("age", "21");gio.setPageVariable(myActivity, jsonObject);
检验数据发送日志示例:
注意 t
等于pvar
字段,表示自定义事件发送成功,只需注意 var
字段,其它字段无需仔细验证。
{"s":"0a7e8150-c409-45d4-96ed-b5781fe652cb",// t 为事件类型,pvar 页面级事件"t":"pvar","tm":1532337448255,"d":"com.growingio.android.test","cs1":"GrowingIO","p":"SetUserIdFragment1","ptm":1532337448255,//页面级变量"var":{"gender":"male","age":"21"},"gesid":292,"esid":0}
发送一个转化信息用于高级归因分析,在添加代码之前必须在打点管理界面上声明转化变量。
// setEvar API原型GrowingIO gio = GrowingIO.getInstance();gio.setEvar(String key, String value);gio.setEvar(String key, Number value);gio.setEvar(String key, Boolean value);gio.setEvar(JSONObject conversionVariables);
参数说明
参数名称 | 类型 | 是否必须 | 说明 |
key | string | 否 | 转化变量的标识符 限制:非空,长度限制小于等于50 |
value | string | 否 | 转化变量的值 限制:非空,长度限制小于等于1000 |
conversionVariables | JSONObject | 否 | 转化变量用于高级归因分析 限制:非空,长度限制小于等于100(
|
推荐您使用Mobile Debugger,我们为您列举了应用场景和验证示例,请参考:验证埋点事件>evar(转化变量)事件。
// setEvar API调用示例一GrowingIO gio = GrowingIO.getInstance();gio.setEvar("campaignId", "1234567890");
// setEvar API调用示例二GrowingIO gio = GrowingIO.getInstance();JSONObject jsonObject = new JSONObject();jsonObject.put("campaignId", "1234567890");jsonObject.put("campaignOwner", "Li Si");gio.setEvar(jsonObject);
检验数据发送日志示例:
注意 t
等于evar
字段,表示转化事件发送成功,只需注意 var
字段,其它字段无需仔细验证。
{"s":"e1c48845-dd60-4cf2-b1a5-a8e529d2188d",// t 为事件类型, evar 为转化事件"t":"evar","tm":1532338526083,"d":"com.growingio.android.test","cs1":"GrowingIO",// 转化变量"var":{"evarTest":111,"campaignId":"1234567890","campaignOwner":"Li Si"},"gesid":300,"esid":22}
发送一个自定义事件。在添加所需要发送的事件代码之前,需要在打点管理用户界面配置事件以及事件级变量。
// track API原型GrowingIO gio = GrowingIO.getInstance();gio.track(String eventId);gio.track(String eventId, JSONObject eventLevelVariables);
参数名称 | 类型 | 是否必须 | 说明 |
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(事件以及关联的事件级变量)事件。
示例代码
// track API调用示例一GrowingIO gio = GrowingIO.getInstance();gio.track("registerSuccess");
// track API调用示例二GrowingIO gio = GrowingIO.getInstance();JSONObject jsonObject = new JSONObject();jsonObject.put("gender", "male");jsonObject.put("age", "21");gio.track("registerSuccess", jsonObject);
检验数据发送日志示例
注意 t
等于 cstm
字段,表示自定义事件发送成功,只需注意 var
、n
字段,其它字段无需仔细验证。
//展示 track 接口调用示例三日志内容{"s":"31e3aa14-5241-490c-821c-a741e9bf0f87",// t 为事件类型, track 接口调用发送的事件类型为 cstm"t":"cstm","tm":1532085495251,"d":"com.growingio.android.test",// n 为 eventId 参数携带的值"n":"loanAmount",// var 为 eventLevelVariable 参数携带的值"var":{"gender":"male","age":"21"},"ptm":0,"gesid":18,"esid":0,"u":"b6247b01-a31a-3bc6-a391-4c456888c1ee"}