Android v3 (legado) - Visão geral

Este guia descreve as APIs que pertencem a uma versão legada do SDK. Novos usuários precisam começar a usar o SDK mais recente.

Observação:este guia descreve a implementação antiga do Gerenciador de tags do Google em apps Android. Os novos usuários devem usar o Gerenciador de tags + Firebase para implementar o Gerenciador de tags do Google nos aplicativos iOS.

Neste guia do desenvolvedor, descrevemos como implementar o Gerenciador de tags do Google em um aplicativo para dispositivos móveis.

Introdução

Com o Gerenciador de tags do Google, os desenvolvedores podem alterar os valores de configuração nos apps para dispositivos móveis usando a interface dessa ferramenta sem precisar recriar e reenviar os binários de aplicativos aos marketplaces.

Isso é útil para gerenciar todos os valores de configuração ou sinalizações no aplicativo que você possa precisar alterar no futuro, incluindo:

• Várias configurações de interface e strings de exibição.
• Tamanhos, locais ou tipos de anúncios veiculados no seu aplicativo
• Configurações de jogos

Os valores de configuração também podem ser avaliados no ambiente de execução usando regras, permitindo configurações dinâmicas como:

• Usando o tamanho da tela para determinar o tamanho do banner do anúncio
• Como usar o idioma e o local para configurar elementos da interface

O Google TagManager também permite a implementação dinâmica de tags de acompanhamento e pixels de acompanhamento em aplicativos. Eles podem enviar eventos importantes para uma camada de dados e decidir quais pixels ou tags de acompanhamento devem ser disparados. No momento, o TagManager é compatível com as seguintes tags:

• Google Mobile App Analytics
• Tag de chamada de função personalizada

Antes de começar

Antes de usar este Guia explicativo, você precisa do seguinte:

• Uma conta do Gerenciador de tags do Google
• Uma nova macro de coleta de valores e contêiner do Gerenciador de tags
• Um aplicativo para dispositivos móveis Android no qual é possível implementar o Gerenciador de tags do Google
• O SDK de serviços do Google Analytics, que contém a biblioteca do Gerenciador de tags.

Se você não tem experiência com o Gerenciador de tags do Google, recomendamos que saiba mais sobre contêineres, macros e regras (Central de Ajuda) antes de continuar este guia.

Vamos começar

Esta seção orienta os desenvolvedores pelo fluxo de trabalho típico do Gerenciador de tags:

1. Adicionar o SDK do Gerenciador de tags do Google ao seu projeto
2. Definir valores de contêiner padrão
3. Abra o contêiner
4. Receber valores de configuração do contêiner
5. Enviar eventos para a DataLayer
6. Visualizar e publicar o contêiner

1. Como adicionar o SDK do Gerenciador de tags do Google ao seu projeto

Antes de usar o SDK do Gerenciador de tags do Google, descompacte o pacote do SDK, adicione a biblioteca ao caminho de criação do projeto e inclua permissões no arquivo AndroidManifest.xml.

Primeiro, adicione a biblioteca do Gerenciador de tags do Google à pasta /libs do projeto.

Em seguida, atualize o arquivo AndroidManifest.xml para usar as seguintes permissões:

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

2. Como adicionar um arquivo de contêiner padrão ao seu projeto

Observação: se você ainda não configurou seu contêiner na interface da Web do Gerenciador de tags do Google, volte para esta etapa depois.

O Gerenciador de tags do Google usa um contêiner padrão na primeira execução do seu aplicativo. O contêiner padrão será usado até que o app possa recuperar um novo contêiner pela rede.

Para fazer o download e adicionar um binário de contêiner padrão ao aplicativo, siga estas etapas:

1. Faça login na interface da Web do Gerenciador de tags do Google.
2. Selecione a Versão do contêiner que você quer fazer o download.
3. Clique no botão Download para recuperar o binário do contêiner.
4. Adicione o arquivo binário ao seguinte caminho: <project-root>/assets/tagmanager/

O nome de arquivo padrão precisa ser o ID do contêiner (por exemplo, GTM-1234). Depois de fazer o download do arquivo binário, remova o sufixo da versão do nome do arquivo para garantir que você siga a convenção de nomenclatura correta.

Embora o uso do arquivo binário seja recomendado, se o contêiner não tiver regras ou tags, use um arquivo JSON simples. O arquivo precisa estar localizado em uma nova pasta /assets/tagmanager do projeto Android e seguir esta convenção de nomenclatura: <Container_ID>.json. Por exemplo, se o ID do contêiner for GTM-1234, adicione os valores padrão do contêiner a /assets/tagmanager/GTM-1234.json.

3. Abrir um contêiner

Antes de recuperar valores de um contêiner, seu aplicativo precisa abrir o contêiner. Quando um contêiner é aberto, ele é carregado do disco (se disponível) ou pela rede (se necessário).

A maneira mais fácil de abrir um contêiner no Android é usando ContainerOpener.openContainer(..., Notifier notifier), como no exemplo a seguir:

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.
  }
}

Neste exemplo, ContainerOpener.openContainer(..., Notifier notifier) é usado para solicitar um contêiner salvo do armazenamento local. Ao processar a atribuição de mContainer no callback containerAvailable, garantimos que a linha de execução principal não esteja bloqueada. Se o contêiner salvo tiver mais de 12 horas, a chamada também agendará uma solicitação para recuperar de maneira assíncrona um novo contêiner pela rede.

Esse exemplo de implementação representa a maneira mais simples de abrir e recuperar valores de um contêiner usando a classe de conveniência ContainerOpener. Para opções de implementação mais avançadas, consulte Configuração avançada.

4. Como receber valores de configuração do contêiner

Quando o contêiner é aberto, os valores de configuração podem ser recuperados usando os 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");

As solicitações feitas com uma chave inexistente retornarão um valor padrão apropriado ao 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. Enviar valores para a DataLayer

A DataLayer é um mapa que permite que informações do ambiente de execução sobre seu app, como eventos de toque ou exibições de tela, sejam disponibilizadas para macros e tags do Gerenciador de tags em um contêiner.

Por exemplo, ao inserir informações sobre exibições de tela no mapa da DataLayer, você pode configurar tags na interface da Web do Gerenciador de tags para disparar pixels de conversão e acompanhar chamadas em resposta a essas exibições de tela sem precisar codificá-las no seu app.

Os eventos são enviados à DataLayer usando push() e o 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
}

Na interface da Web, agora é possível criar tags (como tags do Google Analytics) que são disparadas para cada exibição de tela. Para isso, crie esta regra: é igual a "openScreen". Para transmitir o nome da tela a uma dessas tags, crie uma macro de camada de dados que faça referência à chave "screenName" na camada de dados. Você também pode criar uma tag (como um pixel de conversão do Google Ads) para disparar somente em exibições de tela específicas. Para isso, crie uma regra em que seja igual a "openScreen" && seja igual a "ConfirmationScreen".

Observação: os valores e as chaves do evento DataLayer precisam ser usados da maneira mais consistente possível para que, neste exemplo, todas as exibições de tela usem "openScreen" como valor do evento e "screenName" como a chave do nome da tela. Isso facilita ao máximo o acesso à DataLayer e a criação de outras tags no futuro.

6. Como visualizar e publicar um contêiner

Os valores das macro sempre corresponderão à versão publicada atual. Antes de publicar a versão mais recente de um contêiner, você pode visualizar seu contêiner de rascunho.

Para gerar um URL de visualização, gere um URL de visualização na interface da Web do Gerenciador de tags do Google. Para isso, escolha a versão do contêiner que você quer visualizar e selecione Preview. Segure esse URL de visualização, porque você precisará dele nas próximas etapas.

Figura 1 : como gerar um URL de visualização na interface da Web do Gerenciador de tags.

Em seguida, adicione a atividade abaixo ao arquivo AndroidManifest.xml do aplicativo:

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

Observação: application_package_name precisa corresponder ao nome do app usado para gerar o URL de visualização (Figura 1).

Abra o link em um emulador ou dispositivo físico para visualizar o contêiner de rascunho no seu app.

Quando estiver tudo pronto para disponibilizar os valores de configuração de rascunho no seu aplicativo, publique o contêiner.

Configuração avançada

O Gerenciador de tags do Google para dispositivos móveis tem várias opções avançadas de configuração que permitem selecionar valores com base nas condições de ambiente de execução usando regras, atualizar manualmente o contêiner e ter mais opções para abrir contêineres. As seções a seguir descrevem várias das configurações avançadas mais comuns.

Opções avançadas para abrir contêineres

O SDK do Gerenciador de tags do Google oferece vários métodos para abrir contêineres que oferecem mais controle sobre o processo de carregamento:

TagManager.openContainer()

TagManager.openContainer() é a API de nível mais baixo e mais flexível para abrir um contêiner. Ele retorna imediatamente com um contêiner padrão e também carrega de maneira assíncrona um contêiner do disco ou da rede se não houver um contêiner salvo ou se o contêiner salvo não for atualizado (há mais 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.
  }

Ao longo do processo de carregamento, TagManager.openContainer() emite vários callbacks de ciclo de vida para que seu código possa descobrir quando a solicitação de carregamento começa, se e por que ela falha ou teve êxito e se o contêiner foi carregado do disco ou da rede.

A menos que seja aceitável que seu aplicativo use os valores padrão, você vai precisar usar esses callbacks para saber quando um contêiner salvo ou de rede foi carregado. Não será possível carregar um contêiner salvo ou de rede se esta for a primeira vez que o app for executado e não houver conexão de rede.

O TagManager.openContainer() transmite os seguintes valores de enum como argumentos para esses callbacks:

RefreshType

Valor	Descrição
Container.Callback.SAVED	A solicitação de atualização está carregando um contêiner salvo localmente.
Container.Callback.NETWORK	A solicitação de atualização está carregando um contêiner na rede.

RefreshFailure

Valor	Descrição
Container.Callback.NO_SAVED_CONTAINER	Não há contêineres salvos disponíveis.
Container.Callback.IO_ERROR	Um erro de E/S impediu a atualização do contêiner.
Container.Callback.NO_NETWORK	Não há conexão de rede disponível.
Container.Callback.NETWORK_ERROR	Ocorreu um erro de rede.
Container.Callback.SERVER_ERROR	Ocorreu um erro no servidor.
Container.Callback.UNKNOWN_ERROR	Ocorreu um erro que não pode ser classificado.

Métodos para abrir contêineres novos e não padrão

ContainerOpener envolve TagManager.openContainer() e fornece dois métodos convenientes para abrir contêineres: ContainerOpener.openContainer(..., Notifier notifier) e ContainerOpener.openContainer(..., Long timeoutInMillis).

Cada um desses métodos usa uma enumeração que solicita um contêiner não padrão ou novo.

O OpenType.PREFER_NON_DEFAULT é recomendado para a maioria dos aplicativos e tenta retornar o primeiro contêiner não padrão disponível dentro de um determinado período de tempo limite, seja do disco ou da rede, mesmo que esse contêiner tenha mais de 12 horas. Se ele retornar um contêiner salvo desatualizado, ele também vai fazer uma solicitação de rede assíncrona para um novo. Ao usar OpenType.PREFER_NON_DEFAULT, um contêiner padrão será retornado se nenhum outro contêiner estiver disponível ou se o período de tempo limite for excedido.

OpenType.PREFER_FRESH tenta retornar um novo contêiner do disco ou da rede dentro do tempo limite especificado. Ela retorna um contêiner salvo se uma conexão de rede não estiver disponível e/ou o tempo limite for excedido.

Não é recomendado usar OpenType.PREFER_FRESH em locais em que um tempo de solicitação mais longo pode afetar visivelmente a experiência do usuário, como em sinalizações de IU ou strings de exibição. Também é possível usar Container.refresh() a qualquer momento para forçar uma solicitação de contêiner de rede.

Esses dois métodos de conveniência não causam bloqueio. ContainerOpener.openContainer(..., Long timeoutInMillis) retorna um objeto ContainerOpener.ContainerFuture, cujo método get retorna uma Container assim que é carregado (mas isso será bloqueado até lá). O método ContainerOpener.openContainer(..., Notifier notifier) recebe um único callback, chamado quando o contêiner está disponível, que pode ser usado para evitar o bloqueio da linha de execução principal. Ambos os métodos têm um tempo limite padrão de 2000 milissegundos.

Avaliação de macros no momento da execução usando regras

Os contêineres podem avaliar os valores no ambiente de execução usando regras. As regras podem ser baseadas em critérios como idioma do dispositivo, plataforma ou qualquer outro valor macro. Por exemplo, as regras podem ser usadas para selecionar uma string de exibição localizada com base no idioma do dispositivo durante a execução. Isso pode ser configurado usando a seguinte regra:

Figura 1:como adicionar uma regra para ativar uma macro de coleta de valores somente para dispositivos configurados para usar o idioma espanhol.

Em seguida, é possível criar macros de coleta de valores para cada idioma e adicionar essa regra a cada macro, inserindo o código do idioma apropriado. Quando esse contêiner for publicado, o aplicativo poderá mostrar strings de exibição localizadas, dependendo do idioma do dispositivo do usuário durante a execução.

Se o contêiner padrão precisar de regras, será necessário usar um arquivo de contêiner binário como o contêiner padrão.

Saiba mais sobre como configurar regras (Central de Ajuda).

Arquivos de contêiner padrão binários

Os contêineres padrão que precisam de regras precisam usar um arquivo de contêiner binário em vez de um arquivo JSON como contêiner padrão. Os contêineres binários oferecem suporte para determinar valores de macro no ambiente de execução com as regras do Gerenciador de tags do Google, ao contrário dos arquivos JSON.

É possível fazer o download dos arquivos de contêiner binários na interface da Web do Gerenciador de tags do Google e adicioná-los à pasta /assets/tagmanager/ do projeto e seguir este padrão: /assets/tagmanager/GTM-XXXX, em que o nome do arquivo representa o ID do contêiner.

Quando há um arquivo JSON e um arquivo de contêiner binário, o SDK usa o arquivo de contêiner binário como o contêiner padrão.

Como usar macros de chamada de função

As macros de chamada de função são aquelas definidas como o valor de retorno de uma função especificada no aplicativo. As macros de chamada de função podem ser usadas para incorporar valores de tempo de execução às regras do Gerenciador de tags do Google. Por exemplo, determinar qual preço será exibido para um usuário com base no idioma e na moeda configurados de um dispositivo.

Para configurar uma macro de chamada de função:

1. Defina a macro de chamada de função na interface da Web do Gerenciador de tags do Google. Os argumentos podem ser configurados como pares de chave-valor.
2. Registre um FunctionCallMacroHandler no seu aplicativo usando Container.registerFunctionCallMacroHandler() e o nome da função que você configurou na interface da Web do Gerenciador de tags do Google, substituindo o 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;
     }
   });
   

Como usar tags de chamada de função

As tags de chamada de função permitem que as funções pré-registradas sejam executadas sempre que um evento for enviado à camada de dados e as regras da tag forem avaliadas como true.

Para configurar uma tag de chamada de função:

1. Defina a tag de chamada de função na interface da Web do Gerenciador de tags do Google. Os argumentos podem ser configurados como pares de chave-valor.
2. Registre um gerenciador de tags de chamada de função no seu aplicativo usando 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.
       }
     }
   });
   

Como configurar um período de atualização personalizado

O SDK do Gerenciador de tags do Google tentará recuperar um novo contêiner se a idade atual dele exceder 12 horas. Para definir um período de atualização de contêiner personalizado, use Timer, como no exemplo a seguir:

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

Como depurar com o logger

Por padrão, o SDK do Gerenciador de tags do Google imprime erros e avisos nos registros. Ativar um registro mais detalhado pode ser útil para a depuração. Isso é possível implementando seu próprio Logger com TagManager.setLogger, como neste exemplo:

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.

});

Ou defina o LogLevel do logger existente usando TagManager.getLogger().setLogLevel(LogLevel), como neste exemplo:

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