Android v3 (heredado): Descripción general

En esta guía, se describen las APIs que pertenecen a una versión heredada del SDK. Los usuarios nuevos deben Comienza a usar el SDK más reciente.

Nota: En esta guía, se describe la implementación anterior de la etiqueta de Google en aplicaciones para Android. Los usuarios nuevos deben utilizar Tag Manager y Firebase para implementar Google Tag Manager en sus aplicaciones para iOS.

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

Introducción

Google Tag Manager permite a los desarrolladores cambiar valores en sus aplicaciones para dispositivos móviles con Google Tag Manager sin tener que recompilar y volver a enviar los objetos binarios de la aplicación a la app mercados.

Esto es útil para administrar cualquier valor de configuración o marcas en tu aplicación que debas cambiar en el futuro, como:

• Diversas opciones de configuración de la IU y cadenas de la pantalla
• Tamaños, ubicaciones o 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 tiempo de ejecución usando reglas, habilitar parámetros de configuración dinámicos, como los siguientes:

• Cómo usar el tamaño de la pantalla para determinar el tamaño del banner de 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 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é píxeles o etiquetas de seguimiento deben activarse. Actualmente, TagManager admite las siguientes etiquetas:

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

Antes de comenzar

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

• Una cuenta de Google Tag Manager
• Una nueva versión de Tag Manager macro de colección de contenedor y valor
• Una aplicación para dispositivos móviles Android en la que se puede implementar Google Tag Manager
• Los servicios de Google Analytics SDK, que contiene la biblioteca de Tag Manager.

Si es la primera vez que utilizas Google Tag Manager, te recomendamos obtén más información sobre contenedores, macros y 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 los valores predeterminados de los contenedores
3. Abre el contenedor
4. Obtén los valores de configuración del contenedor
5. Cómo enviar eventos a DataLayer
6. Vista previa y Publica el contenedor

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

Antes de usar el SDK de Google Tag Manager, deberás descomprimir el paquete del SDK, agregar la biblioteca a la ruta 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 que use lo siguiente: 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

Nota: Si todavía no tienes configuraste tu contenedor en la interfaz web de Google Tag Manager vuelve a este paso una vez que lo hayas hecho.

Google Tag Manager usa un contenedor predeterminado en la primera ejecución de tu aplicación. Predeterminado hasta que la aplicación pueda recuperar un nuevo contenedor en cada 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: <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 optar por utilizar una forma sencilla JSON en su lugar. El archivo debe estar ubicado en un nuevo /assets/tagmanager de tu proyecto de Android y debería seguir esta convención de nombres: <Container_ID>.json Por ejemplo, si el ID del contenedor es GTM-1234, debes agregar los valores de contenedor predeterminados /assets/tagmanager/GTM-1234.json

3. Abrir un contenedor

Antes de recuperar valores de un contenedor, tu aplicación debe abrirse el contenedor. Abrir un contenedor lo cargará desde el disco (si está disponible). lo solicitará a la red (si es necesario).

La forma más fácil de abrir un contenedor en Android es con 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 lo siguiente: solicitar un contenedor guardado en el almacenamiento local. Al controlar la asignación de mContainer en la devolución de llamada containerAvailable, nos aseguramos subproceso principal no esté bloqueado. Si el contenedor guardado tiene más de 12 horas de antigüedad, el 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 ejemplo representa la forma más sencilla de abrir y recuperar de un contenedor con la clase de conveniencia ContainerOpener Para ver opciones de implementación más avanzadas, consulta Configuración avanzada.

4. Obtener valores de configuración del contenedor

Una vez que el contenedor está abierto, se pueden recuperar los valores de configuración mediante 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 apropiado al 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 habilita información sobre el tiempo de ejecución de tu app, como eventos o vistas de pantalla, que estarán disponibles para las macros y etiquetas de Tag Manager en un contenedor.

Por ejemplo, al enviar 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 visitas a una pantalla sin necesidad de dificultar codificarlos en tu app.

Los eventos se envían a DataLayer mediante push() y Método de ayuda 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) para activar cada vista de pantalla creando esta regla: equivale a "openScreen". Para pasar el nombre de la pantalla, haz lo siguiente: a una de estas etiquetas, cree una macro de capa de datos que haga referencia a "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 activen solo en vistas de pantalla específicas, creando una regla en la que sea igual a "openScreen" & es igual a "ConfirmationScreen".

Nota: Claves y valores de eventos de DataLayer se debe usar de la forma más coherente posible. las vistas de pantalla usan "openScreen" como el valor del evento y "screenName" como la tecla de nombre de pantalla. Esto hace que acceder a DataLayer y crear etiquetas adicionales en el futuro de la manera más fácil posible.

6. Vista previa y Publicación de un contenedor

Los valores de 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 tu contenedor en borrador.

Para obtener una vista previa de un contenedor, genera una URL de vista previa en la pestaña La interfaz web de Tag Manager seleccionando la versión del contenedor deseas obtener una vista previa y, luego, selecciona Preview. Conserva esta URL de vista previa, ya que la necesitarás en pasos posteriores.

Figura 1: Obtención de una URL de vista previa desde Interfaz web de Tag Manager

Luego, agrega la siguiente actividad al archivo Archivo AndroidManifest.xml:

<!-- 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>
  

Nota: application_package_name debe coincidir con el nombre de la app que se usa para generar la URL de vista previa (Figura 1).

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

Cuando esté todo listo para que tus valores de configuración de borrador estén disponibles para tu aplicación, publicar el contenedor

Configuración avanzada

Google Tag Manager para dispositivos móviles ofrece diversas opciones de configuración avanzada. que te permiten seleccionar valores según las condiciones del entorno de ejecución usando actualizar el contenedor de forma manual y obtener opciones adicionales contenedores. En las siguientes secciones, se describen varias de las técnicas avanzadas parámetros de configuración.

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 la API de nivel más bajo y más flexible para abrir una contenedor. Se muestra inmediatamente con un contenedor predeterminado y también carga de forma asíncrona un contenedor desde el disco o la red si no hay contenedor existe o si el contenedor guardado no está actualizado (con 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() problemas varias devoluciones de llamada de ciclo de vida para que el código pueda detectar cuándo se antes de comenzar una solicitud de carga, si falla o se realiza de forma correcta y de que 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 un archivo se cargó el contenedor. Ten en cuenta que no podrás cargar un archivo de red si es la primera vez que se ejecuta la app y no hay conexión de red.

TagManager.openContainer() pasa el siguiente enum: como argumentos para estas devoluciones de llamada:

RefreshType

Valor	Descripción
Container.Callback.SAVED	La solicitud de actualización carga un contenedor guardado de forma local.
Container.Callback.NETWORK	La solicitud de actualización carga un contenedor en la red.

RefreshFailure

Valor	Descripción
Container.Callback.NO_SAVED_CONTAINER	No hay ningún contenedor guardado disponible.
Container.Callback.IO_ERROR	Un error de E/S evitó que se actualizara el contenedor.
Container.Callback.NO_NETWORK	No hay una 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 solicitando una solicitud no predeterminada o contenedor nuevo.

OpenType.PREFER_NON_DEFAULT se recomienda para la mayoría de las aplicaciones y intenta mostrar el primer contenedor no predeterminado disponible dentro de un tiempo de espera, ya sea desde el disco o la red, incluso si el contenedor es mayor hace más de 12 horas. Si devuelve un contenedor inactivo guardado, también hará una de red asíncrona por una nueva. Cuando usas OpenType.PREFER_NON_DEFAULT, se usará el contenedor se devolverá si no hay otro contenedor disponible o si el tiempo de espera es superada.

OpenType.PREFER_FRESH intenta mostrar un contenedor nuevo de disco o red dentro del tiempo de espera establecido. Devuelve un contenedor guardado si una red la conexión no está disponible o se superó el tiempo de espera.

No se recomienda usar OpenType.PREFER_FRESH en lugares en los que un tiempo más prolongado podría afectar la experiencia del usuario como con marcas de 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 generan bloqueos. ContainerOpener.openContainer(..., Long timeoutInMillis) muestra un Un objeto ContainerOpener.ContainerFuture, cuyo método get muestra un Container en cuanto se cargue (pero se bloqueará hasta entonces). El método ContainerOpener.openContainer(..., Notifier notifier) toma una sola devolución de llamada, 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 milésimas de segundo.

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

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

Figura 1: Incorporación de una regla para habilitar una macro de recopilación de valores solo para dispositivos configurado para usar el idioma español.

Luego, puedes crear macros de recopilación de valores para cada idioma y agregar esto regla a cada macro e insertar el código de idioma apropiado. Cuando este contenedor se publicó, tu aplicación podrá mostrar la visualización localizada 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 tu contenedor.

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

Archivos binarios predeterminados de contenedores

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

Los archivos de contenedores binarios se pueden descargar de la Web de Google Tag Manager interfaz y deben agregarse a la configuración /assets/tagmanager/ y sigue este patrón: /assets/tagmanager/GTM-XXXX, donde el nombre del archivo representa tu el ID del contenedor.

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

Usa macros de llamadas a funciones

Las macros de llamada a función son macros configuradas para el valor que se muestra de una función especificada en tu aplicación. Las macros de llamadas a funciones se pueden usar para incorporar valores de entorno de ejecución con las reglas de Google Tag Manager, como determina en el tiempo de ejecución qué precio mostrar a un usuario según la configuración el idioma y la moneda 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. Los argumentos se pueden configurar de forma opcional 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 para anular 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;
     }
   });
   

Usa etiquetas de llamada a función

Las etiquetas de llamada a función permiten que las funciones con registro previo se ejecuten siempre se envía un evento a la capa de datos, y las reglas de etiquetas evaluar 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. Los argumentos se pueden configurar de forma opcional 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.
       }
     }
   });
   

Cómo configurar 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 el período de actualización del contenedor personalizado, usar 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 registros de forma predeterminada. Habilitar registros más detallados 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.

});

O puedes definir el LogLevel del registrador existente usando 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);