Android v4 - Primeiros passos

Introdução

O Gerenciador de tags do Google permite que os desenvolvedores alterem os valores de configuração nos seus aplicativos para dispositivos móveis usando a interface do Gerenciador de tags do Google sem ter que recriar e reenviar os binários do aplicativo aos mercados de apps.

Isso é útil para gerenciar quaisquer valores de configuração ou flags no seu aplicativo que você possa precisar mudar 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 tempo de execução usando regras, permitindo o configurações, 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 e pixels de acompanhamento em aplicativos conteinerizados. Os desenvolvedores podem enviar eventos importantes para uma camada de dados e decidir posteriormente qual tags ou pixels de rastreamento devem ser disparados.

Antes de começar

Conclua as etapas a seguir antes de iniciar este Guia de primeiros passos:

Depois que você concluir essas etapas, o restante deste guia vai orientar você sobre como configurar e usar o Gerenciador de tags do Google no seu app Android.

Primeiros passos

Depois de seguir este Guia explicativo, você entenderá como:

Este guia usa snippets de código do Cute Animals aplicativo de exemplo incluído no SDK do Google Play Services. A origem completa deste projeto está disponível em: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. 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 IDE diferente de Android Studio, adicione as seguintes permissões 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 ativar InstallReferrerReceiver para chamar o receptor do Google Analytics Para definir os dados da campanha, adicione o seguinte à 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 padrão será interrompido assim que o aplicativo puder 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 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 salvo ao projeto como um recurso bruto.
    1. Se a subpasta raw em <project-root>/res/ não existe, crie-o.
    2. Se necessário, renomeie o arquivo binário do contêiner. 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 seja recomendado usar o arquivo binário, se seu contêiner não tiver regras ou tags, use um arquivo JSON simples.

3. Inicializando o Gerenciador de tags do Google

Para inicializar o Gerenciador de tags do Google no seu aplicativo:

  1. Receba o Singleton TagManager: 
    TagManager tagManager = TagManager.getInstance(this);
  2. Use o Singleton TagManager para fazer uma solicitação para carregar um contêiner, especificando um ID do contêiner do Gerenciador de tags do Google, bem como seu contêiner padrão . O ID do contêiner precisa estar em letras maiúsculas e corresponder exatamente ao ID na tag do Google Manager. A chamada para loadContainerPreferNonDefault() não bloqueia e retorna uma PendingResult: 
    PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
  3. Use um ResultCallback para retornar o ContainerHolder depois de 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 ContainerHolder

    Mantenha apenas uma instância de ContainerHolder por execução do seu para o aplicativo. É por isso que o exemplo acima usa uma classe de utilitário ContainerHolderSingleton para gerenciar o acesso à instância ContainerHolder. Aqui está o que isso A classe ContainerHolderSingleton tem esta aparência:

    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, você pode recuperar os valores de configuração usando qualquer um dos Container.get<type>(). Os valores de configuração são definidos usando 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 de interface do usuário 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), em que você tem definiu a chave e o valor na interface da Web do Gerenciador de tags do Google.

5. Como 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 lidos em outras partes do aplicativo ou usados para disparar tags que você configurou na interface da Web do Gerenciador de tags do Google.

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 podem ser usados em outras partes do aplicativo, ou como entradas para as tags do Gerenciador de tags do Google.

Para enviar um valor ao dataLayer, siga este padrão:

  1. Obtenha 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 extrair um valor de dataLayer, use DataLayer.get(key).

Como enviar eventos para o dataLayer

Enviar eventos para o dataLayer permite separar o código do aplicativo dos tags que você pode disparar em resposta a esses eventos.

Por exemplo, em vez de codificar chamadas de acompanhamento de exibições de tela do Google Analytics no seu aplicativo, É possível enviar eventos de tela para o dataLayer e definir suas tags de acompanhamento pelo Interface da Web do Gerenciador de tags do Google. Assim, você tem a flexibilidade de modificar a tag ou adicionar tags adicionais que respondem a eventos de tela, sem atualizar o código do aplicativo.

Para enviar um evento para o dataLayer, siga este padrão:

  1. Obtenha o Singleton DataLayer: 
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Envie o evento usando DataLayer.pushEvent(): 
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

    O DataLayer.mapOf() é um método utilitário que pode ser usado para gerar facilmente um mapa de pares de chave-valor que vão atualizar o dataLayer ao mesmo tempo em que o evento é enviado.

6. Visualização, depuração e publicação

Antes de publicar uma versão do seu contêiner, é preciso visualizá-la para ter certeza de que ela funciona como pretendido. 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 seu 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 a visualização Activity ao 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 essa linha para incluir o nome do pacote do seu aplicativo:

    <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
  2. Gerar 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 Gerar link de entrada na visualização.
  3. Use o link gerado ou o QR code para iniciar seu aplicativo
  4. Para sair do modo de visualização, siga um link gerado por 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);

Publicação

Depois de visualizar o contêiner e verificar se ele está funcionando conforme o esperado, você pode publique seu contêiner. Seu valores de configuração do contêiner, tags e eventos estarão ativos para os usuários na próxima vez contêineres são atualizados. Saiba mais sobre a atualização de contêineres.

Configuração avançada

As seções a seguir descrevem as opções de configuração avançada que você deseja usar para personalizar ainda mais seu implementação do Gerenciador de tags do Google.

Como atualizar o contêiner

Por padrão, seu contêiner se qualifica para ser atualizado a cada 12 horas. Atualizar manualmente contêiner, use ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Essa é uma chamada assíncrona que não será retornada imediatamente. Para reduzir o tráfego de rede, o refresh() pode só será chamado uma vez a cada 15 minutos. Caso contrário, será um ambiente autônomo.