App Center Analytics (Unity)

  • 项目

重要

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

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

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

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

注意

若要使用下面显示的 API，必须将以下 using 语句添加到 文件中 .cs ：

using Microsoft.AppCenter.Unity.Analytics;

此外，必须确保在 App Center 游戏对象的设置中选中 “使用分析 ”。

会话和设备信息

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

自定义事件

可以使用最多 20 个属性跟踪自己的自定义事件，以了解应用中发生的情况、了解用户操作以及查看 App Center 门户中的聚合。

TrackEvent()使用 方法通过属性跟踪事件。 最多可以发送 200 个不同的事件名称。 每个事件名称的最大限制为 256 个字符，每个事件属性名称和值的最大限制为 125 个字符。

Analytics.TrackEvent("Video clicked", new Dictionary<string, string> {
	{ "Category", "Music" },
	{ "FileName", "favorite.avi" }
});

事件属性是可选的 - 如果只想跟踪事件，请改用此示例：

Analytics.TrackEvent("Video clicked");

警告

Analytics.TrackEvent()如果在脚本 AppCenterBehavior.cs中的 方法之前Awake()调用，则跨平台的行为不一致。 为安全起想，应仅依赖于在应用程序中的第一个场景唤醒所有 MonoBehaviour 脚本后发送的事件。 若要将 事件与 MonoBehavour的初始化一起跟踪，请考虑将 API 添加到脚本的 Start() 方法， Awake()而不是 。

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

可以在运行时启用和禁用 App Center Analytics。 如果禁用它，SDK 将停止收集应用的分析信息。 若要禁用 Analytics，请使用以下 API 作为参数传递 false 。

Analytics.SetEnabledAsync(false);

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

Analytics.SetEnabledAsync(true);

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

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

检查是否启用了 App Center Analytics

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

bool isEnabled = await Analytics.IsEnabledAsync();

事件优先级和持久性

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

开发人员可以在 API) Flags.PersistenceNormal 中将事件的持久性设置为“普通 (”或“API) 中的关键 (Flags.PersistenceCritical”。

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

Analytics.TrackEvent("eventName", Flags.PersistenceCritical);

如果使用属性：

Analytics.TrackEvent("eventName", new Dictionary<string, string> {
	{ "Category", "Music" },
	{ "FileName", "favorite.avi" }
}, Flags.PersistenceCritical);

暂停和继续发送日志

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

Analytics.Pause();
Analytics.Resume();

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

管理启动会话

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

注意

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

注意

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

  • 取消选中附加了 AppCenterBehavior 的游戏对象的“分析”部分下的“启用手动会话跟踪器”复选框。
  • 然后，可以在 之后使用 StartSession API AppCenter.Start：
Analytics.StartSession();

本地存储大小

默认情况下，SDK 在存储中存储最多 10 MB 的日志。

无法访问 Internet

如果没有任何网络连接，SDK 将最多 10 MB 的日志保存在本地存储中。 存储已满后，SDK 将开始放弃旧日志，为新日志腾出空间。 设备重新访问 Internet 后，SDK 将每隔 6 秒发送一批 50 或每 6 秒发送一次日志。

批处理事件日志

App Center SDK 分批上传 50 个日志，如果 SDK 没有 50 个要发送的日志，它仍将在 6 秒后发送日志。 最多可以并行发送三个批。

重试和退让逻辑

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

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

退让逻辑

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