SDK Google Analytics pour iOS – Migration vers la version 3

Ce guide explique comment passer à la version 3 du SDK Google Analytics pour iOS.

Aperçu: nouveautés de la version 3

Les API de la version 3 ont été refactorisées pour être plus cohérentes sur les plates-formes natives et Web. Tous les utilisateurs de la version 2 doivent noter les changements suivants:

Les appels sont désormais envoyés à l'aide d'une seule méthode send:(NSDictionary *)params.
La gestion automatique des sessions côté client a été supprimée. Le délai avant expiration de la session peut être configuré dans l'interface de gestion à la place. En savoir plus
Le mode débogage a été remplacé par un Logger
Nouveau : Un indicateur dryRun a été ajouté pour empêcher les données distribuées d'apparaître dans les rapports.
Nouveau : Les devises locales sont désormais acceptées sur iOS.

Pour obtenir la liste complète des modifications, consultez le journal des modifications.

Avant de commencer

Avant de passer à la version 3, vous avez besoin des éléments suivants:

Méthodes de mise à niveau

Pour commencer, choisissez un processus de mise à niveau vers la v3 dans votre implémentation actuelle:

v1.x à v3
v2.x à v3

v1.x à v3

Il est recommandé aux utilisateurs de la version 1.x du SDK Google Analytics pour iOS de suivre le guide de démarrage de la version 3 pour commencer à utiliser la version 3.

v2.x à v3

Les utilisateurs de la version 2.x doivent suivre ces étapes pour passer à la version 3:

Remplacez toutes les méthodes pratiques de send<hit-type> par la nouvelle méthode 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.

La gestion automatique des sessions côté client a été supprimée dans la version 3. Le délai avant expiration de la session peut être défini dans l'interface de gestion. La valeur par défaut est de 30 minutes. Les sessions peuvent également être démarrées et arrêtées manuellement à l'aide du paramètre sessionControl. En savoir plus sur la gestion des sessions dans la version 3

Les utilisateurs du suivi automatique de l'écran doivent remplacer les références à GAITrackedViewController.trackedViewName par 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.

Le mode débogage est obsolète. Utilisez plutôt Logger :

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

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

Suppression de la propriété GAI.useHttp. Pour envoyer des appels via HTTP au lieu du protocole HTTPS par défaut, définissez plutôt le paramètre kGAIUseSecure sur chaque 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]];

}

Le SDK v3 ne démarre plus automatiquement une nouvelle session à l'ouverture de l'application. Si vous souhaitez conserver ce comportement dans la version 2, vous devez implémenter votre propre logique de contrôle de session lorsqu'un utilisateur démarre l'application:

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

Le paramètre de désactivation au niveau de l'application n'est plus conservé par le SDK et doit être défini chaque fois que l'application est lancée (valeur par défaut : NO). En savoir plus sur la désactivation au niveau de l'application

Reference

Les sections suivantes fournissent des exemples de référence sur la définition et l'envoi de données à l'aide du SDK V3.

Envoyer des données à l'aide de dictionnaires dans la version 3

Dans la version 3, les données sont envoyées à l'aide d'une seule méthode send: qui accepte comme argument un NSDictionary de champs et de valeurs Google Analytics. Une classe utilitaire GAIDictionaryBuilder est fournie pour simplifier le processus de création des appels:

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 peut être utilisée pour créer n'importe quel type d'appel compatible, comme des événements:

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

En savoir plus sur l'envoi de données dans la version 3

Définition des données sur l'outil de suivi dans la version 3

Les valeurs peuvent également être définies directement dans un GAITracker à l'aide de la méthode set:value:forKey. Les valeurs définies directement sont appliquées à tous les appels suivants à partir de cette 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]];

Pour effacer une valeur définie dans GAITracker, définissez la propriété sur 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]];

En savoir plus sur la définition des données dans la version 3