Android v3 (heredado): Descripción general

En esta guía para desarrolladores, se describe cómo implementar Google Tag Manager en una aplicación para dispositivos móviles.

Introducción

Google Tag Manager permite que los desarrolladores cambien los valores de configuración en sus aplicaciones para dispositivos móviles con la interfaz de Google Tag Manager sin tener que volver a compilar y enviar los archivos binarios de la aplicación a los mercados de aplicaciones.

Esto es útil para administrar cualquier valor o marca de configuración en tu aplicación que puedas necesitar cambiar en el futuro, incluidos los siguientes:

  • Varios parámetros de configuración de la IU y cadenas de visualización
  • Tamaños, ubicaciones o tipos de anuncios publicados en tu aplicación
  • Configuración de juegos

Los valores de configuración también se pueden evaluar en el tiempo de ejecución con reglas, lo que permite configuraciones dinámicas como las siguientes:

  • Usar el tamaño de la pantalla para determinar el tamaño del banner publicitario
  • Usar el idioma y la ubicación para configurar elementos de la IU

Google TagManager también permite la implementación dinámica de etiquetas de seguimiento y píxeles en las aplicaciones. Los desarrolladores pueden enviar eventos importantes a una capa de datos y decidir más adelante qué etiquetas de seguimiento o píxeles se deben activar. TagManager admite las siguientes etiquetas:

  • Google Analytics para aplicaciones móviles
  • Etiqueta de llamada a función personalizada

Antes de comenzar

Antes de usar esta guía de introducción, necesitarás lo siguiente:

Si es la primera vez que usas Google Tag Manager, te recomendamos que obtengas más información sobre los contenedores, las macros y las reglas (Centro de ayuda) antes de continuar con esta guía.

Comenzar

En esta sección, se guiará a los desarrolladores a través de un flujo de trabajo típico de Tag Manager:

  1. Agrega el SDK de Google Tag Manager a tu proyecto
  2. Establece valores predeterminados del contenedor
  3. Abre el contenedor
  4. Obtén valores de configuración del contenedor
  5. Envía eventos a la capa de datos
  6. Obtén una vista previa del contenedor y publícalo

1. Agrega el SDK de Google Tag Manager a tu proyecto

Antes de usar el SDK de Google Tag Manager, deberás extraer el paquete del SDK, agregar la biblioteca a la ruta de acceso de compilación de tu proyecto y agregar permisos a tu archivo AndroidManifest.xml.

Primero, agrega la biblioteca de Google Tag Manager a la carpeta /libs de tu proyecto.

Luego, actualiza tu archivo AndroidManifest.xml para usar los siguientes permisos:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

2. Agrega un archivo de contenedor predeterminado a tu proyecto

Google Tag Manager usa un contenedor predeterminado en la primera ejecución de tu aplicación. El contenedor predeterminado se usará hasta que la app pueda recuperar un contenedor nuevo a través de la red.

Para descargar y agregar un objeto binario de contenedor predeterminado a tu aplicación, sigue estos pasos:

  1. Accede a la interfaz web de Google Tag Manager.
  2. Selecciona la versión del contenedor que deseas descargar.
  3. Haz clic en el botón Descargar para recuperar el archivo binario del contenedor.
  4. Agrega el archivo binario a la siguiente ruta de acceso: <project-root>/assets/tagmanager/

El nombre de archivo predeterminado debe ser el ID del contenedor (por ejemplo GTM-1234). Una vez que hayas descargado el archivo binario, asegúrate de quitar el sufijo de la versión del nombre de archivo para asegurarte de seguir la convención de nomenclatura correcta.

Aunque se recomienda usar el archivo binario, si tu contenedor no contiene reglas ni etiquetas, puedes usar un archivo JSON. El archivo debe ubicarse en una carpeta /assets/tagmanager nueva de tu proyecto de Android y debe seguir esta convención de nomenclatura: <Container_ID>.json. Por ejemplo, si el ID de tu contenedor es GTM-1234, debes agregar los valores predeterminados del contenedor a /assets/tagmanager/GTM-1234.json.

3. Abre un contenedor

Antes de recuperar valores de un contenedor, tu aplicación debe abrirlo. Si abres un contenedor, se cargará desde el disco (si está disponible) o se solicitará desde la red (si es necesario).

La forma más sencilla de abrir un contenedor en Android es usar ContainerOpener.openContainer(..., Notifier notifier), como en el siguiente ejemplo:

import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;

import android.app.Activity;
import android.os.Bundle;

public class RacingGame {

  // Add your public container ID.
  private static final String CONTAINER_ID = "GTM-YYYY";

  volatile private Container mContainer;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TagManager mTagManager = TagManager.getInstance(this);

    // The container is returned to containerFuture when available.
    ContainerOpener.openContainer(
        mTagManager,                            // TagManager instance.
        CONTAINER_ID,                           // Tag Manager Container ID.
        OpenType.PREFER_NON_DEFAULT,            // Prefer not to get the default container, but stale is OK.
        null,                                   // Time to wait for saved container to load (ms). Default is 2000ms.
        new ContainerOpener.Notifier() {        // Called when container loads.
          @Override
          public void containerAvailable(Container container) {
            // Handle assignment in callback to avoid blocking main thread.
            mContainer = container;
          }
        }
    );
    // Rest of your onCreate code.
  }
}

En este ejemplo, se usa ContainerOpener.openContainer(..., Notifier notifier) para solicitar un contenedor guardado del almacenamiento local. Si controlamos la asignación de mContainer en la devolución de llamada containerAvailable, nos aseguramos de que no se bloquee el subproceso principal. Si el contenedor guardado tiene más de 12 horas, la llamada también programará una solicitud para recuperar de forma asíncrona un contenedor nuevo a través de la red.

Esta implementación de muestra representa la forma más sencilla de abrir y recuperar valores de un contenedor con la clase de conveniencia ContainerOpener. Para obtener opciones de implementación más avanzadas, consulta Configuración avanzada.

4. Obtén valores de configuración del contenedor

Una vez que el contenedor esté abierto, se podrán recuperar los valores de configuración con los get<type>Value() métodos:

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

Las solicitudes realizadas con una clave inexistente mostrarán un valor predeterminado adecuado para el tipo solicitado:

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.

5. Envía valores a la capa de datos

La capa de datos es un mapa que permite que la información del tiempo de ejecución sobre tu app, como los eventos táctiles o las vistas de pantalla, esté disponible para las macros y las etiquetas de Tag Manager en un contenedor.

Por ejemplo, si envías información sobre las vistas de pantalla al mapa de la capa de datos, puedes configurar etiquetas en la interfaz web de Tag Manager para activar píxeles de conversión y llamadas de seguimiento en respuesta a esas vistas de pantalla sin necesidad de codificarlas de forma rígida en tu app.

Los eventos se envían a la capa de datos con push() y el DataLayer.mapOf() método auxiliar:

//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//

import com.google.tagmanager.TagManager;
import com.google.tagmanager.DataLayer;

import android.app.Activity;
import android.os.Bundle;

public MainActivity extends Activity {

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

  }

  // This screen becomes visible when Activity.onStart() is called.
  public void onStart() {
    super.onStart();

    // The container should have already been opened, otherwise events pushed to
    // the DataLayer will not fire tags in that container.
    DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
    dataLayer.push(DataLayer.mapOf("event",
                                   "openScreen",      // The event type. This value should be used consistently for similar event types.
                                   "screenName",      // Writes a key "screenName" to the dataLayer map.
                                   "Home Screen")     // Writes a value "Home Screen" for the "screenName" key.
    );
  }
  // Rest of the Activity implementation
}

En la interfaz web, ahora puedes crear etiquetas (como las de Google Analytics) para que se activen para cada vista de pantalla creando esta regla: es igual a "openScreen". Para pasar el nombre de la pantalla a una de estas etiquetas, crea una macro de capa de datos que haga referencia a la clave "screenName" en la capa de datos. También puedes crear una etiqueta (como un píxel de conversión de Google Ads) para que se active solo para vistas de pantalla específicas. Para ello, crea una regla en la que sea igual a "openScreen" && sea igual a "ConfirmationScreen".

6. Obtén una vista previa de un contenedor y publícalo

Los valores de las macros siempre corresponderán a la versión publicada actual. Antes de publicar la versión más reciente de un contenedor, puedes obtener una vista previa del contenedor en borrador.

Para obtener una vista previa de un contenedor, genera una URL de vista previa en la interfaz web de Google Tag Manager. Para ello, selecciona la versión del contenedor que deseas obtener una vista previa y, luego, selecciona Preview. Guarda esta URL de vista previa, ya que la necesitarás en pasos posteriores.

Las URLs de vista previa están disponibles en la ventana de vista previa de la interfaz web de Tag Manager.
Figura 1: Cómo obtener una URL de vista previa de la interfaz web de Tag Manager.

A continuación, agrega la siguiente actividad al archivo AndroidManifest.xml de tu aplicación:

<!-- Google Tag Manager Preview Activity -->
<activity
  android:name="com.google.tagmanager.PreviewActivity"
  android:label="@string/app_name"
  android:noHistory="true" >  <!-- Optional, removes the PreviewActivity from activity stack. -->
  <intent-filter>
    <data android:scheme="tagmanager.c.application_package_name" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE"/>
  </intent-filter>
</activity>

Abre el vínculo en un emulador o dispositivo físico para obtener una vista previa del contenedor en borrador en tu app.

Cuando tengas todo listo para que los valores de configuración en borrador estén disponibles para tu aplicación, publica el contenedor.

Configuración avanzada

Google Tag Manager para dispositivos móviles tiene varias opciones de configuración avanzadas que te permiten seleccionar valores según las condiciones del tiempo de ejecución con reglas, actualizar el contenedor de forma manual y obtener opciones adicionales para abrir contenedores. En las siguientes secciones, se describen varias de las configuraciones avanzadas más comunes.

Opciones avanzadas para abrir contenedores

El SDK de Google Tag Manager proporciona varios métodos para abrir contenedores que pueden brindarte más control sobre el proceso de carga:

TagManager.openContainer()

TagManager.openContainer() es la API de nivel más bajo y más flexible para abrir un contenedor. Muestra un contenedor predeterminado de inmediato y también carga de forma asíncrona un contenedor desde el disco o la red si no existe un contenedor guardado o si el contenedor guardado no está actualizado (tiene más de 12 horas).

mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {

  // Called when a refresh is about to begin for the given refresh type.
  @Override
  public void containerRefreshBegin(Container container, RefreshType refreshType) {
    // Notify UI that the Container refresh is beginning.
   }

  // Called when a successful refresh occurred for the given refresh type.
  @Override
  public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
    // Notify UI that Container is ready.
  }

  // Called when a refresh failed for the given refresh type.
  @Override
  public void containerRefreshFailure(Container container,
                                      RefreshType refreshType,
                                      RefreshFailure refreshFailure) {
    // Notify UI that the Container refresh has failed.
  }

Durante todo el proceso de carga, TagManager.openContainer() emite varias devoluciones de llamada del ciclo de vida para que tu código pueda saber cuándo comienza la solicitud de carga, si falla o tiene éxito, y por qué, y si el contenedor se cargó finalmente desde el disco o la red.

A menos que sea aceptable que tu aplicación use los valores predeterminados, deberás usar estas devoluciones de llamada para saber cuándo se cargó un contenedor guardado o de red. Ten en cuenta que no podrás cargar un contenedor guardado o de red si es la primera vez que se ejecuta la app y no hay conexión de red.

TagManager.openContainer() pasa los siguientes valores enum como argumentos a estas devoluciones de llamada:

RefreshType

ValorDescripción
Container.Callback.SAVED La solicitud de actualización está cargando un contenedor guardado de forma local.
Container.Callback.NETWORK La solicitud de actualización está cargando un contenedor a través de la red.

RefreshFailure

ValorDescripción
Container.Callback.NO_SAVED_CONTAINER No hay ningún contenedor guardado disponible.
Container.Callback.IO_ERROR Un error de E/S impidió la actualización del contenedor.
Container.Callback.NO_NETWORK No hay conexión de red disponible.
Container.Callback.NETWORK_ERROR Se produjo un error de red.
Container.Callback.SERVER_ERROR Se produjo un error en el servidor.
Container.Callback.UNKNOWN_ERROR Se produjo un error que no se puede categorizar.

Métodos para abrir contenedores no predeterminados y nuevos

ContainerOpener encapsula TagManager.openContainer() y proporciona dos métodos de conveniencia para abrir contenedores: ContainerOpener.openContainer(..., Notifier notifier) y ContainerOpener.openContainer(..., Long timeoutInMillis).

Cada uno de estos métodos toma una enumeración que solicita un contenedor no predeterminado o nuevo.

Se recomienda OpenType.PREFER_NON_DEFAULT para la mayoría de las aplicaciones y se intenta mostrar el primer contenedor no predeterminado disponible dentro de un período de tiempo de espera determinado, ya sea desde el disco o la red, incluso si ese contenedor tiene más de 12 horas. Si muestra un contenedor guardado obsoleto, también realizará una solicitud de red asíncrona para obtener uno nuevo. Cuando se usa OpenType.PREFER_NON_DEFAULT, se mostrará un contenedor predeterminado si no hay ningún otro contenedor disponible o si se supera el período de tiempo de espera.

OpenType.PREFER_FRESH intenta mostrar un contenedor nuevo desde el disco o la red dentro del período de tiempo de espera determinado. Muestra un contenedor guardado si no hay una conexión de red disponible o si se supera el período de tiempo de espera.

No se recomienda usar OpenType.PREFER_FRESH en lugares donde un tiempo de solicitud más largo puede afectar notablemente la experiencia del usuario, como con marcas de la IU o cadenas de visualización. También puedes usar Container.refresh() en cualquier momento para forzar una solicitud de contenedor de red.

Ambos métodos de conveniencia no son bloqueadores. ContainerOpener.openContainer(..., Long timeoutInMillis) muestra un ContainerOpener.ContainerFuture objeto, cuyo get método muestra un Container en cuanto se carga (pero se bloqueará hasta entonces). El método ContainerOpener.openContainer(..., Notifier notifier) toma una sola devolución de llamada, a la que se llama cuando el contenedor está disponible, que se puede usar para evitar bloquear el subproceso principal. Ambos métodos tienen un período de tiempo de espera predeterminado de 2000 milisegundos.

Evalúa macros en el tiempo de ejecución con reglas

Los contenedores pueden evaluar valores en el tiempo de ejecución con reglas. Las reglas pueden basarse en criterios como el idioma del dispositivo, la plataforma o cualquier otro valor de macro. Por ejemplo, las reglas se pueden usar para seleccionar una cadena de visualización localizada según el idioma del dispositivo en el tiempo de ejecución. Esto se puede configurar con la siguiente regla:

Se usa una regla para seleccionar cadenas de visualización según el idioma del dispositivo en el tiempo de ejecución: el idioma es igual a es. Esta regla usa la macro de idioma predefinida y un código de idioma ISO 639-1 de dos caracteres.
Figura 1:Cómo agregar una regla para habilitar una macro de recopilación de valores solo para dispositivos configurados para usar el idioma español.

Luego, puedes crear macros de recopilación de valores para cada idioma y agregar esta regla a cada macro, insertando el código de idioma adecuado. Cuando se publique este contenedor, tu aplicación podrá mostrar cadenas de visualización localizadas, según el idioma del dispositivo del usuario en el tiempo de ejecución.

Ten en cuenta que, si tu contenedor predeterminado necesita reglas, debes usar un archivo de contenedor binario como contenedor predeterminado.

Obtén más información para configurar reglas (Centro de ayuda).

Archivos de contenedor predeterminados binarios

Los contenedores predeterminados que necesitan reglas deben usar un archivo de contenedor binario en lugar de un JSON archivo como contenedor predeterminado. Los contenedores binarios ofrecen compatibilidad para determinar los valores de las macros en el tiempo de ejecución con las reglas de Google Tag Manager, mientras que los archivos JSON no lo hacen.

Los archivos de contenedor binarios se pueden descargar desde la interfaz web de Google Tag Manager y deben agregarse a la carpeta de tu proyecto y seguir este patrón: , en el que el nombre de archivo representa el ID del contenedor./assets/tagmanager//assets/tagmanager/GTM-XXXX

En los casos en los que haya un archivo JSON y un archivo de contenedor binario, el SDK usará el archivo de contenedor binario como contenedor predeterminado.

Usa macros de llamada a función

Las macros de llamada a función son macros que se establecen en el valor que muestra una función especificada en tu aplicación. Las macros de llamada a función se pueden usar para incorporar valores de tiempo de ejecución con tus reglas de Google Tag Manager, como determinar en el tiempo de ejecución qué precio mostrar a un usuario según el idioma y la moneda configurados de un dispositivo.

Para configurar una macro de llamada a función, haz lo siguiente:

  1. Define la macro de llamada a función en la interfaz web de Google Tag Manager. De manera opcional, los argumentos se pueden configurar como pares clave-valor.
  2. Registra un FunctionCallMacroHandler en tu aplicación con Container.registerFunctionCallMacroHandler() y el nombre de la función que configuraste en la interfaz web de Google Tag Manager, anulando su getValue() método: 
    /**
 * Registers a function call macro handler.
 *
 * @param functionName The function name field, as defined in the Google Tag
 *     Manager web interface.
 */
mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() {

  /**
   * This code will execute when any custom macro's rule(s) evaluate to true.
   * The code should check the functionName and process accordingly.
   *
   * @param functionName Corresponds to the function name field defined
   *     in the Google Tag Manager web interface.
   * @param parameters An optional map of parameters
   *     as defined in the Google Tag Manager web interface.
   */
  @Override
  public Object getValue(String functionName, Map<String, Object> parameters)) {

    if (functionName.equals("myConfiguredFunctionName")) {
      // Process and return the calculated value of this macro accordingly.
      return macro_value
    }
    return null;
  }
});

Usa etiquetas de llamada a función

Las etiquetas de llamada a función permiten que se ejecuten funciones registradas previamente cada vez que se envía un evento a la capa de datos y las reglas de la etiqueta se evalúan como true.

Para configurar una etiqueta de llamada a función, haz lo siguiente:

  1. Define la etiqueta de llamada a función en la interfaz web de Google Tag Manager. De manera opcional, los argumentos se pueden configurar como pares clave-valor.
  2. Registra un controlador de etiquetas de llamada a función en tu aplicación con Container.registerFunctionCallTagHandler(): 
    /**
 * Register a function call tag handler.
 *
 * @param functionName The function name, which corresponds to the function name field
 *     Google Tag Manager web interface.
 */
mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() {

  /**
   * This method will be called when any custom tag's rule(s) evaluates to true.
   * The code should check the functionName and process accordingly.
   *
   * @param functionName The functionName passed to the functionCallTagHandler.
   * @param parameters An optional map of parameters as defined in the Google
   *     Tag Manager web interface.
   */
  @Override
  public void execute(String functionName, Map<String, Object> parameters) {
    if (functionName.equals("myConfiguredFunctionName")) {
      // Process accordingly.
    }
  }
});

Establece un período de actualización personalizado

El SDK de Google Tag Manager intentará recuperar un contenedor nuevo si la antigüedad del contenedor actual supera las 12 horas. Para establecer un período de actualización de contenedor personalizado, usa Timer, como en el siguiente ejemplo:

timer.scheduleTask(new TimerTask() {
  @Override
  public void run() {
    mContainer.refresh();
  }
}, delay, <new_period_in milliseconds>);

Depura con Logger

De forma predeterminada, el SDK de Google Tag Manager imprime errores y advertencias en los registros. Habilitar un registro más detallado puede ser útil para la depuración y es posible implementando tu propio Logger con TagManager.setLogger, como en este ejemplo:

TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {

  final String TAG = "myGtmLogger";

  // Log output with verbosity level of DEBUG.
  @Override
  public void d(String arg0) {
    Log.d(TAG, arg0);
  }

  // Log exceptions when provided.
  @Override
  public void d(String arg0, Throwable arg1) {
    Log.d(TAG, arg0);
    arg1.printStackTrace();
  }

  // Rest of the unimplemented Logger methods.

});

También puedes establecer el LogLevel del Logger existente con TagManager.getLogger().setLogLevel(LogLevel) , como en este ejemplo:

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
TagManager tagManager = TagManager.getInstance(this);
tagManager.getLogger().setLogLevel(LogLevel.INFO);