You need to enable JavaScript to run this app.
导航
埋点开发者工具
  • 文档首页
    • /
  • 埋点开发者工具

Android 快速接入

最近更新时间：2024.04.23 14:33:22

首次发布时间：2023.07.04 19:18:25

我的收藏

1. 功能说明

通过Android端 DevTools 工具，可以在应用上线前快速对采集的事件（埋点）内容进行检查，该工具提供了查看 SDK（增长营销套件SDK） 接入状态、实时查看事件、查看调试日志、查看网络请求、查看A/B实验分流等功能。

2. 接入DevTools组件

2.1 接入要求

  • 已接入增长营销套件Android SDK，支持的最小版本为6.12.0
  • 工程已支持AndroidX
  • Kotlin版本不低于1.3.70
  • Android版本不低于14

2.2 权限说明

火山引擎的客户在使用DevTools组件时，DevTools组件将向火山引擎的客户申请以下权限（不是向客户的C端用户申请）。禁用权限后相关功能的使用将会受限。

  • 网络权限：该权限用于DevTools组件访问远程服务数据，例如埋点校验功能中的元数据信息同步、扫一扫开启埋点实时验证功能的扫码建连、A/B测试实验列表拉取等。禁用该权限后，DevTools组件将无法访问远程服务。
  • 相机权限：该权限用于DevTools组件的扫一扫识别二维码功能。禁用该权限后，扫一扫功能将无法正常使用。

2.3 引入仓库

该步骤同增长营销套件SDK的仓库引入，确保在project级别的build.gradle或settings.gradle配置中包含以下maven仓库：

maven {
    url 'https://artifact.bytedance.com/repository/Volcengine/'
}

2.4 引入DevTools组件

在app项目的build.gradle中添加DevTools组件的依赖：

// debug或测试包中依赖DevTools组件
debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:3.4.4'
// release下依赖DevTools-No-Op组件
releaseImplementation 'com.bytedance.applog:RangersAppLog-DevTools-No-Op:3.4.4'

说明：DevTools组件包含有独立的视图资源文件，建议仅在开发环境引入该组件（即使用debugImplementation）。RangersAppLog-DevTools-No-Op 组件为空实现组件，保留了公开的API，可在Release下依赖，与RangersAppLog-DevTools组件不能共存。

如果需要在Release包中使用DevTools（请关注权限和隐私合规），请修改依赖的配置如下：

implementation 'com.bytedance.applog:RangersAppLog-DevTools:3.4.4'

3. 功能说明

完成接入操作后，启动应用即可使用下述功能。

3.1 面板入口

打开应用后会看到一个悬浮的按钮，按钮下方是本次启动后产生的事件总数和上报完成百分比（已上报到服务端的事件数/累计采集的事件数），点击该按钮后会打开DevTools面板。
图片

3.1.1 悬浮入口配置

悬浮按钮默认在App启动后常驻吸边显示，可拖动调整位置。如果需要隐藏悬浮按钮，可以通过以下任意方式关闭：

  1. 一般建议在App的Debug页面（或开发者工具页面）添加一个新的按钮，来控制悬浮按钮的显示和隐藏。开关的值会默认持久化到本地。
// 隐藏悬浮按钮
AppLogDevTools.setFloatingButtonVisible(false);

// 如果需要手动显示悬浮按钮，设置参数为true即可
AppLogDevTools.setFloatingButtonVisible(true);

DevTools v3.1.0+版本新接口
注意：在Application的初始化中调用该接口不会生效。

  1. 在DevTools设置页面关闭悬浮显示：

图片

  1. 首次接入DevTools组件时如果需要默认关闭悬浮按钮的显示，可以参考下面的配置关闭默认显示。后续使用setFloatingButtonVisible接口或在设置页面修改悬浮入口显示状态后该配置会自动失效。
AppLogDevTools.setFloatingButtonVisibleDefault(false); // 关闭首次接入默认显示悬浮按钮

DevTools v3.4.2+版本新接口

  1. 支持修改悬浮按钮背景的透明度，可以在控制台-DevTools设置页面修改透明度。

DevTools v3.4.2+版本新接口

3.1.2 手动显示面板

在关闭了悬浮按钮后，如果需要打开DevTools面板，可以在任意位置通过调用以下方法显示：

// 显示DevTools可视化面板
AppLogDevTools.showPanel();

// 手动关闭可视化面板
AppLogDevTools.closePanel();

DevTools v3.1.0+版本新接口

3.1.3 显示悬浮事件列表

默认关闭了悬浮按钮上下的事件列表，悬浮事件列表会显示最新采集的5-50个事件名称，可以通过以下任意方式显示出悬浮的事件列表（只有悬浮入口显示的条件下才生效）：
方法一：调用接口显示出悬浮事件列表：

// 显示悬浮事件列表
AppLogDevTools.setFloatingButtonEventVisible(true);

// 手动关闭悬浮事件列表
AppLogDevTools.setFloatingButtonEventVisible(false);

DevTools v3.1.0+版本新接口

方法二：在DevTools设置页面（控制台面板点击“DevTools设置”进入）打开悬浮显示最新事件开关，也可以调整悬浮事件显示数量：
图片

3.1.4 面板页面结构

DevTools面板页面分标题区、内容区两个部分：

  • 标题区：显示子页面标题、显示APP ID（可切换多实例）和关闭面板按钮；
  • 内容区：显示各个功能栏的具体内容。

图片

3.2 接入栏

首次使用DevTools面板默认显示的是接入栏。接入栏中显示了DevTools对增长营销套件SDK的核心信息的检查结果。首次接入增长营销套件SDK时可以通过该栏信息判断是否接入成功。

  • 版本检查：初始化AppLog后会显示SDK版本号、是否接入全埋点、是否集成Plugin。
  • 初始化检查：显示了核心的初始化信息，包含APP ID、渠道、启动状态和服务环境。
    • 启动状态：
      • 已初始化：执行了AppLog.init之后的状态；
      • 已启动：SDK开始正常工作后的状态。
    • 服务环境：
      • 国内SaaS；
      • 海外SaaS；
      • 私有化。
  • 功能接入检查：显示核心功能的开关状态。
    • 全埋点开关：显示本地和服务同时控制的状态，本地与服务开关不一致会警告色高亮；
    • AB实验开关：显示本地和服务同时控制的状态，本地与服务开关不一致会警告色高亮；
    • H5打通开关；
    • DevTools版本；
    • DevTools功能：如果没有设置Open API密钥（见4.2章节），则会显示警告信息“AK&SK未设置”。
  • 服务接口检查：显示核心网络请求是否正常。
  • 埋点上报检查：显示埋点从采集、本地缓存到上报的过程是否正常。

图片

3.3 事件栏

在DevTools面板中的功能栏点击“事件”即可切换到事件栏。通过实时查看事件信息可以检查事件参数等是否正确。事件栏功能包含：

  • 搜索区：事件列表支持按关键字（支持正则匹配）、事件类型、上报状态、录入状态搜索，支持按时间正序、倒序排列，支持清空当前面板的事件列表，支持手动拉取数据管理中的元数据信息，支持一键清空输入框，支持历史搜索埋点；
  • 事件区：事件列表包含事件的产生时间、事件类型、事件状态等基本信息，点击单个事件可以查看事件详细内容（JSON格式），长按单个事件可以复制事件内容到剪切板。
    • 事件状态：
      • 已采集：表示事件已产生；
      • 已落库：表示事件已缓存到本地；
      • 已上报：表示事件已通过网络请求上传到服务端。
  • 录入状态：该状态依赖数据管理的元数据信息，通过配置Open API密钥（4.2章节）即可使用。
    • 正常上报：可以正常上报和落离线表；
    • 未录入：在数据管理中没有录入该事件；
    • 已禁用：禁止上报，不影响埋点SDK采集上报，但会影响落离线表；
    • 未验收：在数据质量中没有验收该事件；
    • 已删除：数据管理中已删除。
  • 事件详情：详情中可以看到属性数量和异常信息。属性的校验功能依赖数据管理的元数据信息，通过配置Open API密钥（4.2章节）即可使用。
    • 异常属性：指属性名称、属性值等校验结果异常；
    • 缺失属性：指在数据管理中录入的事件属性未采集。

图片

3.4 控制台

在DevTools面板中的导航栏点击“控制台”即可切换到控制台。控制台是DevTools的功能集合面板，提供了丰富的调试功能。功能涵盖增长营销分析SDK的API调用、采集的事件分类统计、A/B测试实验查询和修改等。在控制台中，具体可以完成以下调试工作：

  • 查看调试日志，实时显示日志总数
  • 查看网络抓包，实时显示网络请求总数
  • 查看增长营销套件SDK相关的配置
  • 扫一扫，支持扫描埋点实时验证二维码开启实时验证，同时支持扫码打开网页
  • 查看事件聚合统计，实时显示事件类型总数和大体积事件类型总数
  • 查看A/B测试实验列表
  • 刷新A/B测试实验配置
  • 清空事件缓存并上报
  • 模拟随机事件采集
  • 模拟5秒播放时长事件采集
  • 动态切换事件上报接口加密开关，实时显示当前的加密开关状态
  • 模拟随机公共参数配置
  • 查看自定义公共参数配置，实时显示当前的自定义公共参数数量
  • 模拟随机用户登录
  • 手动激活用户
  • 模拟随机GPS坐标配置
  • DevTools配置
  • 过滤事件列表

图片

3.5 SDK配置

在控制台面板点击SDK配置即可进入配置详情页。SDK配置页中显示了增长营销套件SDK接入后的各种参数配置，以及服务端下发的配置信息：

  • 基本信息：包含设备注册相关的SSID、uuid、bd_did等信息；
  • 初始化配置：包含初始化传入的参数以及实时设置的配置信息；
  • 服务端配置：包含服务端下发的配置信息；
  • 公共参数配置：包含采集的设备信息和自定义公参，并标记敏感参数；
  • AB实验配置：包含AB实验命中的内容（JSON格式）。

图片

3.6 调试日志

在控制台面板中点击“调试日志”即可进入调试日志页面。通过查看错误日志等可以快速排查接入等问题。日志栏功能包含：

  • 搜索区：支持按关键字、功能模块、日志级别搜索，支持按时间正序、倒序排列，支持清空当前列表的全部日志、支持分享所有日志（含被清空的日志）到第三方应用；
  • 日志区：实时显示增长营销套件SDK产生的所有日志（无需打开日志开关），点击单个日志可以查看日志详情，日志详情支持复制内容到剪切板，支持解析JSON内容并格式化显示JSON。

图片

3.7 网络抓包

在控制台面板中点击“网络抓包”即可进入网络抓包页面。通过网络请求的状态和请求体可以查看埋点上报是否成功。网络栏功能包含：

  • 搜索区：支持按URL、接口类型、请求方式搜索，支持按时间正序、倒序排序，支持清空当前列表的网络请求；
  • 网络区：包含请求时间、耗时、状态码、请求方法等基本信息，点击单个网络请求可以查看详细信息。详情的单个信息内容可长按复制到剪切板。网络请求详细信息包含：
    • 完整URL
    • 请求的Headers
    • 请求体（支持JSON格式化查看）
    • 响应的Headers
    • 响应体（支持JSON格式化查看）

图片

RangersAppLog:6.15.3+支持显示响应头

3.8 实验列表

在控制台面板中点击“实验分流”即可进入实验分流页面。该功能依赖于A/B测试产品的实验数据，通过配置Open API密钥（4.2章节）方可使用。
实验分流页面显示了所有A/B测试实验列表（包含进行中、调试中、已结束等状态），同时显示当前设备是否命中实验的状态。搜索区支持按实验名称和实验命中状态搜索实验，同时会记录最近浏览的10个实验名称，点击历史记录可以快速打开实验详情。列表的信息包含：

  • 实验命中标签：表示当前设备命中了该实验，并且实验名称下方会显示命中的变体名称
  • mock标签：表示当前设备修改了该实验的进组
  • 最近浏览：表示查看了该实验详情

点击单个实验会进入实验详情，实验详情页会显示实验名称、实验类型、实验描述、实验状态和实验的开始结束时间。实验配置卡片显示了实验下的所有变体信息，单个变体信息包含变体名称和配置的JSON内容。在实验配置卡片右侧可以打开实验进组编辑开关，打开进组编辑（mock）开关后即可选择进组的变体。点击“提交更改”按钮后，再重新启动APP即可完成实验进组修改操作。
图片

3.9 事件统计

在控制台面板中点击“事件统计”即可进入事件统计页面，点击“大体积事件”即可进入大体积事件统计页面。事件统计是按事件名称为维度做的聚合统计，包括采集的总次数和总大小（内容字节总数），支持按名称搜索指定事件。大体积事件页面，显示的是单次采集的事件内容大于指定值（可以修改）的次数和总大小。根据事件统计，可以发现并治理异常的事件。
图片

4. 其他

4.1 关闭内置埋点

DevTools组件本身会在部分场景下进行行为分析埋点，用于优化基础功能。关闭内置埋点的方法：

// 关闭DevTools内置埋点采集
AppLogDevTools.setTrackEnabled(false);

DevTools v3.1.0+版本新接口

4.2 设置Ak&SK

事件栏中除了基本的事件信息校验，还支持数据管理中的事件元数据信息导入和校验。开启该功能需要提前设置Open API的密钥（AccessKey和SecretKey，获取方式参考https://www.volcengine.com/docs/6285/111905）。获取到AK&SK之后，在Application初始化中对指定的App ID配置以下内容即可：

AppLogDevTools.setOpenApiAuthKey("{appId}", "{accessKey}", "{secretKey}");

如果是私有化环境，需要额外设置私有化的域名信息（使用火山引擎环境请忽略该步骤）：

AppLogDevTools.setCustomDomain("{私有化环境的后台管理首页域名}");

4.3 生产环境使用DevTools

一般建议用户通过debugImplementation的方式接入DevTools，在Debug包中进行调试。如果需要在Release包中使用DevTools做调试，请使用implementation接入（见2.3章节），同时需要在Application初始化中设置以下开关或在DevTools设置页面打开DevTools数据同步开关：

// 设置DevTools开关，默认在接入DevTools后即开启
// 如果设置为false，则debug和release下均无法使用DevTools
// 如果设置为true，则debug和release下接入了DevTools后可正常使用DevTools
AppLog.setDevToolsEnable(true);

RangersAppLog:6.14.2+版本支持