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 permettant de définir et d'envoyer des données à Google Analytics, ainsi qu'un singleton GAI qui sert d'interface avec les valeurs de configuration globales de votre mise en œuvre.

Initialisation

Pour pouvoir mesurer des données, vous devez initialiser au moins un outil de suivi via le singleton GoogleAnalytics en lui attribuant 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 l'utiliser pour définir des données et les envoyer à Google Analytics.

Configuration et envoi de 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. Elle est recommandée pour la plupart des cas d'utilisation. Ici, nous pouvons envoyer le même visionnage de l'é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 des esperluettes du protocole de mesure

Vous pouvez également définir les valeurs pour un appel unique, en définissant la valeur sur un Builder, ou sur tous les appels ultérieurs, en les définissant sur l'objet de suivi lui-même, à l'aide de l'esperluette 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, consultez la documentation de référence sur les paramètres du protocole de mesure.

Appliquer des valeurs à plusieurs appels

Toutes les valeurs définies directement dans l'outil de suivi seront 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 logique de définir un nom d'écran sur un coach électronique, car la même valeur peut être appliquée aux appels de type visionnage d'écran et événement ultérieurs. Cependant, il n'est pas recommandé de définir un champ tel que le type d'appel sur l'outil de suivi, car il sera probablement modifié à chaque appel.

Utilisation de plusieurs coachs électroniques

Plusieurs outils de suivi peuvent être utilisés dans une seule implémentation, ce qui peut s'avérer 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, telles que la mesure automatique des écrans et les exceptions d'exception 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 outils de suivi, vous devez le faire manuellement.

À titre de référence, la mesure automatique de l'écran utilise l'outil de suivi spécifié dans la propriété tracker d'une propriété GAITrackedViewController donnée. 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 gère un outil de suivi par défaut. Le premier outil de suivi initialisé devient l'outil de suivi par défaut, mais il peut être remplacé:

// 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 permet d'éviter toute interruption.

Par exemple, pour implémenter un é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"];

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 dans l'ensemble de l'application. Notez que cet indicateur doit être défini à chaque démarrage de l'application et qu'il sera défini par défaut sur NO.

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

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

Pour définir la désactivation au niveau de l'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 pour 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 pour 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.

Vous pouvez utiliser l'exemple de méthode suivant pour supprimer les fichiers Google Analytics. La 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.
    }
  }
}

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 antérieures ne seront pas associées au nouveau Client ID.

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;

Rendre l'IP anonyme

L'activation de la fonctionnalité d'anonymisation des adresses IP indique à Google Analytics de rendre anonymes 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 activer la fonctionnalité d'anonymisation d'adresses IP pour un outil de suivi:

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

La fonctionnalité d'anonymisation de l'adresse 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.

Simulation

Le SDK fournit une option dryRun qui, lorsqu'elle est définie, empêche l'envoi de données à Google Analytics. L'option dryRun doit être définie lorsque vous testez ou déboguez une mise en œuvre et que vous ne souhaitez pas que les données de test apparaissent dans vos rapports Google Analytics.

Pour définir l'indicateur de simulation:

[[GAI sharedInstance] setDryRun:YES];

Logger

Le protocole GAILogger est fourni pour gérer les messages utiles du SDK aux niveaux de verbosité suivants : error, warning, info et verbose.

Le SDK initialise une mise en œuvre Logger standard, qui ne consigne par défaut que les messages d'avertissement ou d'erreur dans la console. Pour définir la verbosité de Logger, procédez comme suit:

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

Vous pouvez également utiliser des 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 requis pour initialiser une implémentation Google Analytics et envoyer un seul visionnage de l'écran.

Ensuite, un visionnage est mesuré lorsque le premier écran est présenté à un utilisateur:

En règle générale, l'initialisation d'une mise en œuvre 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

Pour mesurer un visionnage de l'écran lorsqu'un utilisateur le voit, procédez comme suit:

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