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

Android SDK 集成

最近更新时间2023.11.30 14:32:26

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

1. 集成增长营销套件SDK

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/'
            }
        }
    }
    

    说明

    目前暂不支持 SDK 兼容 Gradle 8.0,将在后续版本中增加此功能。

1.2 引入插件(可选)

说明

如需开启全埋点、webview 自动注入、隐私字段代码移除等功能,请执行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/'
            }
            // 其他仓库
        }
        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'
    }
    

1.2.2 插件使用示例

在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
  // 示例:trackBlackList = ['MAC_ADDRESS', 'IMEI_MEID', 'OPERATOR']
  trackBlackList = []
  
  // 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.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。详细接入文档请查阅:Android埋点开发工具

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

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

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

注意

请务必确保在正式上线前移除scheme包,仅在debug期间使用,避免合规风险。

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

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

如需使用广告监测功能,为使其反作弊识别准确度更高,请执行1.6节引入风控子库,否则可跳过此步骤。
特别说明,如开发者集成了设备安全SDK相关服务,我们可能会按照《设备安全SDK隐私政策》有关声明采集、处理您的数据。

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

1.7 Kotlin相关依赖(可选)

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

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

1.8 手动引入须知

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

Android SDK下载SDK版本大小MD5
增长营销套件SDK下载6.16.2518KB3e8e15c5196dc5b769d2d4b9b6f4e3b6
必选依赖:
 - 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. 初始化增长营销套件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("yourAPPID", "yourCHANNEL");
        // 设置数据上送地址
        config.setUriConfig(UriConstants.DEFAULT);
				// 是否 init 后自动 start 可改为 false,并请在用户授权后调用 start 开启采集
				config.setAutoStart(false);
        config.setAutoTrackEnabled(true); // 全埋点开关,true开启,false关闭
        config.setLogEnable(false); // true:开启日志,参考4.3节设置logger,false:关闭日志
        AppLog.setEncryptAndCompress(true); // 加密开关,true开启,false关闭
        AppLog.init(this, config);
        
				// 请在用户授权后调用如下方法:
				AppLog.start();
    }
}

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("yourAPPID", "yourCHANNEL");
        // 设置私有化部署数据上送地址,参考2.2节获取,例如 https://yourdomain.com,注意域名后不要加“/”
        config.setUriConfig(UriConfig.createByDomain("yourREPORT_URL", null));
        // 是否 init 后自动 start 可改为 false,并请在用户授权后调用 start 开启采集
        config.setAutoStart(false);
        config.setAutoTrackEnabled(true); // 全埋点开关,true开启,false关闭
        config.setLogEnable(false); // true:开启日志,参考4.3节设置logger,false:关闭日志
        AppLog.setEncryptAndCompress(true); // 加密开关,true开启,false关闭
        AppLog.init(this, config);
        
				// 请在用户授权后调用如下方法:
				AppLog.start();
    }
}

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("yourAPPID", "yourCHANNEL");
        // 设置数据上送地址
        config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null));
        // 是否 init 后自动 start 可改为 false,并请在用户授权后调用 start 开启采集
        config.setAutoStart(false);
        config.setAutoTrackEnabled(true); // 全埋点开关,true开启,false关闭
        config.setLogEnable(false); // true:开启日志,参考4.3节设置logger,false:关闭日志
        AppLog.setEncryptAndCompress(true); // 加密开关,true开启,false关闭
        AppLog.init(this, config);
                
				// 请在用户授权后调用如下方法:
				AppLog.start();
    }
}

2.4 多实例初始化(可选)

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

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

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

public class TheApplication extends Application {
		@Override
    public void onCreate() {
				super.onCreate();
				/* 多实例初始化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关闭
				appLogInst1.init(this, config1);
        
				//实例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关闭
				appLogInst2.init(this, config2);

				// 用户授权后调用如下方法
				appLogInst1.start();
				appLogInst2.start();
		}
}

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 是重要设备追踪信息,若关闭 OAID 会影响 Tracer 归因,使用 Tracer 请谨慎考虑。

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

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

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

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

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

3.5 关闭Android ID采集

注意

关闭 Android ID 会影响 device_id 生成逻辑,导致 device_id 卸载重装不一致,请谨慎关闭。

后续文档中会简称 device_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", "yourURL_SCHEME".toLowerCase())

5. 初始化基本配置

以下为常用的初始化基本配置,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/JS SDK 与 Android SDK 同时集成并彼此配合,且当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能,因为此时上报都由 Android SDK 接管,如果还想采集 H5 全埋点,需要查看 5.7 小节:原生端采集 H5 全埋点 。 Web/JS SDK 集成请参考《Web/JS SDK 集成》 以及 3.4 小节。

// 注:该功能仅支持原生 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
  // 省略插件的其他使用
}

// 本功能仅支持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 页开启全埋点功能。

注意

  • 可以独立使用该功能,无需集成 Web/JS SDK。
  • 该功能 6.14.4 版本后提供,且目前的 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.常用回调介绍

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

7.其他功能介绍

7.1 私有化云控能力

注意:本功能仅限私有化V4.4.0以上版本、SDK6.15.0以上版本支持

可以通过私有化服务端下发 SDK 设置,详细介绍文档请查阅:SDK设置

8. 权限说明

增长营销套件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标识设备