最近更新时间:2023.11.01 17:18:09
首次发布时间:2022.02.23 18:13:28
上报事件和属性前,请先阅读数据格式介绍。
如您的产品中有账户体系,请在用户登录后立即设置uuid,以保证用户登录前后口径一致性。 6.13.0+版本支持在初始化AppLog之前调用,用于设置已登录的用户uuid。
// 设置您账号体系的ID, 并保证其唯一性 // 6.13.0+版本支持此方法在初始化AppLog前调用 AppLog.setUserUniqueID("your_USER_UNIQUE_ID");
(6.13.0+版本不推荐使用)通过该方法设置uuid,仅在首次冷启动时设置生效。由于 AppLog.setUserUniqueID 在 6.13.0+ 已支持在初始化之前调用,所以不再推荐使用该方法设置uuid,建议统一使用 AppLog.setUserUniqueID。
// 初始化时设置uuid // 6.13.0+版本请勿使用此方法 config.setUserUniqueId("your_USER_UNIQUE_ID");
在账户登出时调用。
// 登出时设置uuid为null AppLog.setUserUniqueID(null);
注意
不要误写成(“null”)
或 (“”)
,否则会影响数据和用户的绑定关系。
设置用户属性,存在则覆盖,不存在则创建。
// 示例:设置用户属性,属性名为key,属性值为value JSONObject paramsObj = new JSONObject(); try { paramsObj.put("key", "value"); } catch (JSONException e) { e.printStackTrace(); } AppLog.profileSet(paramsObj);
设置用户属性,存在则不设置,不存在则创建。适合首次相关的用户属性,比如首次访问时间等。
// 示例:设置用户属性,属性名为key\_once,属性值为value_once JSONObject paramsObj = new JSONObject(); try { paramsObj.put("key_once", "value_once"); } catch (JSONException e) { e.printStackTrace(); } AppLog.profileSetOnce(paramsObj);
设置数值类型的属性,可进行累加。
// 示例:设置用户属性,属性名为key,属性值为1 JSONObject paramsObj = new JSONObject(); try { paramsObj.put("key", 1); } catch (JSONException e) { e.printStackTrace(); } AppLog.profileIncrement(paramsObj);
设置List类型的用户属性,可持续向List内添加。
// 示例:设置用户属性,属性名为key,原本已有属性值,现添加属性值为value_append JSONObject paramsObj = new JSONObject(); try { paramsObj.put("key", "value_append"); } catch (JSONException e) { e.printStackTrace(); } AppLog.profileAppend(paramsObj);
删除用户的属性。
// 示例:删除用户属性,属性名为key AppLog.profileUnset("key");
用户行为日志采用事件event+属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。
仅上报事件的代码埋点,示例如下:
// 示例:上报事件event,该事件不包含属性 // 置于业务逻辑对应位置 AppLog.onEventV3("event");
上报事件和对应属性的代码埋点,示例如下:
// 示例:上报事件event,该事件包含两个属性 // 一个string类型的属性,属性名为key_string,属性值为value_string //. 一个int类型的属性,属性名为key_int,属性值为10 // 置于业务逻辑对应位置 JSONObject paramsObj = new JSONObject(); try { paramsObj.put("key_string", "value_string"); paramsObj.put("key_int", 10); } catch (JSONException e) { e.printStackTrace(); } AppLog.onEventV3("event", paramsObj);
如需在每个事件中都包括某属性,可通过公共属性设置,无需在每个事件中重复设置。公共属性只需设置一次,即可包括在所有代码埋点事件、预置事件和全埋点事件中。
/* * 示例:设置自定义的公共属性,属性名为key_public,属性值为value_public * 关于自定义 “公共属性” 请注意: * 1. 上报机制是随着每一次日志发送进行提交,默认的日志发送频率是1分钟, * 所以如果在一分钟内连续修改自定义公共属性,按照日志发送前的最后一次修改为准; * 2. 不推荐高频次修改,如每秒修改一次。 */ Map<String,Object> headerMap = new HashMap<String, Object>(); headerMap.put("key_public", "value_public"); AppLog.setHeaderInfo((HashMap<String, Object>)headerMap);
// 示例:移除属性名为key_public的公共属性 AppLog.removeHeaderInfo("key_public"); // 通过传入 null 移除所有设置过的公共属性 AppLog.setHeaderInfo(null);
// 请在初始化完成的3秒后开始获取,否则可能返回为空 String ssid = AppLog.getSsid(); // 获取SSID String did = AppLog.getDid(); // 获取设备bddid
// SDK版本号格式为X.X.X String sdk_version = AppLog.getSdkVersion();
切换账号时,同时切换数据发送方式。
AppLog.setPrivacyMode(true); //默认是false,设置后true,不采集不上报
SDK提供addDataObserver方法,用以获取各类通知,建议放在 Application 中。
public static void addDataObserver(IDataObserver listener)
设置iid、ssid、did、abconfig从本地加载和server加载成功的回调。
IDataObserver接口方法的参数说明如下:
import com.bytedance.applog.IDataObserver; AppLog.addDataObserver(new com.bytedance.applog.IDataObserver() { /** * 本地的id数据加载结果通知 * @param did device id * @param iid install id * @param ssid ssid */ @Override public void onIdLoaded(@NonNull String did, @NonNull String iid, @NonNull String ssid) { } /** * 通知注册结果,以及id变化情况 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param oldDid 原device id * @param newDid server返回新的device id * @param oldIid 原install id * @param newIid server返回新install id * @param oldSsid 原ssid * @param newSsid server返回新ssid */ @Override public void onRemoteIdGet(boolean changed, @Nullable String oldDid, @NonNull String newDid, @NonNull String oldIid, @NonNull String newIid, @NonNull String oldSsid, @NonNull String newSsid) { } /** * Config拉取数据,和本地数据对比有变化的通知 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param config server返回新config内容 */ @Override public void onRemoteConfigGet(boolean changed, @Nullable JSONObject config) { } /** * server拉取AbConfig数据,和本地数据对比有变化的通知 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param abConfig server返回新abConfig内容 */ @Override public void onRemoteAbConfigGet(boolean changed, @NonNull JSONObject abConfig) { Log.i("---测试---返回全部进组信息",""+ jsonObject.toString()); } /** * Vid变化通知 */ @Override public void onAbVidsChange(@NonNull String vids, @NonNull String extVids) { } });
SDK 默认采集以下信息,并作为用户公共属性,可在增长分析(DataFinder)中分组和筛选。
字段名称 | 字段类型 | 参数名称 |
---|---|---|
os | string | 设备系统,对应产品内属性为 os_name。 |
os_version | string | 操作系统版本 |
app_version | string | App 版本 |
app_version_minor | string | 次版本号,App四位版本号,需要初始化调用如: config.setVersionMinor( 1.2.3.r6 ) |
channel | string | 下载渠道(设置后可覆盖),对应产品内属性为 app_channel。 |
device_model | string | 设备机型 |
region | string | 操作系统地区 |
language | string | 系统语言 |
sdk_version | string | SDK版本 |
timezone | int | 时区 |
timezone_offset | int | 时区偏移量,对应产品内属性为 tz_offset。 |
timezone_name | string | 时区名称 |
sim_region | string | SIM卡地域 |
carrier | string | 运营商 |
resolution | string | 分辨率 |
device_brand | string | 设备品牌 |
access | string | 网络类型 |
如果您曾经使用火山引擎的游戏增长分析产品(该产品已经下架),目前在使用增长分析(DataFinder)产品,为了提升您的埋点效率,SDK 提供了内置接口,您只需要根据提示传入指定的参数即可。
import com.bytedance.applog.WhalerGameHelper; /** 广告按钮点击:gt_ad_button_click ad_type string 广告类型:激励视频、插屏、banner等,直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型:按照提供分类接入 ad_position string 广告点位:复活、翻倍、试用、buff、奖励道具、新道具、减CD等,直接使用文字或者英文进行标识 触发条件:用户点击app内各广告位button时。 */ public static void adButtonClick(String ad_type, String ad_position_type, String ad_position, HashMap<String, Object> otherParams); /** 广告开始展示:gt_ad_show ad_type string 广告类型:激励视频、插屏、banner等,直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型:按照提供分类接入 ad_position string 广告点位:复活、翻倍、试用、buff、奖励道具、新道具、减CD等,直接使用文字或者英文进行标识 触发条件:用户点击并观看广告时。穿山甲广告有回调,可以直接获取。 */ public static void adShow(String ad_type, String ad_position_type, String ad_position, HashMap<String, Object> otherParams); /** 广告结束展示:gt_ad_show_end ad_type string 广告类型:激励视频、插屏、banner等,直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型:按照提供分类接入 ad_position string 广告点位:复活、翻倍、试用、buff、奖励道具、新道具、减CD等,直接使用文字或者英文进行标识 result string 广告观看结果:跳过、成功、失败等,使用英文进行标识. 跳过标记为skip, 成功标记为success,失败为fail 触发条件:用户观看广告结束时。 */ public static void adShowEnd(String ad_type, String ad_position_type, String ad_position, String result, HashMap<String, Object> otherParams); /** (总等级)升级和经验:gt_levelup lev int 当前玩家等级 get_exp int 获得经验 method string 获得经验途径:闯关成功、引导完成、领取奖励等,使用汉字或者英文进行标识 aflev int 用户获得经验后等级,如获得经验未导致升级,则lev=aflev,如导致升级,则lev<aflev 触发条件:用户获得经验或者等级发生变化时。 */ levelUp(int lev, int get_exp, String method, int aflev, HashMap<String, Object> otherParams); /** 开始玩法:gt_start_play ectype_name string 针对闯关性质玩法,标注关卡名称 触发条件:用户开始玩法时。 */ public static void startPlay(String ectype_name, HashMap<String, Object> otherParams); /** 结束玩法:gt_end_play ectype_name string 针对闯关性质玩法,标注关卡名称 result string 玩法的结果:未完成、成功、失败等,使用英文进行标识. 未完成标记为uncompleted, 成功标记为success,失败为fail duration int 消耗时间,单位秒 触发条件:用户结束玩法时,涵盖中途退出、完成但失败和完成且成功。 */ public static void endPlay(String ectype_name, WhalerGameHelper.Result result, int duration, HashMap<String, Object> otherParams); /** 获得游戏币:gt_get_coins coin_type string 货币类型:元宝、绑元、金币、银币等,使用文字或者英文进行标识 method string 获得途径:观看激励视频、闯关成功、活动奖励等,使用文字或者英文进行标识 coin_num int 获得数量 触发条件:用户获得游戏币,导致游戏币增加时 */ public static void getCoins(String coin_type, String method, int coin_num, HashMap<String, Object> otherParams); /** 消耗游戏币:gt_cost_coins coin_type string 货币类型:元宝、绑元、金币、银币等,使用文字或者英文进行标识 method string 消耗途径:复活、购买道具、解锁关卡等,使用文字或者英文进行标识 coin_num int 消耗数量 触发条件:用户消耗游戏币,导致游戏币减少时。 */ public static void costCoins(String coin_type, String method, int coin_num, HashMap<String, Object> otherParams); /** 内购充值相关:purchase content_type string 内购充值内容类型 content_name string 内购充值内容名称 content_id string 内购充值内容id content_num int 内购充值内容的数量 payment_channel string 支付渠道:例如 支付宝,微信等 currency string 支付货币类型 is_success string 支付是否成功 currency_amount int 支付的金额,单位元 触发条件:用户完成内购充值并获得对应的游戏内货币和道具时 */ public static void purchase(String content_type, String content_name, String content_id, int content_num, String payment_channel, String currency, String is_success, int currency_amount, HashMap<String, Object> otherParams); /** 初始化信息:gt_init_info lev nt 玩家等级 coin_type string 获得货币的类型 coin_left int 用户身上剩余的货币数量 触发条件:用户启动游戏,初始化完成时上报 */ public static void gameInitInfo(int lev, String coin_type, int coin_left, HashMap<String, Object> otherParams);
本功能在6.10.1+后开始支持。
用户需要手动标记监听某个 View 的曝光事件。当这个 View 出现在屏幕可视范围内时,会自动触发一个曝光事件。
在初始化配置中可开启曝光配置开关,开启方法:
config.setExposureEnabled(true);
开启配置后,在需要曝光的View上增加曝光监听,示例代码:
View banner = findViewById(R.id.banner); // Optional,自定义曝光事件属性 JSONObject properties = new JSONObject(); properties.put("custom_key", "custom_value"); // Optional,默认为 "$bav2b_exposure" String eventName = "custom_exposure"; // Optional, 曝光配置,有效曝光面积和可视化调试开关 // 有效曝光面积: 有效曝光的 View 显示面积的比例,默认是 0,取值 0-1 // 可视化调试开关: 默认 false,线上不要开启,开启后曝光的 View 会增加 background 红色边框,用于调试 ViewExposureConfig config = new ViewExposureConfig(0.5F, false); ViewExposureData data = new ViewExposureData(eventName, properties, config);; // 开始监听 View 曝光事件 viewExposureManager.observeViewExposure(banner, data); // 取消监听 viewExposureManager.disposeViewExposure(banner);
全局曝光配置设置:
// Optional, 曝光配置,有效曝光面积和可视化调试开关 // 有效曝光面积: 有效曝光的 View 显示面积的比例,默认是 0,取值 0-1 // 可视化调试开关: 默认 false,线上不要开启,开启后曝光的 View 会增加 background 红色边框,用于调试 ViewExposureConfig config = new ViewExposureConfig(0.5F, false); // 6.15.2 前通过 InitConfig 设置全局曝光配置 config.setViewExposureConfig(config); // 6.15.2 后调整至 ViewExposureManager 中,用以代替之前 InitConfig.setViewExposureConfig 的方法 AppLog.getViewExposureManager().updateViewExposureConfig(config);
在部分特殊场景下可能会由于页面不断重绘导致一直无法触发曝光,目前新增了两种曝光检测策略以供选择,可动态调整:
// 6.15.2 新增 // 默认检测策略 如果有多次频繁触发 会在最后一次触发的 100ms 后触发曝光检测 AppLog.getViewExposureManager().updateExposureCheckStrategy(ExposureCheckType.DEBOUNCE); // 新增检测策略 如果有多次频繁触发 会在每隔 500ms 触发一次曝光检测 AppLog.getViewExposureManager().updateExposureCheckStrategy(ExposureCheckType.THROTTLE);
本小节功能在6.9.0+后开始支持。
开启全埋点事件采集开关后,会默认采集页面事件和View点击事件等。
有2种自定义配置页面事件($bav2b_page)的属性:@PageMeta注解和实现IPageMeta接口。
@PageMeta
注解支持自定义标题和路径,在Activity或Fragment上添加该注解和配置参数,例如:
@PageMeta(path = "/mypath", title = "自定义页面") public class MyActivity extends Activity { }
IPageMeta
接口类支持自定义标题、路径和属性,优先级高于@PageMeta
。在Activity或Fragment上实现该接口和对应的函数,例如:
public class MyActivity extends Activity implements IPageMeta { @Override public String title() { return "自定义页面"; } @Override public String path() { return "/mypath"; } @Override public JSONObject pageProperties() { JSONObject params = new JSONObject(); try { params.put("key", "value"); } catch (JSONException e) { } return params; } }
支持对指定的View对象设置一个元素ID,字符串即可,示例:
AppLog.setViewId(view, "myElementId");
支持对指定的View对象设置属性值,示例:
JSONObject props = new JSONObject(); try { props.put("key", "value"); } catch (Exception e) { } AppLog.setViewProperties(view, props);
支持忽略特定的Activity或Fragment的全埋点事件,示例:
AppLog.ignoreAutoTrackPage(MyActivity.class, MyFragment.class);
忽略指定View对象的点击事件,示例:
AppLog.ignoreAutoTrackClick(findViewById(R.id.button1));
忽略指定View类型的点击事件,示例:
// 忽略所有Switch组件的点击事件 AppLog.ignoreAutoTrackClickByViewType(Switch.class);
支持手动采集特定的Activity和Fragment对象的页面事件以及属性,示例:
JSONObject params = new JSONObject(); try { params.put("param1", "test"); } catch (JSONException e) { } AppLog.trackPage(MyActivity.this, params);
支持手动采集特定View的点击事件以及属性,示例:
JSONObject params = new JSONObject(); try { params.put("param1", "test"); } catch (JSONException e) { } AppLog.trackClick(myView, params);
本小节功能在6.10.1+后开始支持。
带有时间属性的事件可以使用时长事件采集接口,例如采集视频播放时长事件等。示例:
// 在视频开始播放时调用 AppLog.startDurationEvent("play"); // 在视频暂停播放时调用 AppLog.pauseDurationEvent("play"); // 在视频继续播放时调用 AppLog.resumeDurationEvent("play"); // 在结束播放时调用,此时会上报一个play事件,且带有$event\_duration属性(记录了播放时长,单位毫秒) JsonObject params = new JsonObject() // 可以在 params 填入自己的自定义参数 AppLog.stopDurationEvent("play", params);