Configuración avanzada: SDK para iOS

En este documento se ofrece una visión general de algunas de las funciones avanzadas de configuración de la versión 3 del SDK de Google Analytics para iOS.

Descripción general

El SDK de Google Analytics para iOS proporciona una clase GAITracker para configurar y enviar datos a Google Analytics y una instancia única de GAI que se publica como una interfaz con los valores de configuración globales de la implementación.

Inicialización

Antes de poder medir cualquier dato, tienes que inicializar al menos un objeto de seguimiento mediante el patrón de singleton GoogleAnalytics. Para ello, proporciona un nombre para el objeto de seguimiento y un ID de propiedad de Google Analytics:

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

Desde ese momento, el objeto de seguimiento podrá usarse para configurar y enviar datos a Google Analytics.

Configuración y envío de datos

Para enviar datos a Google Analytics, configura mapas de pares parámetro-valor en el objeto de seguimiento y envíalos mediante los métodos set y 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 clase GAIDictionaryBuilder simplifica el proceso de creación de hits y se recomienda en la mayoría de los casos prácticos. Aquí necesitamos menos líneas de código para enviar la misma visita a una pantalla:

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

Sintaxis del signo "&" del protocolo de medición

Los valores también se pueden configurar en un solo hit, configurando el valor en un objeto Builder, o en todos los hits posteriores, configurándolos en el objeto de seguimiento, mediante la sintaxis del signo "&" del protocolo de medición:

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

Si quieres ver la lista completa de parámetros disponibles para el Protocolo de medición, consulta la Referencia de parámetros para el Protocolo de medición.

Aplicar valores a varios hits

Cualquier valor asignado directamente en el objeto de seguimiento se conservará y se aplicará a varios hits, como en el siguiente ejemplo:

// 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 deben configurarse directamente en el objeto de seguimiento los valores que quieras mantener en varios hits. Lo lógico sería especificar un nombre de pantalla en un objeto de seguimiento, ya que el mismo valor puede aplicarse a los próximos hits de visita a una pantalla y de evento. Sin embargo, no sería recomendable configurar un campo como tipo de hit en el objeto de seguimiento, ya que lo más probable es que cambie con cada hit.

Uso de varios objetos de seguimiento

Se pueden usar varios objetos de seguimiento en una sola implementación, lo cual puede resultar útil para enviar datos a varias propiedades:

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.

Las funciones de medición automatizadas (por ejemplo, la medición de pantalla automática y de excepciones no detectadas) solo utilizan un objeto de seguimiento para enviar datos a Google Analytics. Si usas estas funciones y quieres enviar datos a otros objetos de seguimiento, debes hacerlo manualmente.

A modo informativo, debes saber que la medición de pantalla automatizada utiliza el objeto de seguimiento especificado en la propiedad tracker de un GAITrackedViewController determinado. La medición de excepciones no detectadas utiliza el objeto de seguimiento predeterminado que se especifica en la instancia de GAI.

Usar el objeto de seguimiento predeterminado

Google Analytics mantiene un objeto de seguimiento predeterminado. El primer objeto de sque se inicializa se convierte en el predeterminado, pero se puede cambiar:

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

Muestreo

Puedes habilitar el muestreo del cliente para limitar el número de hits que se envían a Google Analytics. Si tu aplicación tiene un gran número de usuarios o envía un gran volumen de datos a Google Analytics, al habilitar el muestreo, te asegurarás de que los informes sean constantes.

Por ejemplo, para aplicar el muestreo cliente a un ritmo del 50%, usa el siguiente código:

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

Para evitar incoherencias en los informes, cada una de las vistas (perfiles) de aplicación debe contener datos recopilados con la misma frecuencia de muestreo. Si cada versión de tu aplicación tiene una frecuencia de muestreo distinta, debes configurar los filtros de vista (perfil) usando la dimensión de versión de la aplicación para aislar los datos de cada versión de la aplicación.

Inhabilitación en la aplicación

Puedes colocar una marca de inhabilitación en la aplicación que inhabilite Google Analytics en toda la aplicación. Ten en cuenta que esta marca utiliza NO como valor predeterminado y se debe asignar cada vez que la aplicación se inicia.

Para obtener la opción de inhabilitación en la aplicación, usa:

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

Para asignar la opción de inhabilitación en la aplicación, usa:

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

Eliminar los datos de usuario de clientes

Si necesitas cambiar o eliminar los datos de usuario final de algún cliente de Google Analytics, puedes eliminar los archivos de Google Analytics o asignar otro Client-ID.

Opción 1: Eliminar los archivos de Google Analytics

Si tu aplicación no asigna explícitamente el Client-ID de un usuario final, puedes forzar la generación de otro Client-ID eliminando los archivos de Google Analytics que se utilizan para almacenarlo.

El método del ejemplo que se indica a continuación puede usarse para eliminar los archivos de Google Analytics y debe ejecutarse antes de inicializar este programa:

/* 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.
    }
  }
}

Los archivos de Google Analytics se deben eliminar antes de que se inicialice [GAI sharedInstance].

Opción 2: Asignar otro Client-ID

Puedes generar y asignar otro Client-ID único. Todos los hits posteriores utilizarán el nuevo Client-ID y los datos anteriores no se asociarán al nuevo Client-ID.

Ejecuta el siguiente código para generar y asignar otro Client-ID.

[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 decides asignar explícitamente un Client-ID en lugar de generar uno aleatorio, asegúrate de que sea una cadena de UUID (ID de usuario único) válida (versión 4) como se describe en https://goo.gl/0dlrGx.

Si has habilitado un IDFA (identificador de anunciantes), al asignar otro Client-ID, este se sobrescribirá de inmediato con un nuevo Client-ID generado aleatoriamente. No te recomendamos aplicar esta opción si necesitas asignar un Client-ID específico y has habilitado un IDFA (identificador de anunciantes). En su lugar, es mejor usar la Opción 1: Eliminar los archivos de Google Analytics para cambiar el Client-ID.

IP anónima

Al habilitar la IP anónima se indica a Google Analytics que haga anónima la información de IP enviada por el SDK mediante la supresión del último octeto de la dirección IP antes de su almacenamiento.

En el siguiente ejemplo se muestra cómo habilitar la función de IP anónima para objeto de seguimiento.

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

La función de IP anónima se puede configurar en cualquier momento.

Prueba y depuración

El SDK de Google Analytics para iOS ofrece herramientas para facilitar las pruebas y la depuración.

Ejecución segura

El SDK ofrece una marca dryRun que, cuando se activa, evita que los datos se envíen a Google Analytics. La marca dryRun debería establecerse durante la depuración de una implementación y cuando no desees que los datos de la prueba aparezcan en los informes de Google Analytics.

Para configurar la marca de ejecución segura:

[[GAI sharedInstance] setDryRun:YES];

Logger

El protocolo GAILogger permite gestionar mensajes útiles desde el SDK en los siguientes niveles de cantidad de información: error, warning, info y verbose.

El SDK inicializa una implementación de Logger estándar, que solo registrará mensajes de advertencia o de error en la consola de forma predeterminada. Para ver el nivel de cantidad de información de Logger:

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

También pueden usarse implementaciones personalizadas de Logger:

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

Ejemplo completo

En el ejemplo siguiente se muestra el código necesario para inicializar una implementación de Google Analytics y enviar una visita a una pantalla individual.

A continuación, la visita a una pantalla se mide cuando se muestra la primera pantalla al usuario:

Normalmente, la inicialización de una implementación se puede llevar a cabo desde el delegado de aplicación, como en este ejemplo:

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

A continuación, para medir una visita a una pantalla cuando se muestra una vista a un usuario, se utiliza este código:

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