Condividi tramite

App Center Analytics (tvOS)

  • Articolo

Importante

Visual Studio App Center è pianificato 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 a cui è possibile prendere in considerazione la migrazione.

Altre informazioni sulle sequenze temporali di supporto e sulle alternative.

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

Nota

Il paese del vettore e il nome del vettore non sono disponibili in App Center Analytics per tvOS, ma è possibile impostare il paese del vettore con la posizione del dispositivo.

Nota

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

Se l'SDK non è ancora stato configurato nell'applicazione, seguire la sezione Introduzione .

Informazioni sulla sessione e sul dispositivo

Dopo aver aggiunto App Center Analytics all'app e aver avviato l'SDK, tiene automaticamente traccia delle sessioni e delle proprietà del dispositivo, tra cui versione del sistema operativo, modello e così via, senza 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 dispone di un modem dati mobile e di una scheda SIM installata. I dispositivi solo Wi-Fi non segnalano un codice paese per impostazione predefinita. Per impostare il codice paese di tali utenti, è necessario recuperare manualmente la posizione dell'utente e usare il setCountryCode: metodo nell'SDK. Il nostro consiglio è quello di tenere traccia delle posizioni degli utenti e di usare una risoluzione della posizione bassa. L'esempio seguente usa kCLLocationAccuracyKilometer.

  • Assicurarsi di abilitare Location Services 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 ad AppDelegate e aggiungere la proprietà locationManager:

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

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

In didFinishLaunchingWithOptions: metodo set-up the location manager:

  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 degli eventi personalizzati con un massimo di 20 proprietà per sapere cosa accade nell'app, comprendere le azioni degli utenti 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 solo 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 business critical con un'importanza maggiore rispetto ad altri eventi.

  • Gli sviluppatori possono impostare la priorità degli eventi come Normale (FlagsNormal nell'API) o Critico (FlagsCritical nell'API).
  • Gli eventi con priorità impostata come Critico verranno recuperati dall'archiviazione prima e inviati prima degli eventi Normal .
  • Quando l'archiviazione locale è piena e devono essere archiviati nuovi eventi. Gli eventi meno recenti con la priorità più bassa vengono eliminati per primi per fare spazio a quelli nuovi.
  • Se lo spazio di archiviazione è pieno di log con priorità Critica , il rilevamento di un evento con priorità Normale avrà esito negativo perché l'SDK non può fare spazio in questo caso.
  • Se si usa anche il servizio Arresti anomali , i log di arresto anomalo vengono impostati su Critico e condividono la stessa risorsa 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 aziendali più critiche. È possibile sospendere l'invio dei log al back-end di App Center. Quando vengono sospesi, gli eventi possono comunque essere rilevati e salvati, ma non vengono inviati immediatamente. Tutti gli eventi tracciati dall'app durante la sospensione verranno inviati solo dopo la chiamata resumea .

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

Abilitare o disabilitare Analisi di App Center in fase di esecuzione

È possibile abilitare e disabilitare Analisi di App Center in fase di esecuzione. Se la si 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 salvato in modo permanente nella risorsa di archiviazione del dispositivo tra i lanci dell'applicazione.

Nota

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

Controllare se App Center Analytics è abilitato

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

[MSACAnalytics isEnabled];

Analytics.enabled

Nota

Questo metodo deve essere utilizzato solo dopo Analytics l'avvio, verrà sempre restituito NO o false prima dell'avvio.

Gestire la sessione di avvio

Per impostazione predefinita, l'ID sessione dipende dal ciclo di vita dell'applicazione. Se si vuole controllare manualmente l'inizio di una nuova sessione, seguire questa procedura:

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 che una nuova applicazione avvia 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 lo spazio di archiviazione non è pieno.

Nessun accesso a Internet

Quando non è presente alcuna connettività di rete, l'SDK salva fino a 10 MB di log nella risorsa di archiviazione locale. Una volta che lo spazio di archiviazione è pieno, l'SDK inizia a rimuovere i log precedenti per liberare spazio per 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 più vecchi di 25 giorni verranno eliminati.

Invio in batch dei 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.

Riprovare e eseguire il back-off della logica

App Center SDK supporta tentativi di back-off sugli errori di rete recuperabili. Di seguito è riportata la logica di ripetizione dei tentativi:

  • Tre tentativi massimo per richiesta.
  • Ogni richiesta ha il proprio computer di stato di ripetizione dei tentativi.
  • Tutti i canali di trasmissione sono disabilitati (fino al processo dell'app successiva) dopo che una richiesta esaurisce tutti i tentativi.

Logica di back-off

  • 50% casualizzazione, primo tentativo compreso tra 5 e 10 secondi, secondo tentativo compreso tra 2,5 e 5 minuti, ultimo tentativo compreso tra 10 e 20 minuti.
  • Se la rete passa da disattivata a (o da wi-fi a mobile), gli stati di ripetizione dei tentativi vengono reimpostati e le richieste vengono riprovate immediatamente.