App Center Analytics (iOS)

Importante

Visual Studio App Center è previsto per il ritiro il 31 marzo 2025. Anche se è possibile continuare a usare Visual Studio App Center fino a quando non viene completamente ritirato, esistono diverse alternative consigliate che è possibile considerare la migrazione a.

Altre informazioni sulle sequenze temporali di supporto e sulle alternative.

• Android
• iOS
• React Native
• Windows
• MAUI/Xamarin
• Unity
• macOS
• tvOS
• Cordova

App Center Analytics consente di comprendere il comportamento degli utenti e il coinvolgimento dei clienti per migliorare l'app. L'SDK acquisisce automaticamente il conteggio delle sessioni e le proprietà del dispositivo, ad esempio modello, versione del sistema operativo e così via. È possibile definire gli eventi personalizzati per misurare le cose che importa. Tutte le informazioni acquisite sono disponibili nel portale di App Center per analizzare i dati.

Nota

I dispositivi iOS senza una scheda SIM non invierà il report con il codice del paese del vettore al portale di App Center. Se si vuole specificare un valore del paese, usare il metodo per eseguire l'override del setCountryCode codice paese dalla posizione del dispositivo.

Nota

4.0.0 Nella versione di App Center sono state introdotte modifiche di rilievo. Seguire la sezione Migrate to App Center SDK 4.0.0 e versioni successive per eseguire la migrazione di App Center dalle versioni precedenti.

Seguire la sezione Introduzione se non è ancora stato configurato l'SDK nell'applicazione.

Informazioni sulla sessione e sul dispositivo

Dopo aver aggiunto App Center Analytics all'app e avviare l'SDK, tiene traccia automaticamente delle sessioni e delle proprietà del dispositivo, tra cui versione del sistema operativo, modello e così via, senza alcun codice aggiuntivo.

Nota

Nelle app Mac Catalyst la quantità di sessioni può essere inferiore rispetto alle app iOS. Gli eventi del ciclo di vita usati per tenere traccia delle sessioni in Mac Catalyst si comportano in modo diverso da quelli in iOS.

L'SDK segnala automaticamente il codice paese di un utente se il dispositivo ha un modem dati mobile e una scheda SIM installata. Per impostazione predefinita, i dispositivi solo WiFi non segnalano un codice paese. Per impostare il codice paese di tali utenti, è necessario recuperare la posizione dell'utente e usare il setCountryCode: metodo nell'SDK. Il nostro consiglio è quello di tenere presente il rilevamento delle posizioni degli utenti e usare una risoluzione a bassa posizione. L'esempio seguente usa kCLLocationAccuracyKilometer.

• Assicurarsi di abilitare Servizi di posizione nel dispositivo.
• Ottenere la posizione corrente del dispositivo usando CLLocationManager.
• Convertire la posizione in un codice paese ISO usando CLGeocoder.
• Eseguire l'override del codice paese del vettore usando il metodo dell'SDK setCountryCode .

Usare il codice seguente per ottenere la posizione del dispositivo ed eseguire l'override del codice paese del vettore nell'app:

Aggiungere il protocollo CLLocationManagerDelegate all'AppDelegate e aggiungere la proprietà locationManager:

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

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

Nel metodo didFinishLaunchingWithOptions: configurare il gestore della posizione:

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

Nota

Il requestWhenInUseAuthorization metodo non è disponibile per macOS. Rimuovere le chiamate a tale metodo durante lo sviluppo per macOS.

Aggiungere i metodi delegati:

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

Eventi personalizzati

È possibile tenere traccia dei propri eventi personalizzati con un massimo di 20 proprietà per sapere cosa accade nell'app, comprendere le azioni utente e visualizzare le aggregazioni nel portale di App Center.

Dopo aver avviato l'SDK, usare il trackEvent:withProperties metodo per tenere traccia degli eventi con le proprietà. È possibile inviare fino a 200 nomi di eventi distinti. È inoltre previsto un limite massimo di 256 caratteri per nome evento e 125 caratteri per nome della proprietà evento e valore della proprietà evento.

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

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

Le proprietà per gli eventi sono completamente facoltative: se si vuole tenere traccia di un evento, usare invece questo esempio:

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

Priorità e persistenza degli eventi

È possibile tenere traccia degli eventi critici aziendali che hanno un'importanza maggiore rispetto ad altri eventi.

• Gli sviluppatori possono impostare la priorità degli eventi come Normal (nell'API) o Critical (FlagsCriticalFlagsNormalnell'API).
• Gli eventi con priorità impostata come Critical verranno recuperati prima dell'archiviazione e inviati prima degli eventi normali .
• Quando l'archiviazione locale è completa e devono essere archiviati nuovi eventi. Gli eventi meno recenti con la priorità più bassa vengono eliminati prima per renderli disponibili per i nuovi.
• Se l'archiviazione è piena di log con priorità critica , il rilevamento di un evento con priorità normale avrà esito negativo perché l'SDK non può rendere spazio in questo caso.
• Se si usa anche il servizio Arresti anomali, i log di arresto anomalo vengono impostati come Critici e condividono lo stesso spazio di archiviazione degli eventi.
• L'intervallo di trasmissione viene applicato solo agli eventi normali , gli eventi critici verranno inviati dopo 3 secondi.

È possibile usare l'API seguente per tenere traccia di un evento come Critico:

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.

Sospendere e riprendere l'invio dei log

La sospensione della trasmissione degli eventi può essere utile negli scenari in cui l'app deve controllare la larghezza di banda di rete per esigenze più critiche aziendali. È possibile sospendere l'invio dei log al back-end di App Center. Quando viene sospeso, gli eventi possono comunque essere rilevati e salvati, ma non vengono inviati immediatamente. Tutti gli eventi che l'app tiene traccia durante la sospensione verranno inviati solo dopo aver chiamato resume.

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

Abilitare o disabilitare App Center Analytics in fase di esecuzione

È possibile abilitare e disabilitare App Center Analytics in fase di esecuzione. Se la disabilita, l'SDK non raccoglierà altre informazioni di analisi per l'app.

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

Per abilitare di nuovo App Center Analytics, usare la stessa API ma passare YES/true come parametro.

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

Lo stato viene mantenuto nello spazio di archiviazione del dispositivo tra i lanci dell'applicazione.

Nota

Questo metodo deve essere usato solo dopo Analytics l'avvio.

Verificare se App Center Analytics è abilitato

È anche possibile verificare se App Center Analytics è abilitato o meno.

[MSACAnalytics isEnabled];

Analytics.enabled

Nota

Questo metodo deve essere usato solo dopo Analytics l'avvio, restituirà sempre NO o false prima dell'avvio.

Gestire la sessione iniziale

Per impostazione predefinita, l'ID sessione dipende dal ciclo di vita dell'applicazione. Per controllare manualmente l'inizio di una nuova sessione, seguire i passaggi successivi:

Nota

Prestare attenzione che ogni chiamata dell'API Analytics.StartSession() genererà una nuova sessione. Se in modalità di rilevamento sessione manuale questa API non verrà chiamata, tutti i log di invio avranno un valore di sessione Null.

Nota

Prestare attenzione che dopo l'avvio di una nuova applicazione l'ID sessione verrà rigenerato.

• Chiamare il metodo seguente prima dell'avvio dell'SDK:

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

• È quindi possibile usare l'API startSession dopo :AppCenter.start

[MSACAnalytics startSession];

Analytics.startSession()

Dimensioni di archiviazione locale

Per impostazione predefinita, l'SDK archivia tutti i log fino a 10 MB. Gli sviluppatori possono usare un'API per aumentare le dimensioni di archiviazione e l'SDK manterrà l'archiviazione dei log fino a quando l'archiviazione non è completa.

Nessun accesso a Internet

Quando non esiste connettività di rete, l'SDK salva fino a 10 MB di log nell'archiviazione locale. Una volta completata l'archiviazione, l'SDK inizia a eliminare i vecchi log per rendere disponibili i nuovi log. Una volta restituita la connettività di rete, l'SDK invia i log nel batch di 50 o dopo ogni 6 secondi (per impostazione predefinita).

Nota

I log precedenti a 25 giorni verranno eliminati.

Batching di log eventi

App Center SDK carica i log in un batch di 50 e se l'SDK non dispone di 50 log da inviare, i log verranno comunque inviati dopo 6 secondi (per impostazione predefinita). È possibile inviare un massimo di tre batch in parallelo. L'intervallo di trasmissione può essere modificato:

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

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

Il valore dell'intervallo di trasmissione deve essere compreso tra 6 secondi e 86400 secondi (un giorno) e questo metodo deve essere chiamato prima dell'avvio del servizio.

Logica di ripetizione e back-off

App Center SDK supporta i tentativi di back-off in caso di errori di rete ripristinabili. Di seguito è riportata la logica di ripetizione dei tentativi:

• Tre tentativi massimo per richiesta.
• Ogni richiesta ha una propria macchina a stati di ripetizione dei tentativi.
• Tutti i canali di trasmissione vengono disabilitati (fino al processo successivo dell'app) dopo che una richiesta esaurisce tutti i tentativi.

Logica di back-off

• 50% casuale, primo tentativo tra 5 e 10 secondi, secondo tentativo tra 2,5 e 5 minuti, ultimo tentativo compreso tra 10 e 20 minuti.
• Se la rete passa da off a on (o da Wi-Fi a mobile), gli stati di ripetizione dei tentativi vengono reimpostati e le richieste vengono ritentate immediatamente.