SDK Google Analytics per iOS - Migrazione alla versione 3

Gli sviluppatori che non hanno mai utilizzato Google Analytics devono Iniziare subito con la versione 3.

Questa guida descrive come eseguire l'upgrade alla versione V3 dell'SDK Google Analytics per iOS.

Riepilogo: novità della V3

Le API nella V3 sono state sottoposte a refactoring per garantire una maggiore coerenza tra le piattaforme native e web. Tutti gli utenti della versione 2 devono notare i seguenti cambiamenti:

• Ora gli hit vengono inviati con un unico metodo send:(NSDictionary *)params.
• La gestione automatica delle sessioni lato client è stata rimossa. Il timeout della sessione può essere configurato nell'interfaccia di gestione. Scopri di più.
• La modalità di debug è stata sostituita con Logger
• Novità: è stato aggiunto un flag dryRun per impedire la visualizzazione dei dati inviati nei report.
• Novità: il supporto delle valute locali è stato aggiunto per iOS.

Per l'elenco completo delle modifiche, consulta il log delle modifiche.

Prima di iniziare

Prima di iniziare l'upgrade alla versione 3, è necessario quanto segue:

• Una proprietà abilitata per Universal Analytics e un profilo dell'app
• SDK di Google Analytics per iOS v3

Percorsi di upgrade

Per iniziare, seleziona un percorso di upgrade alla versione 3 dall'implementazione attuale:

• Da v1.x a v3
• Da v2.x a v3

Da v1.x a v3

È consigliabile che gli utenti dell'SDK Google Analytics per iOS v1.x seguano la Guida introduttiva v3 per iniziare a utilizzare la versione 3.

Da v2.x a v3

Gli utenti della versione 2.x devono seguire questi passaggi per eseguire l'upgrade alla versione 3:

1. Sostituisci tutti i metodi di convenienza send<hit-type> con il nuovo metodo 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. La gestione automatica delle sessioni lato client è stata rimossa nella versione 3. Il periodo di timeout della sessione può essere impostato nell'interfaccia di gestione e il valore predefinito è 30 minuti. Le sessioni possono anche essere avviate e arrestate manualmente utilizzando il parametro sessionControl. Scopri di più sulla gestione delle sessioni in v3.


3. Gli utenti del monitoraggio automatico delle schermate devono sostituire i riferimenti a GAITrackedViewController.trackedViewName con 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. La modalità di debug è deprecata. Utilizza Logger:

   // v2 (Old)
   [GAI sharedInstance].debug = YES;
   

   // v3
   [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
   

5. La proprietà GAI.useHttp è stata rimossa. Per inviare hit utilizzando HTTP anziché il protocollo HTTPS predefinito, imposta il parametro kGAIUseSecure su ogni 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. L'SDK v3 non avvia più automaticamente una nuova sessione all'apertura dell'app. Se vuoi mantenere questo comportamento dalla versione 2, devi implementare la tua logica di controllo della sessione quando un utente avvia l'app:

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

7. L'impostazione di disattivazione a livello di app non è più impostata come persistente dall'SDK e deve essere impostata a ogni avvio dell'app (il valore predefinito è NO). Scopri di più sull'impostazione della disattivazione a livello di applicazione.

Riferimento

Le seguenti sezioni forniscono esempi di riferimento su come impostare e inviare dati utilizzando l'SDK V3.

Invio di dati utilizzando i dizionari in v3

Nella versione V3, i dati vengono inviati utilizzando un singolo metodo send: che prende come argomento un NSDictionary di campi e valori di Google Analytics. Viene fornita una classe di utilità GAIDictionaryBuilder per semplificare il processo di creazione degli hit:

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.

La classe GAIDictionaryBuilder può essere utilizzata per creare qualsiasi tipo di hit supportato, come gli eventi:

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

Scopri di più sull'invio di dati nella versione 3.

Impostazione dei dati sul tracker in v3

I valori possono anche essere impostati direttamente su un GAITracker utilizzando il metodo set:value:forKey. I valori impostati direttamente vengono applicati a tutti gli hit successivi da quel 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]];

Per cancellare un valore impostato in GAITracker, imposta la proprietà su 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]];

Scopri di più sull'impostazione dei dati nella versione 3