Configuration avancée – SDK iOS

Ce document présente certaines des fonctionnalités de configuration avancées du SDK Google Analytics pour iOS v3.

Présentation

Le SDK Google Analytics pour iOS fournit une classe GAITracker pour définir et envoyer des données à Google Analytics, ainsi qu'un singleton GAI qui sert d'interface pour les valeurs de configuration globales de votre implémentation.

Initialisation

Avant de pouvoir mesurer des données, vous devez initialiser au moins un outil de suivi via Singleton GoogleAnalytics en fournissant un nom et un ID de propriété Google Analytics:

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

Vous pouvez désormais utiliser cet outil de suivi pour définir et envoyer des données à Google Analytics.

Définition et envoi des données

Les données sont envoyées à Google Analytics en définissant des mappages de paires paramètre/valeur sur l'outil de suivi et en les envoyant via les méthodes set et 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 simplifie le processus de création des appels et est recommandée pour la plupart des cas d'utilisation. Ici, nous pouvons envoyer la même vue d'écran avec moins de lignes de code:

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

Syntaxe de l'esperluette du protocole de mesure

Vous pouvez également définir les valeurs sur un seul appel, en définissant la valeur sur un Builder ou sur tous les appels suivants, en la définissant sur l'objet de suivi lui-même, à l'aide de la syntaxe du protocole de mesure:

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

Pour obtenir la liste complète des paramètres du protocole de mesure disponibles, consultez la documentation de référence sur les paramètres du protocole de mesure.

Application de valeurs à plusieurs appels

Toutes les valeurs définies directement sur l'outil de suivi sont conservées et appliquées à plusieurs appels, comme dans cet exemple:

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

Seules les valeurs que vous souhaitez conserver pour plusieurs appels doivent être définies directement dans l'outil de suivi. Il serait judicieux de définir un nom d'écran sur un outil de suivi, car la même valeur peut être appliquée aux vues d'écran et aux appels avec événement suivants. Toutefois, nous vous déconseillons de définir un champ tel que le type d'appel sur l'outil de suivi, car il est susceptible de changer à chaque appel.

Utiliser plusieurs coachs électroniques

Plusieurs outils de suivi peuvent être utilisés dans une même implémentation, ce qui peut être utile pour envoyer des données à plusieurs propriétés:

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.

Les fonctionnalités de mesure automatisée, comme l'écran automatique et la mesure des exceptions non détectées, n'utilisent qu'un seul outil de suivi pour envoyer des données à Google Analytics. Si vous utilisez ces fonctionnalités et que vous souhaitez envoyer des données à l'aide d'autres traceurs, vous devez le faire manuellement.

Pour référence, la mesure automatique de l'écran utilise le traceur spécifié dans la propriété tracker d'un GAITrackedViewController donné. La mesure des exceptions non détectées utilise l'outil de suivi par défaut spécifié dans votre instance GAI.

Utilisation de l’outil de suivi par défaut

Google Analytics dispose d'un outil de suivi par défaut. Le premier outil de suivi initialisé devient l'outil de suivi par défaut, mais peut être ignoré:

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

Échantillonnage

Vous pouvez activer l'échantillonnage côté client pour limiter le nombre d'appels envoyés à Google Analytics. Si votre application compte un grand nombre d'utilisateurs ou envoie un grand volume de données à Google Analytics, l'activation de l'échantillonnage vous permettra de générer des rapports sans interruption.

Par exemple, pour implémenter l'échantillonnage côté client à un taux de 50%, utilisez le code suivant:

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

Pour éviter les incohérences dans les rapports,chacune des vues d'application (profils) doit contenir des données collectées avec le même taux d'échantillonnage. Si différentes versions de votre application utilisent des taux d'échantillonnage différents, vous devez configurer des filtres de vue (profil) à l'aide de la dimension "Version de l'application" pour séparer les données de chaque version.

Désactivation au niveau de l'application

Vous pouvez activer un indicateur de désactivation au niveau de l'application, qui désactivera Google Analytics pour l'ensemble de l'application. Notez que cet indicateur doit être défini chaque fois que l'application démarre et qu'il est défini par défaut sur NO.

Pour obtenir le paramètre de désactivation au niveau d'une application, utilisez:

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

Pour désactiver la fonctionnalité au niveau d'une application, utilisez:

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

Supprimer les données utilisateur côté client

Si vous devez réinitialiser ou supprimer les données Google Analytics côté client de vos utilisateurs finaux, vous pouvez supprimer les fichiers Google Analytics ou définir un nouvel ID client.

Option 1: Supprimer les fichiers Google Analytics

Si votre application ne définit pas explicitement l'ID client d'un utilisateur final, vous pouvez forcer la génération d'un nouvel ID client en supprimant les fichiers Google Analytics utilisés pour le stocker.

La méthode suivante peut être utilisée pour supprimer les fichiers Google Analytics. Cette méthode doit être exécutée avant l'initialisation de 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.
    }
  }
}

Vous devez supprimer les fichiers Google Analytics avant l'initialisation de [GAI sharedInstance].

Option 2: Définir un nouvel ID client

Vous pouvez générer et définir un nouvel ID client unique. Tous les appels suivants utiliseront le nouvel ID client, et les données précédentes ne seront pas associées à celui-ci.

Exécutez le code suivant pour générer et définir un nouvel 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;

Si vous décidez de définir explicitement un ID client au lieu d'en générer un de manière aléatoire, assurez-vous qu'il s'agit d'une chaîne UUID (version 4) valide, comme décrit sur la page https://goo.gl/0dlrGx.

Si vous avez activé l'identifiant pour les annonceurs (IDFA, Identifier for Advertisers), le fait de définir un nouvel ID client sera immédiatement remplacé par un nouvel ID client généré de manière aléatoire. Si vous avez besoin de définir un numéro client spécifique et que vous avez activé l'IDFA (Identifier for Advertisers), cette option n'est pas recommandée. Utilisez plutôt l'Option 1: Supprimer les fichiers Google Analytics pour réinitialiser l'ID client.

Rendre l'IP anonyme

Activer la fonctionnalité d'anonymisation de l'adresse IP indique à Google Analytics d'anonymiser les informations IP envoyées par le SDK en supprimant le dernier octet de l'adresse IP avant son stockage.

L'exemple suivant montre comment enable la fonctionnalité d'anonymisation d'adresses IP pour un outil de suivi:

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

La fonctionnalité d'anonymisation des adresses IP peut être définie à tout moment.

Tester et déboguer

Le SDK Google Analytics pour iOS fournit des outils qui facilitent les tests et le débogage.

Test à blanc

Le SDK fournit un indicateur dryRun qui, lorsqu'il est défini, empêche l'envoi de données à Google Analytics. L'indicateur dryRun doit être défini chaque fois que vous testez ou déboguez une implémentation et que vous ne souhaitez pas que des données de test apparaissent dans vos rapports Google Analytics.

Pour définir l'indicateur de dry run:

[[GAI sharedInstance] setDryRun:YES];

Logger

Le protocole GAILogger permet de gérer les messages utiles du SDK à ces niveaux de verbosité : error, warning, info et verbose.

Le SDK initialise une implémentation Logger standard, qui par défaut ne consigne que les messages d'avertissement ou d'erreur dans la console. Pour définir la verbosité de Logger:

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

Vous pouvez également utiliser les implémentations personnalisées de Logger:

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

Exemple complet

L'exemple ci-dessous présente le code nécessaire pour initialiser une implémentation Google Analytics et envoyer un seul visionnage de l'écran.

Ensuite, un visionnage de l'écran est mesuré lorsque le premier écran s'affiche:

En règle générale, l'initialisation d'une implémentation peut être effectuée à partir du délégué de l'application, comme dans cet exemple:

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

Ensuite, pour mesurer un visionnage de l'écran lorsqu'une vue est présentée à un utilisateur:

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