SDK de Google Analytics para Android: 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 Android.

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(Map<String, String> parameters).
  • Se reemplazó el modo de depuración por Logger.
  • EasyTracker ahora crea subclases Tracker, lo que genera algunos cambios en la interfaz.
  • Nuevo: Se agregó una marca dryRun para evitar que los datos enviados aparezcan en los informes.

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

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:

EasyTracker: de la versión 1.x a la versión 3

Se recomienda que los usuarios de EasyTracker v1.x sigan la guía de introducción de la versión 3 para comenzar a usar la versión 3 con EasyTracker.

EasyTracker: de la versión 2.x a la versión 3

Los usuarios de EasyTracker v2.x deben seguir estos pasos para completar la actualización a la versión 3:

  1. Actualiza las llamadas a EasyTracker.getInstance() para proporcionar un Context: 
    // v2 (Old)
// EasyTracker.getInstance().activityStart(this);

    // v3:
EasyTracker.getInstance(this).activityStart(this);
  2. EasyTracker ahora es subclase Tracker: quita las llamadas a EasyTracker.getTracker(): 
    // v2 (Old)
Tracker v2Tracker = EasyTracker.getInstance().getTracker();

    // v3
Tracker v3Tracker = EasyTracker.getInstance(this);
  3. Reemplaza todos los métodos de conveniencia send<hit-type> por el nuevo método send(Map<String, String> parameters): 
    // v2 (Old)
Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
v2EasyTracker.sendView("Home Screen");

    // v3
Tracker v3EasyTracker = EasyTracker.getInstance(this);

// Set the screen name on the tracker so that it is used in all hits sent from this screen.
v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screenview.
v3EasyTracker.send(MapBuilder
  .createAppView()
  .build()
);
    Obtén más información sobre el envío de datos en la versión 3.


  4. Reemplaza el parámetro ga_debug de EasyTracker con ga_logLevel y uno de estos valores de verbosidad: verbose, info, warning, error:
    <!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <!-- REMOVE: <bool name="ga_debug">true</bool> -->
  <string name="ga_logLevel">verbose</string>
</resources>
    . Consulta la referencia de parámetros de EasyTracker para obtener más detalles.


  5. GoogleAnalytics.requestAppOptOut() dejó de estar disponible; usa GoogleAnalytics.getAppOptOut() en su lugar: 
    // v2 (Old)
GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
   @Override
   public void reportAppOptOut(boolean optOut) {
     if (optOut) {
     ... // Alert the user that they've opted out.
     }
   });
}

    // v3
boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
  6. Agrega el parámetro ga_dryRun de EasyTracker y configúralo en true cuando pruebes tu implementación para evitar que aparezcan datos de prueba en los informes de producción (opcional):
    7. <!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>

<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <string name="ga_logLevel">verbose</string>

  <!-- Prevent data from appearing in reports. Useful for testing. -->
  <bool name="ga_dryRun">true</bool>

</resources>

Implementación personalizada: de la versión 1.x a la v3

Los usuarios de la versión 1.x que no usen EasyTracker deben seguir la Guía de introducción de la versión 3 y consultar la Guía para desarrolladores de configuración avanzada según sea necesario.

Implementación personalizada: de la versión 2.x a la versión 3

Los usuarios de la versión 2.x que no usen EasyTracker deben seguir los pasos que se indican a continuación para completar la actualización a la versión 3:

  1. Reemplaza todos los métodos útiles 'send<hit-type>' por el nuevo método send(Map<String, String> parameters): 
    // v2 (Old)
Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
v2Tracker.sendView("Home Screen");

    // v3
Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");

// This screen name value will remain set on the tracker and sent with
// hits until it is set to a new value or to null.
v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");

v3Tracker.send(MapBuilder
  .createAppView()
  .build()
);
  2. Quita las llamadas a GoogleAnalytics.setDebug() y reemplázalas por GoogleAnalytics.getLogger().setLogLevel(): 
    // V2 (Old)
GoogleAnalytics.getInstance(this).setDebug(true);

    // V3
GoogleAnalytics.getInstance(this)
    .getLogger()
    .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
    Más información sobre Logger

  3. El SDK v3 ya no inicia automáticamente una sesión nueva cuando se abre la app (excepto cuando se usa EasyTracker). Si deseas conservar este comportamiento de una implementación personalizada de la versión 2, debes implementar tu propia lógica de control de sesión cuando un usuario inicie la app:
    4. package com.example.app;

import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;

public class MyApp extends Application {

  private static Tracker mTracker;
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  @Override
  public void onCreate() {
    super.onCreate();
    mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);

    // 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.
    //
    // mTracker.set(Fields.SESSION_CONTROL, "start");

    // Instead, send a single hit with session control to start the new session.
    mTracker.send(MapBuilder
      .createEvent("UX", "appstart", null, null)
      .set(Fields.SESSION_CONTROL, "start")
      .build()
    );
  }
}
  4. (Opcional) Configura la marca dryRun mientras realizas pruebas para evitar que los datos de prueba se procesen con los informes de producción:
    5. // When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

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.

Envío de datos con Maps en la versión 3

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

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

La clase MapBuilder se puede usar para compilar cualquiera de los tipos de hits admitidos, como los eventos:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

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 Tracker con el método set(). Los valores establecidos directamente se aplican a todos los hits posteriores de ese Tracker: 

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

Para borrar un valor que se estableció en Tracker, establece la propiedad en null:

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

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