Android SDK集成开发指南

「A/B 测试」 在 Android 客户端的SDK 使用的为增长营销套件SDK ，主要的和A/B Test 相关接口有两个：

• 实验组分流接口

• 指标上报（事件埋点上报）接口

1.集成SDK

• 如果已经集成了RangerAppLog-lite/ RangerAppLog-all 可以跳过此部分；

• 如果没有，请参照下面：

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 引入插件(可选)

如需开启全埋点、webview 自动注入、隐私字段代码移除等功能，请执行1.2引入插件。否则可跳过此步骤。

插件依赖

Gradle 7.0 以下：

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

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

Gradle 7.0 及以上：

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

// project 级别的 build.gradle 中
buildscript {
    dependencies {
       classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.15.4'
    }
}

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

插件使用示例

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

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

  // 插装黑名单，包路径前缀
  blackList = []

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

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

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

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.15.4'

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

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

请注意，上述两个版本只需要二选一集成，否则会导致编译报错。

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

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

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

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

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

如需使用实时埋点检测或圈选功能，请引入scheme包，并且按照第3章节配置。 否则可跳过此步骤。
⚠️ 请务必确保在正式上线前移除scheme包，仅在debug期间使用，避免合规风险。

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

1.6 反作弊风控子库(可选)

如需使用广告监测功能，为使其反作弊识别准确度更高，请执行1.5节引入风控子库。否则可跳过此步骤。

// 在build.gradle文件的dependencies中添加
implementation 'com.volcengine:metasec_ml:4.3.4'
implementation 'com.bytedance.applog:RangersAppLog-All-metasec-cn:6.15.4'

1.7 Kotlin相关依赖(可选)

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

implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.61'

1.8 手动引入须知

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

AndroidSDK 下载	SDK版本	大小	MD5
Android_6.15.12_CN.zip 1.03MB	6.15.2	511KB	1b8b604b85e9135f2b200e6a4ad7211b

必选依赖：
 - if_encryptor-xxx.aar / encryptor-xxx.noasan.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 打通 / 黑名单过滤 / 移除部分隐私采集代码功能


集成方式一，项目中已包含所有 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-Log-xxx.aar')
implementation files('libs/plugin-aggregation-xxx.aar')
implementation files('libs/RangersAppLog-All/Lite-cn-xxx.aar')
// 剩余部分按需集成

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

2. 初始化SDK

说明
SDK会在初始化的时候就采集用户信息，请确保您采集用户信息之前已经获得用户授权。
合规建议操作如下：
用户授权后再进行SDK的初始化，取得用户授权前所有的信息都不会采集，预置事件也不会被采集。

2.1 获取appid

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

2.2 获取数据上送地址

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

2.3 初始化SDK

2.3.1 SaaS版本

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

public class TheApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        /* 初始化SDK开始 */
        // 第一个参数APPID: 参考2.1节获取
        // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空
        final InitConfig config = new InitConfig("{{APPID}}", "{{CHANNEL}}");
        // 设置数据上送地址
        config.setUriConfig(UriConstants.DEFAULT);
        config.setAbEnable(true); // 开启 AB 测试      
        config.setAutoTrackEnabled(true); // 全埋点开关，true开启，false关闭
        config.clearABCacheOnUserChange(true); // 默认true，切换用户清空AB版本信息
        config.setLogEnable(false); // true:开启日志，参考4.3节设置logger，false:关闭日志
        AppLog.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
        AppLog.init(this, config);
        /* 初始化SDK结束 */
    }
}

2.3.2 私有化版本

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

public class TheApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        /* 初始化SDK开始 */
        // 第一个参数APPID: 参考2.1节获取
        // 第二个参数CHANNEL: 填写渠道，请注意不能为空
        final InitConfig config = new InitConfig("{{APPID}}", "{{CHANNEL}}");
        // 设置私有化部署数据上送地址，参考2.2节获取，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
        config.setUriConfig(UriConfig.createByDomain("{{REPORT_URL}}", null));
        config.setAbEnable(true); // 开启 AB 测试      
        config.setAutoTrackEnabled(true); // 全埋点开关，true开启，false关闭
        config.clearABCacheOnUserChange(true); // 默认true，切换用户清空AB版本信息
        config.setLogEnable(false); // true:开启日志，参考4.3节设置logger，false:关闭日志
        AppLog.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
        AppLog.init(this, config);
        /* 初始化SDK结束 */
    }
}

2.3.3 SaaS云原生版本

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

public class TheApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        /* 初始化SDK开始 */
        // 第一个参数APPID: 参考2.1节获取
        // 第二个参数CHANNEL: 填写渠道，请注意不能为空
        final InitConfig config = new InitConfig("{{APPID}}", "{{CHANNEL}}");
        // 设置数据上送地址
        UriConfig uriConfig = UriConfig.createByDomain("https://gator.volces.com", null);
        uriConfig.setAbUri("https://tab.volces.com");
        config.setUriConfig(uriConfig);
        config.setAutoTrackEnabled(true); // 全埋点开关，true开启，false关闭
        config.setAbEnable(true); // 开启 AB 测试 
        config.setLogEnable(false); // true:开启日志，参考4.3节设置logger，false:关闭日志
        config.clearABCacheOnUserChange(true); // 默认true，切换用户清空AB版本信息
        AppLog.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
        AppLog.init(this, config);
        /* 初始化SDK结束 */
    }
}

2.4 多实例初始化(可选)

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

• 第三方SDK依赖 增长营销套件SDK 做SDK内部产生的埋点时；

• 同一个App或系统中，关联多个埋点应用(多个appid)，共用 增长营销套件SDK 时。

// @since 6.8.0，使用本节功能需先升级增长营销套件SDK到6.8.0及以上
public class TheApplication extends Application {
    
    @Override
    public void onCreate() {
        super.onCreate();
        /* 多实例初始化SDK开始 实例1*/
        final InitConfig config1 = new InitConfig("APPID1", "CHANNEL1");        
        // 创建实例
        IAppLogInstance appLogInst1 = AppLog.newInstance();       
        // 设置数据上送地址
        config1.setUriConfig(UriConstants.DEFAULT);        
       // 开启全埋点事件的上送
        config1.setAutoTrackEnabled(true); // 全埋点开关，true开启，false关闭
        config1.setLogEnable(true); // true:开启日志，参考4.3节设置logger，false:关闭日志
        appLogInst1.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
        appLogInst1.init(this, config1);
        
        //实例2
       final InitConfig config2 = new InitConfig("APPID2", "CHANNEL1");
       IAppLogInstance appLogInst2 = AppLog.newInstance();
       config2.setUriConfig(UriConstants.DEFAULT);
       config2.setAutoTrackEnabled(true);
       config2.setLogEnable(true); // true:开启日志，参考4.3节设置logger，false:关闭日志
       appLogInst2.setEncryptAndCompress(true); // 加密开关，true开启，false关闭
       appLogInst2.init(this, config2);
        /* 初始化SDK结束 */

      }
   }

3.延迟初始化与敏感信息采集

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
}

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
}

3.4 关闭OAID采集

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

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

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

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

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

3.5 关闭Android ID采集

注意
关闭 Android ID 会影响 did 卸载重装一致性，请谨慎关闭。
设备的Android ID采集默认开启，如需关闭：

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

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

// 本功能仅支持6.10.1及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = [ "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);

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

3.9 关闭运营商信息采集

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

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

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

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

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

4. 配置Scheme(可选)

如需使用实时埋点检测或圈选功能，请配置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", "{{URL_SCHEME}}".toLowerCase())

5. 初始化基本配置

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

5.1 全埋点采集开关

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

// 开启全埋点事件的上送
config.setAutoTrackEnabled(true); // true:开启全埋点，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);

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

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

5.2 开启圈选埋点

圈选埋点默认关闭。

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

5.3 AB功能开关

config.setAbEnable(true); // 开启 AB 测试

5.4 查看日志打印

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

5.5 切换用户清空AB信息开关

开关默认开启，当切换用户时，清空缓存里命中的AB信息；如果切换用户不想清空缓存可改为false。

config.clearABCacheOnUserChange(true); // 默认true，切换用户清空AB版本信息

5.6 加密设置开关

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

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

5.7 设置APP Language 和 APP Region

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

5.8 打通内嵌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.8.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.8.2 打通内嵌 H5 页的插件注入注意项

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

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

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

5.9 原生端采集H5全埋点

原生端内嵌webview页时，通过打开以下开关，可从原生端全埋点事件采集h5页全埋点事件。

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

5.10 是否区分鸿蒙设备

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

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

5.11 开启Fragment页面事件采集

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

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

6. 权限说明

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

7. 用户与用户属性

7.1 登录态变化调用

7.1.1 账户登录

如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。

// 设置您账号体系的ID, 并保证其唯一性
AppLog.setUserUniqueID("{{USER_UNIQUE_ID}}"); 
// 如果使用多实例，可以使用对应实例设置
IAppLogInstance other = Applog.newInstance();
other.setUserUniqueID("{{USER_UNIQUE_ID}}");

7.1.2 账户登出

在账户登出时调用。

// 登出时设置uuid为null
AppLog.setUserUniqueID(null); 
// 多实例同 6.1.1

请注意，不要误写成("null") 或 ("")，否则会影响数据和用户的绑定关系。

7.2 设置用户属性

7.2.1 profileSet

设置用户属性，存在则覆盖，不存在则创建。

// 示例：设置用户属性，属性名为key，属性值为value
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key", "value"); 
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.profileSet(paramsObj);

7.2.2 profileSetOnce

设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。

// 示例：设置用户属性，属性名为key_once，属性值为value_once
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key_once", "value_once");
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.profileSetOnce(paramsObj);

7.2.3 profileIncrement

设置数值类型的属性，可进行累加。

// 示例：设置用户属性，属性名为key，属性值为1
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key", 1);
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.profileIncrement(paramsObj);

7.2.4 profileAppend

设置List类型的用户属性，可持续向List内添加。

// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key", "value_append");
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.profileAppend(paramsObj);

7.2.5 profileUnset

删除用户的属性。

// 示例：删除用户属性，属性名为key
AppLog.profileUnset("key");

8.获取实验参数

通常在SDK 初始化后会向分流服务发送一个分流请求（request），在获取到分流服务的响应（response）后，客户端开发可以根据分流的结果参数完成代码分支。

• 请注意此步骤的前置条件：已经根据实验的需求方创建好了实验及相关的参数，具体见“创建实验”。

• 请注意每次调用getAbConfig时,会默认上报一条曝光事件 abtest_exposure

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 jsonObject) {
 
    }
 
    /**
     * server拉取AbConfig数据，和本地数据对比有变化的通知
     * 仅主进程会被调用
     * @param changed 是否和本地缓存有所不同
     * @param abConfig server返回新abConfig内容
     */
    @Override
    public void onRemoteAbConfigGet(boolean changed, @NonNull JSONObject jsonObject) {
        // 比如配置的ab实验参数名称是 "MyTest", 参数类型是 string，对照组参数值 "groupA", 实验组参数值 "groupB"// 通过applog接口获取实验分流结果// 第一个参数是实验名称，第二个参数是获取实验分流结果失败时的默认参数值，如默认为对照组参数值或null// 返回值是获取的ab实验分流结果，即实验参数值
        String group = AppLog.getAbConfig("MyTest", null);
        if ("groupA".equals(group)) {
          // 执行对照组逻辑
        } else if ("groupB".equals(group)) {
          // 执行实验组逻辑
        } else {
          // 其它
        }
    }
 
    /**
     *  Vid变化通知
     */
    @Override
    public void onAbVidsChange(@NonNull String vids, @NonNull String extVids) {
 
    }
});

如果想实时拉取实验分流结果，可以通过 pullABTestConfigs 方法手动触发实验配置更新 (10秒内多次调用只会触发一次请求)

AppLog.pullAbTestConfigs();//此功能需要6.7.0以上版本
// 执行该接口后，如果拉取到实验数据，会触发 IDataObserver.onRemoteAbConfigGet 回调。

9. 上报实验指标（用户行为事件）

9.1 上报代码埋点

用户行为日志采用事件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);

9.2 事件公共属性

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

9.2.1 设置公共属性

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

9.2.2 移除公共属性

// 示例：移除属性名为key_public的公共属性
AppLog.removeHeaderInfo("key_public");

10. 获取平台ID与通知

10.1 获取平台生成ID

// 请在初始化完成的3秒后开始获取，否则可能返回为空
String ssid = AppLog.getSsid(); // 获取SSID
String did = AppLog.getDid(); // 获取设备bddid

10.2 获取SDK版本号

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

10.3 切换账号设置数据发送方式

切换账号时，同时切换数据发送方式

AppLog.setPrivacyMode(true); //默认是false，设置后true，不采集不上报

10.4 常用回调介绍

SDK提供addDataObserver方法，用以获取各类通知，建议放在 Application 中。

public static void addDataObserver(IDataObserver listener)

设置iid、ssid、did、abconfig从本地加载和server加载成功的回调。
IDataObserver接口方法的参数说明如下：

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

1、当我需要创建客户端实验，但是想要关注服务端事件相关的指标，需要怎么上报服务端事件才能正常查看实验报告?

• 获取全部的实验 id, onRemoteAbConfigGet 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 jsonObject) {
 
    }
 
    /**
     * server拉取AbConfig数据，和本地数据对比有变化的通知
     * 仅主进程会被调用
     * @param changed 是否和本地缓存有所不同
     * @param abConfig server返回新abConfig内容
     */
    @Override
    public void onRemoteAbConfigGet(boolean changed, @NonNull JSONObject jsonObject) {
        String group = AppLog.getAllAbTestConfigs();
        Log.i("---测试---返回全部进组信息",""+ jsonObject.toString());
    }
 
    /**
     *  Vid变化通知
     */
    @Override
    public void onAbVidsChange(@NonNull String vids, @NonNull String extVids) {
 
    }
});

• 传给服务端

• 调用http接口上报服务端事件时，需要在事件里带上客户端实验信息(ab_sdk_version)，具体事件上报格式参考HTTP API 增长分析-火山引擎