Android埋点开发工具

通过Android SDK埋点开发工具（DevTools组件），可以在开发阶段便捷的对埋点内容和格式进行检查，该工具提供了实时事件查看、实时接入状态查看、实时日志查看、实时网络请求查看等功能。

2.1 接入要求 #

• 已接入增长营销套件Android SDK，支持的最小版本：6.12.0

• 支持AndroidX

• Kotlin版本不低于1.3.70

• Android版本不低于21

2.2 引入仓库 #

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

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

2.3 引入DevTools组件 #

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

debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:2.2.3'

说明：DevTools组件包含有独立的视图资源文件，建议仅在开发环境引入该组件（即使用debugImplementation）

如果需要在release包中使用DevTools，请修改依赖的配置为：

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

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

3.1 面板入口 #

打开应用后会看到一个悬浮的按钮，按钮下方是本次启动后产生的事件总数，点击该按钮后会打开工具面板。

3.1.1 关闭悬浮入口 #

如果需要隐藏悬浮按钮，请在应用的Application初始化中设置关闭悬浮按钮：

AppLogDevTools.floatingButtonVisible = false;

3.1.2 手动显示面板 #

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

AppLogDevTools.show();

3.1.3 面板页面结构 #

DevTools面板页面分标题区、导航区、内容区三部分：

• 标题区：显示APP ID（可切换多实例）和关闭面板按钮；

• 导航区：功能导航，点击图标即可切换功能栏；

• 内容区：显示各个功能栏的具体内容。

3.2 接入栏 #

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

• 版本检查：初始化AppLog后会显示版本号和是否接入全埋点。

• 初始化检查：显示了核心的初始化信息，包含APP ID、渠道、启动状态和服务环境。

  • 启动状态：

    • 已初始化：执行了AppLog.init之后的状态；

    • 已启动：SDK开始正常工作后的状态。

  • 服务环境：

    • 国内SaaS；

    • 海外SaaS；

    • 私有化。

• 功能接入检查：显示核心功能的开关状态。

  • 全埋点开关：显示本地和服务同时控制的状态，本地与服务开关不一致会警告色高亮；

  • AB实验开关：显示本地和服务同时控制的状态，本地与服务开关不一致会警告色高亮；

  • H5打通开关；

  • DevTools版本；

  • DevTools功能：如果没有设置Open API密钥（见4.2章节），则会显示警告信息“AK&SK未设置”。

• 服务接口检查：显示核心网络请求是否正常。

• 埋点上报检查：显示埋点从采集、本地缓存到上报的过程是否正常。

3.3 配置栏 #

在DevTools面板中的导航栏点击“配置”即可切换到配置栏。配置栏中显示了埋点SDK接入成功的各种配置和下发的参数信息：

• 基本信息：包含设备注册相关的SSID、uuid、bd_did等信息；

• 初始化配置：包含初始化传入的参数以及实时设置的配置信息；

• 服务端配置：包含服务端下发的配置信息；

• 公共参数配置：包含采集的设备信息和自定义公参，并标记敏感参数；

• AB实验配置：包含AB实验命中的内容（JSON格式）。

3.4 事件栏 #

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

• 搜索区：事件列表支持按关键字、事件类型、上报状态、录入状态搜索，支持按时间正序、倒序排列，支持清空当前面板的事件列表，支持手动拉取数据管理中的元数据信息；

• 事件区：事件列表包含事件的产生时间、事件类型、事件状态等基本信息，点击单个事件可以查看事件详细内容（JSON格式），长按单个事件可以复制事件内容到剪切板。

  • 事件状态：

    • 已采集：表示事件已产生；

    • 已落库：表示事件已缓存到本地；

    • 已上报：表示事件已通过网络请求上传到服务端。

  
  • 录入状态：该状态依赖数据管理的元数据信息，通过配置Open API密钥（4.2章节）即可使用。

    • 正常上报：可以正常上报和落离线表；

    • 未录入：在数据管理中没有录入该事件；

    • 已禁用：禁止上报，不影响埋点SDK采集上报，但会影响落离线表；

    • 未验收：在数据质量中没有验收该事件；

    • 已删除：数据管理中已删除。

• 事件详情：详情中可以看到属性数量和异常信息。

  • 异常属性：指属性名称、属性值等校验结果异常；

  • 缺失属性：指在数据管理中录入的事件属性未采集。

3.5 日志栏 #

在DevTools面板中的功能栏点击“日志”即可切换到日志栏。通过查看错误日志等可以快速排查接入等问题。日志栏功能包含：

• 搜索区：支持按关键字、功能模块、日志级别搜索，支持按时间正序、倒序排列，支持清空当前列表的全部日志、支持分享所有日志（含被清空的日志）到第三方应用；

• 日志区：实时显示增长营销套件SDK产生的所有日志（无需打开日志开关），点击单个日志可以查看日志详情，日志详情支持复制内容到剪切板，支持解析JSON内容并格式化显示JSON。

3.6 网络栏 #

在DevTools面板中的功能栏点击“网络”即可切换到网络栏。通过网络请求的状态和请求体可以查看埋点上报是否成功。网络栏功能包含：

• 搜索区：支持按URL、接口类型、请求方式搜索，支持按时间正序、倒序排序，支持清空当前列表的网络请求；

• 网络区：包含请求时间、耗时、状态码、请求方法等基本信息，点击单个网络请求可以查看详细信息。详情的单个信息内容可长按复制到剪切板。网络请求详细信息包含：

  • 完整URL

  • 请求的Headers

  • 请求体（支持JSON格式化查看）

  • 响应的Headers

  • 响应体（支持JSON格式化查看）

4.1 关闭内置埋点 #

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

AppLogDevTools.trackEnabled = false;

4.2 设置Ak&SK #

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

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

该功能暂时仅支持火山引擎的SaaS环境，不支持私有化环境。

4.3 生产环境使用DevTools #

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

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

RangersAppLog:6.14.2+版本支持