• SDK版本：当前SDK版本在不断迭代发布中，您可前往Git开源页面查看各端的SDK版本情况，推荐使用最新版本SDK。本文中的代码示例以一个版本号作为示例，您实际使用时，需根据使用的实际SDK版本修改其中的版本号。
• 下载SDK包：集成SDK时，如果您需要手动引入SDK，需前往Git开源页面下载对应版本的SDK包。
• 使用Android SDK时，您可先了解通用的数据上报策略（数据上报策略）、已支持的预置事件（APP预置事件及属性）和Android端的上报流程（9. 参考：数据上报流程与触发时机）。

1.1 引入仓库 #

• Gradle 7.0以下

  // 在 project 级别的 build.gradle 中添加 maven 仓库
  // 在 allprojects 的 repositories 中添加 maven 仓库
  allprojects {
      repositories {
          maven {
              url 'https://artifact.bytedance.com/repository/Volcengine/'
          }
          // 其他仓库
      }
  }
  

• Gradle 7.0及以上

  // 在 project 级别的 setting.gradle 中添加 maven 仓库
  dependencyResolutionManagement {
      repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
      repositories {
          maven {
              url 'https://artifact.bytedance.com/repository/Volcengine/'
          }
          // 其他仓库
      }
  }
  

1.2 引入插件(可选) #

1.2.1 插件仓库 #

• 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/'
          }
          // 省略其他
      }
  }
  

1.2.2 插件依赖 #

• Gradle 7.0以下

  // 在project 级别的 build.gradle 的 buildscript的repositories中添加maven仓库、引入SDK plugin
  buildscript {
      // 省略其他
      dependencies {
          classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.17.1'
      }
  }
  
  // 在 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.1'
      }
  }
  
  // 在 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'
  }
  

1.2.3 插件使用示例 #

在 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
  }
  

1.3 引入 SDK #

在 app module 级别的 build.gradle 文件中，在 dependencies 里引入 SDK。
增长营销套件提供两个版本的 SDK，请根据业务需要择一引用即可。

• 如您需要使用完整的 SDK 功能，请集成All版本：

  // 在 build.gradle 文件的 dependencies 中 引入 SDK，集成 All 版本，推荐此版本
  implementation 'com.bytedance.applog:RangersAppLog-All-cn:6.17.1'
  

• 如您不需要全埋点采集、圈选、web 打通等功能，仅需要自定义埋点，可集成 Lite 版本：

  // 在 build.gradle 文件的 dependencies 中引入SDK，集成Lite版本
  implementation 'com.bytedance.applog:RangersAppLog-Lite-cn:6.17.1'
  

1.4 引入调试工具 DevTools 组件(可选) #

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

DevTools是 Debug 环境下辅助开发者或测试人员进行应用内埋点验证和 SDK 接入问题排查的组件。在 app module 级别的 build.gradle 文件中，在 dependencies 里引入DevTools。详细接入文档请查阅：Android埋点开发工具。

// 建议仅在 debug 或者测试包下做调试
// debug 或测试包中依赖 DevTools 组件
debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:3.4.7'

1.5 实时埋点检测和圈选功能(可选) #

如需实时埋点检测或圈选事件，请执行 1.5 节引入 scheme 包，否则可跳过此步骤。

// 在 build.gradle 文件的 dependencies 中添加
implementation 'com.bytedance.applog:RangersAppLog-All-scheme:6.17.1'

1.6 Kotlin 相关依赖(可选) #

如您使用 kotlin 语言编写项目，请执行 1.7 节确认 kotlin 依赖的引入，否则可跳过此步骤。

// 示例版本
implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.61'

1.7 手动引入须知 #

推荐您远程引入 SDK。如特殊情况需要手动引入，请补充阅读本小节。
请前往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：实时埋点检测和圈选功能，请参考 1.5 解释
 - RangersAppLog-All-metasec-cn-xxx.aar：反作弊风控子库，请参考 1.6 解释
 - 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);
}

2.1 获取 appid #

在开始集成前，首先需要在集团中拥有一个应用，进行 SDK 集成前，您需要获取对应应用的 appid 信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见项目管理。
  
• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见应用列表。
  

2.2 获取数据上送地址 #

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，如果上报地址设置错误，后续会导致您无法查询到上报的数据。

SaaS-云原生 & SaaS-非云原生 #

私有化环境 #

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化 SDK #

2.3.1 SaaS-云原生 #

如您使用 SaaS-云原生部署版本，请参照如下代码初始化 SDK。

• Java

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
  // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文 获取数据上送地址 章节
  config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null));    
  // 确保 start 才开始用用户信息采集
  config.setAutoStart(false);
  // 全埋点开关，true开启，false关闭
  config.setAutoTrackEnabled(true); 
  // true:开启日志，参考4.3节设置logger，false:关闭日志
  config.setLogEnable(false); 
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true); 
  // 初始化一次即可
  // Applition 中初始化建议使用该方法
  AppLog.init(this, config);
  // Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity);
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()；
  

• Kotlin

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  val config = InitConfig("yourAPPID", "yourCHANNEL").apply {
      // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文 获取数据上送地址 章节
      uriConfig = UriConfig.createByDomain("https://gator.volces.com", null)
      // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
      setAutoStart(false)
      // 全埋点开关，true开启，false关闭
      isAutoTrackEnabled = true
      // true:开启日志，参考4.3节设置logger，false:关闭日志
      isLogEnable = false
  }
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true)
  // 初始化一次即可
  // 在 Applition 中初始化建议使用该方法
  AppLog.init(this, config)
  // 在 Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity)
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()
  

2.3.2 SaaS-非云原生 #

如您使用 SaaS-非云原生 部署版本，请参照如下代码初始化 SDK。

• Java

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
  // 设置数据上送地址，详情见上文 获取数据上送地址 章节
  config.setUriConfig(UriConstants.DEFAULT);
  // 确保 start 才开始用用户信息采集
  config.setAutoStart(false);
  // 全埋点开关，true开启，false关闭
  config.setAutoTrackEnabled(true); 
  // true:开启日志，参考4.3节设置logger，false:关闭日志
  config.setLogEnable(false); 
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true); 
  // 初始化一次即可
  // Applition 中初始化建议使用该方法
  AppLog.init(this, config);
  // Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity);
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()；
  

• Kotlin

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  val config = InitConfig("yourAPPID", "yourCHANNEL").apply {
      // 设置数据上送地址，详情见上文 获取数据上送地址 章节
      setUriConfig(UriConstants.DEFAULT)
      // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
      setAutoStart(false)
      // 全埋点开关，true开启，false关闭
      isAutoTrackEnabled = true
      // true:开启日志，参考4.3节设置logger，false:关闭日志
      isLogEnable = false
  }
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true)
  // 初始化一次即可
  // 在 Applition 中初始化建议使用该方法
  AppLog.init(this, config)
  // 在 Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity)
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()
  

2.3.2 私有化版本 #

如您使用私有化部署版本，请参照如下代码初始化 SDK。

• Java

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
  // 设置私有化部署数据上送地址，参考2.2节获取，例如 https://yourdomain.com，注意域名后不要加“/”
  config.setUriConfig(UriConfig.createByDomain("yourREPORT_URL", null));
  // 确保 start 才开始用用户信息采集
  config.setAutoStart(false);
  // 全埋点开关，true开启，false关闭
  config.setAutoTrackEnabled(true); 
  // true:开启日志，参考4.3节设置logger，false:关闭日志
  config.setLogEnable(false); 
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true); 
  // 初始化一次即可
  // Applition 中初始化建议使用该方法
  AppLog.init(this, config);
  // Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity);
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()；
  

• Kotlin

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  val config = InitConfig("yourAPPID", "yourCHANNEL").apply {
      // 设置私有化部署数据上送地址，参考2.2节获取，例如 https://yourdomain.com，注意域名后不要加“/”
      uriConfig = UriConfig.createByDomain("yourREPORT_URL", null)
      // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
      setAutoStart(false)
      // 全埋点开关，true开启，false关闭
      isAutoTrackEnabled = true
      // true:开启日志，参考4.3节设置logger，false:关闭日志
      isLogEnable = false
  }
  // 加密开关，true开启，false关闭
  AppLog.setEncryptAndCompress(true)
  // 初始化一次即可
  // 在 Applition 中初始化建议使用该方法
  AppLog.init(this, config)
  // 在 Activity 中初始化建议使用该方法
  AppLog.init(this, config, activity)
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  AppLog.start()
  

2.4 多实例初始化(可选) #

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

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

示例代码如下。

• Java

  /* 多实例初始化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:开启日志，参考4.3节设置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();
  

• Kotlin

  /* 初始化SDK */
  // 第一个参数APPID: 参考2.1节获取
  // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
  val appLogInst1 = AppLog.newInstance()
  val config1 = InitConfig("yourAPPID1", "yourCHANNEL1").apply {
      // 设置数据上送地址
      uriConfig = UriConfig.createByDomain("https://gator.volces.com", null)
      // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
      setAutoStart(false)
      // 全埋点开关，true开启，false关闭
      isAutoTrackEnabled = true
      // true:开启日志，参考4.3节设置logger，false:关闭日志
      isLogEnable = false
  }
  // 加密开关，true开启，false关闭
  appLogInst1.encryptAndCompress = true
  // 初始化一次即可
  // Applition 中初始化建议使用该方法
  appLogInst1.init(this, config1)
  // Activity 中初始化建议使用该方法
  appLogInst1.init(this, config1, activity)
  
  val appLogInst2 = AppLog.newInstance()
  val config2 = InitConfig("yourAPPID2", "yourCHANNEL2").apply {
      // 设置数据上送地址
      uriConfig = UriConfig.createByDomain("https://gator.volces.com", null)
      // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集
      setAutoStart(false)
      // 全埋点开关，true开启，false关闭
      isAutoTrackEnabled = true
      // true:开启日志，参考4.3节设置logger，false:关闭日志
      isLogEnable = false
  }
  // 加密开关，true开启，false关闭
  appLogInst2.encryptAndCompress = true
  appLogInst2.init(context, config2)
  // 初始化一次即可
  // Applition 中初始化建议使用该方法
  appLogInst2.init(this, config2)
  // Activity 中初始化建议使用该方法
  appLogInst2.init(this, config2, activity)
          
  // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
  appLogInst1.start();
  appLogInst2.start();
  

3.1 延迟初始化 #

为确保合规，建议您在获得用户授权之后进行 SDK 的初始化，依据场景开启功能并获取个人信息。如您采用以上建议延迟初始化 SDK，为补偿延迟初始化对启动事件的数据影响，请修改初始化 init 方法：

/* 初始化SDK */
// ......其他配置不变
// 修改初始化init方法，增加第三个参数为当前Activity对象
AppLog.init(this, mConfig, XXXActivity.this);

为避免延迟数据获取对 SDK 服务的影响，建议在初始化后尽快开启埋点采集，我们为您提供自动开始采集开关。如果您想自主控制开启埋点采集的时机，可以关闭自动开始采集开关，不过由于开始初始化至用户授权之间的事件将无法采集到设备号，因此会影响广告推广效果归因等分析。

// Application 通过配置调整非自动开始采集
config.setAutoStart(false);
AppLog.init(this, config);


// 用户授权后调用如下方法
AppLog.start()；

3.2 Oaid 采集配置 #

6.16.10 后支持 360 Oaid 采集，如需采集，请在 App 的 AndroidManifest.xml 进行配置：

<queries>
    <!--    qiku 360 OAID 获取添加    -->
    <package android:name="com.qiku.id"/>
</queries>

3.3 自定义 Oaid 采集 #

如果集成了 MSA 等 OAID 采集 SDK，可以将 AppLog 内置的 Oaid 获取逻辑改为应用侧采集逻辑。

// 6.16.11 版本新增
/* 初始化SDK */
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 重点：确保 start 才开始用用户信息采集
config.setAutoStart(false);
// 重点：设置自定义 Oaid 自定义设置回调
config.setCustomOaidCallback(new DynamicValueCallback<String>() {
    @Override
    public String get() {
        // 自定义获取逻辑，如果未设置回调或回调返回 "" / null 走内置 Oaid 采集逻辑
        return getCustomOaid();
    }
});
// 省略其他 SDK 配置
// 初始化一次即可
// Applition 中初始化建议使用该方法
AppLog.init(this, config);
// Activity 中初始化建议使用该方法
AppLog.init(this, config, activity);
        
// 重点：由于设置了 setAutoStart false，需要手动调用 start 触发 SDK，请在拿到 oaid 后调用
// start 开始实际采集用户信息+上报：
AppLog.start()；

3.4 关闭 MAC 地址采集 #

以下为敏感字段采集的初始化基本配置，config 均指初始化时的InitConfig。
设备的 MAC 地址采集默认开启。如需关闭：

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

如需移除 MAC 地址采集的相关代码，可以在全埋点插件 Plugin 中配置：

• 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
  }
  

3.5 关闭设备 IMEI/MEID 采集 #

设备的 imei 地址采集默认开启。如需关闭：

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

如需移除 IMEI 和 MEID 采集的相关代码，可以在全埋点 Plugin 中配置：

• 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.6 关闭 OAID 采集 #

设备的 OAID 信息采集默认开启。如需关闭：

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

如需移除 OAID 采集的相关代码，可以在全埋点 Plugin 中配置：

• 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
  }
  

3.7 关闭 Android ID 采集 #

设备的 Android ID 采集默认开启，如需关闭：

// 开关关闭后相关代码不运行，属性不采集，关闭后会随机生成
config.setAndroidIdEnabled(false);

如需移除 Android ID 采集代码，可以在全埋点 Plugin 中配置：

• 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
  }
  

3.8 关闭 ICCID 采集 #

设备的 ICCID 采集默认开启，如需关闭：

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

ICCID 目前不支持通过插件移除采集代码。

3.9 关闭 SN（硬件序列号） 采集 #

设备的 SN 采集默认开启，如需关闭：

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

SN 目前不支持通过插件移除采集代码。

3.10 关闭 GAID 采集 #

设备的 GAID 采集默认方案：

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

如需关闭：

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

⚠️请注意，由于该开关国内外 SDK 包 6.15.0 版本之前都默认开启，可能会导致国内应用包内部的第三方集成了 Google Service 后也尝试获取 GAID，且 GAID 是耗时的，可能在部分机型存在 ANR 问题或者影响设备注册请求响应时间。

// 针对 Gaid 获取耗时 SDK 提供了采集超时时间控制，如果超过采集时间还未采集到直接返回空
// 默认时间 2s 超时，方法参数 ms
// 该方法 6.15.0 提供
config.setGaidTimeOutMilliSeconds(2000)

⚠️请注意，由于该开关国内外 SDK 包都默认开启，可能会导致国内应用包内部的第三方集成了 Google Service 后也尝试获取 GAID，且 GAID 是耗时的，可能在部分机型存在 ANR 问题或者影响设备注册请求响应时间。

3.11 关闭运营商信息采集 #

设备的运营商信息默认采集，如需关闭：

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

如需移除运营商信息采集代码，可以在全埋点Plugin中配置：

• 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
  }
  

3.12 移除剪切板访问代码 #

剪切版访问目前用于广告监测，默认关闭。

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

如需移除剪切板访问代码，可以在全埋点 Plugin 中配置：

• 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
  }
  

3.13 关闭 CPU 架构采集 #

设备的 CPU 架构采集默认开启，如需关闭：

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

3.14 关闭屏幕分辨率 / 屏幕密度采集 #

设备的屏幕分辨率 / 屏幕密度采集默认开启，如需关闭：

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

如需使用实时埋点检测或圈选事件，请配置 Scheme，否则可跳过此步骤。

4.1 获取URL Scheme #

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

4.2 添加URL Scheme #

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

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

以下为常用的初始化基本配置，config 均指初始化时的InitConfig。

5.1 全埋点设置开关 #

// 开启全埋点事件的上送
config.setAutoTrackEnabled(true); // true:开启全埋点，false:关闭全埋点

全埋点中的页面浏览事件，默认针对 Activity 页面。如需开启针对 Fragment 的 bav2b_page 事件采集，除如上开关外，还需额外开启 Fragment 采集开关。

// 开启Fragment全埋点事件采集
config.setAutoTrackFragmentEnabled(true);

5.2 开启圈选埋点 #

圈选埋点默认关闭。

// 开启圈选埋点功能，使用此功能需先开启全埋点
config.setPicker(new Picker(this, config));

// 如果想要对 App 内嵌 h5 打开圈选，请打开 js 注入开关：
config.setH5CollectEnable(true);
// 注：h5 圈选仅支持原生 WebView 与腾讯 X5 

5.3 查看日志打印 #

• 当前实例日志打印

  // 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭
  config.setLogEnable(true); // true:开启日志，false:关闭日志
  config.setLogger(new ILogger() {
      @Override
      public void log(String s, Throwable throwable) {
          Log.d("AppLog------->: ", "" + s);
      }
  });
  

• 多实例日志统一打印

  // 如需要打印所有实例的日志，可以参考如下配置：
  // 仅支持 6.12.0+ 版本
  LogProcessorHolder.addProcessor(
      new ILogProcessor() {
          @Override
          public void onLog(LogInfo log) {
              Log.d("AppLog------->: ", log.toLiteString());
          }
  });
  

5.4 加密设置开关 #

加密设置默认开启。您可在 debug 阶段关闭加密，以便于抓包联调。

// 加密设置开关，线上版本建议开启
AppLog.setEncryptAndCompress(true); // true:打开加密，false:关闭加密

5.5 设置 APP Language 和 APP Region #

// 修改语言和地区，设置 APP Language 和 APP Region
config.setLanguage(...); // 设置APP Language，例如zh-cn 
config.setRegion(...); // 设置APP Region，例如cn

5.6 打通内嵌 H5 页 #

如果您的应用同时集成 Web/JS SDK 以及 Android SDK，默认情况下，所有 H5 事件会通过 Web/JS SDK 上报，如果您希望 H5 事件由 Android SDK 接管上报，可以使用打通内嵌 H5 功能，此时 H5 页上产生的事件将通过 Android SDK 上报，而不在 Web/JS SDK 上报，这种接管上报场景下会复用 Android 端设置的user_unique_id和公共属性，但是也支持打通时 web 侧设置 / 更新端上的 uuid / 公共属性，请在打通时注意采用哪边数据，如果完全以端上为准可以去掉 web sdk 侧的 uuid（如需支持打通从 web 侧更新多口径，需使用新版本 SDK）/ 公共属性操作。

// 注：该功能仅支持原生 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 及之后版本正常采集）
})

5.6.1 打通内嵌 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);

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

一般情况下，H5 打通需要您参考 1.2 小节集成 plugin 插件，此时注入 Bridge 由 Plugin 插桩完成，但部分场景下，插桩可能不生效（插装失效的场景可能是混淆、被覆盖等等情况），您可以选择手动关闭 SDK 的自动注入 Bridge 能力，然后手动调用注入，此时可以在全埋点插件 Plugin 中增加配置autoInjectWebViewBridge = false，然后在需要打通的 WebView 加载H5之前手动注入 Bridge。

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

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

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

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

5.7 原生端采集 H5 全埋点 #

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

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

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

// 内嵌H5页面的全埋点事件
config.setH5CollectEnable(true); // true:开启h5全埋点事件，false:关闭h5全埋点事件

// 补充，该功能默认也通过插件方式注入，当插件失效或者想要自己手动注入时，
// 可以参考 4.6.2 小节，4.6、4.7 虽然功能独立但是都通过统一方法进行注入控制，
// 不过可以通过各自开关配置是否开启

5.8 全埋点事件采集 #

默认全埋点开关开启，如需关闭：

config.setAutoTrackEnabled(false);

开启全埋点后默认会采集页面事件和点击事件，如需定制全埋点采集，配置方法如下：

// 默认值：AutoTrackEventType.PAGE | AutoTrackEventType.CLICK
//
// AutoTrackEventType.ALL: 全埋点所有事件
// AutoTrackEventType.PAGE: 全埋点页面事件 默认开启
// AutoTrackEventType.CLICK: 全埋点点击事件 默认开启
// AutoTrackEventType.PAGE_LEAVE: 全埋点页面时长事件 默认关闭
// 本功能仅支持6.11.0及以上版本
config.setAutoTrackEventType(AutoTrackEventType.PAGE | AutoTrackEventType.CLICK | AutoTrackEventType.PAGE_LEAVE);

5.9 设置 GPS 坐标 #

默认不采集 GPS 坐标，如需采集，需要手动设置 GPS 坐标信息，示例：

// GeoCoordinateSystemConst 为坐标系静态类
// WGS84 地球坐标系
// GCJ02 火星坐标系
// BD09 百度坐标系
// BDCS 北斗坐标系
// 本功能仅支持6.10.1及以上版本
AppLog.setGPSLocation(18.00f, 18.00f, GeoCoordinateSystemConst.WGS84);

5.10 开启崩溃采集 #

默认不采集应用崩溃事件$crash，如需开启：

// 目前仅支持采集JAVA崩溃
// 本功能仅支持6.13.0及以上版本
config.setTrackCrashType(AppCrashType.JAVA);

5.11 开启 Fragment 页面事件采集 #

默认 Fragment 页面事件采集关闭，开启开关后每个 Fragment 的访问也会记录一次页面访问事件（$bav2b_page）。如需开启：

// 本功能仅支持6.13.0及以上版本
config.setAutoTrackFragmentEnabled(true);

5.12 是否区分鸿蒙设备 #

数据采集上报会区分是否是鸿蒙系统：

// 本功能仅支持6.14.3及以上版本
config.setHarmonyEnable(true);

6.1 如何正确获取 DID 等参数 #

由于参数获取可能存在一定延迟性，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.2 事件过滤以及自定义参数补齐 #

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

• 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;
      }
  });
  

6.3 请求自定义加密 #

私有化 V4.4.0 版本支持了国密 SM2 算法的请求加密，并且 SDK 提供了自定义加密接口，后续如果私有化版本支持了其他加密协议均可使用自定义加密接口进行请求加密实现。

• Java

  // sm2 加密
  Sm2Helper sm2Helper = new Sm2Helper(yourPublicKey);
  config.setEncryptor(new IEncryptor() {
      @Override
      public byte[] encrypt(byte[] data, int size) {
          // 将原数据转换为加密数据
          return sm2Helper.encrypt(data, size);
      }
      // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致
  }, sm2Helper.encryptorType());
  
  // 自定义加密
  // 可以通过自定义加密接口实现与私有化部署自定义协议加密模式
  config.setEncryptor(new IEncryptor() {
      @Override
      public byte[] encrypt(byte[] data, int size) {
          // 将原数据转换为加密数据
          return yourEncryptMethod(data, size);
      }
      // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致
  }, "yourEncryptType");
  

• Kotlin

  // sm2 加密
  val sm2Helper = Sm2Helper(yourPublicKey)
  config.setEncryptor({ data, size -> 
          // 将原数据转换为加密数据
          sm2Helper.encrypt(data, size)
      }, 
      // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致
      sm2Helper.encryptorType()
  )
  
  // 自定义加密
  // 可以通过自定义加密接口实现与私有化部署自定义协议加密模式
  config.setEncryptor({ data, size -> 
          // 将原数据转换为加密数据
          yourEncryptMethod(data, size)
      }, 
      // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致
      "yourEncryptType"
  )
  

7.1 云控能力 #

注意：本功能仅SaaS云原生版本或私有化V4.4.0以上版本，且SDK 6.15.0 以上版本支持；
DataFinder支持通过服务端下发 SDK 设置，包括上报时机、全埋点开关等，详细介绍文档请查阅：项目管理-SDK设置。

增长营销套件 Android 端 SDK 权限列表：

数据上报前提 #

数据上报前置条件为完成SDK初始化，上报前会检查SDK初始化的 config 中是否配置了setAutoStart(false) ：

• 如果没有配置过， init 之后就会定时上报数据。
• 如果配置过，会等待开发者调用 start 之后开始定时上报数据。

数据上报流程与逻辑 #

1. SDK 初始化：
   SDK初始化之后会检测当前进程，如果是主进程则开始创建定时上报任务，子进程不会处理。
2. 触发时机：
   • 启动定时发送任务，默认上报间隔为 1min，每隔 5s 检测一次是否触发下次上报，私有化支持云控配置缩短上报间隔。
   • 如果检测已经到了上报时间，就会触发上报，否则延迟 5s 下次检测。
3. 上报前检测：
   • 检测设备是否注册成功，因为前置上报需要设备注册返回的 did 与 ssid（事件需要正确绑定 ssid 所以针对产生时没有 ssid 的事件，会在上报前做 ssid 补充），如果已成功则继续。
   • 上报前还会检测是否满足频控限制，如果当前没有触发频控则继续走上报流程，如果触发了频控则按照频控判断当前是否能够上报。
   1. 频控的目的主要是为了在服务端不可用时限制端上上报请求频次，避免在服务端不可用时带来更多压力。
4. 数据打包与上报：
   • 首先先查询已存储至APP数据库中的数据进行打包，用于上报数据（上报数据单位为 pack，pack 是数据包，每个数据包最多包含 200 事件，将查询到事件整体打包成一个 pack 进行上报），来源分成两部分：
     • 上次失败的 pack
     • 本地事件聚合成的新 pack
   • 按照不同版本的查询策略查询到需要发送的 pack 后，针对每个 pack 单独上报。
     • 6.15.0 之后，每次最多查询 8 个 pack（可粗略理解每分钟最多上报 200 * 8 = 1600 条事件）。
     • 6.15.0 之前，每次最多查询 1 个 pack（可粗略理解每分钟最多上报 200 * 1 = 200 条事件）。
5. 数据上报后处理：
   每个 pack 上报后，都会做以下处理：
   • 上报成功，删除上报对应 pack，并对频控做升级处理。
   • 上报失败，将失败信息记录到对应 pack 中，等待下次重新发送，如果本次服务端返回的错误为 5xx 则进行频控降级处理。
6. 发送完查询到的 pack 后，本次发送结束，回到第 2 步，等待下次触发上报。