App Center Analytics (tvOS)

重要

Visual Studio App Center 已排定於 2025 年 3 月 31 日淘汰。 雖然您可以繼續使用 Visual Studio App Center，直到完全淘汰為止，但有數個建議的替代方案可以考慮移轉至。

深入瞭解支持時程表和替代方案。

• Android
• iOS
• React Native \(英文\)
• Windows
• MAUI/Xamarin
• Unity
• macOS
• tvOS
• Cordova

App Center Analytics 可協助您了解使用者行為和客戶參與，以改善您的應用程式。 SDK 會自動擷取會話計數和裝置屬性，例如模型、OS 版本等。您可以定義自己的自定義事件，以測量對您而言很重要的專案。 您可以在 App Center 入口網站中取得擷取的所有資訊，以便您分析數據。

注意

tvOS 的 App Center Analytics 不提供貨運公司國家/地區和電信業者名稱，但您可以使用您的裝置位置來設定電信業者國家/地區。

注意

4.0.0在 App Center 重大變更版本中引進。 遵循 移轉至 App Center SDK 4.0.0 和更新 版本一節，從舊版移轉 App Center。

如果您尚未在應用程式中設定 SDK，請遵循 開始使用 一節。

會話和裝置資訊

將 App Center Analytics 新增至您的應用程式並啟動 SDK 之後，它會自動追蹤會話和裝置屬性，包括 OS 版本、模型等等，而不需要任何其他程式碼。

注意

在 Mac 上，會話數量可能會低於 iOS 應用程式。 用來追蹤 Mac Catalyst 上會話的生命週期事件與 iOS 上的會話不同。

如果裝置已安裝行動數據數據數據機和 SIM 卡，SDK 會自動報告使用者的國家/地區代碼。 僅限WiFi的裝置預設不會報告國家/地區代碼。 若要設定這些使用者的國家/地區代碼，您必須自行擷取使用者的位置，並使用 setCountryCode: SDK中的方法。 我們的建議是留意追蹤使用者位置，並使用低位置解析度。 下列範例使用 kCLLocationAccuracyKilometer。

• 請確定您在裝置上 啟用位置服務 。
• 使用 CLLocationManager取得裝置的目前位置。
• 使用 CLGeocoder將位置轉換成 ISO 國家/地區代碼。
• 使用 SDK 的 setCountryCode 方法來覆寫貨運公司國家/地區代碼。

使用下列程式代碼取得裝置的位置，並覆寫應用程式中的電信業者國家/地區代碼：

將 CLLocationManagerDelegate 通訊協定新增至 AppDelegate，並新增 locationManager 属性：

@interface AppDelegate () <CLLocationManagerDelegate>
@property(nonatomic) CLLocationManager *locationManager;
@end

class AppDelegate: CLLocationManagerDelegate {
  private var locationManager: CLLocationManager = CLLocationManager()
}

在 didFinishLaunchingWithOptions：方法設定位置管理員：

  self.locationManager = [[CLLocationManager alloc] init];
  self.locationManager.delegate = self;
  self.locationManager.desiredAccuracy = kCLLocationAccuracyKilometer;
  [self.locationManager requestWhenInUseAuthorization];

  self.locationManager.delegate = self
  self.locationManager.desiredAccuracy = kCLLocationAccuracyKilometer
  self.locationManager.requestWhenInUseAuthorization()

注意

macOS requestWhenInUseAuthorization 無法使用 方法。 針對macOS進行開發時，請移除該方法的呼叫。

新增委派方法：

- (void)locationManager:(CLLocationManager *)manager didChangeAuthorizationStatus:(CLAuthorizationStatus)status {
  if (status == kCLAuthorizationStatusAuthorizedWhenInUse) {
    [manager requestLocation];
  }
}

- (void)locationManger:(CLLocationManager *)manager didUpdateLocations:(NSArray<CLLocation *> *)locations {
  CLLocation *location = [locations lastObject];
  CLGeocoder *geocoder = [[CLGeocoder alloc] init];
  [geocoder reverseGeocodeLocation:location
                 completionHandler:^(NSArray *placemarks, NSError *error) {
                   if (placemarks.count == 0 || error)
                     return;
                   CLPlacemark *pm = [placemarks firstObject];
                   [MSACAppCenter setCountryCode:pm.ISOcountryCode];
                 }]
}

- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error {
  NSLog(@"Failed to find user's location: \(error.localizedDescription)");
}

func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
  if (status == kCLAuthorizationStatusAuthorizedWhenInUse) {
    manager.requestLocation()
  }
}

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
  let userLocation:CLLocation = locations[0] as CLLocation
  CLGeocoder().reverseGeocodeLocation(userLocation) { (placemarks, error) in
    if error == nil {
      AppCenter.countryCode = placemarks?.first?.isoCountryCode
    }
  }
}
  
func locationManager(_ Manager: CLLocationManager, didFailWithError error: Error) {
  print("Failed to find user's location: \(error.localizedDescription)")
}

自訂事件

您可以使用 最多 20 個屬性 來追蹤自己的自定義事件，以瞭解應用程式發生的情況、瞭解用戶動作，以及查看 App Center 入口網站中的匯總。

啟動 SDK 之後，請使用 trackEvent:withProperties 方法來追蹤事件與屬性。 您最多可以傳送 200 個不同的事件名稱。 此外，每個事件名稱的最大限制為 256 個字元，每個事件屬性名稱和事件屬性值有 125 個字元。

NSDictionary *properties = @{@"Category" : @"Music", @"FileName" : @"favorite.avi"};
[MSACAnalytics trackEvent:@"Video clicked" withProperties: properties];

Analytics.trackEvent("Video clicked", withProperties: ["Category" : "Music", "FileName" : "favorite.avi"])

事件的屬性是完全選擇性的 – 如果您只想要追蹤事件，請改用此範例：

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

事件優先順序和持續性

您可以追蹤重要性高於其他事件的商務關鍵事件。

• 開發人員可以在 API) 或 API) 中將事件優先順序設定為 標準FlagsNormal (或 重大 (FlagsCritical 。
• 優先順序設定為 [重大 ] 的事件會先從記憶體擷取，並在 一般 事件之前傳送。
• 當本機記憶體已滿且需要儲存新的事件時。 系統會先刪除優先順序最低的最舊事件，讓新事件有空間。
• 如果記憶體已滿含 重大 優先順序的記錄，則追蹤具有 正常 優先順序的事件將會失敗，因為 SDK 在該情況下無法有空間。
• 如果您也使用 當機 服務，當機記錄會設定為 [重大 ]，並共用與事件相同的記憶體。
• 傳輸間隔只會套用至 一般 事件， 重大 事件會在 3 秒後傳送。

您可以使用下列 API，將事件追蹤為 [重大]：

NSDictionary *properties = @{@"Category" : @"Music", @"FileName" : @"favorite.avi"};
[MSACAnalytics trackEvent:@"Video clicked" withProperties:properties flags:MSACFlagsCritical];

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

let properties = ["Category" : "Music", "FileName" : "favorite.avi"];
Analytics.trackEvent("Video clicked", withProperties: properties, flags: .critical)

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

暫停和繼續傳送記錄

暫停事件傳輸在應用程式需要控制網路頻寬以取得更多業務關鍵需求的案例中很有用。 您可以暫停將記錄傳送至 App Center 後端。 暫停時，事件仍可追蹤和儲存，但不會立即傳送。 應用程式在暫停時追蹤的任何事件，只會在您呼叫 resume之後傳送。

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

在運行時間啟用或停用 App Center Analytics

您可以在運行時間啟用和停用 App Center Analytics。 如果您停用此功能，SDK 將不會收集應用程式的任何其他分析資訊。

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

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

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

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

注意

只有在啟動之後 Analytics ，才能使用這個方法。

檢查 App Center Analytics 是否已啟用

您也可以檢查 App Center Analytics 是否已啟用。

[MSACAnalytics isEnabled];

Analytics.enabled

注意

這個方法只能在啟動之後 Analytics 使用，它一律會傳回 NO 或 false 啟動之前。

管理開始會話

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

注意

請注意，每個 Analytics.StartSession () API 呼叫都會產生新的會話。 如果在手動會話追蹤器模式中，將不會呼叫此 API，則所有傳送記錄都會有 Null 會話值。

注意

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

• 在 SDK 啟動之前呼叫下列方法：

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

• 然後，您可以在 之後AppCenter.start使用 startSession API：

[MSACAnalytics startSession];

Analytics.startSession()

本機儲存體大小

根據預設，SDK 會儲存最多 10 MB 的所有記錄。 開發人員可以使用 API 來增加 記憶體大小 ，而 SDK 會持續儲存記錄，直到記憶體已滿為止。

沒有因特網存取

當沒有任何網路連線時，SDK 會在本機記憶體中儲存最多 10 MB 的記錄。 記憶體已滿之後，SDK 會開始捨棄舊的記錄，以空間容納新的記錄。 一旦網路連線傳回，SDK 預設會每隔 6 秒傳送 50 或每隔 6 秒 (記錄) 。

注意

超過25天的記錄將會捨棄。

批處理事件記錄

App Center SDK 會以 50 個批次上傳記錄，如果 SDK 沒有 50 個要傳送的記錄，它預設仍會在 6 秒後傳送記錄 () 。 最多可以平行傳送三個批次。 傳輸間隔可以變更：

// Change transmission interval to 10 seconds.
[MSACAnalytics setTransmissionInterval:10000];

// Change transmission interval to 10 seconds.
Analytics.transmissionInterval = 10000

傳輸間隔值必須介於 6 秒到 86400 秒之間， (一天) ，而且必須先呼叫此方法，才能啟動服務。

重試和回復邏輯

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

• 三次嘗試每個要求的最大次數。
• 每個要求都有自己的重試狀態機器。
• 所有傳輸通道都會停用 (，直到下一個應用程式進程在一個要求耗盡所有重試之後) 為止。

倒退邏輯

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