SDK do Google Analytics para iOS – migração para v3

Este guia descreve como fazer upgrade para a V3 do SDK do Google Analytics para iOS.

Visão rápida: o que há de novo na V3

As APIs na V3 foram refatoradas para serem mais consistentes em plataformas nativas e da Web. Todos os usuários da V2 devem observar estas alterações:

  • Agora, os hits são enviados com um único método send:(NSDictionary *)params.
  • O gerenciamento automático de sessões de clientes foi removido. O tempo limite da sessão pode ser configurado na interface de gerenciamento. Saiba mais.
  • O modo de depuração foi substituído por um Logger
  • Novo: um sinalizador dryRun foi adicionado para evitar que dados enviados sejam exibidos nos relatórios.
  • Novo: o suporte a moedas locais foi adicionado para iOS.

Para ver a lista completa das alterações, consulte o registro de alterações.

Antes de começar

Antes de começar a fazer upgrade para a v3, você precisará de:

Caminhos de upgrade

Para começar, selecione um caminho de upgrade para a v3 a partir da sua implementação atual:

Da v1.x para a v3

É recomendável que os usuários do SDK v1.x do Google Analytics para iOS sigam o Guia de primeiros passos v3 para começar a usar a v3.

Da v2.x para a v3

Os usuários da v2.x devem seguir estas etapas para fazer o upgrade para a v3:

  1. Substitua todos os métodos de conveniência send<hit-type> pelo novo método send::
    // v2 (Old)
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    [tracker sendView:@"HomeScreen"];
    
    // v3
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    // Set the screen name on the tracker so that it is used in all hits sent from this screen.
    [tracker set:kGAIScreenName value:@"Home Screen"];
    
    // Send a screenview.
    // [tracker send:[[GAIDictionaryBuilder createAppView]  build]];   // Previous V3 SDK versions.
    [tracker send:[[GAIDictionaryBuilder createScreenView]  build]];   // SDK Version 3.08 and up.
    
  2. O gerenciamento automático de sessões de clientes foi removido na v3. O tempo limite da sessão pode ser definido na interface de gerenciamento, e o padrão é 30 minutos. As sessões também podem ser iniciadas e interrompidas manualmente por meio do parâmetro sessionControl. Saiba mais sobre o gerenciamento de sessões na v3.

  3. Os usuários do Acompanhamento automático de telas devem substituir as referências a GAITrackedViewController.trackedViewName por GAITrackedViewController.screenName:
    // v2 (Old)
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.trackedViewName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
    // v3
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.screenName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
  4. O uso do modo de depuração foi suspenso. Use o Logger:
    // v2 (Old)
    [GAI sharedInstance].debug = YES;
    
    // v3
    [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
    
  5. A propriedade GAI.useHttp foi removida. Para enviar hits usando HTTP em vez do HTTPS padrão, defina o parâmetro kGAIUseSecure em cada GAITracker:
    // v2 (Old)
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        tracker.useHttps = NO;
    
    }
    
    // v3
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        [tracker set:kGAIUseSecure value:[@NO stringValue]];
    
    }
    
  6. O SDK v3 não inicia mais uma nova sessão automaticamente quando o aplicativo é aberto. Se você quiser preservar esse comportamento da v2, precisará implementar sua própria lógica de controle de sessão quando um usuário iniciar o aplicativo:
  7. // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // CAUTION: Setting session control directly on the tracker persists the
        // value across all subsequent hits, until it is manually set to null.
        // This should never be done in normal operation.
        //
        // [tracker set:kGAISessionControl value:@"start"];
    
        // Instead, send a single hit with session control to start the new session.
        [tracker send:[[[GAIDictionaryBuilder createEventWithCategory:@"UX"
                                                               action:@"appstart"
                                                                label:nil
                                                                value:nil] set:@"start" forKey:kGAISessionControl] build]];
    
    
  8. O SDK não armazenará mais a configuração de desativação no nível do aplicativo. Será necessário defini-la sempre que o aplicativo for iniciado (O padrão é NÃO). Saiba mais sobre como definir a desativação no nível do aplicativo.

Referência

As seções a seguir fornecem exemplos de referências de como definir e enviar dados usando o SDK V3.

Envio de dados com dicionários na v3

Na V3, os dados são enviados com um único método send: que leva um NSDictionary de campos e valores do Google Analytics como um argumento. Uma classe de utilitário GAIDictionaryBuilder é fornecida para simplificar o processo de criação de hits:

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
[tracker set:kGAIScreenName value:@"Home Screen"];

// Previous V3 SDK versions.
// [tracker send:[[GAIDictionaryBuilder createAppView] setValue:@"Premium"  // Creates a Map of hit type 'AppView' (screenview) and set any additional fields.
//                                                     forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

// SDK Version 3.08 and up.
[tracker send:[[GAIDictionaryBuilder createScreenView] setValue:@"Premium"  // Creates a Map of hit type 'ScreenView' and set any additional fields.
                                                       forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

A classe GAIDictionaryBuilder pode ser usada para criar qualquer um dos tipos de hit compatíveis, como eventos:

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"     // Event category (required)
                                                      action:@"button_press"  // Event action (required)
                                                       label:@"play"          // Event label
                                                       value:nil] build]];    // Event value

Saiba mais sobre o envio de dados na v3.

Definição de dados no rastreador na v3

Os valores também podem ser definidos diretamente em um GAITracker com o método set:value:forKey . Os valores definidos diretamente são aplicados a todos os hits subsequentes desse GAITracker:

// Values set directly on a tracker apply to all subsequent hits.
[tracker set:kGAIScreenName value:@"Home Screen"];

// This screenview hit will include the screen name "Home Screen".
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// And so will this event hit.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

Para remover um valor que foi definido no GAITracker, defina a propriedade como nil:

// Clear the previously-set screen name value.
[tracker set:kGAIScreenName
       value:nil];

// Now this event hit will not include a screen name value.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

Saiba mais sobre a definição de dados na v3