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 mediante su interfaz sin tener que volver a compilar y volver a enviar los objetos binarios de la aplicación a los mercados de apps.

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

  • Varias strings de configuración y visualización de la IU
  • Los tamaños, las ubicaciones o los tipos de anuncios que se publican en tu aplicación
  • Configuración de juegos

Los valores de configuración también se pueden evaluar en el entorno de ejecución a través de reglas, que habiliten opciones de configuración dinámicas como las siguientes:

  • Uso del tamaño de la pantalla para determinar el tamaño del banner del anuncio
  • Cómo usar el idioma y la ubicación para configurar los elementos de la IU

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

  • Google Analytics para aplicaciones para dispositivos 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.

Getting Started

Esta sección guiará a los desarrolladores por un flujo de trabajo típico de Tag Manager:

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

1. Cómo agregar el SDK de Google Tag Manager a tu proyecto

Antes de usar el SDK de Google Tag Manager, debes descomprimir el paquete de SDK, agregar la biblioteca a la ruta de compilación de tu proyecto y agregar permisos al archivo AndroidManifest.xml.

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

A continuación, actualiza el 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. Cómo agregar 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 objeto 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 o etiquetas, puedes optar por usar un archivo JSON simple en su lugar. El archivo debe estar ubicado en una carpeta /assets/tagmanager nueva de tu proyecto de Android y debe seguir esta convención de nombres: <Container_ID>.json. Por ejemplo, si el ID del contenedor es GTM-1234, debes agregar los valores predeterminados del contenedor a /assets/tagmanager/GTM-1234.json.

3. Cómo abrir un contenedor

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

La forma más fácil 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, ContainerOpener.openContainer(..., Notifier notifier) se usa para solicitar un contenedor guardado desde el almacenamiento local. Si controlas 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 de antigüedad, 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 mediante la clase de conveniencia ContainerOpener. Para ver 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, los valores de configuración se pueden recuperar mediante los métodos get<type>Value():

// 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 que no existe mostrarán un valor predeterminado apropiado 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 DataLayer

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

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

Los eventos se envían a DataLayer mediante push() y el método auxiliar DataLayer.mapOf():

//
// 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) que se activarán para cada vista de pantalla creando esta regla: equivale a "openScreen". Para pasar el nombre de 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 en vistas de pantallas específicas. Para ello, debes crear una regla en la que equivalga a "openScreen" & y sea igual a "ConfirmationScreen".

6. Vista previa y publicación de un contenedor

Los valores de la macro 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.

Si deseas 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 de la que deseas obtener una vista previa y, luego, Preview. Mantén 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: Obtención de 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 de borrador en tu app.

Cuando tengas todo listo para que los valores de configuración de 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 avanzada que te permiten seleccionar valores según las condiciones de tiempo de ejecución mediante 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 darte más control sobre el proceso de carga:

TagManager.openContainer()

TagManager.openContainer() es el nivel más bajo y la API más flexible para abrir un contenedor. Se muestra de inmediato con un contenedor predeterminado y también carga un contenedor de forma asíncrona 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 de antigüedad).

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 el proceso de carga, TagManager.openContainer() emite varias devoluciones de llamada de ciclo de vida para que tu código pueda determinar cuándo comienza la solicitud de carga, si falla o se realiza de forma correcta, y si el contenedor se cargó en última instancia 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 de red o guardado. Ten en cuenta que no podrás cargar un contenedor de red o guardado 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 localmente.
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ó que se actualizara el contenedor.
Container.Callback.NO_NETWORK No hay ninguna 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 nuevos y no predeterminados

ContainerOpener une TagManager.openContainer() y proporciona dos métodos convenientes 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 nuevo o no predeterminado.

Se recomienda OpenType.PREFER_NON_DEFAULT para la mayoría de las aplicaciones y trata de 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 el contenedor tiene más de 12 horas de antigüedad. Si muestra un contenedor guardado inactivo, también realizará una solicitud de red asíncrona para 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 excede el tiempo de espera.

OpenType.PREFER_FRESH intenta mostrar un contenedor nuevo desde el disco o la red dentro del tiempo de espera determinado. Muestra un contenedor guardado si una conexión de red no está disponible o si se supera el 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 IU o strings 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 realizan bloqueos. ContainerOpener.openContainer(..., Long timeoutInMillis) muestra un objeto ContainerOpener.ContainerFuture, cuyo método get muestra un Container en cuanto se carga (pero se bloqueará hasta ese momento). El método ContainerOpener.openContainer(..., Notifier notifier) recibe una sola devolución de llamada, que se llama cuando el contenedor está disponible, que se puede usar para evitar que se bloquee el subproceso principal. Ambos métodos tienen un tiempo de espera predeterminado de 2000 milisegundos.

Evalúa macros en el entorno de ejecución mediante reglas

Los contenedores pueden evaluar valores en el entorno de ejecución mediante reglas. Las reglas pueden basarse en criterios como el idioma del dispositivo, la plataforma o cualquier otro valor de macro. Por ejemplo, se pueden usar reglas para seleccionar una string de pantalla 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 strings de visualización según el idioma del dispositivo durante el tiempo de ejecución: 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: Se agregó una regla para habilitar una macro de recopilación de valores solo en dispositivos configurados para usar el idioma español.

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

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

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

Archivos de contenedores binarios predeterminados

Los contenedores predeterminados que necesitan reglas deben usar un archivo de contenedor binario en lugar de un archivo JSON como contenedor predeterminado. Los contenedores binarios son compatibles con la determinación de valores de macros en el entorno de ejecución con las reglas de Google Tag Manager, mientras que los archivos JSON no.

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

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

Cómo usar macros de llamada a funciones

Las macros de llamada a funciones son macros que se configuran con el valor que se muestra de una función específica en tu aplicación. Las macros de llamada a funciones se pueden usar para incorporar valores del entorno de ejecución con las reglas de Google Tag Manager, como determinar en el entorno de ejecución qué precio mostrar a un usuario en función del 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 y anula su método getValue():
    /**
     * 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;
      }
    });
    

Cómo usar etiquetas de llamada a funciones

Las etiquetas de llamada a función permiten que se ejecuten funciones con registro previo cada vez que se envíe un evento a la capa de datos y las reglas de la etiqueta se evalúen como true.

Para configurar una etiqueta de llamada a función, sigue estos pasos:

  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 etiqueta 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.
        }
      }
    });
    

Cómo establecer un período de actualización personalizado

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

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

Depuración con Logger

El SDK de Google Tag Manager imprime errores y advertencias en los registros de forma predeterminada. Habilitar un registro más detallado puede ser útil para la depuración y es posible si implementas 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 nivel de registro del registrador 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);
.