Android v4 - Primeiros passos

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:

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:

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:

  1. Configure o SDK do Google Play Services.
  2. 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" />
  3. Para permitir que InstallReferrerReceiver chame o receptor do Google Analytics e defina os dados da campanha, adicione o seguinte ao arquivo 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. 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:

  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 de contêiner transferido por download ao seu projeto como um recurso bruto.
    1. Se a subpasta raw em <project-root>/res/ não existir, crie-a.
    2. Renomeie o arquivo binário do contêiner, se necessário. Ele consiste apenas em letras minúsculas, dígitos e sublinhados.
    3. Copie o arquivo binário do contêiner para a pasta <project-root>/res/raw.

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:

  1. Consiga o Singleton do TagManager: 
    TagManager tagManager = TagManager.getInstance(this);
  2. 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 para loadContainerPreferNonDefault() não faz bloqueios e retorna um PendingResult: 
    PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
  3. Use um ResultCallback para retornar o ContainerHolder 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ário ContainerHolderSingleton para gerenciar o acesso à instância ContainerHolder. Esta é a aparência da classe 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. 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:

  1. Recebe o Container do ContainerHolder usando ContainerHolder.getContainer().
  2. 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:

  1. Consiga o Singleton DataLayer: 
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 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:

  1. Consiga o Singleton DataLayer: 
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 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 o dataLayer 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:

  1. Adicionando esta Activity de visualização ao seu arquivo 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>

    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" />
  2. Gere um link de visualização na interface da Web do Gerenciador de tags do Google.
    1. Faça login no Gerenciador de tags do Google
    2. Selecione a Versão do contêiner para visualizar.
    3. Clique no botão Visualizar
    4. Insira o nome do pacote do seu aplicativo e clique em Generate begin preview link.
  3. Use o link gerado ou o código QR para iniciar o aplicativo
  4. 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.