Android v4: Cómo empezar

Introducción

Google Tag Manager permite a los desarrolladores cambiar los valores de configuración en sus aplicaciones para dispositivos móviles mediante la interfaz de Google Tag Manager 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 o marca de configuración en tu aplicación que puedas tener que cambiar en el futuro, por ejemplo:

  • 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
  • Varios parámetros de 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, lo que habilita configuraciones 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 etiquetas y píxeles de seguimiento en las aplicaciones. Los desarrolladores pueden enviar eventos importantes a una capa de datos y decidir más adelante qué etiquetas o píxeles de seguimiento deben activarse.

Antes de comenzar

Completa los siguientes pasos antes de comenzar con esta guía de introducción:

Una vez que hayas completado estos pasos, en el resto de esta guía se te indicará cómo configurar y utilizar Google Tag Manager en tu aplicación para Android.

Getting Started

Después de seguir esta guía de introducción, sabrás cómo hacer lo siguiente:

En esta guía, se usan fragmentos de código de la aplicación de ejemplo Cute Animals incluida con el SDK de Servicios de Google Play. La fuente completa de este proyecto está disponible en <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

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

Para agregar Google Tag Manager a tu proyecto, sigue estos pasos:

  1. Configura el SDK de los Servicios de Google Play.
  2. Si usas un IDE que no sea Android Studio, agrega los siguientes permisos al archivo AndroidManifest.xml: 
    <!-- For TagManager SDK -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  3. Si quieres permitir que InstallReferrerReceiver llame al receptor de Google Analytics para configurar los datos de la campaña, agrega lo siguiente al archivo AndroidManifest.xml: 
    <!-- Used for install referrer tracking-->
<service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
<receiver
  android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
  android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

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 dejará de usarse en cuanto 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, haz lo siguiente:

  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 del contenedor descargado a tu proyecto como recurso sin procesar.
    1. Si la subcarpeta raw en <project-root>/res/ no existe, créala.
    2. Cambia el nombre del archivo binario del contenedor si es necesario. Se compone solo de letras minúsculas, dígitos y guiones bajos.
    3. Copia el archivo binario del contenedor en la carpeta <project-root>/res/raw.

Si bien 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.

3. Cómo inicializar Google Tag Manager

Para inicializar Google Tag Manager en tu aplicación, sigue estos pasos:

  1. Obtén el singleton TagManager: 
    TagManager tagManager = TagManager.getInstance(this);
  2. Usa el singleton TagManager para realizar una solicitud de carga de un contenedor y especifica un ID de contenedor de Google Tag Manager, así como tu archivo contenedor predeterminado. El ID del contenedor debe estar en mayúsculas y coincidir exactamente con el ID del contenedor en la interfaz web de Google Tag Manager. La llamada a loadContainerPreferNonDefault() no genera bloqueos y muestra un PendingResult:
    PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
  3. Usa ResultCallback para mostrar ContainerHolder una vez que se haya terminado de cargar o se haya agotado el tiempo de espera: 
    // The onResult method will be called as soon as one of the following happens:
//     1. a saved container is loaded
//     2. if there is no saved container, a network container is loaded
//     3. the 2-second timeout occurs
pending.setResultCallback(new ResultCallback<ContainerHolder>() {
    @Override
    public void onResult(ContainerHolder containerHolder) {
        ContainerHolderSingleton.setContainerHolder(containerHolder);
        Container container = containerHolder.getContainer();
        if (!containerHolder.getStatus().isSuccess()) {
            Log.e("CuteAnimals", "failure loading container");
            displayErrorToUser(R.string.load_error);
            return;
        }
        ContainerLoadedCallback.registerCallbacksForContainer(container);
        containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
        startMainActivity();
    }
}, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);

    Cómo crear un singleton ContainerHolder

    Solo debes mantener una instancia de ContainerHolder por ejecución de tu aplicación. Por eso, en el ejemplo anterior, se usa una clase de utilidad ContainerHolderSingleton para administrar el acceso a la instancia ContainerHolder. Así se ve la clase ContainerHolderSingleton:

    package com.google.android.tagmanager.examples.cuteanimals;

import com.google.android.gms.tagmanager.ContainerHolder;

/**
 * Singleton to hold the GTM Container (since it should be only created once
 * per run of the app).
 */
public class ContainerHolderSingleton {
    private static ContainerHolder containerHolder;

    /**
     * Utility class; don't instantiate.
     */
    private ContainerHolderSingleton() {
    }

    public static ContainerHolder getContainerHolder() {
        return containerHolder;
    }

    public static void setContainerHolder(ContainerHolder c) {
        containerHolder = c;
    }
}

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

Una vez cargado el contenedor, puedes recuperar valores de configuración mediante cualquiera de los métodos Container.get<type>(). Los valores de configuración se definen mediante las variables de recopilación de valores de Google Tag Manager. Por ejemplo, el siguiente método recupera el color más reciente que decidimos usar para un elemento de la IU y lo muestra como un número entero:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Este código realiza dos acciones para recuperar el nombre del color del contenedor:

  1. Obtiene el Container de ContainerHolder con ContainerHolder.getContainer().
  2. Obtiene el valor de color mediante Container.getString(key), donde definiste la clave y el valor en la interfaz web de Google Tag Manager.

5. Envía eventos y valores a dataLayer

Google Tag Manager también proporciona un dataLayer, en el que puedes enviar información sobre tu aplicación, que se puede leer en otras partes de ella o usarse para activar etiquetas que configuraste en la interfaz web de Google Tag Manager.

Envía valores a dataLayer

dataLayer proporciona una capa de persistencia que puedes usar para almacenar pares clave-valor que tal vez quieras usar en otras partes de tu aplicación o como entradas a las etiquetas de Google Tag Manager.

Para enviar un valor a dataLayer, sigue este patrón:

  1. Obtén el singleton DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Envía el evento con DataLayer.push(): 
    // Put the image_name into the data layer for future use.
TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);

Para obtener un valor de dataLayer, usa DataLayer.get(key).

Envía eventos a dataLayer

Enviar eventos a dataLayer te permite separar el código de tu aplicación de las etiquetas que quizás desees activar en respuesta a esos eventos.

Por ejemplo, en lugar de codificar las llamadas de seguimiento de vista de pantalla de Google Analytics a tu aplicación, puedes enviar eventos de pantalla a dataLayer y definir tus etiquetas de seguimiento a través de la interfaz web de Google Tag Manager. Esto te brinda la flexibilidad de modificar esa etiqueta o agregar etiquetas adicionales que respondan a eventos de pantalla, sin tener que actualizar el código de tu aplicación.

Para enviar un evento a dataLayer, sigue este patrón:

  1. Obtén el singleton DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Envía el evento con DataLayer.pushEvent(): 
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

    DataLayer.mapOf() es un método de utilidades que puedes usar para generar fácilmente un mapa de pares clave-valor que actualizará dataLayer al mismo tiempo que se envía el evento.

6. Vista previa, depuración y publicación

Antes de publicar una versión de tu contenedor, te recomendamos que obtengas una vista previa para asegurarte de que funcione según lo previsto. Google Tag Manager te permite obtener una vista previa de las versiones de tu contenedor mediante la generación de vínculos y códigos QR en la interfaz web y su uso para abrir tu aplicación. También puedes habilitar un modo de registro detallado para depurar cualquier comportamiento inesperado.

Obteniendo vista previa

Para obtener una vista previa de la versión de tu contenedor, sigue estos pasos:

  1. Agregando esta vista previa Activity a tu archivo AndroidManifest: 
    <!--  Add preview activity. -->
<activity
    android:name="com.google.android.gms.tagmanager.PreviewActivity"
    android:label="@string/app_name"
    android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
    <intent-filter>
      <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>

    Asegúrate de modificar esta línea para incluir el nombre del paquete de tu aplicación:

    <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
  2. Genera un vínculo de vista previa en la interfaz web de Google Tag Manager
    1. Cómo acceder a Google Tag Manager
    2. Selecciona la Versión del contenedor para obtener una vista previa.
    3. Haz clic en el botón Vista previa.
    4. Ingresa el nombre del paquete de la aplicación y haz clic en la opción para generar el vínculo para iniciar la vista previa.
  3. Usa el vínculo generado o el código QR para iniciar tu aplicación
  4. Para salir del modo de vista previa, sigue un vínculo generado con la opción Generar vínculo de la vista previa final en la interfaz web.

Depuración

Si necesitas solucionar problemas de la implementación del contenedor, habilita el registro detallado llamando a TagManager.setVerboseLoggingEnabled(true):

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

En proceso de publicación

Una vez que hayas obtenido una vista previa del contenedor y verificado que funciona según lo previsto, puedes publicar el contenedor. Los valores de configuración, las etiquetas y los eventos de los contenedores estarán activos para los usuarios la próxima vez que se actualicen sus contenedores. Obtén más información para actualizar contenedores.

Configuración avanzada

En las siguientes secciones, se describen las opciones de configuración avanzada que puedes usar para personalizar aún más tu implementación de Google Tag Manager.

Cómo actualizar el contenedor

De forma predeterminada, tu contenedor es apto para actualizarse cada 12 horas. Para actualizar el contenedor de forma manual, usa ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Esta es una llamada asíncrona que no se mostrará de inmediato. Para reducir el tráfico de red, solo se puede llamar a refresh() una vez cada 15 minutos; de lo contrario, será una no-op.