自定义数据上传API

自定义数据常用作打通业务逻辑

您的APP 集成了 Android 无埋点 SDK 之后,它将会自动地为您采集访问,页面浏览,元素点击等用户行为数据,进行数据分析。除自动收集的用户行为数据(或称为无埋点数据)之外,SDK 还提供了多种 API 接口,供您上传一些自定义数据,下面介绍自定义数据 API 使用方法,后文简称埋点 API。

GrowingIO所有运行时API需要在主线程调用。

API概览

// 发送自定义事件 API
GrowingIO gio = GrowingIO.getInstance();
gio.track(String eventId);
gio.track(String eventId, JSONObject eventLevelVariables);

// 发送页面级变量 API,适用于无埋点SDK
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);

// 发送转化变量 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);

// 设置登录用户ID API
GrowingIO.getInstance().setUserId(String userId);

// 发送登录用户变量 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);

// 清除登录用户ID API
GrowingIO.getInstance().clearUserId();

// 设置访问用户变量,或者设置 A/B 测试标签
GrowingIO.getInstance().setVisitor(JSONObject visitorVariable);

接口定义

1. 设置登录用户ID

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

//setuserid API原型
GrowingIO.getInstance().setUserId(String userId);

参数说明

//setUserId API调用示例
GrowingIO.getInstance().setUserId("1234567890");

如果您的App每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级App版本后初次访问时重新调用上述setUserId方法。

2. 清除登录用户ID

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

示例代码

//clearUserId API原型和调用示例
GrowingIO.getInstance().clearUserId();

3. 设置登录用户变量

当需要上报登录用户变量时,调用 setPeopleVariable API。

发送登录用户信息用于登录用户信息相关分析,在添加代码之前必须在打点管理界面上创建登录用户变量。

// 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);

推荐您使用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字段中的 keyvalue 是否符合预期,其它字段无需仔细验证。

{
    "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
}

4. 设置访问用户变量

当用户未登录时,定义用户属性变量,也可用于A/B测试上传标签。

当需要上报访问用户变量时,调用 setVisitor API。

发送访问用户信息用于访问用户信息相关分析,在添加代码之前必须在打点管理界面上创建访问用户变量。

版本支持:>=2.4.0

//setVisitor API原型
GrowingIO.getInstance().setVisitor(JSONObject visitorVar)

参数说明

//setVisitor API调用示例
GrowingIO gio = GrowingIO.getInstance();
jsonObject.put("gender", "male");
jsonObject.put("age", "21");
gio.setVisitor(jsonObject);

检验数据发送日志示例

注意 t 字段值为 vstr,表示访问用户变量发送成功,需注意 var字段中的 keyvalue 是否符合预期,其它字段无需仔细验证

{
    "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
}

5. 设置页面级变量

使用限制:适用于无埋点SDK

当需要上报页面级变量时,调用 setPageVariable API。

发送页面级别的维度信息,用于标记当前页面,在添加代码之前必须在打点管理界面上创建页面级变量。

// 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日志确认。

SDK 2.4.0 以上能够在 Log 日志中查看对应报错,之下版本无提示信息。调用后请关注日志,查看数据发送是否成功,事件类型tpvar

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字段中的 keyvalue 是否符合预期,其它字段无需仔细验证

{
    "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
}

6. 设置转化变量

当需要上报转化变量时,调用 setEvar API。

发送一个转化信息用于高级归因分析,在添加代码之前必须在打点管理界面上创建转化变量。

// 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);

参数说明

推荐您使用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字段中的 keyvalue 是否符合预期,其它字段无需仔细验证。

{
    "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
}

7. 设置埋点事件和事件级变量

当需要上报埋点事件和事件级变量时,调用 track API。

发送一个埋点事件,在添加所需要发送的事件代码之前,需要在打点管理用户界面创建埋点事件以及事件级变量,并完成埋点事件和事件级变量的绑定。

// track API原型
GrowingIO gio = GrowingIO.getInstance();
gio.track(String eventId);
gio.track(String eventId, JSONObject eventLevelVariables);

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 ,表示自定义事件发送成功,n 字段表示埋点事件的标识符,需注意 var字段中的 keyvalue 是否符合预期,其它字段无需仔细验证

//展示 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"
}

最后更新于