Configurazione avanzata: SDK per iOS

Questo documento fornisce una panoramica di alcune delle funzionalità di configurazione avanzate dell'SDK di Google Analytics per iOS v3.

Panoramica

L'SDK Google Analytics per iOS fornisce una classe GAITracker per impostare e inviare dati a Google Analytics e un singleton GAI che funge da interfaccia per i valori di configurazione globali dell'implementazione.

Inizializzazione

Prima di poter misurare i dati, devi inizializzare almeno un tracker tramite un singleton GoogleAnalytics fornendo un nome per il tracker e un ID proprietà di Google Analytics:

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

Ora questo tracker può essere utilizzato per l'impostazione e l'invio di dati a Google Analytics.

Impostazione e invio di dati

I dati vengono inviati a Google Analytics impostando mappe di coppie parametro-valore sul tracker e inviandole tramite i metodi 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];

La classe GAIDictionaryBuilder semplifica il processo di creazione degli hit ed è consigliata per la maggior parte dei casi d'uso. Qui possiamo inviare la stessa visualizzazione di schermata con meno righe di codice:

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

Sintassi e commerciale di Measurement Protocol

I valori possono anche essere impostati per un singolo hit, impostandoli su un Builder o su tutti gli hit successivi, impostandoli sull'oggetto tracker stesso tramite la sintassi e commerciale di Measurement Protocol:

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

Per l'elenco completo dei parametri di Measurement Protocol disponibili, consulta il documento di riferimento per i parametri di Measurement Protocol.

Applicazione di valori a più hit

Qualsiasi valore impostato direttamente sul tracker verrà mantenuto e applicato a più hit, come in questo esempio:

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

Solo i valori che vuoi mantenere per più hit devono essere impostati direttamente nel tracker. L'impostazione di un nome di schermata su un tracker avrebbe senso, poiché lo stesso valore può essere applicato a visualizzazioni di schermata e hit da evento successivi. Tuttavia, non è consigliabile impostare un campo come il tipo di hit sul tracker, perché probabilmente cambierà a ogni hit.

Utilizzo di più tracker

È possibile utilizzare più tracker in un'unica implementazione, il che può essere utile per l'invio di dati a più proprietà:

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.

Le funzionalità di misurazione automatica, come la misurazione automatica delle schermate e delle eccezioni non rilevate, utilizzano un solo tracker per inviare i dati a Google Analytics. Se usi queste funzionalità e vuoi inviare dati utilizzando altri tracker, dovrai farlo manualmente.

Come riferimento, la misurazione automatica dello schermo utilizza il tracker specificato nella proprietà tracker di un determinato GAITrackedViewController. La misurazione dell'eccezione non rilevata utilizza il tracker predefinito specificato nell'istanza GAI.

Uso del tracker predefinito

Google Analytics gestisce un tracker predefinito. Il primo tracker inizializzato diventa il tracker predefinito, ma può essere sostituito:

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

Campionamento

Puoi attivare il campionamento lato client per limitare il numero di hit inviati a Google Analytics. Se la tua app ha un numero elevato di utenti o invia un elevato volume di dati a Google Analytics, l'attivazione del campionamento aiuta a garantire report senza interruzioni.

Ad esempio, per implementare il campionamento lato client a una percentuale del 50%, utilizza il seguente codice:

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

Per evitare incongruenze nei report, ciascuna vista (profili) delle tue app deve contenere i dati raccolti con la stessa frequenza di campionamento. Se versioni diverse della tua app utilizzano frequenze di campionamento diverse, dovrai configurare i filtri della vista (profilo) utilizzando la dimensione della versione dell'app per mantenere separati i dati di ogni versione dell'app.

Disattivazione a livello di app

Puoi abilitare un flag di disattivazione a livello di app che disattiverà Google Analytics nell'intera app. Tieni presente che questo flag deve essere impostato a ogni avvio dell'app e che, per impostazione predefinita, sarà NO.

Per attivare l'impostazione di disattivazione a livello di app, utilizza:

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

Per impostare la disattivazione a livello di app, utilizza:

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

Eliminare i dati utente lato client

Se devi reimpostare o eliminare i dati lato client di Google Analytics per i tuoi utenti finali, puoi eliminare i file di Google Analytics o impostare un nuovo ID cliente.

Opzione 1: elimina i file di Google Analytics

Se l'app non imposta esplicitamente l'ID client per un utente finale, puoi forzare la generazione di un nuovo ID client eliminando i file di Google Analytics utilizzati per archiviare l'ID client.

Il seguente metodo di esempio può essere utilizzato per eliminare i file di Google Analytics. Il metodo deve essere eseguito prima di inizializzare 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.
    }
  }
}

I file di Google Analytics devono essere eliminati prima dell'inizializzazione di [GAI sharedInstance].

Opzione 2: imposta un nuovo ID cliente

Puoi generare e impostare un nuovo ID cliente univoco. Tutti gli hit successivi utilizzeranno il nuovo ID client e i dati precedenti non saranno associati al nuovo ID client.

Esegui questo codice per generare e impostare un nuovo ID client:

[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 decidi di impostare esplicitamente un ID client invece di generarne uno casuale, assicurati che sia una stringa UUID (versione 4) valida, come descritto all'indirizzo https://goo.gl/0dlrGx.

Se hai attivato l'IDFA (identificatore per gli inserzionisti), l'impostazione di un nuovo ID cliente ne verrà sovrascritto immediatamente da un nuovo ID cliente generato in modo casuale. Se richiedi l'impostazione di un ID cliente specifico e hai attivato l'IDFA (identificatore per gli inserzionisti), questa opzione non è consigliata. Utilizza invece l'Opzione 1: elimina i file di Google Analytics per reimpostare l'ID client.

Anonimizza IP

L'attivazione della funzionalità di anonimizzazione IP indica a Google Analytics di anonimizzare le informazioni IP inviate dall'SDK rimuovendo l'ultimo ottetto dell'indirizzo IP prima di archiviarlo.

Nell'esempio seguente viene illustrato come enable la funzionalità di anonimizzazione dell'indirizzo IP per un tracker:

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

La funzionalità di anonimizzazione IP può essere impostata in qualsiasi momento.

Test e debug

L'SDK Google Analytics per iOS fornisce strumenti che semplificano test e debug.

Prova

L'SDK fornisce un flag dryRun che, se impostato, impedisce l'invio di dati a Google Analytics. Il flag dryRun deve essere impostato ogni volta che esegui il test o il debug di un'implementazione e non vuoi che i dati dei test vengano visualizzati nei report di Google Analytics.

Per impostare il flag di prova:

[[GAI sharedInstance] setDryRun:YES];

Logger

Il protocollo GAILogger viene fornito per gestire i messaggi utili dell'SDK ai seguenti livelli di dettaglio: error, warning, info e verbose.

L'SDK inizializza un'implementazione Logger standard, che per impostazione predefinita registra solo messaggi di avviso o errore nella console. Per impostare il livello di dettaglio di Logger:

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

Puoi utilizzare anche implementazioni personalizzate di Logger:

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

Esempio completo

L'esempio di seguito mostra il codice necessario per inizializzare un'implementazione di Google Analytics e inviare una visualizzazione di schermata singola.

Successivamente, viene misurata una visualizzazione di schermata quando la prima schermata viene mostrata a un utente:

In genere l'inizializzazione di un'implementazione può essere eseguita dal delegato dell'app, come in questo esempio:

//
//  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

Quindi, per misurare una visualizzazione di schermata quando questa viene mostrata a un utente:

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