Introdução
Com o Gerenciador de tags do Google, os desenvolvedores podem alterar os valores de configuração no app para dispositivos móveis usando a interface dessa solução 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
- Várias 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 e pixels de acompanhamento em aplicativos. Os desenvolvedores podem enviar eventos importantes para uma camada de dados e decidir quais pixels ou tags de acompanhamento precisam ser disparados.
Antes de começar
Conclua as etapas a seguir antes de começar este guia de iniciação:
- Instalar o SDK para Android
- Fazer o download do SDK do Google Play Services
- Crie uma conta do Gerenciador de tags do Google.
- Configurar um contêiner do Gerenciador de tags do Google
Depois de concluir essas etapas, você verá no restante deste guia como configurar e usar o Gerenciador de tags do Google no seu app Android.
Vamos começar
Depois de acompanhar este Guia explicativo, você entenderá como:
- Adicionar o Gerenciador de tags do Google ao seu projeto
- Inicializar o Gerenciador de tags no seu aplicativo
- Acessar valores de configuração de um contêiner do Gerenciador de tags
- Enviar valores e eventos para o
dataLayer
- Visualizar, depurar e publicar seu contêiner
Este guia usa snippets de código do aplicativo de exemplo Cute Animals
incluído no
SDK do Google Play Services.
A fonte completa desse projeto está disponível em: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals
.
1. Como adicionar o Gerenciador de tags do Google ao seu projeto
Para adicionar o Gerenciador de tags do Google ao seu projeto:
- Configure o SDK do Google Play Services.
- Se você usa um ambiente de desenvolvimento integrado diferente do
Android Studio, adicione as permissões abaixo ao
arquivo
AndroidManifest.xml
:<!-- For TagManager SDK --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
- Para permitir que
InstallReferrerReceiver
chame o receptor do Google Analytics e defina os dados da campanha, adicione o seguinte ao arquivoAndroidManifest.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. Como adicionar um arquivo de contêiner padrão ao seu projeto
O Gerenciador de tags do Google usa um contêiner padrão na primeira execução do seu aplicativo. O contêiner padrão deixará de ser usado assim que o app puder recuperar um novo contêiner pela rede.
Para fazer o download e adicionar um binário de contêiner padrão ao aplicativo:
- Faça login na interface da Web do Gerenciador de tags do Google.
- Selecione a Versão do contêiner que você quer fazer o download.
- Clique no botão Download para recuperar o binário do contêiner.
- Adicione o arquivo binário de contêiner transferido por download ao seu projeto como um recurso bruto.
- Se a subpasta
raw
em<project-root>/res/
não existir, crie-a. - Renomeie o arquivo binário do contêiner, se necessário. Ele consiste apenas em letras minúsculas, dígitos e sublinhados.
- Copie o arquivo binário do contêiner para a pasta
<project-root>/res/raw
.
- Se a subpasta
Embora o uso do arquivo binário seja recomendado, se o contêiner não tiver regras ou tags, você poderá usar um arquivo JSON simples.
3. Inicializar o Gerenciador de tags do Google
Para inicializar o Gerenciador de tags do Google no seu aplicativo:
- Consiga o Singleton do
TagManager
:TagManager tagManager = TagManager.getInstance(this);
- Use o Singleton
TagManager
para fazer uma solicitação de carregamento de um contêiner, especificando um ID de contêiner do Gerenciador de tags do Google, bem como seu arquivo de contêiner padrão. O ID do contêiner precisa estar em letras maiúsculas e corresponder exatamente ao ID do contêiner na interface da Web do Gerenciador de tags do Google. A chamada paraloadContainerPreferNonDefault()
não faz bloqueios e retorna umPendingResult
:PendingResult<ContainerHolder> pending = tagManager.loadContainerPreferNonDefault(CONTAINER_ID, R.raw.defaultcontainer_binary);
- Use um
ResultCallback
para retornar oContainerHolder
quando ele terminar de carregar ou expirar:// 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);
Como criar um Singleton do ContainerHolder
Mantenha apenas uma instância de
ContainerHolder
por execução do aplicativo. É por isso que o exemplo acima usa uma classe de utilitárioContainerHolderSingleton
para gerenciar o acesso à instânciaContainerHolder
. Esta é a aparência da classeContainerHolderSingleton
: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. Como receber valores de configuração do contêiner
Depois que o contêiner é carregado, é possível recuperar os valores de configuração usando qualquer um dos métodos Container.get<type>()
. Os valores de configuração são definidos usando as variáveis de coleta de valores do Gerenciador de tags do Google. Por exemplo, o método a seguir
recupera a última cor que decidimos usar para um elemento da interface e a retorna como
um número inteiro:
/** * Returns an integer representing a color. */ private int getColor(String key) { return colorFromColorName(containerHolder.getContainer().getString(key)); }
Esse código faz duas coisas para recuperar o nome da cor do contêiner:
- Recebe o
Container
doContainerHolder
usandoContainerHolder.getContainer()
. - Recebe o valor da cor usando
Container.getString(key)
, onde você definiu a chave e o valor na interface da Web do Gerenciador de tags do Google.
5. Enviar eventos e valores para o dataLayer
O Gerenciador de tags do Google também fornece um dataLayer
, em que você pode enviar informações sobre seu aplicativo que podem ser lidas em outras partes dele ou usadas para disparar tags configuradas na interface da Web do Gerenciador.
Como enviar valores para o dataLayer
O dataLayer
fornece uma camada de persistência que pode ser usada para armazenar pares de chave-valor que você queira usar em outras partes do aplicativo ou como entradas para tags do Gerenciador de tags do Google.
Para enviar um valor ao dataLayer
, siga este padrão:
- Consiga o Singleton
DataLayer
:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- Envie o evento usando
DataLayer.push()
:// Put the image_name into the data layer for future use. TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
Para receber um valor do dataLayer
, use
DataLayer.get(key)
.
Enviar eventos para o dataLayer
Enviar eventos para o dataLayer
permite separar o código do aplicativo das tags que você pode disparar em resposta a esses eventos.
Por exemplo, em vez de codificar as chamadas de acompanhamento de exibição de tela do Google Analytics no seu aplicativo, você pode enviar eventos de tela ao dataLayer
e definir suas tags de acompanhamento na interface da Web do Gerenciador de tags do Google. Isso dá a você a flexibilidade de modificar essa tag ou adicionar outras que respondam aos eventos de tela, sem atualizar o código do aplicativo.
Para enviar um evento ao dataLayer
, siga este padrão:
- Consiga o Singleton
DataLayer
:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- Envie o evento usando
DataLayer.pushEvent()
:dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
DataLayer.mapOf()
é um método utilitário que pode ser usado para gerar com facilidade um mapa de pares de chave-valor que vai atualizar odataLayer
ao mesmo tempo que o evento é enviado.
6. Visualização, depuração e publicação
Antes de publicar uma versão do seu contêiner, confira se ele funciona conforme o esperado. Com o Gerenciador de tags do Google, você pode visualizar as versões do seu contêiner, gerando links e códigos QR na interface da Web e usando-os para abrir o aplicativo. Você também pode ativar um modo de registro detalhado para depurar qualquer comportamento inesperado.
Visualização
Para visualizar uma versão do seu contêiner, siga estas etapas:
- Adicionando esta
Activity
de visualização ao seu arquivoAndroidManifest
:<!-- 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>
Certifique-se de modificar esta linha para incluir o nome do pacote do seu aplicativo:
<data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
- Gere um link de visualização na interface da Web do Gerenciador de tags do Google.
- Faça login no Gerenciador de tags do Google
- Selecione a Versão do contêiner para visualizar.
- Clique no botão Visualizar
- Insira o nome do pacote do seu aplicativo e clique em Generate begin preview link.
- Use o link gerado ou o código QR para iniciar o aplicativo
- Para sair do modo de visualização, acesse um link gerado pela opção Gerar link de saída da visualização na interface da Web.
Depuração
Se você precisar resolver problemas na implementação do contêiner, ative o registro detalhado chamando
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);
Publicando
Publique seu contêiner depois de visualizá-lo e verificar se ele está funcionando conforme o esperado. Os valores de configuração, as tags e os eventos do contêiner vão estar ativos para os usuários na próxima vez que os contêineres forem atualizados. Saiba como atualizar contêineres.
Configuração avançada
As seções a seguir descrevem as opções de configuração avançada que você quer usar para personalizar ainda mais sua implementação do Gerenciador de tags do Google.
Como atualizar o contêiner
Por padrão, seu contêiner se qualifica para atualização a cada 12 horas. Para atualizar manualmente o contêiner, use
ContainerHolder.refresh()
:
ContainerHolderSingleton.getContainerHolder().refresh();
Trata-se de uma chamada assíncrona que não retornará imediatamente. Para reduzir o tráfego de rede, refresh()
só pode ser chamado uma vez a cada 15 minutos. Caso contrário, será um ambiente autônomo.