Android v3 (legado) - Visão geral

Este guia descreve APIs que pertencem a uma versão legada do SDK. Novos usuários devem Comece a usar o SDK mais recente.

.

Observação: Neste guia, descrevemos a implementação antiga da tag do Google. Manager em aplicativos Android. Novos usuários devem usar o Gerenciador de tags + Firebase para implementar o Gerenciador de tags do Google nos aplicativos iOS.

Este guia do desenvolvedor descreve como implementar o Gerenciador de tags do Google em uma aplicativo para dispositivos móveis.

Introdução

Com o Gerenciador de tags do Google, os desenvolvedores podem mudar a configuração em seus aplicativos para dispositivos móveis usando o Gerenciador de tags do Google do aplicativo sem precisar recriar e reenviar os binários ao app em marketplaces.

Isso é útil para gerenciar valores de configuração ou sinalizações em seu 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 tempo de execução usando regras, ativando configurações dinâmicas, como:

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

O Gerenciador de tags do Google também permite a implementação dinâmica de tags de acompanhamento e pixels nos aplicativos. Os desenvolvedores podem enviar eventos importantes para um e decide depois quais tags ou pixels de rastreamento devem ser disparados. Atualmente, o TagManager é compatível com as seguintes tags:

• Google Mobile App Analytics
• Tag Custom Function Call

Antes de começar

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

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

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

Primeiros passos

Esta seção orienta os desenvolvedores em um 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 o DataLayer
6. Visualização 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, você precisa descompactar o pacote do SDK adicionar a biblioteca ao caminho de build do projeto e adicionar permissões ao arquivo AndroidManifest.xml.

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

Em seguida, atualize o arquivo AndroidManifest.xml para usar o seguinte: :

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

Observação: se você ainda não configurou seu contêiner na interface da Web do Gerenciador de tags do Google; volte a esta etapa quando tiver feito isso.

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

Para fazer o download e adicionar um binário de contêiner padrão ao seu 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 a o seguinte caminho: <project-root>/assets/tagmanager/

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

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

3. Como abrir um contêiner

Antes de recuperar valores de um contêiner, seu aplicativo precisa abrir o contêiner. A abertura de um contêiner o carregará do disco (se disponível). vai solicitá-lo à rede (se necessário).

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

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 lidar com a atribuição de mContainer no callback containerAvailable, garantimos que o a linha de execução principal não está bloqueada. Se o contêiner salvo tiver mais de 12 horas, a chamada também vai programar uma solicitação para recuperar assincrônicamente um contêiner novo pela rede.

Este 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 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");

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. Como enviar valores para a DataLayer

A DataLayer é um mapa que permite informações sobre o aplicativo, como toque, em tempo de execução ou exibições de tela, sejam disponibilizados para tags e macros do Gerenciador de tags em um contêiner do Docker.

Por exemplo, ao inserir informações sobre exibições de tela no mapa DataLayer, é possível 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á-los no seu app.

Os eventos são enviados ao 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 as do Google Analytics) que devem ser disparadas em cada exibição de tela criando essa 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 ao nome de tela na camada de dados. Também é possível criar uma tag (como um pixel de conversão do Google Ads) para ser acionado somente em exibições de tela específicas, criar uma regra em que seja igual a "openScreen" && é igual a "ConfirmationScreen".

Observação: valores e chaves de eventos do DataLayer deve ser usado da forma mais consistente possível, para que, neste exemplo, todos as exibições de tela usam "openScreen" como o valor do evento, e "screenName" quando a tecla de nome de tela. Isso faz com que o acesso à DataLayer e a criação de tags adicionais no futuro da maneira mais fácil possível.

6. Prévia e Publicar um contêiner

Os valores das macros sempre correspondem à versão publicada atual. Antes de publicar a versão mais recente de um contêiner, é possível visualizar seu contêiner de rascunho.

Para visualizar um contêiner, gere um URL de visualização no a interface da Web do Gerenciador de tags selecionando a versão do contêiner que você quer visualizar e, em seguida, selecione Preview. Continue esse URL de visualização, porque você vai precisar dele em etapas posteriores.

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

Em seguida, adicione a seguinte atividade ao Arquivo 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>
  

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

Quando estiver tudo pronto para disponibilizar os valores de rascunho para sua aplicativo, publicar o contêiner.

Configuração avançada

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

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 podem dar a você mais controle sobre o processo de carregamento:

TagManager.openContainer()

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

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

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

TagManager.openContainer() transmite o seguinte enum valores 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 categorizado.

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

ContainerOpener encapsula 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 recebe uma enumeração solicitando um valor não padrão ou novo contêiner.

OpenType.PREFER_NON_DEFAULT é recomendado para a maioria dos aplicativos e tenta retornar o primeiro contêiner não padrão disponível em um determinado tempo limite, seja do disco ou da rede, mesmo que o contêiner seja maior há mais de 12 horas. Se ele retornar um contêiner salvo desatualizado, também fará uma solicitação de rede assíncrona para uma nova. Ao usar OpenType.PREFER_NON_DEFAULT, um valor padrão contêiner 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 de no disco ou na rede dentro do período de tempo limite determinado. Ela retorna um contêiner salvo se uma não estiver disponível e/ou o tempo limite for excedido.

Não é recomendável usar OpenType.PREFER_FRESH em locais onde um tempo de solicitação maior pode afetar visivelmente a experiência do usuário, como com flags de interface ou strings de exibição. Você também pode usar Container.refresh() a qualquer momento para forçar uma solicitação de contêiner de rede.

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

Avaliar macros no ambiente de execução usando regras

Os contêineres podem avaliar valores no ambiente de execução usando regras. As regras podem se basear com base 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 na língua do dispositivo no momento da execução. Para configurar isso, use o seguinte regra:

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

Você pode criar macros de coleta de valores para cada idioma e adicionar esse a cada macro, inserindo o código de idioma apropriado. Quando esse contêiner for publicado, seu aplicativo poderá exibir telas localizadas strings, dependendo da linguagem do dispositivo do usuário no tempo de execução.

Se o contêiner padrão precisar de regras, você precisará usar uma arquivo de contêiner binário como padrão contêiner do Docker.

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 uma string JSON arquivo como contêiner padrão. Os contêineres binários ajudam a determinar no ambiente de execução com as regras do Gerenciador de tags do Google, enquanto JSON os arquivos não têm.

É possível fazer o download dos arquivos de contêiner binário no Gerenciador de tags do Google na Web interface de usuário precisa ser adicionada ao arquivo /assets/tagmanager/ e siga este padrão: /assets/tagmanager/GTM-XXXX, em que o nome do arquivo representa seu ID do contêiner.

Nos casos em que um arquivo JSON e um arquivo contêiner binário estiverem presentes, o SDK usará o contêiner binário como o contêiner padrão.

Como usar macros de chamada de função

Macros de chamada de função são macros definidas para o valor de retorno do uma função específica no seu aplicativo. As macros de chamada de função podem ser usadas para incorporar valores de tempo de execução às suas regras do Gerenciador de tags do Google, como determinar no tempo de execução qual preço mostrar para um usuário com base no idioma e a moeda 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. Como opção, os argumentos podem ser configurados como pares de chave-valor.
2. Registre um FunctionCallMacroHandler no aplicativo usando Container.registerFunctionCallMacroHandler() e o nome da função que você configurou na interface da Web do Gerenciador de tags do Google, substituindo 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 funções pré-registradas sejam executadas sempre que Um evento é enviado para a camada de dados, e as regras da tag avaliar 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. Como opção, os argumentos podem ser configurados como pares de chave-valor.
2. Registre um manipulador de tags de chamada de função em 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 definir um período de atualização personalizado

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

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

Depurar com o logger

Por padrão, o SDK do Gerenciador de tags do Google imprime erros e avisos nos registros. A ativação de um registro mais detalhado pode ser útil para depuração e é possível implementar 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 você pode definir 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);