You need to enable JavaScript to run this app.
导航
Android 快速接入
最近更新时间:2024.05.14 16:31:29首次发布时间: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.6'
// release下依赖DevTools-No-Op组件
releaseImplementation 'com.bytedance.applog:RangersAppLog-DevTools-No-Op:3.4.6'

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

如果需要在Release包中使用DevTools(请关注权限和隐私合规),请修改依赖的配置如下:

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

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+版本支持