App Center Analytics （Unity）

2025-05-13

這很重要

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 遊戲物件的設定中已核取 Use Analytics 。

會話和裝置資訊

新增 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 將會停止收集應用程式的分析資訊。若要停用分析，請使用下列 API，以 false 參數的形式傳遞。

Analytics.SetEnabledAsync(false);

若要再次啟用App Center Analytics，請使用相同的API，但傳遞 true 做為參數。

Analytics.SetEnabledAsync(true);

狀態會保存在裝置跨應用程式啟動時的記憶體中。

此 API 是異步的，您可以在我們的 App Center 異步 API 指南中深入瞭解。

檢查 App Center 分析是否已啟用

您也可以檢查 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 指南中深入瞭解。

管理啟動工作階段

根據預設，會話標識碼取決於應用程式的生命週期。如果您想要手動控制新工作階段的開始，請遵循後續步驟：

備註

請注意 ，Analytics.StartSession（） API 的每個呼叫都會產生新的會話。如果在手動會話追蹤器模式下未呼叫此 API，則所有傳送記錄將具有空會話值。

備註

請注意，在新的應用程式啟動之後，會話標識碼將會重新產生。

在附加了 AppCenterBehavior 的遊戲物件上，取消勾選 [分析] 區段中的 [啟用手動會話追蹤] 勾選框。
接著，您可以在 StartSession 之後使用 AppCenter.Start API。

Analytics.StartSession();

本機儲存體大小

根據預設，SDK 會將最多 10 MB 的記錄儲存在記憶體中。

沒有因特網存取

當沒有任何網路連線時，SDK 會在本機記憶體中儲存最多 10 MB 的記錄。記憶體已滿之後，SDK 會開始捨棄舊的記錄，以騰出空間供新的記錄使用。裝置返回因特網存取之後，SDK 會每隔 6 秒傳送 50 或之後的記錄。

批處理事件記錄

App Center SDK 會在 50 個批次中上傳記錄，如果 SDK 沒有 50 個要傳送的記錄，它仍會在 6 秒後傳送記錄。最多可以平行傳送三個批次。

重試和退避邏輯

App Center SDK 支援可復原網路錯誤的回復重試。以下是重試邏輯：

每個請求最多可嘗試3次。
每個請求都有自己的重試狀態機。
在一個請求耗盡其所有重試後，所有傳輸通道都會停用（直到下一次應用程式進程）。

退後邏輯

50% 隨機化，第一次重試 5 到 10 秒，第二次重試介於 2.5 到 5 分鐘之間，最後一次嘗試介於 10 到 20 分鐘之間。
如果網路從關閉切換為開啟（或從 wi-fi 切換至行動裝置），則會重設重試狀態，並立即重試要求。

共用方式為