App Center Analytics (Android)

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center,直到它完全停用,但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方法。

App Center Analytics 可帮助你了解用户行为和客户参与度,以改进应用。 SDK 会自动捕获会话计数和设备属性,例如模型、OS 版本等。可以定义自己的自定义事件来度量对你而言很重要的事情。 App Center 门户中提供了捕获的所有信息,供你分析数据。

如果尚未在应用程序中设置 SDK, 请按照 SDK 入门部分进行操作。

会话和设备信息

将 App Center Analytics 添加到应用并启动 SDK 后,它将自动跟踪会话和设备属性(如 OS 版本、模型等),而无需编写任何其他代码。

国家/地区代码

如果设备安装了移动数据调制解调器和 SIM 卡,SDK 会自动报告用户的国家/地区代码。 默认情况下,仅限 WiFi 的设备不会报告国家/地区代码。 若要设置这些用户的国家/地区代码,必须自行检索用户的位置,并使用 setCountryCode: SDK 中的 方法:

AppCenter.setCountryCode("en");
AppCenter.setCountryCode("en")

备注

对于要在 Analytics 会话上显示的国家/地区代码, AppCenter.setCountryCode 必须在调用 之前调用 AppCenter.start

自定义事件

可以使用 最多 20 个属性 跟踪自己的自定义事件,以了解用户与应用之间的交互。

启动 SDK 后,使用 trackEvent() 方法通过属性跟踪事件。 最多可以发送 200 个不同的事件名称。 此外,还有最大字符限制:

  • 每个 event name256 个字符。
  • 每个 event property name & event property value125 个字符。
Map<String, String> properties = new HashMap<>();
properties.put("Category", "Music");
properties.put("FileName", "favorite.avi");

Analytics.trackEvent("Video clicked", properties);
val properties = hashMapOf("Category" to "Music", "FileName" to "favorite.avi")
Analytics.trackEvent("Video clicked", properties)

事件的属性是完全可选的 - 如果只想跟踪事件,请改用此示例:

Analytics.trackEvent("Video clicked");
Analytics.trackEvent("Video clicked")

事件优先级和持久性

可以跟踪重要性高于其他事件的业务关键事件。

  • 开发人员可以将事件的优先级设置为 API) Flags.NORMAL 中的普通 (或 API) 中的关键 (Flags.CRITICAL
  • 优先级设置为 “严重 ”的事件将首先从存储中检索,并在 正常 事件之前发送。
  • 当本地存储已满,并且需要存储新事件时,将首先删除优先级最低的最早事件。
  • 如果存储中满是具有 严重 优先级的日志,则跟踪具有 正常 优先级的事件将失败,因为在这种情况下,SDK 无法腾出空间。
  • 如果还使用 崩溃 服务,则崩溃日志将设置为 “严重 ”,并共享与事件相同的存储。
  • 传输间隔仅适用于 Normal 事件, 关键 事件将在 3 秒后发送。

可以使用以下 API 将事件跟踪为 “严重”事件:

Map<String, String> properties = new HashMap<>();
properties.put("Category", "Music");
properties.put("FileName", "favorite.avi");

Analytics.trackEvent("eventName", properties, Flags.CRITICAL);

// If you're using name only, you can pass null as properties.
val properties = hashMapOf("Category" to "Music", "FileName" to "favorite.avi")
Analytics.trackEvent("Video clicked", properties, Flags.CRITICAL)

// If you're using name only, you can pass null as properties.

暂停和继续发送日志

在应用需要控制网络带宽以满足更多业务关键需求的情况下,暂停事件传输非常有用。 可以暂停将日志发送到 App Center 后端。 暂停后,仍可跟踪和保存事件,但不会立即发送事件。 应用在暂停时跟踪的任何事件将仅在调用 resume后发送。

Analytics.pause();
Analytics.resume();
Analytics.pause()
Analytics.resume()

在运行时启用或禁用 App Center Analytics

可以在运行时启用和禁用 App Center Analytics。 如果禁用它,SDK 将不会为应用收集任何其他分析信息。

Analytics.setEnabled(false);
Analytics.setEnabled(false)

若要再次启用 App Center Analytics,请使用同一 API,但将 作为参数传递 true

Analytics.setEnabled(true);
Analytics.setEnabled(true)

在应用程序启动时,状态将保留在设备的存储中。

此 API 是异步的,可以在 App Center 异步 API 指南中详细了解此 API。

备注

只有在启动之后 Analytics 才能使用此方法。

检查是否启用了 App Center Analytics

还可以检查是否启用 App Center Analytics。

Analytics.isEnabled();
Analytics.isEnabled()

此 API 是异步的,可以在 App Center 异步 API 指南中详细了解此 API。

备注

此方法只能在启动后 Analytics 使用,它将始终在启动之前返回 false

管理启动会话

默认情况下,会话 ID 取决于应用程序的生命周期。 如果要手动控制新会话的开始,请执行后续步骤:

备注

请注意,每次调用 Analytics.StartSession () API 都会生成一个新会话。 如果在手动会话跟踪器模式下不会调用此 API,则所有发送日志都将具有空会话值。

备注

请注意,新应用程序启动后,将重新生成会话 ID。

  • 在 SDK 启动之前调用以下方法:
Analytics.enableManualSessionTracker();
Analytics.enableManualSessionTracker()
  • 然后,可以在 之后使用 startSession API AppCenter.start
Analytics.startSession();
Analytics.startSession()

本地存储大小

默认情况下,SDK 将所有事件日志存储到 10 MB。 开发人员可以使用 API 来增加 存储大小 ,SDK 会一直存储日志,直到存储已满。

无法访问 Internet

如果没有网络连接,SDK 将最多 10 MB 的日志保存在本地存储中。 存储已满后,SDK 将开始放弃旧日志,以便为新日志腾出空间。 网络连接恢复后,SDK 会在默认情况下) 每隔 6 秒发送一批 50 或每隔 6 秒发送一次日志 (。

备注

超过 25 天的日志不会被后端接受。

批处理事件日志

App Center SDK 上传一批 50 个日志,如果 SDK 没有要发送的 50 个日志,则默认 (6 秒后仍会发送日志) 。 最多可以并行发送三个批。 可以更改传输间隔:

// Change transmission interval to 10 seconds.
Analytics.setTransmissionInterval(10000);
// Change transmission interval to 10 seconds.
Analytics.setTransmissionInterval(10000)

传输间隔值必须介于 6 秒到 86400 秒之间, (一天) 并且必须在启动服务之前调用此方法。

重试和退让逻辑

App Center SDK 支持对可恢复的网络错误进行回退重试。 下面是重试逻辑:

  • 3 次尝试每个请求的最大值。
  • 每个请求都有自己的重试状态机。
  • 所有传输通道 (禁用,直到下一个应用进程在一个请求耗尽其所有重试后) 。

退让逻辑

  • 50% 随机化,第一次重试 5 到 10 秒,下一次尝试 2.5 到 5 分钟,最后一次尝试在 10 到 20 分钟之间。
  • 如果网络从关闭切换到 (或从 wi-fi 切换到移动) ,则会重置重试状态并立即重试请求。