Android SDK 集成

1.1 引入仓库

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

// 在 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 插件仓库

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

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

1.2.2 插件依赖

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

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

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

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

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

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

1.2.3 插件使用示例

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

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
}

// 新版插件使用调整为 appLog 
appLog {
    // 自动注入webview的对接bridge
    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.16.3'
  

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

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

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

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

// 请使用 debug 依赖，建议仅在 debug 下做调试
debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:3.3.4'

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

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

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

1.5 Kotlin 相关依赖(可选)

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

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

1.6 手动引入须知

推荐您远程引入 SDK。如特殊情况需要手动引入，请补充阅读本小节。

必选依赖：
 - if_encryptor-xxx.aar / 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')
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

在开始集成前，首先需要在集团中拥有一个应用，详情请参见如何创建应用。
「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid。

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。
如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化 SDK

2.3.1 SaaS 版本

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

/* 初始化SDK */
// 第一个参数APPID: 参考2.1节获取
// 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址
config.setUriConfig(UriConstants.DEFAULT);
// 是否 init 后自动 start 可改为 false，并请在用户授权后调用 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()；

/* 初始化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。

/* 初始化SDK */
// 第一个参数APPID: 参考2.1节获取
// 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置私有化部署数据上送地址，参考2.2节获取，例如 https://yourdomain.com，注意域名后不要加“/”
config.setUriConfig(UriConfig.createByDomain("yourREPORT_URL", null));
// 是否 init 后自动 start 可改为 false，并请在用户授权后调用 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()；

/* 初始化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.3.3 SaaS 云原生

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

/* 初始化SDK */
// 第一个参数APPID: 参考2.1节获取
// 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址
config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null));    
// 是否 init 后自动 start 可改为 false，并请在用户授权后调用 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()；

/* 初始化SDK */
// 第一个参数APPID: 参考2.1节获取
// 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
val config = InitConfig("yourAPPID", "yourCHANNEL").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关闭
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 时；

/* 多实例初始化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();

/* 初始化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 的初始化并开始采集信息，请确保您采集用户信息前已得到用户的授权。如您需要延迟初始化 SDK，为补偿延迟对启动事件的数据影响，请修改初始化init方法：

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

如您依然想尽早初始化，但在用户授权后开启埋点采集，可以关闭自动开始采集，不过由于开始初始化至用户授权之间的事件将无法采集到设备号，因此会影响广告推广效果归因等分析。

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


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

3.2 关闭 MAC 地址采集

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

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

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

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

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

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

3.3 关闭设备 IMEI/MEID 采集

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

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

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

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

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

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

3.4 关闭 OAID 采集

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

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

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

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

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

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

3.5 关闭 Android ID 采集

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

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

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

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

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

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

3.6 关闭 ICCID 采集

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

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

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

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

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

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

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

3.8 关闭 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.9 关闭运营商信息采集

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

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

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

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

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

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

3.10 移除剪切板访问代码

剪切版访问目前用于广告监测默认关闭，如需打开可以参考：开启剪切板
如需移除剪切板访问代码，可以在全埋点 Plugin 中配置：

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

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

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

如需使用实时埋点检测或圈选事件，请配置 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和公共属性。

// 注：该功能仅支持原生 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/JS SDK 屏蔽了 H5 的全埋点功能，
// 所以 Web/JS SDK 的全埋点设置开关就失效了，
// 想要依然保持 H5 全埋点功能，请查看 4.7 小节
window.collectEvent('init', {
    // 全埋点设置开关 
    autotrack: 失效
})

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。

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

// 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.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 事件过滤以及自定义参数补齐

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

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) {
        // 过滤 xx 事件
        if ("xx".equals(eventName)) {
            return EventPolicy.DENY;
        }
        // 添加自定义属性
        try {
            properties.put("eventHandlerProps", "12345");
        } catch (JSONException ignored) {

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

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

    // 针对单事件做事件过滤 或 自定义参数额外处理
    @Override
    public EventPolicy onReceive(
            int eventType,
            @NonNull String eventName,
            @NonNull JSONObject properties) {
        // 过滤 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 提供了自定义加密接口，后续如果私有化版本支持了其他加密协议均可使用自定义加密接口进行请求加密实现。

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

// 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 私有化云控能力

注意：本功能仅限私有化 V4.4.0 以上版本、SDK 6.15.0 以上版本支持
可以通过私有化服务端下发 SDK 设置，详细介绍文档请查阅：SDK设置

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