# 操作前须知 * SDK版本：当前SDK版本在不断迭代发布中，您可前往[Git开源页面](https://github.com/volcengine/datarangers-sdk-packages/tree/main)查看各端的SDK版本情况，推荐使用最新版本SDK。本文中的代码示例以一个版本号作为示例，您实际使用时，需根据使用的实际SDK版本修改其中的版本号。 * 下载SDK包：集成SDK时，如果您需要手动引入SDK，需前往[Git开源页面](https://github.com/volcengine/datarangers-sdk-packages/tree/main)下载对应版本的SDK包。 * 使用Android SDK时，您可先了解通用的数据上报策略（[数据上报策略](/docs/84129/1261814#1e80ed67)）、已支持的预置事件（[APP预置事件及属性](/docs/84129/1261724)）和Android端的上报流程（[9. 参考：数据上报流程与触发时机](/docs/84129/1261741#d366c09b)）。 # 1. 集成增长营销套件 SDK ## 1.1 引入仓库 * Gradle 7.0以下 ```Groovy // 在 project 级别的 build.gradle 中添加 maven 仓库 // 在 allprojects 的 repositories 中添加 maven 仓库 allprojects { repositories { maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } // 其他仓库 } } ``` * Gradle 7.0及以上 ```Groovy // 在 project 级别的 setting.gradle 中添加 maven 仓库 dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } // 其他仓库 } } ``` ## 1.2 引入插件(可选) :::tip 如需开启全埋点、webview 自动注入、隐私字段代码移除等功能，请执行 1.2 引入插件。否则可跳过此步骤。 ::: ### 1.2.1 插件仓库 * Gradle 7.0以下 ```Groovy // 在 project 级别的 build.gradle 的 buildscript 的 repositories 中添加 maven 仓库、引入 SDK plugin buildscript { repositories { maven{ url 'https://artifact.bytedance.com/repository/Volcengine/' } // 省略其他 } } ``` * Gradle 7.0及以上 ```Groovy // setting.gradle 中 pluginManagement { repositories { maven{ url 'https://artifact.bytedance.com/repository/Volcengine/' } // 省略其他 } } ``` ### 1.2.2 插件依赖 * Gradle 7.0以下 ```Groovy // 在project 级别的 build.gradle 的 buildscript的repositories中添加maven仓库、引入SDK plugin buildscript { // 省略其他 dependencies { classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.16.11' } } // 在 app module 级别的 build.gradle // 默认放到插件列表最后一个声明，如遇到冲突， // 可以将其调整到 application / kotlin 等官方插件后的第一个 apply plugin: 'com.bytedance.std.tracker' ``` * Gradle 7.0及以上~8.0以下 ```Groovy // project 级别的 build.gradle 中 buildscript { // 省略其他 dependencies { classpath 'com.bytedance.applog:RangersAppLog-All-plugin:6.16.11' } } // 在 app module 级别的 build.gradle // 默认放到插件列表最后一个声明，如遇到冲突， // 可以将其调整到 application / kotlin 等官方插件后的第一个 plugins { // 省略其他插件 id 'com.bytedance.std.tracker' } ``` * Gradle 8.0 及以上 ```Groovy // project 级别的 build.gradle 中 buildscript { dependencies { // agp8 版本使用新版本插件 classpath 'com.bytedance.applog:RangersAppLog-All-plugin-agp8:6.16.11' } } // 在 app module 级别的 build.gradle // 默认放到插件列表最后一个声明，如遇到冲突， // 可以将其调整到 application / kotlin 等官方插件后的第一个 plugins { // 省略其他插件 id 'com.bytedance.std.tracker' } ``` ### 1.2.3 插件使用示例在 app module 级别的 build.gradle文件中应用 plugin。 * Gradle 8.0以下 ```Groovy teaExtension { // 自动注入webview的对接bridge autoInjectWebViewBridge = true // 插装黑名单，包路径前缀，针对某些不希望进行插桩的包进行配置 // 需要将包名中的 . 替换成 /，可配置多个，通过 , 分割 // 示例：blackList = ['dji/upgrade/internal','org/bouncycastle/jcajce'] blackList = [] // 埋点黑名单配置 // 仅支持以下配置： // 'MAC_ADDRESS'： mac地址 // 'IMEI_MEID'： imei和meid // 'OAID'： oaid // 'ANDROIDID': android id // 'OPERATOR': carrier、mcc_mnc // 'CLIPBOARD':剪切板相关代码 // 示例：trackBlackList = ['MAC_ADDRESS', 'IMEI_MEID', 'OPERATOR'] trackBlackList = [] // 6.14.3 新功能 // 关闭接口/类自动跟踪功能 // 使用场景举例：当您使用 lite 包时，但又需要 trackBlackList 来移除部分采集代码时，可以使用该功能 disableAutoTrack = false } ``` * Gradle 8.0及以上 ```Groovy // 新版插件使用调整为 appLog appLog { // 自动注入webview的对接bridge // agp8 的打通功能需要使用 6.16.7 及以上版本 autoInjectWebViewBridge = true // 插装黑名单，包路径前缀，针对某些不希望进行插桩的包进行配置，对标老版插件 blackList // 示例：ignoredInstrumentationPaths = ['dji.upgrade.internal','org.bouncycastle.jcajce'] // 写法从 ['dji/upgrade/internal','org/bouncycastle/jcajce'] 调整为 ['dji.upgrade.internal','org.bouncycastle.jcajce'] ignoredInstrumentationPaths = [] // 埋点黑名单配置，对标老版插件 trackBlackList // 仅支持以下配置： // 'MAC_ADDRESS'： mac地址 // 'IMEI_MEID'： imei和meid // 'OAID'： oaid // 'ANDROIDID': android id // 'OPERATOR': carrier、mcc_mnc // 'CLIPBOARD':剪切板相关代码 // 示例：sensitiveFieldsBlocklist = ['MAC_ADDRESS', 'IMEI_MEID', 'OPERATOR'] sensitiveFieldsBlocklist = [] // 6.14.3 新功能 // 关闭接口/类自动跟踪功能 // 使用场景举例：当您使用 lite 包时，但又需要 trackBlackList 来移除部分采集代码时，可以使用该功能 disableAutoTrack = false } ``` ## 1.3 引入 SDK 在 app module 级别的 build.gradle 文件中，在 dependencies 里引入 SDK。增长营销套件提供两个版本的 SDK，请根据业务需要择一引用即可。 * 如您需要使用完整的 SDK 功能，请集成All版本： ```groovy // 在 build.gradle 文件的 dependencies 中引入 SDK，集成 All 版本，推荐此版本 implementation 'com.bytedance.applog:RangersAppLog-All-cn:6.16.11' ``` * 如您不需要全埋点采集、圈选、web 打通等功能，仅需要自定义埋点，可集成 Lite 版本： ```groovy // 在 build.gradle 文件的 dependencies 中引入SDK，集成Lite版本 implementation 'com.bytedance.applog:RangersAppLog-Lite-cn:6.16.11' ``` :::warning 上述两个版本只需要二选一集成，否则会导致编译报错。 ::: ## 1.4 引入调试工具 DevTools 组件(可选) > 本小节功能在 6.12.0+ 后开始支持。 `DevTools`是 Debug 环境下辅助开发者或测试人员进行应用内埋点验证和 SDK 接入问题排查的组件。在 app module 级别的 build.gradle 文件中，在 dependencies 里引入`DevTools`。详细接入文档请查阅：[Android埋点开发工具](https://www.volcengine.com/docs/76880/1033614)。 ```java // 建议仅在 debug 或者测试包下做调试 // debug 或测试包中依赖 DevTools 组件 debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:3.4.7' ``` ## 1.5 实时埋点检测和圈选功能(可选) 如需[实时埋点检测](/docs/84129/1261787)或[圈选事件](/docs/84129/1261666)，请执行 1.5 节引入 scheme 包，否则可跳过此步骤。 :::warning 请务必确保在正式上线前移除 scheme 包，仅在 debug 期间使用，避免合规风险。 ::: ```groovy // 在 build.gradle 文件的 dependencies 中添加 implementation 'com.bytedance.applog:RangersAppLog-All-scheme:6.16.11' ``` ## 1.6 Kotlin 相关依赖(可选) 如您使用 kotlin 语言编写项目，请执行 1.7 节确认 kotlin 依赖的引入，否则可跳过此步骤。 ```groovy // 示例版本 implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.61' ``` ## 1.7 手动引入须知推荐您远程引入 SDK。如特殊情况需要手动引入，请补充阅读本小节。请前往[Android SDK包下载页面](https://github.com/volcengine/datarangers-sdk-packages/tree/main/Android)获取对应版本的SDK包。 :::tip Android离线包名称为*`All-cn-Android_版本号`*`.zip`格式。例如：`All-cn_Android_6.16.6.zip`，其中6.16.6为SDK版本号。 ::: ```Plain 必选依赖： - 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 :::tip 建议您在用户同意您App中的隐私政策后，再进行 SDK 初始化；用户同意隐私政策之前，应避免动态申请涉及用户个人信息的敏感设备权限，应避免私自采集和上报个人信息。当您的 App 未向用户提供服务时，请勿请求 SDK 的相关服务。 ::: ## 2.1 获取 appid 在开始集成前，首先需要在集团中拥有一个应用，进行SDK集成前，您需要获取对应应用的appid信息。 * SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见[项目管理](/docs/84129/1261713)。 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d05754a0d1dd4807a36b938876cdd65b~tplv-goo7wpa0wc-image.image =3724x) * SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见[应用列表](/docs/84129/1261706)。 ![Image](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_609acc9329f00e76f12e901fbc869e68.png =753x) ## 2.2 获取数据上送地址私有化部署版本需要获取数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。 ## 2.3 初始化 SDK ### 2.3.1 SaaS-云原生如您使用 SaaS-云原生部署版本，请参照如下代码初始化 SDK。 * Java ```Java /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL"); // 设置数据上送地址 config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null)); // 确保 start 才开始用用户信息采集 config.setAutoStart(false); // 全埋点开关，true开启，false关闭 config.setAutoTrackEnabled(true); // true:开启日志，参考4.3节设置logger，false:关闭日志 config.setLogEnable(false); // 加密开关，true开启，false关闭 AppLog.setEncryptAndCompress(true); // 初始化一次即可 // Applition 中初始化建议使用该方法 AppLog.init(this, config); // Activity 中初始化建议使用该方法 AppLog.init(this, config, activity); // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start()； ``` * Kotlin ```Kotlin /* 初始化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.3.2 SaaS-非云原生如您使用 SaaS-非云原生部署版本，请参照如下代码初始化 SDK。 * Java ```Java /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL"); // 设置数据上送地址 config.setUriConfig(UriConstants.DEFAULT); // 确保 start 才开始用用户信息采集 config.setAutoStart(false); // 全埋点开关，true开启，false关闭 config.setAutoTrackEnabled(true); // true:开启日志，参考4.3节设置logger，false:关闭日志 config.setLogEnable(false); // 加密开关，true开启，false关闭 AppLog.setEncryptAndCompress(true); // 初始化一次即可 // Applition 中初始化建议使用该方法 AppLog.init(this, config); // Activity 中初始化建议使用该方法 AppLog.init(this, config, activity); // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start()； ``` * Kotlin ```Kotlin /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 val config = InitConfig("yourAPPID", "yourCHANNEL").apply { // 设置数据上送地址 setUriConfig(UriConstants.DEFAULT) // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 setAutoStart(false) // 全埋点开关，true开启，false关闭 isAutoTrackEnabled = true // true:开启日志，参考4.3节设置logger，false:关闭日志 isLogEnable = false } // 加密开关，true开启，false关闭 AppLog.setEncryptAndCompress(true) // 初始化一次即可 // 在 Applition 中初始化建议使用该方法 AppLog.init(this, config) // 在 Activity 中初始化建议使用该方法 AppLog.init(this, config, activity) // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start() ``` ### 2.3.2 私有化版本如您使用私有化部署版本，请参照如下代码初始化 SDK。 * Java ```Java /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL"); // 设置私有化部署数据上送地址，参考2.2节获取，例如 https://yourdomain.com，注意域名后不要加“/” config.setUriConfig(UriConfig.createByDomain("yourREPORT_URL", null)); // 确保 start 才开始用用户信息采集 config.setAutoStart(false); // 全埋点开关，true开启，false关闭 config.setAutoTrackEnabled(true); // true:开启日志，参考4.3节设置logger，false:关闭日志 config.setLogEnable(false); // 加密开关，true开启，false关闭 AppLog.setEncryptAndCompress(true); // 初始化一次即可 // Applition 中初始化建议使用该方法 AppLog.init(this, config); // Activity 中初始化建议使用该方法 AppLog.init(this, config, activity); // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start()； ``` * Kotlin ```Kotlin /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 val config = InitConfig("yourAPPID", "yourCHANNEL").apply { // 设置私有化部署数据上送地址，参考2.2节获取，例如 https://yourdomain.com，注意域名后不要加“/” uriConfig = UriConfig.createByDomain("yourREPORT_URL", null) // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 setAutoStart(false) // 全埋点开关，true开启，false关闭 isAutoTrackEnabled = true // true:开启日志，参考4.3节设置logger，false:关闭日志 isLogEnable = false } // 加密开关，true开启，false关闭 AppLog.setEncryptAndCompress(true) // 初始化一次即可 // 在 Applition 中初始化建议使用该方法 AppLog.init(this, config) // 在 Activity 中初始化建议使用该方法 AppLog.init(this, config, activity) // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start() ``` ## 2.4 多实例初始化(可选) 多实例初始化，指 SDK 支持在同包名的 App 中向多个应用(多个 appid)开启埋点，且埋点数据相互隔离，每一个 appid 对应一个单独的实例。使用场景例如： * 第三方 SDK 依赖**增长营销套件 SDK** 做 SDK 内部产生的埋点时； * 同一个 App 或系统中，关联多个埋点应用(多个 appid)，共用**增长营销套件 SDK** 时；示例代码如下。 * Java ```Java /* 多实例初始化SDK 实例1*/ final InitConfig config1 = new InitConfig("yourAPPID1", "yourCHANNEL1"); // 创建实例 IAppLogInstance appLogInst1 = AppLog.newInstance(); // 设置数据上送地址 config1.setUriConfig(UriConstants.DEFAULT); // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 config1.setAutoStart(false); // 开启全埋点事件的上送 config1.setAutoTrackEnabled(true); // 全埋点开关，true开启，false关闭 config1.setLogEnable(true); // true:开启日志，参考4.3节设置logger，false:关闭日志 appLogInst1.setEncryptAndCompress(true); // 加密开关，true开启，false关闭 // 初始化一次即可 // Applition 中初始化建议使用该方法 appLogInst1.init(this, config1); // Activity 中初始化建议使用该方法 appLogInst1.init(this, config1, activity); //实例2 final InitConfig config2 = new InitConfig("yourAPPID2", "yourCHANNEL2"); IAppLogInstance appLogInst2 = AppLog.newInstance(); config2.setUriConfig(UriConstants.DEFAULT); // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 config2.setAutoStart(false); config2.setAutoTrackEnabled(true); config2.setLogEnable(true); // true:开启日志，参考4.3节设置logger，false:关闭日志 appLogInst2.setEncryptAndCompress(true); // 加密开关，true开启，false关闭 // 初始化一次即可 // Applition 中初始化建议使用该方法 appLogInst2.init(this, config2); // Activity 中初始化建议使用该方法 appLogInst2.init(this, config2, activity); // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： appLogInst1.start(); appLogInst2.start(); ``` * Kotlin ```Kotlin /* 初始化SDK */ // 第一个参数APPID: 参考2.1节获取 // 第二个参数CHANNEL: 填写渠道信息，请注意不能为空 val appLogInst1 = AppLog.newInstance() val config1 = InitConfig("yourAPPID1", "yourCHANNEL1").apply { // 设置数据上送地址 uriConfig = UriConfig.createByDomain("https://gator.volces.com", null) // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 setAutoStart(false) // 全埋点开关，true开启，false关闭 isAutoTrackEnabled = true // true:开启日志，参考4.3节设置logger，false:关闭日志 isLogEnable = false } // 加密开关，true开启，false关闭 appLogInst1.encryptAndCompress = true // 初始化一次即可 // Applition 中初始化建议使用该方法 appLogInst1.init(this, config1) // Activity 中初始化建议使用该方法 appLogInst1.init(this, config1, activity) val appLogInst2 = AppLog.newInstance() val config2 = InitConfig("yourAPPID2", "yourCHANNEL2").apply { // 设置数据上送地址 uriConfig = UriConfig.createByDomain("https://gator.volces.com", null) // 是否 init 后自动 start 可改为 false，并请在用户授权后调用 start 开启采集 setAutoStart(false) // 全埋点开关，true开启，false关闭 isAutoTrackEnabled = true // true:开启日志，参考4.3节设置logger，false:关闭日志 isLogEnable = false } // 加密开关，true开启，false关闭 appLogInst2.encryptAndCompress = true appLogInst2.init(context, config2) // 初始化一次即可 // Applition 中初始化建议使用该方法 appLogInst2.init(this, config2) // Activity 中初始化建议使用该方法 appLogInst2.init(this, config2, activity) // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： appLogInst1.start(); appLogInst2.start(); ``` # 3. 延迟初始化与敏感信息采集 :::tip SaaS-云原生和私有化4.4.0版本以上也支持在DataFinder控制台关闭敏感字段采集，您可以在项目管理>SDK设置中关闭敏感字段采集，详情请参见[项目管理-SDK设置](/docs/84129/1261714)。 ::: ## 3.1 延迟初始化为确保合规，建议您在获得用户授权之后进行 SDK 的初始化，依据场景开启功能并获取个人信息。如您采用以上建议延迟初始化 SDK，为补偿延迟初始化对启动事件的数据影响，请修改初始化 init 方法： ```java /* 初始化SDK */ // ......其他配置不变 // 修改初始化init方法，增加第三个参数为当前Activity对象 AppLog.init(this, mConfig, XXXActivity.this); ``` 为避免延迟数据获取对 SDK 服务的影响，建议在初始化后尽快开启埋点采集，我们为您提供自动开始采集开关。如果您想自主控制开启埋点采集的时机，可以关闭自动开始采集开关，不过由于开始初始化至用户授权之间的事件将无法采集到设备号，因此会影响广告推广效果归因等分析。 ```Java // Application 通过配置调整非自动开始采集 config.setAutoStart(false); AppLog.init(this, config); // 用户授权后调用如下方法 AppLog.start()； ``` ## 3.2 Oaid 采集配置 > 6.16.10 后支持 360 Oaid 采集，如需采集，请在 App 的 AndroidManifest.xml 进行配置： ```Plain Text ``` ## 3.3 自定义 Oaid 采集 > 如果集成了 MSA 等 OAID 采集 SDK，可以将 AppLog 内置的 Oaid 获取逻辑改为应用侧采集逻辑。 ```Plain Text // 6.16.11 版本新增 /* 初始化SDK */ final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL"); // 重点：确保 start 才开始用用户信息采集 config.setAutoStart(false); // 重点：设置自定义 Oaid 自定义设置回调 config.setCustomOaidCallback(new DynamicValueCallback() { @Override public String get() { // 自定义获取逻辑，如果未设置回调或回调返回 "" / null 走内置 Oaid 采集逻辑 return getCustomOaid(); } }); // 省略其他 SDK 配置 // 初始化一次即可 // Applition 中初始化建议使用该方法 AppLog.init(this, config); // Activity 中初始化建议使用该方法 AppLog.init(this, config, activity); // 重点：由于设置了 setAutoStart false，需要手动调用 start 触发 SDK，请在拿到 oaid 后调用 // start 开始实际采集用户信息+上报： AppLog.start()； ``` ## 3.3 关闭 MAC 地址采集以下为敏感字段采集的初始化基本配置，`config` 均指初始化时的`InitConfig`。设备的 MAC 地址采集默认开启。如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 MAC config.setMacEnable(false); ``` 如需移除 MAC 地址采集的相关代码，可以在全埋点插件 Plugin 中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.9.0 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["MAC_ADDRESS"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.9.0 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["MAC_ADDRESS"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` ## 3.4 关闭设备 IMEI/MEID 采集设备的 imei 地址采集默认开启。如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 AppImei config.setImeiEnable(false); ``` 如需移除 IMEI 和 MEID 采集的相关代码，可以在全埋点 Plugin 中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.9.0 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["IMEI_MEID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.9.0 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["IMEI_MEID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` ## 3.5 关闭 OAID 采集 :::warning OAID 是重要设备追踪信息，若关闭 OAID 会影响 Tracer 归因，使用 Tracer 请谨慎考虑。 ::: 设备的 OAID 信息采集默认开启。如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集不上送 config.setOaidEnabled(false); ``` 如需移除 OAID 采集的相关代码，可以在全埋点 Plugin 中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.9.0 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["OAID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.9.0 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["OAID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` ## 3.6 关闭 Android ID 采集 :::warning 关闭 Android ID 会影响 device_id 生成逻辑，导致 device_id 卸载重装不一致，请谨慎关闭。后续文档中会简称 device_id 为 did。 ::: 设备的 Android ID 采集默认开启，如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集，关闭后会随机生成 config.setAndroidIdEnabled(false); ``` 如需移除 Android ID 采集代码，可以在全埋点 Plugin 中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.10.1 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["ANDROIDID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.10.1 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["ANDROIDID"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` ## 3.7 关闭 ICCID 采集设备的 ICCID 采集默认开启，如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集不上送 // 本功能仅支持6.14.3及以上版本 config.setIccIdEnabled(false); ``` ICCID 目前不支持通过插件移除采集代码。 ## 3.8 关闭 SN（硬件序列号）采集设备的 SN 采集默认开启，如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集不上送 // 本功能仅支持6.15.0及以上版本 config.setSerialNumberEnable(false); ``` SN 目前不支持通过插件移除采集代码。 ## 3.9 关闭 GAID 采集设备的 GAID 采集默认方案： * 6.15.0 之前 cn(国内版)与 global(海外版)都默认采集。 * 6.15.0 及之后 cn 默认关闭，global 默认打开。如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集，是否上送取决于客户是否外界传入过 Gaid config.setGaidEnabled(false); ``` ⚠️请注意，由于该开关国内外 SDK 包 6.15.0 版本之前都默认开启，可能会导致国内应用包内部的第三方集成了 Google Service 后也尝试获取 GAID，且 GAID 是耗时的，可能在部分机型存在 ANR 问题或者影响设备注册请求响应时间。 ```java // 针对 Gaid 获取耗时 SDK 提供了采集超时时间控制，如果超过采集时间还未采集到直接返回空 // 默认时间 2s 超时，方法参数 ms // 该方法 6.15.0 提供 config.setGaidTimeOutMilliSeconds(2000) ``` ⚠️请注意，由于该开关国内外 SDK 包都默认开启，可能会导致国内应用包内部的第三方集成了 Google Service 后也尝试获取 GAID，且 GAID 是耗时的，可能在部分机型存在 ANR 问题或者影响设备注册请求响应时间。 ## 3.10 关闭运营商信息采集设备的运营商信息默认采集，如需关闭： ```java // 开关关闭后相关代码不运行，属性不采集不上送 config.setOperatorInfoEnabled(false); ``` 如需移除运营商信息采集代码，可以在全埋点Plugin中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.10.1 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["OPERATOR"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.10.1 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["OPERATOR"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` ## 3.11 移除剪切板访问代码剪切版访问目前用于广告监测默认关闭， ```Plain Text // 开关关闭后不会访问客户剪切板内容 // 通过对应 applog 实例关闭 AppLog.setClipboardEnabled(false); ``` 如需移除剪切板访问代码，可以在全埋点 Plugin 中配置： * Gradle 8.0以下 ```Groovy // 本功能仅支持 6.16.3 及以上版本 teaExtension { // ... 其他配置 trackBlackList = ["CLIPBOARD"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` * Gradle 8.0及以上 ```Groovy // 本功能仅支持 6.16.3 及以上版本 // AGP8 版本插件 6.16.3 支持 appLog { // ... 其他配置 sensitiveFieldsBlocklist = ["CLIPBOARD"] // 您使用的是 Lite 包，需要移除采集相关代码， // 需要在新版本中添加该此配置，避免 Lite 包内容不齐导致运行闪退，6.14.3 起提供 disableAutoTrack = true } ``` # 4. 配置Scheme(可选) 如需使用[实时埋点检测](/docs/84129/1261787)或[圈选事件](/docs/84129/1261666)，请配置 Scheme，否则可跳过此步骤。 ## 4.1 获取URL Scheme 「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的 scheme，一般为`rangersapplog.xxxxx`的形式。 ![Image](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_39874dab5541dd2105b92713d94f0040.png =802x) ## 4.2 添加URL Scheme 在 app module 级别的 build.gradle 中添加 URL Scheme。 ```groovy // 在android的defaultConfig中添加 manifestPlaceholders.put("APPLOG_SCHEME", "yourURL_SCHEME".toLowerCase()) ``` # 5. 初始化基本配置以下为常用的初始化基本配置，`config` 均指初始化时的`InitConfig`。 ## 5.1 全埋点设置开关 :::warning 全埋点开关默认开启。SDK中开启全埋点后，后续实际使用前，您还需在DataFinder控制台查看并确认全埋点的开关已打开。 * SaaS-云原生和私有化场景：进入到项目中心>项目管理>SDK设置，确保全埋点开关已打开。 * SaaS-非云原生场景：进入到「数据管理-圈选事件」页面中，将「全埋点数据采集」开关打开即可正常使用。 ::: ```java // 开启全埋点事件的上送 config.setAutoTrackEnabled(true); // true:开启全埋点，false:关闭全埋点 ``` 全埋点中的页面浏览事件，默认针对 Activity 页面。如需开启针对 Fragment 的 bav2b_page 事件采集，除如上开关外，还需额外开启 Fragment 采集开关。 ```java // 开启Fragment全埋点事件采集 config.setAutoTrackFragmentEnabled(true); ``` ## 5.2 开启圈选埋点圈选埋点默认关闭。 ```java // 开启圈选埋点功能，使用此功能需先开启全埋点 config.setPicker(new Picker(this, config)); // 如果想要对 App 内嵌 h5 打开圈选，请打开 js 注入开关： config.setH5CollectEnable(true); // 注：h5 圈选仅支持原生 WebView 与腾讯 X5 ``` ## 5.3 查看日志打印 :::warning 日志打印默认关闭，建议上线生产包关闭。 ::: * 当前实例日志打印 ```Java // 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭 config.setLogEnable(true); // true:开启日志，false:关闭日志 config.setLogger(new ILogger() { @Override public void log(String s, Throwable throwable) { Log.d("AppLog------->: ", "" + s); } }); ``` * 多实例日志统一打印 ```Java // 如需要打印所有实例的日志，可以参考如下配置： // 仅支持 6.12.0+ 版本 LogProcessorHolder.addProcessor( new ILogProcessor() { @Override public void onLog(LogInfo log) { Log.d("AppLog------->: ", log.toLiteString()); } }); ``` ## 5.4 加密设置开关加密设置默认开启。您可在 debug 阶段关闭加密，以便于抓包联调。 ```java // 加密设置开关，线上版本建议开启 AppLog.setEncryptAndCompress(true); // true:打开加密，false:关闭加密 ``` ## 5.5 设置 APP Language 和 APP Region ```java // 修改语言和地区，设置 APP Language 和 APP Region config.setLanguage(...); // 设置APP Language，例如zh-cn config.setRegion(...); // 设置APP Region，例如cn ``` ## 5.6 打通内嵌 H5 页如果您的应用同时集成 Web/JS SDK 以及 Android SDK，默认情况下，所有 H5 事件会通过 Web/JS SDK 上报，如果您希望 H5 事件由 Android SDK 接管上报，可以使用打通内嵌 H5 功能，此时 H5 页上产生的事件将通过 Android SDK 上报，而不在 Web/JS SDK 上报，这种接管上报场景下会复用 Android 端设置的`user_unique_id`和公共属性，但是也支持打通时 web 侧设置 / 更新端上的 uuid / 公共属性，请在打通时注意采用哪边数据，如果完全以端上为准可以去掉 web sdk 侧的 uuid / 公共属性操作。 :::warning 打通功能需要 Web/JS SDK 与 Android SDK 同时集成并彼此配合，且当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能，因为此时上报都由 Android SDK 接管，如果还想采集 H5 全埋点，需要查看 5.7 小节：原生端采集 H5 全埋点。 Web/JS SDK 集成请参考[《Web/JS SDK 集成》](/docs/84129/1261745) 以及 3.4 小节。 Lite 不支持打包打通功能，如果需要打通请集成 All。 ::: ```java // 注：该功能仅支持原生 WebView 与腾讯 X5 // 以下配置需要同时开启，如果以下两个没有同时满足，H5 事件就会继续保持 Web/JS SDK 上报： // Android SDK 开启内嵌H5打通开关 config.setH5BridgeEnable(true); // Web/JS SDK 设置 H5 内嵌到原生端并打通 window.collectEvent('init', { // ...... 其他初始化配置 enable_native: true // 5.1.3以下版本参数为Native， // 5.1.3以上版本修改为enable_native，但仍然兼容了Native的设置 }) // 补充：开启打通后老版本原本 web sdk 的全埋点配置会失效 // 5.1.10 之前的老版本打通后 Web/JS SDK 屏蔽了 H5 的全埋点功能，所以 Web/JS SDK 的全埋点设置开关会失效， // 老版本 web sdk 想要依然保持 H5 全埋点功能，请查看 4.7 小节或者建议升级到新版本 window.collectEvent('init', { // 全埋点设置开关 autotrack: 打通后老版本失效（web sdk 5.1.10 之前版本失效，5.1.10 及之后版本正常采集） }) ``` ### 5.6.1 打通内嵌 H5 页的白名单前置工作开关开启后，必须配置打通白名单。仅白名单内配置的域名生效打通，白名单可用通配符方式添加，`*`表示通配符。 ```java // 内嵌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`。 ```java // 允许所有h5打通 // 本功能仅支持6.9.7及以上版本 config.setH5BridgeAllowAll(true); ``` ### 5.6.2 打通内嵌 H5 页的插件注入注意项一般情况下，H5 打通需要您参考 1.2 小节集成 plugin 插件，此时注入 Bridge 由 Plugin 插桩完成，但部分场景下，插桩可能不生效（插装失效的场景可能是混淆、被覆盖等等情况），您可以选择手动关闭 SDK 的自动注入 Bridge 能力，然后手动调用注入，此时可以在全埋点插件 Plugin 中增加配置`autoInjectWebViewBridge = false`，然后在需要打通的 WebView 加载H5之前手动注入 Bridge。 * Gradle 8.0 以下关闭插件自动注入 ```Groovy // 通过插件关闭自动注入 teaExtension { // 关闭自动注入webview的对接bridge autoInjectWebViewBridge = false // 省略插件的其他使用 } ``` * Gradle 8.0 及以上关闭插件自动注入 ```Groovy // AGP8 版本插件 6.16.3 支持 appLog { // 关闭自动注入webview的对接bridge autoInjectWebViewBridge = false // 省略插件的其他使用 } ``` ```Java // 本功能仅支持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 页开启全埋点功能。 :::warning * 可以独立使用该功能，无需集成 Web/JS SDK。 * 该功能 6.14.4 版本后提供，且目前的 H5 全埋点仅支持进入页面事件与点击事件。 ::: ```java // 注：该功能仅支持原生 WebView 与腾讯 X5 // 内嵌H5页面的全埋点事件 config.setH5CollectEnable(true); // true:开启h5全埋点事件，false:关闭h5全埋点事件 // 补充，该功能默认也通过插件方式注入，当插件失效或者想要自己手动注入时， // 可以参考 4.6.2 小节，4.6、4.7 虽然功能独立但是都通过统一方法进行注入控制， // 不过可以通过各自开关配置是否开启 ``` ## 5.8 全埋点事件采集默认全埋点开关开启，如需关闭： ```java config.setAutoTrackEnabled(false); ``` 开启全埋点后默认会采集页面事件和点击事件，如需定制全埋点采集，配置方法如下： ```java // 默认值：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 坐标信息，示例： ```java // GeoCoordinateSystemConst 为坐标系静态类 // WGS84 地球坐标系 // GCJ02 火星坐标系 // BD09 百度坐标系 // BDCS 北斗坐标系 // 本功能仅支持6.10.1及以上版本 AppLog.setGPSLocation(18.00f, 18.00f, GeoCoordinateSystemConst.WGS84); ``` ## 5.10 开启崩溃采集默认不采集应用崩溃事件`$crash`，如需开启： ```java // 目前仅支持采集JAVA崩溃 // 本功能仅支持6.13.0及以上版本 config.setTrackCrashType(AppCrashType.JAVA); ``` ## 5.11 开启 Fragment 页面事件采集默认 Fragment 页面事件采集关闭，开启开关后每个 Fragment 的访问也会记录一次页面访问事件（$bav2b_page）。如需开启： ```java // 本功能仅支持6.13.0及以上版本 config.setAutoTrackFragmentEnabled(true); ``` ## 5.12 是否区分鸿蒙设备数据采集上报会区分是否是鸿蒙系统： ```java // 本功能仅支持6.14.3及以上版本 config.setHarmonyEnable(true); ``` # 6.常用回调介绍 ## 6.1 如何正确获取 DID 等参数由于参数获取可能存在一定延迟性，Applog.getDid() 等方法可能第一时间无法获取到对应参数，所以建议通过回调的方式获取，以及回调后，再通过 Applog.getDid() 等方法就可以确保一定获取。 ```typescript // step1：添加数据集观察回调，this 指代实现了 IDataObserver 的类 AppLog.addDataObserver(this); // step2：通过 IDataObserver 的 onIdLoaded 或 onRemoteIdGet 到数据后使用或者使用以下方式获取：默认实例：Applog.getDid() / 使用多实例：IAppLogInstance.getDid() // IDataObserver 主要功能介绍与参数介绍： // - did、iid、ssid 获取都可以通过该回调获取 // - 服务端配置获取 // - ab 实验配置获取 public interface IDataObserver { /** * 本地的id数据加载结果通知 * @param did device id * @param iid install id * @param ssid 数说id */ void onIdLoaded(@NonNull String did, @NonNull String iid, @NonNull String ssid); /** * 通知注册结果，以及id变化情况 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param oldDid 本地老的 oldDid，可能为空 * @param newDid server返回新的 device id * @param newIid server返回新 install id * @param newSsid server返回新数说 id */ void onRemoteIdGet(boolean changed, @Nullable String oldDid, @NonNull String newDid, @NonNull String oldIid, @NonNull String newIid, @NonNull String oldSsid, @NonNull String newSsid); /** * Config拉取数据，和本地数据对比有变化的通知 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param config server返回新config内容 */ void onRemoteConfigGet(boolean changed, @Nullable JSONObject config); /** * server拉取AbConfig数据，和本地数据对比有变化的通知 * 仅主进程会被调用 * @param changed 是否和本地缓存有所不同 * @param abConfig server返回新abConfig内容 */ void onRemoteAbConfigGet(boolean changed, @NonNull JSONObject abConfig); /** * 客户端ab实验曝光vid集合发生变化的通知 * @param vids 客户端ab实验曝光vid集合 * @param extVids 外部设置的external vid集合 */ void onAbVidsChange(@NonNull String vids, @NonNull String extVids); } ``` ## 6.2 事件过滤以及自定义参数补齐针对事件过滤或事件自定义参数补齐，可以使用以下回调： * 6.16.1 及以上版本 ```Groovy 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; } }); ``` * 6.16.1 以下版本 ```Groovy // 设置事件处理回调 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 提供了自定义加密接口，后续如果私有化版本支持了其他加密协议均可使用自定义加密接口进行请求加密实现。 * Java ```Java // sm2 加密 Sm2Helper sm2Helper = new Sm2Helper(yourPublicKey); config.setEncryptor(new IEncryptor() { @Override public byte[] encrypt(byte[] data, int size) { // 将原数据转换为加密数据 return sm2Helper.encrypt(data, size); } // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致 }, sm2Helper.encryptorType()); // 自定义加密 // 可以通过自定义加密接口实现与私有化部署自定义协议加密模式 config.setEncryptor(new IEncryptor() { @Override public byte[] encrypt(byte[] data, int size) { // 将原数据转换为加密数据 return yourEncryptMethod(data, size); } // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致 }, "yourEncryptType"); ``` * Kotlin ```Kotlin // sm2 加密 val sm2Helper = Sm2Helper(yourPublicKey) config.setEncryptor({ data, size -> // 将原数据转换为加密数据 sm2Helper.encrypt(data, size) }, // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致 sm2Helper.encryptorType() ) // 自定义加密 // 可以通过自定义加密接口实现与私有化部署自定义协议加密模式 config.setEncryptor({ data, size -> // 将原数据转换为加密数据 yourEncryptMethod(data, size) }, // 加密类型会放到 Content-Type 中，需要与私有化部署配合协商一致 "yourEncryptType" ) ``` # 7.其他功能介绍 ## 7.1 云控能力注意：本功能仅SaaS云原生版本或私有化V4.4.0以上版本，且SDK 6.15.0 以上版本支持； DataFinder支持通过服务端下发 SDK 设置，包括上报时机、全埋点开关等，详细介绍文档请查阅：[项目管理-SDK设置](/docs/84129/1261714)。 # 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标识设备 | # 9. 参考：数据上报流程与触发时机 :::tip SaaS-云原生、私有化环境支持在DataFinder的控制台设置Android、iOS、web、小程序平台SDK的基础设置，包括是否开启全埋点、埋点上报时机等等。以下为端上默认的上报流程和机制，您也可以在DataFinder的控制台进行配置调整，详情请参见[项目管理-SDK设置](/docs/84129/1261714)。 ::: ## 数据上报前提数据上报前置条件为完成SDK初始化，上报前会检查SDK初始化的 config 中是否配置了setAutoStart(false) ： * 如果没有配置过， init 之后就会定时上报数据。 * 如果配置过，会等待开发者调用 start 之后开始定时上报数据。 ## 数据上报流程与逻辑

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

增长分析 DataFinder