App Center Analytics （Unity）

2025-05-06

重要

Visual Studio App Center 于 2025 年 3 月 31 日停用，但分析和诊断功能除外，这些功能将继续受支持，直到 2026 年 6 月 30 日。了解详细信息。

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()中调用Awake()方法之前执行AppCenterBehavior.cs方法，则其行为在不同平台上会不一致。为了安全起见，你应该只依赖应用程序的第一个场景唤醒了所有 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();

事件优先级和持久性

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

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

可以使用以下 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，则所有发送日志都将具有 null 会话值。

注释

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

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

Analytics.StartSession();

本地存储大小

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

无 Internet 访问

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

批处理事件日志

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

重试和退让逻辑

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

每个请求最多尝试 3 次。
每个请求都有自己的重试状态机。
在一个请求耗尽所有重试后，所有传输通道都会被禁用，直到应用程序进入下一个处理阶段。

退让逻辑

50% 随机化，第一次重试 5 秒到 10 秒，第二次重试介于 2.5 到 5 分钟之间，最后尝试 10 到 20 分钟。
如果网络从关机切换到打开（或从 wi-fi 切换到移动设备），则重试状态将重置，并立即重试请求。

通过