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.

Resumen: novedades de la versión 3

Las API de la versión 3 se han modificado para ofrecer una mayor coherencia entre las plataformas nativas y web. Todos los usuarios de la versión 2 deberían observar los siguientes cambios:

  • Las visitas ahora se envían usando un único método send:(NSDictionary *)params.
  • Se ha eliminado la administración automática de sesiones del cliente. En su lugar, el tiempo de espera de una sesión se puede configurar en la interfaz de administración. Más información.
  • Se ha reemplazado el modo de depuración con Logger.
  • Novedad: Se ha agregado una marca dryRun para evitar que los datos enviados aparezcan en los informes.
  • Novedad: Se ha agregado compatibilidad con monedas locales en iOS.

Para obtener una lista completa de cambios, consulta el registro de cambios.

Antes de empezar

Antes de actualizar a la versión 3, necesitas lo siguiente:

Rutas de actualización

Para empezar, selecciona una ruta de actualización para la versión 3 desde la implementación actual:

De la versión 1.x a la 3

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

De la versión 2.x a la 3

Los usuarios de la versión 2.x deberían seguir los siguientes pasos para actualizar a la versión 3:

  1. Se deben reemplazar todos los métodos de conveniencia send<hit-type> por el método send: nuevo:
    // 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. Se ha eliminado la administración automática de sesiones de cliente en la versión 3. El periodo de tiempo de espera de una sesión puede establecerse en la interfaz de administración y su valor predeterminado es de 30 minutos. Las sesiones también pueden iniciarse y detenerse manualmente usando el parámetro sessionControl. Más información sobre la administración de sesiones en la versión 3.

  3. Los usuarios de la función de seguimiento de pantallas automático 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 ya no se usa. En su lugar, utiliza Logger:
    // v2 (Old)
    [GAI sharedInstance].debug = YES;
    
    // v3
    [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
    
  5. Se ha eliminado la propiedad GAI.useHttp. Para enviar visitas mediante HTTP en lugar de hacerlo mediante el protocolo predeterminado HTTPS, establece 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. La versión 3 del SDK ya no inicia una nueva sesión de forma automática cuando se abre la aplicación. Si quieres conservar este comportamiento de la versión 2, debes implementar tu propia lógica de control de sesión cuando el usuario inicie la aplicación:
  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]];
    
    
  8. La configuración de inhabilitación de la aplicación no se mantiene en el SDK y debe definirse cada vez que se inicie la aplicación (el valor predeterminado es NO). Más información sobre la configuración de inhabilitación de la aplicación.

Referencia

En las siguientes secciones se ofrecen ejemplos de cómo configurar y enviar datos usando la versión 3 del SDK.

Envío de datos usando diccionarios en la versión 3

En la versión 3, los datos se envían usando un solo método send: que usa un NSDictionary de los campos y de los valores de Google Analytics como un argumento. La clase de utilidad GAIDictionaryBuilder se ofrece para simplificar el proceso de creació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 crear cualquiera de los tipos de hit 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 objeto de seguimiento (versión 3)

Los valores también se pueden configurar directamente en un objeto GAITracker mediante el método set:value:forKey. Los valores configurados directamente se aplican a todos los hits posteriores de ese objeto 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 establecido en GAITracker, define la propiedad como 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 la configuración de datos en la versión 3