SDK de Google Analytics para iOS: Migración a la versión 3

En esta guía, se describe cómo actualizar a la versión 3 del SDK de Google Analytics para iOS.

De un vistazo: Novedades de V3

Se refactorizaron las APIs de la versión 3 para que sean más coherentes entre las plataformas nativas y web. Todos los usuarios de V2 deben tener en cuenta estos cambios:

  • Los hits ahora se envían con un solo método send:(NSDictionary *)params.
  • Se quitó la administración automática de la sesión del cliente. El tiempo de espera de la sesión se puede configurar en la interfaz de administración en su lugar. Más información.
  • Se reemplazó el modo de depuración por Logger.
  • Nuevo: Se agregó una marca dryRun para evitar que los datos enviados aparezcan en los informes.
  • Nuevo: Se agregó compatibilidad con las monedas locales para iOS.

Para obtener la lista completa de los cambios, consulta el Registro de cambios.

Antes de comenzar

Antes de comenzar la actualización a la versión 3, necesitarás lo siguiente:

Rutas de actualización

Para comenzar, selecciona una ruta de actualización a la versión 3 de tu implementación actual:

De la versión 1.x a la v3

Se recomienda que los usuarios de la versión 1.x del SDK de Google Analytics para iOS sigan la guía de introducción de la versión 3 para comenzar a usar la versión 3.

v2.x a v3

Los usuarios de la versión 2.x deben seguir estos pasos para actualizar a la versión 3:

  1. Reemplaza todos los métodos de conveniencia send<hit-type> por el nuevo método 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. En la versión 3, se quitó la administración automática de las sesiones del cliente. El período de espera de la sesión se puede establecer en la interfaz de administración y se establece de forma predeterminada en 30 minutos. Las sesiones también se pueden iniciar y detener de forma manual con el parámetro sessionControl. Obtén más información sobre la administración de sesiones en la versión 3.

  3. Los usuarios del seguimiento automático de pantalla deben reemplazar las referencias a GAITrackedViewController.trackedViewName por 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. El modo de depuración dejó de estar disponible. En su lugar, usa Logger: 
    // v2 (Old)
[GAI sharedInstance].debug = YES;

    // v3
[[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
  5. Se quitó la propiedad GAI.useHttp. Para enviar hits con HTTP en lugar del HTTPS predeterminado, configura el parámetro kGAIUseSecure en cada 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. El SDK de la versión 3 ya no inicia automáticamente una sesión nueva cuando se abre la aplicación. Si deseas conservar este comportamiento de la versión 2, debes implementar tu propia lógica de control de sesión cuando un usuario inicie la app:
    7. // 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. El SDK ya no conserva la configuración de inhabilitación a nivel de la app y debe establecerse cada vez que se inicia la app (el valor predeterminado es NO). Obtén más información para configurar la inhabilitación a nivel de la aplicación.

Reference

En las siguientes secciones, se proporcionan ejemplos de referencia sobre cómo configurar y enviar datos con el SDK de la versión 3.

Cómo enviar datos mediante diccionarios en la versión 3

En la versión 3, los datos se envían a través de un solo método send: que toma un NSDictionary de campos y valores de Google Analytics como argumento. Se proporciona una clase de utilidad GAIDictionaryBuilder para simplificar el proceso de compilación de hits:

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 clase GAIDictionaryBuilder se puede usar para compilar cualquiera de los tipos de hits admitidos, como los eventos:

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

Más información sobre el envío de datos en la versión 3.

Configuración de datos en el rastreador en la versión 3

Los valores también se pueden configurar directamente en un objeto GAITracker con el método set:value:forKey. Los valores establecidos directamente se aplican a todos los hits posteriores a partir de ese 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]];

Para borrar un valor que se estableció en GAITracker, establece la propiedad en 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]];

Más información sobre cómo configurar datos en la versión 3