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

Os dados são enviados ao Google Analytics por meio da definição de mapas de pares de valores de parâmetros no rastreador e do envio 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 é recomendado para a maioria dos casos de uso. Aqui, 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. Isso 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 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"];

Desativação no nível do aplicativo

Você pode ativar uma sinalização de desativação no nível do aplicativo que desativará o Google Analytics em todo o aplicativo. Essa sinalização precisa ser definida toda vez que o aplicativo se abre 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];

Anonimização de 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 ativar 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 deve ser definida sempre que você fizer testes ou depurar uma implementação e não quiser que os dados dos testes sejam exibidos nos relatórios do Google Analytics.

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

[[GAI sharedInstance] setDryRun:YES];

Logger

O protocolo GAILogger é fornecido para tratar 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 a verbosidade do Logger:

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

Implementações personalizadas do 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 é avaliada quando a primeira tela for exibida 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, para avaliar uma exibição de tela quando ocorrer uma exibição para um usuário:

//
// 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]];
}