离线文件说明 #

请前往Android SDK包下载页面获取对应版本的SDK包。

必选依赖：
 - if_encryptor-xxx.aar（6.17.0 及之前） / encryptor-xxx-private.aar：加密库相关
 - RangersAppLog-All-cn-xxx.aar：增长营销主模块
 - RangersAppLog-Log-xxx.aar：增长营销 SDK 内部日志依赖
 - plugin-aggregation-xxx.aar：增长营销 SDK 内部信息聚合模块依赖

非必选依赖：
 - RangersAppLog-All-scheme-xxx.aar：实时埋点检测和圈选功能
 - RangersAppLog-All-plugin-xxx.jar：SDK plugin，主要提供全埋点 / h5 打通 / 黑名单过滤 / 移除部分隐私采集代码功能
 - RangersAppLog-DevTools-xxx.aar：可视化埋点调试工具，可用于埋点流程验证

集成说明 #

集成方式一，项目中已包含所有 libs 下 aar / jar：
// app 目录下 build.gradle
implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
// 此时可以将以上必须依赖以及部分需要可选依赖添加到 libs 目录下

集成方式二，逐个集成：
// app 目录下 build.gradle
implementation files('libs/encryptor-xxx-private.aar')
// 6.17.1 及以上移除了 if_encryptor-xxx
implementation files('libs/if_encryptor-xxx.aar')
implementation files('libs/RangersAppLog-All-cn-xxx.aar')
implementation files('libs/RangersAppLog-Log-xxx.aar')
implementation files('libs/plugin-aggregation-xxx.aar')
// 剩余部分按需集成
// 注：调试工具建议仅 debug 模式即成
debugImplementation files('libs/RangersAppLog-DevTools-xxx.aar')

如果离线使用 plugin，请参考以下集成方式：
// 根目录下 build.gradle
buildscript {
  dependencies {
    // 增长营销所需的 gradle 插件
    // 如果放在 app/libs 目录下 xxxdir 可以替换为 app/libs
    classpath fileTree(include: ['*.jar'], dir: 'xxxdir/RangersAppLog-All-plugin-xxx.jar')
  }
}

离线包依赖混淆配置：
-keep class com.bytedance.applog.picker.DomSender { public *; }
-keep class com.bytedance.applog.tracker.WebViewUtil { public *; }
-keep class com.bytedance.applog.metasec.AppLogSecHelper { *; }

-keepclassmembers class * {
    public void loadUrl(java.lang.String);
    public void loadUrl(java.lang.String, java.util.Map);
    public void loadData(java.lang.String, java.lang.String, java.lang.String);
    public void loadDataWithBaseURL(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String);
}

用户登录态设置 #

比如业务有账号体系，并希望 SDK 同步用户状态。就可以考虑在用户登录后立即对 SDK 设置 user_unique_id，在用户登出后立即对 SDK 清除 user_unique_id。

// 用户登录后立即设置 user_unique_id
AppLog.setUserUniqueID("your_USER_UNIQUE_ID");

// 用户登出后立即清除 user_unique_id
AppLog.setUserUniqueID(null);

用户口径相关处理 #

如果要设置用户口径，需要在设置 user_unique_id 的同时设置 user_unique_id_type

// 用户登录后立即设置 user_unique_id, user_unique_id_type
AppLog.setUserUniqueID("your_USER_UNIQUE_ID", "your_USER_UNIQUE_ID_TYPE");

// 用户登出后立即清除 user_unique_id, user_unique_id_type
AppLog.setUserUniqueID(null, null);

多用户口径类型处理 #

如果要进行多口径绑定，在设置 user_unique_id 的同时设置 user_unique_id_type 后，还需要调用 bind 方法处理。注意：仅在SAAS云原生、私有化支持。

// 示例中 phone 和 cust_num 只是举例，具体传啥由业务决定
Map<String, String> ids = new HashMap<String, String>
ids.put("phone", "1230000000"); // 第一个参数 phone 为 id 类型枚举值，同 id 设计方案
ids.put("cust_num", "12345656788888"); //第一个参数 cust_num 为 id 类型枚举值，同 id 设计方案
AppLog.bind(ids, new IDBindCallback() {
    void onSuccess(IDBindResult result) {
        // 请求成功并设置登录状态
        AppLog.setUserUniqueID("12345656788888" ,"cust_num");
    }
    void onFail(int code) {
        // 绑定请求失败
    }
});

插件依赖 #

插件仓库配置 #

Gradle 7.0 以下

// 在 project 级别的 build.gradle 的 buildscript 的 repositories 中添加 maven 仓库、引入 SDK plugin
buildscript {
    repositories {
        maven{
            url 'https://artifact.bytedance.com/repository/Volcengine/'
        }
        // 省略其他
    }
}

Gradle 7.0 及以上

// setting.gradle 中
pluginManagement {
    repositories {
        maven{
            url 'https://artifact.bytedance.com/repository/Volcengine/'
        }
        // 省略其他
    }
}

插件依赖 #

Gradle 7.0 以下

// 在project 级别的 build.gradle 的 buildscript的repositories中添加maven仓库、引入SDK plugin
buildscript {
    // 省略其他
    dependencies {
        classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.17.4'
    }
}

// 在 app module 级别的 build.gradle 
// 默认放到插件列表最后一个声明，如遇到冲突，
// 可以将其调整到 application / kotlin 等官方插件后的第一个
apply plugin: 'com.bytedance.std.tracker'

Gradle 7.0 及以上~8.0 以下

// project 级别的 build.gradle 中
buildscript {
    // 省略其他
    dependencies {
        classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.17.4'
    }
}

// 在 app module 级别的 build.gradle 
// 默认放到插件列表最后一个声明，如遇到冲突，
// 可以将其调整到 application / kotlin 等官方插件后的第一个
plugins {
    // 省略其他插件
    id 'com.bytedance.std.tracker'
}

Gradle 8.0 及以上

// project 级别的 build.gradle 中
buildscript {
    dependencies {
        // agp8 版本使用新版本插件
        classpath 'com.bytedance.applog:RangersAppLog-All-plugin-agp8:6.17.1'
    }
}

// 在 app module 级别的 build.gradle 
// 默认放到插件列表最后一个声明，如遇到冲突，
// 可以将其调整到 application / kotlin 等官方插件后的第一个
plugins {
    // 省略其他插件
    id 'com.bytedance.std.tracker'
}

插件使用示例 #

在 app module 级别的 build.gradle文件中应用 plugin。
Gradle 8.0 以下

teaExtension {
    // 自动注入webview的对接bridge
    autoInjectWebViewBridge = true

    // 插装黑名单，包路径前缀，针对某些不希望进行插桩的包进行配置
    // 需要将包名中的 . 替换成 /，可配置多个，通过 , 分割
    // 示例：blackList = ['dji/upgrade/internal','org/bouncycastle/jcajce']
    blackList = []

    // 埋点黑名单配置
    // 仅支持以下配置：
    // 'MAC_ADDRESS'： mac地址
    // 'IMEI_MEID'： imei和meid
    // 'OAID'： oaid
    // 'ANDROIDID': android id
     // 'OPERATOR': carrier、mcc_mnc
    // 'CLIPBOARD':剪切板相关代码
    // 示例：trackBlackList = ['MAC_ADDRESS', 'IMEI_MEID', 'OPERATOR']
    trackBlackList = []
  
    // 6.14.3 新功能
    // 关闭接口/类自动跟踪功能
    // 使用场景举例：当您使用 lite 包时，但又需要 trackBlackList 来移除部分采集代码时，可以使用该功能
    disableAutoTrack = false
}

Gradle 8.0 及以上

// 新版插件使用调整为 appLog 
appLog {
    // 自动注入webview的对接bridge
    // agp8 的打通功能需要使用 6.16.7 及以上版本
    autoInjectWebViewBridge = true

    // 插装黑名单，包路径前缀，针对某些不希望进行插桩的包进行配置，对标老版插件 blackList
    // 示例：ignoredInstrumentationPaths = ['dji.upgrade.internal','org.bouncycastle.jcajce']
    // 写法从 ['dji/upgrade/internal','org/bouncycastle/jcajce'] 调整为 ['dji.upgrade.internal','org.bouncycastle.jcajce']
    ignoredInstrumentationPaths = []

    // 埋点黑名单配置，对标老版插件 trackBlackList
    // 仅支持以下配置：
    // 'MAC_ADDRESS'： mac地址
    // 'IMEI_MEID'： imei和meid
    // 'OAID'： oaid
    // 'ANDROIDID': android id
    // 'OPERATOR': carrier、mcc_mnc
    // 'CLIPBOARD':剪切板相关代码
    // 示例：sensitiveFieldsBlocklist = ['MAC_ADDRESS', 'IMEI_MEID', 'OPERATOR']
    sensitiveFieldsBlocklist = []
  
    // 6.14.3 新功能
    // 关闭接口/类自动跟踪功能
    // 使用场景举例：当您使用 lite 包时，但又需要 trackBlackList 来移除部分采集代码时，可以使用该功能
    disableAutoTrack = false
}

// 注：该功能仅支持原生 WebView 与腾讯 X5
// 以下配置需要同时开启，如果以下两个没有同时满足，H5 事件就会继续保持 Web/JS SDK 上报：
// Android SDK 开启内嵌H5打通开关
config.setH5BridgeEnable(true);
// Web/JS SDK 设置 H5 内嵌到原生端并打通
window.collectEvent('init', {
    // ...... 其他初始化配置
    enable_native: true 
    // 5.1.3以下版本参数为Native，
    // 5.1.3以上版本修改为enable_native，但仍然兼容了Native的设置
})

// 补充：开启打通后老版本原本 web sdk 的全埋点配置会失效
// 5.1.10 之前的老版本打通后 Web/JS SDK 屏蔽了 H5 的全埋点功能，所以 Web/JS SDK 的全埋点设置开关会失效，
// 老版本 web sdk 想要依然保持 H5 全埋点功能，请查看 4.7 小节或者建议升级到新版本
window.collectEvent('init', {
    // 全埋点设置开关 
    autotrack: 打通后老版本失效（web sdk 5.1.10 之前版本失效，5.1.10 及之后版本正常采集）
})

打通内嵌 H5 页的白名单前置工作 #

开关开启后，必须配置打通白名单。仅白名单内配置的域名生效打通，白名单可用通配符方式添加，*表示通配符。

// 内嵌H5页白名单配置
// 示例：如需打通 www.volcengine.com 和 www.bytedance.com 两个H5页
config.setH5BridgeAllowlist(Arrays.asList("www.volcengine.com", "*.bytedance.*"));
// 适配 www.bytedance.com 的白名单有多种，请根据业务场景配置白名单，例如：
// www.bytedance.com 或 *.bytedance.* 或 *.*.* 均可实现。

如果不过滤任何域名和本地资源文件，可以配置允许所有H5页面打通。该配置优先级高于setH5BridgeAllowlist。

// 允许所有h5打通
// 本功能仅支持6.9.7及以上版本
config.setH5BridgeAllowAll(true);

打通内嵌 H5 页的插件注入注意项 #

• Gradle 8.0 以下关闭插件自动注入

  // 通过插件关闭自动注入
  teaExtension {
      // 关闭自动注入webview的对接bridge
      autoInjectWebViewBridge = false
      // 省略插件的其他使用
  }
  

• Gradle 8.0 及以上关闭插件自动注入

  // AGP8 版本插件 6.16.3 支持
  appLog {
      // 关闭自动注入webview的对接bridge
      autoInjectWebViewBridge = false
      // 省略插件的其他使用
  }
  

// 本功能仅支持6.13.0及以上版本
WebView myWebView = findViewById(R.id.webview);
// 在loadUrl之前注入Bridge
AppLog.initWebViewBridge(myWebView, url);
myWebView.loadUrl(url);

打通内嵌 H5 页时禁止 H5 更新 App 内用户信息（uuid） #

打通时默认用的是端内 SDK 用户信息，但也支持 H5 侧通过 Web SDK 更新端内 SDK 用户信息。
Android 6.17.0 版本新增禁止打通内嵌 H5 页时禁止 H5 更新 App 内用户信息，以避免 H5 多处使用时更新用户信息相关代码不好移除，从而打通时破坏端内 SDK 原本的用户信息。

// 默认开启，支持关闭
config.setUseBridgeUpdateUUIDEnabled(true);

SDK 默认实例介绍 #

Android SDK 提供了默认全局实例，通过 AppLog.xxx 相当于调用默认全局实例。

AppLog.xxx 等效于 AppLog.getInstance().xxx

多实例介绍 #

多实例初始化，指 SDK 支持在同包名的 App 中向多个应用(多个 appid)开启埋点，且埋点数据相互隔离，每一个 appid 对应一个单独的实例。

使用场景例如：

• 第三方 SDK 依赖增长营销套件 SDK 做 SDK 内部产生的埋点时；
• 同一个 App 或系统中，关联多个埋点应用(多个 appid)，共用增长营销套件 SDK 时；

核心 API，使用后返回 IAppLogInstance 对象，需要开发者做好实例保存，确保数据发送到正确实例
AppLog.newInstance()

/* 多实例初始化SDK 实例1*/
final InitConfig config1 = new InitConfig("yourAPPID1", "yourCHANNEL1");
// 创建实例
IAppLogInstance appLogInst1 = AppLog.newInstance();
// 设置数据上送地址
config1.setUriConfig(UriConstants.DEFAULT);
// 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
config1.setAutoStart(false);
// 开启全埋点事件的上送
config1.setAutoTrackEnabled(true); // 全埋点开关，true:开启，false:关闭
config1.setLogEnable(true); // true:开启日志，设置 logger，false:关闭日志
appLogInst1.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
// 初始化一次即可
// Applition 中初始化建议使用该方法
appLogInst1.init(this, config1);
// Activity 中初始化建议使用该方法
appLogInst1.init(this, config1, activity);

//实例2
final InitConfig config2 = new InitConfig("yourAPPID2", "yourCHANNEL2");
IAppLogInstance appLogInst2 = AppLog.newInstance();
config2.setUriConfig(UriConstants.DEFAULT);
// 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
config2.setAutoStart(false);
config2.setAutoTrackEnabled(true);
config2.setLogEnable(true); // true:开启日志，参考4.3节设置logger，false:关闭日志
appLogInst2.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
// 初始化一次即可
// Applition 中初始化建议使用该方法
appLogInst2.init(this, config2);
// Activity 中初始化建议使用该方法
appLogInst2.init(this, config2, activity);

// 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
appLogInst1.start();
appLogInst2.start();

SDK 可关闭采集的敏感字段 #

1. 关闭 MAC 地址采集

// 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 MAC 
config.setMacEnable(false);

2. 关闭设备 IMEI/MEID 采集

// 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 AppImei 
config.setImeiEnable(false);

3. 关闭 OAID 采集

// 开关关闭后相关代码不运行，属性不采集不上送
config.setOaidEnabled(false);

4. 关闭 Android ID 采集

// 开关关闭后相关代码不运行，属性不采集，关闭后会随机生成并保存在本地缓存，卸载重装会丢失缓存
config.setAndroidIdEnabled(false);

5. 关闭 ICCID 采集

// 开关关闭后相关代码不运行，属性不采集不上送
// 本功能仅支持 6.14.3 及以上版本
config.setIccIdEnabled(false);

6. 关闭 SN（硬件序列号） 采集

// 开关关闭后相关代码不运行，属性不采集不上送
// 本功能仅支持 6.15.0 及以上版本
config.setSerialNumberEnable(false);

7. 关闭 GAID 采集
   • 6.15.0 之前 cn(国内版)与 global(海外版)都默认采集
   • 6.15.0 及之后 cn 默认关闭，global 默认打开

// 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 Gaid 
config.setGaidEnabled(false);

8. 关闭运营商信息采集

// 开关关闭后相关代码不运行，属性不采集不上送
config.setOperatorInfoEnabled(false);

9. 关闭剪切板访问

// 开关关闭后不会访问客户剪切板内容
// 通过对应 applog 实例关闭
AppLog.setClipboardEnabled(false);

10. 关闭 CPU 架构采集

// 开关关闭后相关代码不运行，属性不采集不上送
// 本功能仅支持 6.17.1 及以上版本
config.setCPUAbiEnabled(false);

11. 关闭屏幕分辨率 / 屏幕密度采集

// 开关关闭后相关代码不运行，属性不采集不上送
// 本功能仅支持 6.17.1 及以上版本
config.setDisplayDensityAndDpiEnabled(false);

静态检测移除相关代码 #

1. 移除 MAC 地址相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.9.0 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["MAC_ADDRESS"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.9.0 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["MAC_ADDRESS"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

2. 移除 IMEI / MEID 相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.9.0 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["IMEI_MEID"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.9.0 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["IMEI_MEID"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

3. 移除 OAID 相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.9.0 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["OAID"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.9.0 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["OAID"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

4. 移除 AndroidId 相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.10.1 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["ANDROIDID"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.10.1 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["ANDROIDID"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

5. 移除运营商信息相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.10.1 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["OPERATOR"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.10.1 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["OPERATOR"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

6. 移除剪切板相关代码

• Gradle 8.0 以下

// 本功能仅支持 6.16.3 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["CLIPBOARD"]

    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

• Gradle 8.0 及以上

// 本功能仅支持 6.16.3 及以上版本
// AGP8 版本插件 6.16.3 支持
appLog {
    // ... 其他配置
    sensitiveFieldsBlocklist = ["CLIPBOARD"]
  
    // 您使用的是 Lite 包，需要移除采集相关代码，
    // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供
    disableAutoTrack = true
}

自定义页面事件属性 #

IPageMeta接口类支持自定义标题、路径和属性。在 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 点击事件属性 #

除各预置事件的预置属性外，DataFinder 还支持设置点击事件（bav2b_click）的自定义属性。

设置 View 的元素 ID #

支持对指定的 View 对象设置一个元素 ID，字符串即可，示例：

AppLog.setViewId(view, "myElementId");

设置 View 的属性 #

支持对指定的 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 的点击事件 #

• 忽略指定 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 点击事件 #

支持手动采集特定 View 的点击事件以及属性，示例：

JSONObject params = new JSONObject();
try {
    params.put("param1", "test");
} catch (JSONException e) {
}
AppLog.trackClick(myView, params);

原生端采集 H5 全埋点 #

原生端内嵌 H5 页时，通过打开以下开关，可从原生端全埋点事件采集 H5 页全埋点事件。
使用场景一般有两个：

• 由于当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能，为确保打通后依然可以保留 H5 页全埋点功能。
• 独立使用，在 H5 未集成 Web/JS SDK 的情况下想对应用中的 H5 页开启全埋点功能。

// 注：该功能仅支持原生 WebView 与腾讯 X5

// 内嵌H5页面的全埋点事件
config.setH5CollectEnable(true); // true:开启h5全埋点事件，false:关闭h5全埋点事件
// 补充，该功能默认也通过插件方式注入，当插件失效或者想要自己手动注入时

如何正确获取 DID 等参数 #

由于 did / ssid 是通过设备服务请求返回，所以获取可能存在一定延迟性，Applog.getDid() 等方法可能第一时间无法获取到对应参数，所以建议通过回调的方式获取，以及回调后，再通过 Applog.getDid() 等方法就可以确保一定获取。

// step1：添加数据集观察回调，this 指代实现了 IDataObserver 的类
AppLog.addDataObserver(this);
// step2：通过 IDataObserver 的 onIdLoaded 或 onRemoteIdGet 到数据后使用或者使用以下方式获取： 
默认实例：Applog.getDid() / 使用多实例：IAppLogInstance.getDid()


// IDataObserver 主要功能介绍与参数介绍：
//  - did、iid、ssid 获取都可以通过该回调获取
//  - 服务端配置获取
//  - ab 实验配置获取
public interface IDataObserver {
    /**
     * 本地的id数据加载结果通知
     * @param did device id
     * @param iid install id
     * @param ssid 数说id
     */
    void onIdLoaded(@NonNull String did, @NonNull String iid, @NonNull String ssid);

    /**
     * 通知注册结果，以及id变化情况
     * 仅主进程会被调用
     * @param changed 是否和本地缓存有所不同
     * @param oldDid 本地老的 oldDid，可能为空
     * @param newDid server返回新的 device id
     * @param newIid server返回新 install id
     * @param newSsid server返回新数说 id
     */
    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内容
     */
    void onRemoteConfigGet(boolean changed, @Nullable JSONObject config);

    /**
     * server拉取AbConfig数据，和本地数据对比有变化的通知
     * 仅主进程会被调用
     * @param changed 是否和本地缓存有所不同
     * @param abConfig server返回新abConfig内容
     */
    void onRemoteAbConfigGet(boolean changed, @NonNull JSONObject abConfig);

    /**
     * 客户端ab实验曝光vid集合发生变化的通知
     * @param vids 客户端ab实验曝光vid集合
     * @param extVids 外部设置的external vid集合
     */
    void onAbVidsChange(@NonNull String vids, @NonNull String extVids);
}

事件过滤以及自定义参数补齐 #

针对事件过滤或事件自定义参数补齐，可以使用以下回调：

• 6.16.1 及以上版本

AppLog.setEventHandler(new IEventHandler() {
    // 返回可接受的事件类型
    @Override
    public int acceptType() {
        return EventType.EVENT_ALL;
    }

    // 针对单事件做事件过滤 或 自定义参数额外处理
    @Override
    public EventPolicy onReceive(
            int eventType,
            @NonNull String eventName,
            @NonNull JSONObject properties,
            // 新增事件基本信息
            @NonNull EventBasicData basicData) {
        //  用户属性不处理
        if (eventName.startsWith("__profile_")) {
            return EventPolicy.ACCEPT;
        }
        // 过滤 xx 事件
        if ("xx".equals(eventName)) {
            return EventPolicy.DENY;
        }
        // 添加自定义属性
        try {
            properties.put("eventHandlerProps", "12345");
        } catch (JSONException ignored) {

        }
        // 其他事件正常上报
        return EventPolicy.ACCEPT;
    }
});

• 6.16.1 以下版本

// 设置事件处理回调
AppLog.setEventHandler(new IEventHandler() {
    // 返回可接受的事件类型
    @Override
    public int acceptType() {
        return EventType.EVENT_ALL;
    }

    // 针对单事件做事件过滤 或 自定义参数额外处理
    @Override
    public EventPolicy onReceive(
            int eventType,
            @NonNull String eventName,
            @NonNull JSONObject properties) {
        //  用户属性不处理
        if (eventName.startsWith("__profile_")) {
            return EventPolicy.ACCEPT;
        }
        // 过滤 xx 事件
        if ("xx".equals(eventName)) {
            return EventPolicy.DENY;
        }
        // 添加自定义属性
        try {
            properties.put("eventHandlerProps", "12345");
        } catch (JSONException ignored) {

        }
        // 其他事件正常上报
        return EventPolicy.ACCEPT;
    }
});

事件公共属性 #

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。

设置公共属性 #

/*
 * 示例：设置自定义的公共属性，属性名为 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);

获取平台 ID 与通知 #

获取平台生成 ID #

// 正确获取时机建议参考《如何获取 DID 等参数》
String ssid = AppLog.getSsid(); // 获取 SSID
String did = AppLog.getDid(); // 获取设备 bddid

获取 SDK 版本号 #

// SDK 版本号格式为 X.X.X
String sdkVersion = AppLog.getSdkVersion();

采集时长事件 #

本小节功能在 6.10.1+ 后开始支持。

带有时间属性的事件可以使用时长事件采集接口，例如采集视频播放时长事件等。示例：

// 在视频开始播放时调用
AppLog.startDurationEvent("play");

// 在视频暂停播放时调用
AppLog.pauseDurationEvent("play");

// 在视频继续播放时调用
AppLog.resumeDurationEvent("play");

// 在结束播放时调用，此时会上报一个 play 事件，且带有 $event_duration 属性（记录了播放时长，单位毫秒） 
JsonObject params = new JsonObject() 
// 可以在 params 填入自己的自定义参数
AppLog.stopDurationEvent("play", params);
// 6.16.10 后自持自定义时长事件事件名，默认情况事件名为方法第一个参数
AppLog.stopDurationEvent("play", params, "custom_play");

配置Scheme(可选) #

如需使用实时埋点检测或圈选事件，请配置 Scheme，因为需要扫码后 H5 需要通过 Scheme 来唤醒 App，如果您发现扫码成功但是应用未跳转可手动切换回去，在少部分场景下存在无法自动跳转的情况。

获取URL Scheme #

「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的 scheme，一般为rangersapplog.xxxxx的形式。

添加URL Scheme #

在 app module 级别的 build.gradle 中添加 URL Scheme。

// 在android的defaultConfig中添加
manifestPlaceholders.put("APPLOG_SCHEME", "yourURL_SCHEME".toLowerCase())