Configuração avançada – SDK para iOS

Este documento contém uma visão geral de alguns dos recursos de configuração avançada do SDK v3 do Google Analytics para iOS.

Visão geral

O SDK do Google Analytics para iOS fornece uma classe GAITracker para definir e enviar dados ao Google Analytics e um Singleton GAI que serve como uma interface dos valores de configuração globais da sua implementação.

Inicialização

Para que os dados sejam avaliados, você precisa inicializar pelo menos um rastreador por meio do singleton GoogleAnalytics fornecendo um nome para o rastreador e um ID da propriedade do Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
[[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];

Agora esse rastreador pode ser usado para definir e enviar dados ao Google Analytics.

Configuração e envio de dados

Para enviar dados ao Google Analytics, você precisa definir mapas de pares de valores de parâmetros no rastreador e enviá-los pelos métodos set e send:

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */

// Retrieve tracker with placeholder property ID.
id<GAITracker> tracker = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];

NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys:
                            @"appview", kGAIHitType, @"Home Screen", kGAIScreenName, nil];
[tracker send:params];

A classe GAIDictionaryBuilder simplifica o processo de criar hits e é recomendada para a maioria dos casos de uso. Com o comando a seguir, podemos enviar a mesma exibição de tela com menos linhas de código:

// Previous V3 SDK versions.
// Sending the same screen view hit using [GAIDictionaryBuilder createAppView]
// [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen"
//                                                   forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
// Sending the same screen view hit using [GAIDictionaryBuilder createScreenView]
[tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen"
                                                     forKey:kGAIScreenName] build]];

Sintaxe do "e" comercial do Protocolo de avaliação

Os valores também podem ser definidos em um único hit ao definir o valor em um Builder ou em todos os hits subsequentes ao defini-los no próprio objeto do rastreador por meio da sintaxe do "e" comercial do Protocolo de avaliação:

// Sending the same screen view hit using ampersand syntax.
// Previous V3 SDK versions.
// [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen"
//                                                   forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen"
                                                     forKey:kGAIScreenName] build]];

Para ver a lista completa dos parâmetros do Protocolo de avaliação disponíveis, consulte a Referência de parâmetros do Protocolo de avaliação.

Aplicação de valores a vários hits

Todos os valores definidos diretamente no rastreador serão persistidos e aplicados a vários hits, como neste exemplo:

// May return nil if a tracker has not yet been initialized with
// a property ID.
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

// Set screen name on the tracker to be sent with all hits.
[tracker set:kGAIScreenName
       value:@"Home Screen"];

// Send a screen view for "Home Screen".
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// This event will also be sent with &cd=Home%20Screen.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"UX"
                                                      action:@"touch"
                                                       label:@"menuButton"
                                                       value:nil] build]];

// Clear the screen name field when we're done.
[tracker set:kGAIScreenName
       value:nil];

Somente os valores que você deseja persistir em vários hits devem ser definidos diretamente no rastreador. Convém definir um nome de tela em um rastreador, pois o mesmo valor pode ser aplicado a hits subsequentes de exibições de tela e eventos. No entanto, não é recomendado definir um campo como o tipo de hit no rastreador, pois ele provavelmente mudará a cada hit.

Uso de vários rastreadores

Vários rastreadores podem ser usados em uma única implementação, o que pode ser útil para enviar dados a várias propriedades:

id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"];

// Trackers may be named. By default, name is set to the property ID.
id<GAITracker> t2 = [[GAI sharedInstance] trackerWithName:@"altTracker"
                                                     trackingId:@"UA-XXXX-2"];

[t1 set:kGAIScreenName
        value:@"Home Screen"];

[t2 set:kGAIScreenName
        value:NSStringFromClass([self class])];

// Send a screenview to UA-XXXX-1.
// [t1 send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[t1 send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// Send a screenview to UA-XXXX-2.
// [t2 send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[t2 send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

Recursos de avaliação automatizados, como a avaliação automática de telas e exceções não identificadas, usam somente um rastreador para enviar dados ao Google Analytics. Se você usa esses recursos e quer enviar dados por meio de outros rastreadores, precisa fazer isso manualmente.

Para referência, a avaliação automática de telas usa o rastreador especificado na propriedade tracker de um determinado GAITrackedViewController. A avaliação de exceções não identificadas usa o rastreador padrão especificado na instância GAI.

Uso do rastreador padrão

O Google Analytics mantém um rastreador padrão. O primeiro rastreador inicializado se torna o rastreador padrão, mas é possível substituí-lo:

// t1 becomes the default tracker because it is the first tracker initialized.
id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"];

id<GAITracker> t2 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-2"];

// Returns t1.
id<GAITracker> defaultTracker = [[GAI sharedInstance] defaultTracker];

// Hit sent to UA-XXXX-1.
// Previous V3 SDK versions.
// [defaultTracker send:[[[GAIDictionaryBuilder createAppView]
//                 set:@"Home Screen" forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[defaultTracker send:[[[GAIDictionaryBuilder createScreenView]
                set:@"Home Screen" forKey:kGAIScreenName] build]];

// Override the default tracker.
[[GAI sharedInstance] setDefaultTracker:t2];

// Returns t2.
defaultTracker = [[GAI sharedInstance] defaultTracker];

// Hit sent to UA-XXXX-2.
// Previous V3 SDK versions.
// [defaultTracker send:[[[GAIDictionaryBuilder createAppView]
//                        set:NSStringFromClass([self class])
//                     forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[defaultTracker send:[[[GAIDictionaryBuilder createScreenView]
                       set:NSStringFromClass([self class])
                    forKey:kGAIScreenName] build]];

Amostragem

Você pode ativar a amostragem do cliente para limitar o número de hits enviados ao Google Analytics. Se seu aplicativo tem um número grande de usuários ou envia um grande volume de dados ao Google Analytics, ativar a amostragem ajuda a garantir relatórios ininterruptos.

Por exemplo, para implementar a amostragem do cliente a uma taxa de 50%, use este código:

// Assumes a tracker has already been initialized with a property ID, otherwise
// getDefaultTracker returns nil.
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

// Set a sample rate of 50%.
[tracker set:kGAISampleRate value:@"50.0"];

Para evitar inconsistências de relatórios, cada uma das vistas da propriedade (perfis) do seu aplicativo deve conter dados coletados com a mesma taxa de amostragem. Se versões diferentes do seu aplicativo usarem taxas de amostragem diferentes, você terá que configurar filtros da vista (perfil) usando a dimensão de versão do aplicativo para separar os dados de cada versão do seu aplicativo.

Desativação no nível do aplicativo

É possível ativar uma sinalização de desativação no nível do aplicativo que desativa o Google Analytics em todo o aplicativo. Essa sinalização precisa ser definida sempre que o aplicativo é iniciado e o padrão é NO.

Para acessar a configuração de desativação no nível do aplicativo, use:

// Get the app-level opt out preference.
if ([GAI sharedInstance].optOut) {
  ... // Alert the user they have opted out.
}

Para definir a desativação no nível do aplicativo, use:

// Set the app-level opt out preference.
[[GAI sharedInstance] setOptOut:YES];

Excluir dados do usuário do lado do cliente

Se você precisar redefinir ou excluir dados do Google Analytics referentes aos seus usuários finais do lado do cliente, poderá excluir os arquivos do Google Analytics ou definir um novo ID do cliente.

Opção 1: excluir os arquivos do Google Analytics

Você pode forçar a geração de um novo ID do cliente se seu aplicativo não o define explicitamente para um usuário final. Basta excluir os arquivos do Google Analytics usados para armazenar o ID do cliente.

É possível usar o método do exemplo a seguir para excluir os arquivos do Google Analytics. Ele precisa ser executado antes da inicialização do Google Analytics:

/* Execute this before [GAI sharedInstance] is initialized. */
static void DeleteGAFiles(void) {
  NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES);
  NSFileManager *fileManager = [NSFileManager defaultManager];
  NSArray *libraryFiles = [fileManager contentsOfDirectoryAtPath:paths.firstObject error:nil];

  NSPredicate *predicate =
      [NSPredicate predicateWithFormat:@"self BEGINSWITH 'googleanalytics'"];
  NSArray *matchingFileNames = [libraryFiles filteredArrayUsingPredicate:predicate];

  for (NSString *fileName in matchingFileNames) {
    NSError *error;
    NSString *filePath = [paths.firstObject stringByAppendingPathComponent:fileName];
    if (![fileManager removeItemAtPath:filePath error:&error]) {
      // Log error.
    }
  }
}

Os arquivos do Google Analytics precisam ser excluídos antes da inicialização de [GAI sharedInstance].

Opção 2: definir um novo ID do cliente

Você pode gerar e definir um novo ID de cliente exclusivo. Todos os hits subsequentes usarão o novo ID do cliente e os dados anteriores não serão associados a ele.

Execute o seguinte código para gerar e definir um novo ID do cliente:

[GAI sharedInstance].optOut = YES;

// This Id should be a valid UUID (version 4) string as described in https://goo.gl/0dlrGx.
NSString *newClientID = [NSUUID UUID].UUIDString.lowercaseString;
id dispatcher = [[GAI sharedInstance] performSelector:@selector(dispatcher)];
id dataStore = [dispatcher performSelector:@selector(dataStore)];
if ([dataStore respondsToSelector:@selector(setClientId:)]) {
  [dataStore performSelector:@selector(setClientId:) withObject:newClientID];
}

[GAI sharedInstance].optOut = NO;

Se você decidir definir um ID do cliente explicitamente em vez de gerar um aleatório, verifique se ele é uma string UUID (versão 4) válida, conforme descrito em https://goo.gl/0dlrGx.

Se você ativou o IDFA (identificador para anunciantes), definir um novo ID do cliente fará com que ele seja substituído imediatamente por outro gerado aleatoriamente. Esta opção não é recomendada se você precisa definir um ID do cliente específico e ativou o IDFA (Identificador para anunciantes). Em vez disso, use a Opção 1: excluir os arquivos do Google Analytics para redefinir o ID do cliente.

Anonimizar IP

Ao ativar a funcionalidade anonimizar IP, você instrui o Google Analytics a anonimizar as informações de IP enviadas pelo SDK por meio da remoção do último octeto do endereço IP antes do armazenamento dele.

O exemplo a seguir mostra como enable a funcionalidade anonimizar IP para um rastreador:

[tracker set:kGAIAnonymizeIp value:@"1"];

É possível definir a funcionalidade anonimizar IP a qualquer momento.

Testes e depuração

O SDK do Google Analytics para iOS fornece ferramenta para facilitar os testes e a depuração.

Dry Run

O SDK tem uma sinalização dryRun que, quando definida, impede que dados sejam enviados ao Google Analytics. A sinalização dryRun precisa ser definida sempre que você estiver testando ou depurando uma implementação e não quiser que os dados de teste apareçam nos relatórios do Google Analytics.

Para definir a sinalização "dry run":

[[GAI sharedInstance] setDryRun:YES];

Logger

O protocolo GAILogger é fornecido para processar mensagens úteis do SDK nestes níveis de verbosidade: error, warning, info e verbose.

O SDK inicializa uma implementação Logger padrão que, por padrão, só registra mensagens de aviso ou erro no console. Para definir o nível de detalhes de Logger, faça o seguinte:

// Set the log level to verbose.
[[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];

Implementações personalizadas de Logger também podem ser usadas:

// Provide a custom logger.
[[GAI sharedInstance].logger = [[CustomLogger alloc] init];

Exemplo completo

O exemplo abaixo mostra o código exigido para inicializar uma implementação do Google Analytics e enviar uma única exibição de tela.

Em seguida, uma exibição de tela é medida quando a primeira tela é mostrada ao usuário:

Geralmente, é possível fazer a inicialização de uma implementação no delegado do aplicativo, como neste exemplo:

//
//  AppDelegate.h
//
#import <UIKit/UIKit.h>
#import "GAI.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) UIWindow *window;
@property (strong, nonatomic) id<GAITracker> tracker;

@end

//
//  AppDelegate.m
//
#import "AppDelegate.h"

/** Google Analytics configuration constants **/
static NSString *const kGaPropertyId = @"UA-XXXX-Y"; // Placeholder property ID.
static NSString *const kTrackingPreferenceKey = @"allowTracking";
static BOOL const kGaDryRun = NO;
static int const kGaDispatchPeriod = 30;

@interface AppDelegate ()

- (void)initializeGoogleAnalytics;

@end

@implementation AppDelegate
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [GAI sharedInstance].optOut =
    ![[NSUserDefaults standardUserDefaults] boolForKey:kTrackingPreferenceKey];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Do other work for customization after application launch
    // then initialize Google Analytics.
    [self initializeGoogleAnalytics];

    return YES;
}

- (void)initializeGoogleAnalytics {

    [[GAI sharedInstance] setDispatchInterval:kGaDispatchPeriod];
    [[GAI sharedInstance] setDryRun:kGaDryRun];
    self.tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
}

// The rest of the app delegate code omitted.

@end

Em seguida, quando ocorrer uma exibição de tela para um usuário, avalie o evento da seguinte forma:

//
// MyViewController.m
//
#import "MyViewController.h"
#import "AppDelegate.h"
#import "GAI.h"
#import "GAIFields.h"
#import "GAITracker.h"
#import "GAIDictionaryBuilder.h"

@implementation MyViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    // This screen name value will remain set on the tracker and sent with
    // hits until it is set to a new value or to nil.
    [[GAI sharedInstance].defaultTracker set:kGAIScreenName
                                       value:@"Home Screen"];

    // Send the screen view.
    // Previous V3 SDK versions.
    // [[GAI sharedInstance].defaultTracker
    //     send:[[GAIDictionaryBuilder createAppView] build]];

    // SDK Version 3.08 and up.
    [[GAI sharedInstance].defaultTracker
        send:[[GAIDictionaryBuilder createScreenView] build]];
}