You need to enable JavaScript to run this app.
导航

Android SDK集成开发指南

最近更新时间2023.12.21 17:51:29

首次发布时间2021.02.23 10:41:56

一. 概述

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

  • 实验组分流接口
  • 指标上报(事件埋点上报)接口

二. 集成SDK

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.16.2'
    }
}

// 在 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.16.2'
    }
}

// 在 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.16.2'

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

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

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

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

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

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

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

1.7 Kotlin相关依赖(可选)

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

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

1.8 手动引入须知

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

Android SDK下载

SDK版本

大小

MD5

增长营销套件SDK下载

6.16.2

517KB

12424a07a8700948a44b105523a362b6

必选依赖:
 - 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);
        uri.setAbUri("https://tab.volces.com" + UriConfig.PATH\_AB);
        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);

注意

⚠️请注意,由于该开关国内外 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
}

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和公共属性。

注意

打通功能需要 Web/JS SDK 与 Android SDK 同时集成并彼此配合,且当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能,因为此时上报都由 Android SDK 接管,如果还想采集 H5 全埋点,需要查看 5.9 小节:原生端采集 H5 全埋点 。 Web/JS SDK 集成请参考《Web/JS SDK 集成》 以及 3.6 小节。

// 注:该功能仅支持原生 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页内集成js sdk,且与js sdk全埋点功能独立无关联。

// 内嵌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权限列表:

权限

说明

使用场景和目的

android.permission.READ_PHONE_STATE

读取IMEI等设备信息作为设备标识

设备注册:初始化读取,生成设备唯一标识,计算设备数

android.permission.ACCESS_WIFI_STATE

获取网络状态(wifi)

设备注册和埋点数据采集:采集设备网络(wifi)信息

android.permission.ACCESS_NETWORK_STATE

获取网络状态

设备注册和埋点数据采集:采集设备网络信息

android.permission.INTERNET

发送网络请求

注册、上报埋点、归因、激活等:上报埋点数据到远程服务器

com.asus.msa.SupplementaryDID.ACCESS

读取oaid

设备注册和深度链接:跨APP标识设备

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

图片