Configuración avanzada: SDK de Android

Importante: En este documento, se describe una versión heredada del SDK. Los usuarios nuevos deben usar el SDK más reciente.

En este documento, se proporciona una descripción general de algunas de las funciones de configuración avanzadas del SDK de Google Analytics para Android versión 3.

Descripción general

El SDK de Google Analytics para Android proporciona una clase Tracker para configurar y enviar datos a Google Analytics, y un singleton GoogleAnalytics que funciona como interfaz para los valores de configuración globales de tu implementación.

Inicialización

Antes de que se puedan medir datos, debes inicializar al menos un rastreador con el singleton GoogleAnalytics. Para ello, proporciona un Context y un ID de propiedad de Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

Ahora, esta herramienta de seguimiento se puede usar para configurar y enviar datos a Google Analytics.

Configura y envía datos

Los datos se envían a Google Analytics mediante la configuración de mapas de pares de valores de parámetros en la herramienta de seguimiento y su envío a través de 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.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

La clase MapBuilder simplifica el proceso de compilación de hits y se recomienda para la mayoría de los casos de uso. Aquí podemos enviar la misma vista de pantalla con menos líneas de código:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Sintaxis y enumeración del protocolo de medición

Los valores también se pueden configurar en un solo hit. Para ello, debes establecer el valor en un Builder o en todos los hits posteriores. Para ello, debes configurarlos en el objeto de seguimiento con la sintaxis et del Protocolo de medición:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Para obtener una lista completa de los parámetros del Protocolo de medición disponibles, consulta la Referencia de los parámetros del Protocolo de medición.

Aplicación de valores a varios hits

Cualquier valor configurado directamente en la herramienta de seguimiento se conservará y se aplicará a varios hits, como en este ejemplo:

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, null);

Solo los valores que deseas conservar en varios hits deben configurarse directamente en el segmento. Establecer un nombre de pantalla en un dispositivo de rastreo tendría sentido, ya que se puede aplicar el mismo valor a las visitas de pantalla y a las visitas al evento posteriores. Sin embargo, no se recomienda configurar un campo como el tipo de hit en el rastreador, ya que es probable que cambie con cada hit.

Uso de varios monitores

Se pueden usar varias herramientas de seguimiento en una sola implementación, lo que puede ser útil para enviar datos a varias propiedades:

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

Las funciones de medición automatizada, como el análisis automático y la medición de excepciones no detectadas, solo usan una herramienta de seguimiento para enviar datos a Google Analytics. Si estás usando estas funciones y quieres enviar datos con otros rastreadores, deberás hacerlo de forma manual.

Uso del rastreador predeterminado

Google Analytics mantiene una herramienta de seguimiento predeterminada. El primer segmento que se inicializa se convierte en el predeterminado, pero se puede anular:

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

Muestreo

Puedes habilitar el muestreo del cliente para limitar la cantidad de hits que se envían a Google Analytics. Si tu app tiene una gran cantidad de usuarios o envía un gran volumen de datos a Google Analytics, habilitar el muestreo ayudará a garantizar informes sin interrupciones.

Por ejemplo, para habilitar el muestreo del cliente a una tasa del 50% a través de EasyTracker y XML, usa el siguiente parámetro en tu archivo analytics.xml:

<string name="ga_sampleFrequency">50.0</string>

Para habilitar el muestreo del cliente de manera programática para un rastreador, haz lo siguiente:

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

Para evitar incoherencias en los informes, cada una de las vistas de tu app (perfiles) debe contener datos recopilados con la misma tasa de muestreo. Si diferentes versiones de tu app usan tasas de muestreo diferentes, deberás configurar filtros de vista (perfil) con la dimensión de versión de la app para mantener separados los datos de cada versión.

Inhabilitar a nivel de la app

Puedes habilitar una marca de inhabilitación a nivel de la app que inhabilitará Google Analytics en toda la app. Ten en cuenta que esta marca se debe establecer cada vez que se inicie la app y, de forma predeterminada, será NO.

Para obtener la configuración de inhabilitación a nivel de la app, usa lo siguiente:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Para establecer la inhabilitación a nivel de la app, utiliza lo siguiente:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

En una implementación típica, una app puede detectar un cambio en SharedPreferences y actualizar el parámetro de configuración de inhabilitación de Google Analytics según corresponda:

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
      String key) {

    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
    // Any additional changed preference handling.
    }
  }
});

Pruebas y depuración

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

Ejecución de prueba

El SDK proporciona una marca dryRun que, cuando se configura, evita que se envíen datos a Google Analytics. La marca dryRun debe establecerse cada vez que pruebas o depuras una implementación y no deseas que los datos de prueba aparezcan en los informes de Google Analytics.

Para configurar la marca de ejecución de prueba, haz lo siguiente:

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

Logger

Se proporciona la interfaz Logger para controlar mensajes útiles del SDK en estos niveles de verbosidad: error, warning, info y verbose.

El SDK inicializa una implementación estándar de Logger que, de forma predeterminada, solo registrará mensajes de advertencia o error en la consola. Estos mensajes estarán disponibles en logcat. Para establecer la verbosidad de Logger, haz lo siguiente:

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

También se pueden usar implementaciones personalizadas de Logger:

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Ejemplo completo

En el siguiente ejemplo, se muestra el código necesario para inicializar una implementación de Google Analytics y enviar una sola vista de pantalla.

package com.example.app;

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

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);
    userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {
      @Override
      public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
          String key) {
        if (key.equals(TRACKING_PREF_KEY)) {
          GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

A continuación, se mide una vista de pantalla cuando se muestra la primera pantalla a un usuario:

package com.example.app

import android.app.Activity

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private static final String SCREEN_LABEL = "Home Screen";

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}