App Center Analytics (macOS)

2025-05-05

Von Bedeutung

Visual Studio App Center wurde am 31. März 2025 eingestellt, mit Ausnahme der Analyse- und Diagnosefeatures, die bis zum 30. Juni 2026 weiterhin unterstützt werden. Weitere Informationen

App Center Analytics hilft Ihnen, das Benutzerverhalten und die Kundenbindung zu verstehen, um Ihre App zu verbessern. Das SDK erfasst automatisch die Sitzungsanzahl und Geräteeigenschaften wie Modell, Betriebssystemversion usw. Sie können eigene benutzerdefinierte Ereignisse definieren, um Dinge zu messen, die für Sie wichtig sind. Alle erfassten Informationen sind im App Center-Portal verfügbar, damit Sie die Daten analysieren können.

Hinweis

Das Trägerland und der Name des Netzbetreibers sind bei App Center Analytics für macOS nicht verfügbar, aber Sie können das Trägerland mit Ihrem Gerätestandort festlegen.

Hinweis

In der 4.0.0 Version des App Center wurden bahnbrechende Änderungen eingeführt. Folgen Sie dem Abschnitt "Migrieren zu App Center SDK 4.0.0" und höher , um App Center aus früheren Versionen zu migrieren.

Folgen Sie dem Abschnitt " Erste Schritte ", wenn Sie das SDK noch nicht in Ihrer Anwendung eingerichtet haben.

Sitzungs- und Geräteinformationen

Nachdem Sie App Center Analytics zu Ihrer App hinzugefügt und das SDK gestartet haben, verfolgt es automatisch Sitzungen und Geräteeigenschaften, einschließlich Betriebssystemversion, Modell usw., ohne zusätzlichen Code.

Hinweis

Bei Mac Catalyst-Apps kann die Anzahl der Sitzungen geringer sein als bei iOS-Apps. Lebenszyklusereignisse, die zum Nachverfolgen von Sitzungen auf Mac Catalyst verwendet werden, verhalten sich anders als bei iOS.

Das SDK meldet automatisch den Ländercode eines Benutzers, wenn das Gerät über ein mobiles Datenmodem und eine SIM-Karte verfügt. Nur WLAN-Geräte melden standardmäßig keinen Ländercode. Um den Ländercode dieser Benutzer festzulegen, müssen Sie den Standort Des Benutzers selbst abrufen und die setCountryCode: Methode im SDK verwenden. Unser Rat ist, auf das Nachverfolgen von Benutzerstandorten zu achten und eine geringe Standortauflösung zu verwenden. Im folgenden Beispiel wird kCLLocationAccuracyKilometer verwendet.

Stellen Sie sicher, dass Sie Standortdienste auf dem Gerät aktivieren.
Rufen Sie den aktuellen Standort des Geräts mithilfe von CLLocationManager ab.
Konvertieren Sie den Standort mithilfe von CLGeocoder in einen ISO-Ländercode.
Überschreiben Sie den Ländercode des Netzbetreibers mithilfe der Methode des setCountryCode SDK.

Verwenden Sie den folgenden Code, um den Standort des Geräts abzurufen und den Ländercode des Netzbetreibers in der App außer Kraft zu setzen:

Fügen Sie das CLLocationManagerDelegate-Protokoll zum AppDelegate hinzu, und fügen Sie die locationManager-Eigenschaft hinzu:

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

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

In der Methode didFinishLaunchingWithOptions: den Location-Manager einrichten.

  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()

Hinweis

Die requestWhenInUseAuthorization Methode ist für macOS nicht verfügbar. Entfernen Sie Aufrufe dieser Methode, wenn Sie für macOS entwickeln.

Fügen Sie die Delegatmethoden hinzu:

- (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)")
}

Benutzerdefinierte Ereignisse

Sie können ihre eigenen benutzerdefinierten Ereignisse mit bis zu 20 Eigenschaften nachverfolgen, um zu wissen, was in Ihrer App passiert, Benutzeraktionen zu verstehen und die Aggregate im App Center-Portal anzuzeigen.

Nachdem Sie das SDK gestartet haben, verwenden Sie die trackEvent:withProperties Methode, um Ihre Ereignisse mit Eigenschaften nachzuverfolgen. Sie können bis zu 200 unterschiedliche Ereignisnamen senden. Außerdem gibt es ein Maximum von 256 Zeichen pro Ereignisname und 125 Zeichen pro Ereigniseigenschaftsname und Ereigniseigenschaftswert.

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

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

Eigenschaften für Ereignisse sind vollständig optional – wenn Sie nur ein Ereignis nachverfolgen möchten, verwenden Sie stattdessen dieses Beispiel:

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

Ereignispriorität und Persistenz

Sie können geschäftskritische Ereignisse nachverfolgen, die eine höhere Bedeutung haben als andere Ereignisse.

Entwickler können die Priorität von Ereignissen als Normal (FlagsNormal in der API) oder Kritisch (FlagsCritical in der API) festlegen.
Ereignisse mit Priorität, die als kritisch festgelegt sind, werden zuerst aus dem Speicher abgerufen und vor normalen Ereignissen gesendet.
Wenn der lokale Speicher voll ist und neue Ereignisse gespeichert werden müssen. Die ältesten Ereignisse mit der niedrigsten Priorität werden zuerst gelöscht, um Platz für die neuen zu schaffen.
Wenn der Speicher voll von Protokollen mit kritischer Priorität ist, schlägt das Nachverfolgen eines Ereignisses mit normaler Priorität fehl, da das SDK in diesem Fall keinen Platz schaffen kann.
Wenn Sie auch den Absturzdienst verwenden, werden Absturzprotokolle als kritisch festgelegt und teilen denselben Speicher wie Ereignisse.
Das Übertragungsintervall wird nur auf Normale Ereignisse angewendet, kritische Ereignisse werden nach 3 Sekunden gesendet.

Sie können die folgende API verwenden, um ein Ereignis als kritisch zu verfolgen:

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.

Anhalten und Fortsetzen des Sendens von Protokollen

Das Anhalten der Ereignisübertragung kann in Szenarien hilfreich sein, wenn die App die Netzwerkbandbreite für unternehmenskritischere Anforderungen steuern muss. Sie können das Senden von Protokollen an das App Center-Back-End anhalten. Wenn sie angehalten werden, können Ereignisse weiterhin nachverfolgt und gespeichert werden, aber sie werden nicht sofort gesendet. Alle Ereignisse, die Ihre App nachverfolgt, während sie angehalten werden, werden nur gesendet, wenn Sie anrufen resume.

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

Aktivieren oder Deaktivieren von App Center Analytics zur Laufzeit

Sie können App Center Analytics zur Laufzeit aktivieren und deaktivieren. Wenn Sie es deaktivieren, sammelt das SDK keine weiteren Analyseinformationen für die App.

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

Um App Center Analytics erneut zu aktivieren, verwenden Sie dieselbe API, übergeben YES/true sie aber als Parameter.

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

Der Zustand wird im Speicher des Geräts über Anwendungsstarts hinweg beibehalten.

Hinweis

Diese Methode darf nur verwendet werden, nachdem Analytics gestartet wurde.

Überprüfen, ob App Center Analytics aktiviert ist

Sie können auch überprüfen, ob App Center Analytics aktiviert ist oder nicht.

[MSACAnalytics isEnabled];

Analytics.enabled

Hinweis

Diese Methode darf nur verwendet werden, nachdem Analytics sie gestartet wurde, sie wird immer zurückgegeben NO oder false vor dem Start.

Verwalten der Startsitzung

Standardmäßig hängt die Sitzungs-ID vom Lebenszyklus der Anwendung ab. Wenn Sie den Start einer neuen Sitzung manuell steuern möchten, führen Sie die folgenden Schritte aus:

Hinweis

Achten Sie darauf, dass jeder Aufruf der Analytics.StartSession() -API eine neue Sitzung generiert. Wenn diese API im manuellen Sitzungsverfolgungsmodus nicht aufgerufen wird, haben alle sendenden Protokolle einen NULL-Sitzungswert.

Hinweis

Achten Sie darauf, dass nach dem Starten einer neuen Anwendung die Sitzungs-ID neu generiert wird.

Rufen Sie die folgende Methode vor dem SDK-Start auf:

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

Anschließend können Sie die startSession API nach dem AppCenter.start verwenden.

[MSACAnalytics startSession];

Analytics.startSession()

Größe des lokalen Speichers

Standardmäßig speichert das SDK alle Protokolle bis zu 10 MB. Entwickler können eine API verwenden, um die Speichergröße zu erhöhen, und das SDK speichert Protokolle, bis der Speicher voll ist.

Kein Internetzugang

Wenn keine Netzwerkkonnektivität vorhanden ist, speichert das SDK bis zu 10 MB Protokolle im lokalen Speicher. Sobald der Speicher voll ist, verwirft das SDK alte Protokolle, um Platz für die neuen Protokolle zu schaffen. Sobald die Netzwerkkonnektivität zurückkehrt, sendet das SDK Protokolle in Paketen von 50 oder alle 6 Sekunden (standardmäßig).

Hinweis

Die Protokolle, die älter als 25 Tage sind, werden verworfen.

Ereignisprotokolle im Batchmodus

Das App Center SDK lädt Protokolle in einem Batch von 50 hoch und wenn das SDK nicht über 50 zu sendende Protokolle verfügt, sendet es weiterhin Protokolle nach 6 Sekunden (standardmäßig). Es können maximal drei Batches parallel gesendet werden. Das Übertragungsintervall kann geändert werden:

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

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

Der Übertragungsintervallwert muss zwischen 6 Sekunden und 86400 Sekunden (ein Tag) betragen, und diese Methode muss aufgerufen werden, bevor der Dienst gestartet wird.

Wiederholungs- und Back-off-Logik

Das App Center SDK unterstützt Back-off-Wiederholungen bei wiederherstellbaren Netzwerkfehlern. Nachfolgend finden Sie die Wiederholungslogik:

Maximal drei Versuche pro Anforderung.
Jede Anforderung verfügt über einen eigenen Wiederholungsmechanismus.
Alle Übertragungskanäle werden (bis zum nächsten App-Prozess) deaktiviert, nachdem eine Anforderung alle Wiederholungen aufgebraucht hat.

Rückzug-Logik

50% Randomisierung, erste Wiederholung zwischen 5 und 10 Sekunden, zweite Wiederholung zwischen 2,5 und 5 Minuten, letzter Versuch zwischen 10 und 20 Minuten.
Wenn das Netzwerk von "aus" nach "ein" (oder von wi-fi zu "mobil") umgeschaltet wird, werden Wiederholungszustände zurückgesetzt, und Anforderungen werden sofort wiederholt.

Freigeben über

App Center Analytics (macOS)

Sitzungs- und Geräteinformationen

Benutzerdefinierte Ereignisse

Ereignispriorität und Persistenz

Anhalten und Fortsetzen des Sendens von Protokollen

Aktivieren oder Deaktivieren von App Center Analytics zur Laufzeit

Überprüfen, ob App Center Analytics aktiviert ist

Verwalten der Startsitzung

Größe des lokalen Speichers

Kein Internetzugang

Ereignisprotokolle im Batchmodus

Wiederholungs- und Back-off-Logik

Feedback

Zusätzliche Ressourcen