App Center Analytics (tvOS)

Importante

Visual Studio App Center está programado para retirarse el 31 de marzo de 2025. Aunque puede seguir usando Visual Studio App Center hasta que se retire por completo, hay varias alternativas recomendadas a las que puede considerar la posibilidad de migrar.

Obtenga más información sobre las escalas de tiempo y las alternativas de soporte técnico.

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

App Center Analytics le ayuda a comprender el comportamiento del usuario y la participación del cliente para mejorar la aplicación. El SDK captura automáticamente el recuento de sesiones y las propiedades del dispositivo, como el modelo, la versión del sistema operativo, etc. Puede definir sus propios eventos personalizados para medir las cosas que le importan. Toda la información capturada está disponible en el portal de App Center para analizar los datos.

Nota

El país del operador y el nombre del operador no están disponibles en App Center Analytics para tvOS, pero puede establecer el país del operador con la ubicación del dispositivo.

Nota

En la 4.0.0 versión de App Center se introdujeron cambios importantes. Siga la sección Migrar a App Center SDK 4.0.0 y versiones posteriores para migrar App Center desde versiones anteriores.

Siga la sección Introducción si aún no ha configurado el SDK en la aplicación.

Información de la sesión y del dispositivo

Una vez que agregue App Center Analytics a la aplicación e inicie el SDK, realizará un seguimiento automático de las sesiones y las propiedades del dispositivo, incluida la versión del sistema operativo, el modelo, etc., sin código adicional.

Nota

En las aplicaciones de Mac Catalyst, la cantidad de sesiones puede ser menor que en las aplicaciones de iOS. Los eventos del ciclo de vida que se usan para realizar un seguimiento de las sesiones en Mac Catalyst se comportan de forma diferente a las de iOS.

El SDK notifica automáticamente el código de país de un usuario si el dispositivo tiene instalado un módem de datos móviles y una tarjeta SIM. Los dispositivos solo WiFi no notificarán un código de país de forma predeterminada. Para establecer el código de país de esos usuarios, debe recuperar la ubicación del usuario usted mismo y usar el setCountryCode: método en el SDK. Nuestro consejo es tener en cuenta el seguimiento de las ubicaciones de los usuarios y usar una resolución de ubicación baja. En el ejemplo siguiente se usa kCLLocationAccuracyKilometer.

• Asegúrese de habilitar Location Services en el dispositivo.
• Obtenga la ubicación actual del dispositivo mediante CLLocationManager.
• Convierta la ubicación en un código de país ISO mediante CLGeocoder.
• Invalide el código de país del operador mediante el método del setCountryCode SDK.

Use el código siguiente para obtener la ubicación del dispositivo e invalidar el código de país del operador en la aplicación:

Agregue el protocolo CLLocationManagerDelegate a AppDelegate y agregue la propiedad locationManager:

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

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

En didFinishLaunchingWithOptions: método configura el administrador de ubicaciones:

  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

El requestWhenInUseAuthorization método no está disponible para macOS. Quite las llamadas a ese método al desarrollar para macOS.

Agregue los métodos delegados:

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

Eventos personalizados

Puede realizar un seguimiento de sus propios eventos personalizados con hasta 20 propiedades para saber lo que sucede en la aplicación, comprender las acciones del usuario y ver los agregados en el portal de App Center.

Una vez que haya iniciado el SDK, use el método para realizar un trackEvent:withProperties seguimiento de los eventos con propiedades. Puede enviar hasta 200 nombres de eventos distintos. Además, hay un límite máximo de 256 caracteres por nombre de evento y 125 caracteres por nombre de propiedad de evento y valor de propiedad de evento.

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

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

Las propiedades de los eventos son totalmente opcionales: si solo desea realizar un seguimiento de un evento, use este ejemplo en su lugar:

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

Prioridad y persistencia de eventos

Puede realizar un seguimiento de los eventos críticos para la empresa que tienen mayor importancia que otros eventos.

• Los desarrolladores pueden establecer la prioridad de los eventos como Normal (FlagsNormal en la API) o Crítico (FlagsCritical en la API).
• Los eventos con prioridad establecida como Crítico se recuperarán primero del almacenamiento y se enviarán antes de los eventos Normal .
• Cuando el almacenamiento local está lleno y es necesario almacenar nuevos eventos. Los eventos más antiguos con la prioridad más baja se eliminan primero para dejar espacio para los nuevos.
• Si el almacenamiento está lleno de registros con prioridad crítica , se producirá un error en el seguimiento de un evento con prioridad normal , ya que el SDK no puede dejar espacio en ese caso.
• Si también usa el servicio Crashes , los registros de bloqueo se establecen como Crítico y comparten el mismo almacenamiento que los eventos.
• El intervalo de transmisión solo se aplica a los eventos Normal , los eventos críticos se enviarán después de 3 segundos.

Puede usar la SIGUIENTE API para realizar un seguimiento de un evento como Crítico:

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.

Pausar y reanudar el envío de registros

La pausa de la transmisión de eventos puede ser útil en escenarios en los que la aplicación necesita controlar el ancho de banda de red para satisfacer necesidades más críticas para la empresa. Puede pausar el envío de registros al back-end de App Center. Cuando está en pausa, los eventos se pueden seguir y guardar, pero no se envían de inmediato. Cualquier evento que realice el seguimiento de la aplicación mientras esté en pausa solo se enviará una vez que llame a resume.

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

Habilitación o deshabilitación de App Center Analytics en tiempo de ejecución

Puede habilitar y deshabilitar App Center Analytics en tiempo de ejecución. Si la deshabilita, el SDK no recopilará más información de análisis para la aplicación.

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

Para volver a habilitar App Center Analytics, use la misma API, pero pase YES/true como parámetro.

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

El estado se conserva en el almacenamiento del dispositivo en los inicios de la aplicación.

Nota

Este método solo se debe usar después Analytics de haberse iniciado.

Comprobación de si App Center Analytics está habilitado

También puede comprobar si App Center Analytics está habilitado o no.

[MSACAnalytics isEnabled];

Analytics.enabled

Nota

Este método solo se debe usar después Analytics de que se haya iniciado, siempre devolverá NO o false antes del inicio.

Administrar sesión de inicio

De forma predeterminada, el identificador de sesión depende del ciclo de vida de la aplicación. Si desea controlar manualmente el inicio de una nueva sesión, siga los pasos siguientes:

Nota

Preste atención a que cada llamada de analytics.StartSession() API generará una nueva sesión. Si en el modo de seguimiento de sesión manual, no se llamará a esta API, todos los registros de envío tendrán un valor de sesión null.

Nota

Preste atención a que después de que se inicie una nueva aplicación, se volverá a generar el identificador de sesión.

• Llame al método siguiente antes de que se inicie el SDK:

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

• A continuación, puede usar la startSession API después de AppCenter.start:

[MSACAnalytics startSession];

Analytics.startSession()

Tamaño del almacenamiento local

De forma predeterminada, el SDK almacena todos los registros hasta 10 MB. Los desarrolladores pueden usar una API para aumentar el tamaño de almacenamiento y el SDK seguirá almacenando los registros hasta que el almacenamiento esté lleno.

Sin acceso a Internet

Cuando no hay conectividad de red, el SDK guarda hasta 10 MB de registros en el almacenamiento local. Una vez que el almacenamiento está lleno, el SDK comienza a descartar los registros antiguos para dejar espacio para los nuevos registros. Una vez que se devuelve la conectividad de red, el SDK envía registros en el lote de 50 o después de cada 6 segundos (de forma predeterminada).

Nota

Los registros anteriores a 25 días se descartarán.

Procesamiento por lotes de registros de eventos

El SDK de App Center carga los registros en un lote de 50 y, si el SDK no tiene 50 registros para enviar, seguirá enviando registros después de 6 segundos (de forma predeterminada). Puede haber un máximo de tres lotes enviados en paralelo. El intervalo de transmisión se puede cambiar:

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

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

El valor del intervalo de transmisión debe estar entre 6 segundos y 86400 segundos (un día) y se debe llamar a este método antes de que se inicie el servicio.

Lógica de reintento y retroceso

El SDK de App Center admite reintentos de retroceso en errores de red recuperables. A continuación se muestra la lógica de reintento:

• Tres intentos máximo por solicitud.
• Cada solicitud tiene su propia máquina de estado de reintento.
• Todos los canales de transmisión están deshabilitados (hasta el siguiente proceso de aplicación) después de que una solicitud agote todos sus reintentos.

Lógica de retroceso

• 50 % de selección aleatoria, primer reintento entre 5 y 10 segundos, segundo reintento entre 2,5 y 5 minutos, último intento entre 10 y 20 minutos.
• Si la red cambia de apagado a activado (o desde wi-fi a móvil), los estados de reintento se restablecen y las solicitudes se reintentan inmediatamente.