Análise do App Center (macOS)

Importante

O Visual Studio App Center está programado para ser desativado em 31 de março de 2025. Embora você possa continuar a usar o Visual Studio App Center até que ele seja totalmente desativado, há várias alternativas recomendadas para as quais você pode considerar a migração.

Saiba mais sobre linhas do tempo e alternativas de suporte.

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

A Análise do App Center ajuda você a entender o comportamento do usuário e o envolvimento do cliente para melhorar seu aplicativo. O SDK captura automaticamente a contagem de sessão e as propriedades do dispositivo, como modelo, versão do sistema operacional etc. Você pode definir seus próprios eventos personalizados para medir coisas importantes para você. Todas as informações capturadas estão disponíveis no portal do App Center para você analisar os dados.

Observação

O país da operadora e o nome da operadora não estão disponíveis na Análise do App Center para macOS, mas você pode definir o país da operadora com a localização do dispositivo.

Observação

4.0.0 Na versão do App Center, foram introduzidas alterações interruptivas. Siga a seção Migrar para o SDK do App Center 4.0.0 e superior para migrar o App Center de versões anteriores.

Siga a seção Introdução se você ainda não configurou o SDK em seu aplicativo.

Informações sobre a sessão e o dispositivo

Depois de adicionar a Análise do App Center ao seu aplicativo e iniciar o SDK, ele acompanhará automaticamente as sessões e as propriedades do dispositivo, incluindo a versão do sistema operacional, o modelo e assim por diante, sem nenhum código adicional.

Observação

Em aplicativos Mac Catalyst, a quantidade de sessões pode ser menor do que em aplicativos iOS. Os eventos de ciclo de vida usados para acompanhar sessões no Mac Catalyst se comportam de forma diferente daqueles no iOS.

O SDK relatará automaticamente o código do país de um usuário se o dispositivo tiver um modem de dados móvel e um SIM cartão instalado. Os dispositivos somente WiFi não relatarão um código de país por padrão. Para definir o código de país desses usuários, você deve recuperar a localização do usuário por conta própria e usar o setCountryCode: método no SDK. Nosso conselho é estar atento ao acompanhamento de locais do usuário e usar uma resolução de localização baixa. O exemplo abaixo usa a kCLLocationAccuracyKilometer.

• Certifique-se de habilitar os Serviços de Localização no dispositivo.
• Obtenha o local atual do dispositivo usando CLLocationManager.
• Converta o local em um código de país ISO usando CLGeocoder.
• Substitua o código do país da operadora usando o método do setCountryCode SDK.

Use o seguinte código para obter a localização do dispositivo e substituir o código do país da operadora no aplicativo:

Adicione o protocolo CLLocationManagerDelegate ao AppDelegate e adicione a propriedade locationManager:

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

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

No método didFinishLaunchingWithOptions: configure o gerenciador de localização:

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

Observação

O requestWhenInUseAuthorization método não está disponível para macOS. Remova chamadas para esse método ao desenvolver para macOS.

Adicione os 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

Você pode acompanhar seus próprios eventos personalizados com até 20 propriedades para saber o que está acontecendo em seu aplicativo, entender as ações do usuário e ver as agregações no portal do App Center.

Depois de iniciar o SDK, use o trackEvent:withProperties método para acompanhar seus eventos com propriedades. Você pode enviar até 200 nomes de eventos distintos. Além disso, há um limite máximo de 256 caracteres por nome de evento e 125 caracteres por nome da propriedade do evento e valor da propriedade do evento.

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

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

As propriedades para eventos são totalmente opcionais– se você quiser apenas acompanhar um evento, use este exemplo em vez disso:

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

Prioridade e persistência do evento

Você pode acompanhar eventos comercialmente críticos que têm maior importância do que outros eventos.

• Os desenvolvedores podem definir a prioridade dos eventos como Normal (FlagsNormal na API) ou Crítico (FlagsCritical na API).
• Eventos com prioridade definida como Crítico serão recuperados do armazenamento primeiro e enviados antes dos eventos normais .
• Quando o armazenamento local estiver cheio e novos eventos precisarem ser armazenados. Os eventos mais antigos com a prioridade mais baixa são excluídos primeiro para abrir espaço para os novos.
• Se o armazenamento estiver cheio de logs com prioridade crítica , o acompanhamento de um evento com prioridade normal falhará, pois o SDK não poderá abrir espaço nesse caso.
• Se você também usar o serviço Falhas , os logs de falha serão definidos como Críticos e compartilharão o mesmo armazenamento que os eventos.
• O intervalo de transmissão só é aplicado a eventos normais , eventos críticos serão enviados após 3 segundos.

Você pode usar a seguinte API para acompanhar um 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 e retomar o envio de logs

Pausar a transmissão de eventos pode ser útil em cenários em que o aplicativo precisa controlar a largura de banda da rede para obter mais necessidades críticas para os negócios. Você pode pausar o envio de logs para o back-end do App Center. Quando pausados, os eventos ainda podem ser rastreados e salvos, mas não são enviados imediatamente. Todos os eventos que seu aplicativo rastreia enquanto está em pausa só serão enviados quando você chamar resume.

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

Habilitar ou desabilitar a Análise do App Center em runtime

Você pode habilitar e desabilitar a Análise do App Center em runtime. Se você desabilitar, o SDK não coletará mais informações de análise para o aplicativo.

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

Para habilitar a Análise do App Center novamente, use a mesma API, mas passe YES/true como um parâmetro.

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

O estado é persistente no armazenamento do dispositivo entre as inicializações de aplicativos.

Observação

Esse método só deve ser usado depois Analytics de ter sido iniciado.

Verificar se a Análise do App Center está habilitada

Você também pode marcar se a Análise do App Center estiver habilitada ou não.

[MSACAnalytics isEnabled];

Analytics.enabled

Observação

Esse método só deve ser usado depois Analytics de iniciado, ele sempre retornará NO ou false antes de começar.

Gerenciar sessão de início

Por padrão, a ID da sessão depende do ciclo de vida do aplicativo. Se você quiser controlar o início de uma nova sessão manualmente, siga as próximas etapas:

Observação

Preste atenção que cada chamada da API Analytics.StartSession() gerará uma nova sessão. Se no modo de rastreador de sessão manual essa API não for chamada, todos os logs de envio terão um valor de sessão nulo.

Observação

Preste atenção que depois que um novo aplicativo iniciar a ID da sessão será regenerada.

• Chame o seguinte método antes do início do SDK:

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

• Em seguida, você pode usar a startSession API após o AppCenter.start:

[MSACAnalytics startSession];

Analytics.startSession()

Tamanho do armazenamento local

Por padrão, o SDK armazena todos os logs de até 10 MB. Os desenvolvedores podem usar uma API para aumentar o tamanho do armazenamento e o SDK continuará armazenando logs até que o armazenamento esteja cheio.

Sem acesso à Internet

Quando não há conectividade de rede, o SDK salva até 10 MB de logs no armazenamento local. Depois que o armazenamento estiver cheio, o SDK começará a descartar logs antigos para abrir espaço para os novos logs. Depois que a conectividade de rede retorna, o SDK envia logs no lote de 50 ou após a cada 6 segundos (por padrão).

Observação

Os logs com mais de 25 dias serão descartados.

Logs de eventos de envio em lote

O SDK do App Center carrega logs em um lote de 50 e, se o SDK não tiver 50 logs para enviar, ele ainda enviará logs após 6 segundos (por padrão). Pode haver no máximo três lotes enviados em paralelo. O intervalo de transmissão pode ser alterado:

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

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

O valor do intervalo de transmissão deve estar entre 6 segundos e 86400 segundos (um dia) e esse método deve ser chamado antes que o serviço seja iniciado.

Lógica de repetição e retirada

O SDK do App Center dá suporte a novas tentativas de back-off em erros de rede recuperáveis. Abaixo está a lógica de repetição:

• Três tentativas no máximo por solicitação.
• Cada solicitação tem seu próprio computador de estado de repetição.
• Todos os canais de transmissão são desabilitados (até o próximo processo de aplicativo) depois que uma solicitação esgota todas as suas tentativas.

Lógica de back-off

• 50% de randomização, primeira tentativa entre 5 e 10 segundos, segunda repetição entre 2,5 e 5 minutos, última tentativa entre 10 e 20 minutos.
• Se a rede mudar de desativada para ativada (ou de wi-fi para móvel), os estados de repetição serão redefinidos e as solicitações serão repetidas imediatamente.