Android v3 (legacy) - Panoramica

Questa guida per gli sviluppatori descrive come implementare Google Tag Manager in un'applicazione mobile.

Introduzione

Google Tag Manager consente agli sviluppatori di modificare i valori di configurazione nelle loro applicazioni mobile utilizzando l'interfaccia di Google Tag Manager senza dover ricreare e inviare nuovamente i file binari delle applicazioni ai marketplace di app.

Ciò è utile per gestire i valori di configurazione o i flag nell'applicazione che potresti dover modificare in futuro, tra cui:

  • Varie impostazioni della UI e stringhe di visualizzazione
  • Dimensioni, posizioni o tipi di annunci pubblicati nella tua applicazione
  • Impostazioni di gioco

I valori di configurazione possono anche essere valutati in fase di runtime utilizzando le regole, consentendo configurazioni dinamiche come:

  • Utilizzo delle dimensioni dello schermo per determinare le dimensioni del banner dell'annuncio
  • Utilizzo della lingua e della località per configurare gli elementi UI

Google Tag Manager consente inoltre l'implementazione dinamica di tracker e pixel nelle applicazioni. Gli sviluppatori possono inserire eventi importanti in un livello dati e decidere in un secondo momento quali tag di monitoraggio o pixel attivare. Tag Manager supporta i seguenti tag:

  • Google Mobile App Analytics
  • Tag Chiamata di funzione personalizzata

Prima di iniziare

Prima di utilizzare questa guida introduttiva, devi disporre di quanto segue:

Se è la prima volta che utilizzi Google Tag Manager, ti consigliamo di scoprire di più su contenitori, macro e regole (Centro assistenza) prima di continuare con questa guida.

Per iniziare

Questa sezione guiderà gli sviluppatori attraverso un tipico workflow di Tag Manager:

  1. Aggiungi l'SDK Google Tag Manager al progetto
  2. Imposta i valori predefiniti del contenitore
  3. Apri il contenitore
  4. Recupera i valori di configurazione dal container
  5. Inviare eventi al livello dati
  6. Visualizza l'anteprima e pubblica il contenitore

1. Aggiungere l'SDK Google Tag Manager al progetto

Prima di utilizzare l'SDK Google Tag Manager, devi estrarre il pacchetto dell'SDK, aggiungere la libreria al percorso di build del progetto e aggiungere le autorizzazioni al file AndroidManifest.xml.

Innanzitutto, aggiungi la libreria di Google Tag Manager alla cartella /libs del tuo progetto.

Successivamente, aggiorna il file AndroidManifest.xml per utilizzare le seguenti autorizzazioni:

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

2. Aggiunta di un file del contenitore predefinito al progetto

Google Tag Manager utilizza un contenitore predefinito alla prima esecuzione dell'applicazione. Il contenitore predefinito verrà utilizzato finché l'app non sarà in grado di recuperare un nuovo contenitore dalla rete.

Per scaricare e aggiungere un file binario del contenitore predefinito alla tua applicazione, segui questi passaggi:

  1. Accedi all'interfaccia web di Google Tag Manager.
  2. Seleziona la versione del contenitore che vuoi scaricare.
  3. Fai clic sul pulsante Scarica per recuperare il file binario del container.
  4. Aggiungi il file binario al seguente percorso: <project-root>/assets/tagmanager/

Il nome file predefinito deve essere l'ID contenitore (ad esempio GTM-1234). Una volta scaricato il file binario, assicurati di rimuovere il suffisso della versione dal nome file per seguire la convenzione di denominazione corretta.

Sebbene sia consigliabile utilizzare il file binario, se il contenitore non contiene regole o tag, puoi scegliere di utilizzare un file JSON. Il file deve trovarsi in una nuova cartella /assets/tagmanager del tuo progetto Android e deve seguire questa convenzione di denominazione: <Container_ID>.json. Ad esempio, se l'ID contenitore è GTM-1234, devi aggiungere i valori predefiniti del contenitore a /assets/tagmanager/GTM-1234.json.

3. Apertura di un container

Prima di recuperare i valori da un container, l'applicazione deve aprire il container. L'apertura di un contenitore lo caricherà dal disco (se disponibile) o lo richiederà dalla rete (se necessario).

Il modo più semplice per aprire un container su Android è utilizzare ContainerOpener.openContainer(..., Notifier notifier), come nell'esempio seguente:

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

In questo esempio, ContainerOpener.openContainer(..., Notifier notifier) viene utilizzato per richiedere un container salvato dallo spazio di archiviazione locale. Gestendo l'assegnazione di mContainer nel callback containerAvailable, ci assicuriamo che il thread principale non venga bloccato. Se il container salvato ha più di 12 ore, la chiamata pianificherà anche una richiesta per recuperare in modo asincrono un nuovo container sulla rete.

Questa implementazione di esempio rappresenta il modo più semplice per aprire e recuperare i valori da un contenitore utilizzando la classe di utilità ContainerOpener. Per opzioni di implementazione più avanzate, consulta Configurazione avanzata.

4. Recupero dei valori di configurazione dal container

Una volta aperto il contenitore, i valori di configurazione possono essere recuperati utilizzando i metodi get<type>Value():

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

Le richieste effettuate con una chiave inesistente restituiranno un valore predefinito appropriato per il tipo richiesto:

// 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. Push dei valori nel dataLayer

DataLayer è una mappa che consente di rendere disponibili alle macro e ai tag di Tag Manager in un contenitore le informazioni di runtime sulla tua app, ad esempio gli eventi touch o le visualizzazioni di schermata.

Ad esempio, inserendo le informazioni sulle visualizzazioni di schermata nella mappa DataLayer, puoi impostare i tag nell'interfaccia web di Tag Manager in modo che attivino i pixel di conversione e le chiamate di monitoraggio in risposta a queste visualizzazioni di schermata senza doverle inserire come hardcoded nell'app.

Gli eventi vengono inviati al DataLayer utilizzando push() e il metodo helper 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
}

Nell'interfaccia web, ora puoi creare tag (come i tag di Google Analytics) da attivare per ogni visualizzazione di schermata creando questa regola: è uguale a "openScreen". Per passare il nome della schermata a uno di questi tag, crea una macro del livello dati che faccia riferimento alla chiave "screenName" nel livello dati. Puoi anche creare un tag (ad esempio un pixel di conversione di Google Ads) da attivare solo per visualizzazioni di schermate specifiche, creando una regola in cui è uguale a "openScreen" && è uguale a "ConfirmationScreen".

6. Visualizzazione in anteprima e pubblicazione di un contenitore

I valori delle macro corrisponderanno sempre alla versione pubblicata corrente. Prima di pubblicare l'ultima versione di un contenitore, puoi visualizzare l'anteprima della bozza del contenitore.

Per visualizzare l'anteprima di un contenitore, genera un URL di anteprima nell'interfaccia web di Google Tag Manager selezionando la versione del contenitore di cui vuoi visualizzare l'anteprima e poi Preview. Salva questo URL di anteprima perché ti servirà nei passaggi successivi.

Gli URL di anteprima sono disponibili nella finestra di anteprima dell'interfaccia web di Tag Manager
Figura 1: recupero di un URL di anteprima dall'interfaccia web di Tag Manager.

Successivamente, aggiungi la seguente attività al file AndroidManifest.xml dell'applicazione:

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

Apri il link su un emulatore o un dispositivo fisico per visualizzare l'anteprima del contenitore in bozza nella tua app.

Quando è tutto pronto per rendere disponibili i valori di configurazione della bozza per la tua applicazione, pubblica il contenitore.

Configurazione avanzata

Google Tag Manager per dispositivi mobili offre una serie di opzioni di configurazione avanzate che ti consentono di selezionare i valori in base alle condizioni di runtime utilizzando le regole, aggiornare manualmente il contenitore e ottenere opzioni aggiuntive per l'apertura dei contenitori. Le sezioni seguenti descrivono alcune delle configurazioni avanzate più comuni.

Opzioni avanzate per l'apertura dei container

L'SDK Google Tag Manager fornisce diversi metodi per aprire i contenitori che possono darti un maggiore controllo sul processo di caricamento:

TagManager.openContainer()

TagManager.openContainer() è l'API di livello più basso e più flessibile per l'apertura di un contenitore. Restituisce immediatamente un contenitore predefinito e carica anche in modo asincrono un contenitore dal disco o dalla rete se non esiste un contenitore salvato o se il contenitore salvato non è aggiornato (più di 12 ore).

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 il processo di caricamento, TagManager.openContainer() genera diversi callback del ciclo di vita in modo che il tuo codice possa scoprire quando inizia la richiesta di caricamento, se e perché non va a buon fine o ha esito positivo e se il container è stato caricato dal disco o dalla rete.

A meno che non sia accettabile che l'applicazione utilizzi i valori predefiniti, dovrai utilizzare questi callback per sapere quando è stato caricato un contenitore salvato o di rete. Tieni presente che non potrai caricare un contenitore salvato o di rete se è la prima volta che l'app viene eseguita e non è presente una connessione di rete.

TagManager.openContainer() passa i seguenti valori enum come argomenti a questi callback:

RefreshType

ValoreDescrizione
Container.Callback.SAVED La richiesta di aggiornamento sta caricando un contenitore salvato localmente.
Container.Callback.NETWORK La richiesta di aggiornamento sta caricando un contenitore sulla rete.

RefreshFailure

ValoreDescrizione
Container.Callback.NO_SAVED_CONTAINER Nessun container salvato disponibile.
Container.Callback.IO_ERROR Un errore di I/O ha impedito l'aggiornamento del container.
Container.Callback.NO_NETWORK Nessuna connessione di rete disponibile.
Container.Callback.NETWORK_ERROR Si è verificato un errore di rete.
Container.Callback.SERVER_ERROR Si è verificato un errore sul server.
Container.Callback.UNKNOWN_ERROR Si è verificato un errore che non può essere classificato.

Metodi per aprire container non predefiniti e nuovi

ContainerOpener aggrega TagManager.openContainer() e fornisce due metodi pratici per aprire i container: ContainerOpener.openContainer(..., Notifier notifier) e ContainerOpener.openContainer(..., Long timeoutInMillis).

Ognuno di questi metodi accetta un'enumerazione che richiede un contenitore non predefinito o nuovo.

OpenType.PREFER_NON_DEFAULT è consigliato per la maggior parte delle applicazioni e tenta di restituire il primo container non predefinito disponibile entro un determinato periodo di timeout, dal disco o dalla rete, anche se il container ha più di 12 ore. Se restituisce un container salvato non aggiornato, effettuerà anche una richiesta di rete asincrona per un container aggiornato. Quando utilizzi OpenType.PREFER_NON_DEFAULT, verrà restituito un contenitore predefinito se non sono disponibili altri contenitori o se il periodo di timeout viene superato.

OpenType.PREFER_FRESH tenta di restituire un container aggiornato dal disco o dalla rete entro il periodo di timeout specificato. Restituisce un container salvato se non è disponibile una connessione di rete e/o se il periodo di timeout viene superato.

Non è consigliabile utilizzare OpenType.PREFER_FRESH in luoghi in cui un tempo di richiesta più lungo potrebbe influire notevolmente sull'esperienza utente, ad esempio con flag della UI o stringhe di visualizzazione. Puoi anche utilizzare Container.refresh() in qualsiasi momento per forzare una richiesta di container di rete.

Entrambi questi metodi di convenienza non sono bloccanti. ContainerOpener.openContainer(..., Long timeoutInMillis) restituisce un oggetto ContainerOpener.ContainerFuture, il cui metodo get restituisce un Container non appena viene caricato (ma si blocca fino ad allora). Il metodo ContainerOpener.openContainer(..., Notifier notifier) accetta un singolo callback, chiamato quando il container è disponibile, che può essere utilizzato per evitare di bloccare il thread principale. Entrambi i metodi hanno un periodo di timeout predefinito di 2000 millisecondi.

Valutazione delle macro in fase di runtime utilizzando le regole

I contenitori possono valutare i valori in fase di runtime utilizzando le regole. Le regole possono essere basate su criteri quali la lingua del dispositivo, la piattaforma o qualsiasi altro valore macro. Ad esempio, le regole possono essere utilizzate per selezionare una stringa di visualizzazione localizzata in base alla lingua del dispositivo in fase di runtime. Puoi configurare questa opzione utilizzando la seguente regola:

Viene utilizzata una regola per selezionare le stringhe di visualizzazione in base alla lingua del dispositivo in fase di runtime: la lingua è es. Questa regola utilizza la macro della lingua predefinita e un codice lingua ISO 639-1 di due caratteri.
Figura 1:aggiunta di una regola per attivare una macro di raccolta di valori solo per i dispositivi configurati per l'utilizzo della lingua spagnola.

Puoi quindi creare macro di raccolta dei valori per ogni lingua e aggiungere questa regola a ogni macro, inserendo il codice lingua appropriato. Quando questo contenitore viene pubblicato, l'applicazione sarà in grado di mostrare stringhe di visualizzazione localizzate, a seconda della lingua del dispositivo dell'utente in fase di runtime.

Tieni presente che se il container predefinito richiede regole, devi utilizzare un file binario del container come container predefinito.

Scopri di più sulla configurazione delle regole (Centro assistenza).

File binari del container predefinito

I container predefiniti che richiedono regole devono utilizzare un file container binario anziché un file JSON come container predefinito. I contenitori binari offrono supporto per la determinazione dei valori delle macro in fase di runtime con le regole di Google Tag Manager, mentre i file JSON no.

I file binari del contenitore possono essere scaricati dall'interfaccia web di Google Tag Manager e devono essere aggiunti alla cartella /assets/tagmanager/ del progetto seguendo questo pattern: /assets/tagmanager/GTM-XXXX, dove il nome file rappresenta l'ID contenitore.

Nei casi in cui sono presenti sia un file JSON sia un file binario del contenitore, l'SDK utilizzerà il file binario del contenitore come contenitore predefinito.

Utilizzo delle macro di chiamata di funzione

Le macro di chiamata di funzione sono macro impostate sul valore restituito di una funzione specificata nella tua applicazione. Le macro di chiamata di funzione possono essere utilizzate per incorporare i valori di runtime nelle regole di Google Tag Manager, ad esempio per determinare in fase di runtime quale prezzo mostrare a un utente in base alla lingua e alla valuta configurate di un dispositivo.

Per configurare una macro di chiamata di funzione:

  1. Definisci la macro della chiamata di funzione nell'interfaccia web di Google Tag Manager. Gli argomenti possono essere configurati facoltativamente come coppie chiave-valore.
  2. Registra un FunctionCallMacroHandler nella tua applicazione utilizzando Container.registerFunctionCallMacroHandler() e il nome della funzione che hai configurato nell'interfaccia web di Google Tag Manager, eseguendo l'override del relativo metodo 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;
      }
    });

Utilizzo dei tag di chiamata di funzione

I tag di chiamata di funzione consentono di eseguire funzioni preregistrate ogni volta che un evento viene inserito nel livello dati e le regole dei tag restituiscono true.

Per configurare un tag di chiamata di funzione:

  1. Definisci il tag di chiamata di funzione nell'interfaccia web di Google Tag Manager. Gli argomenti possono essere configurati facoltativamente come coppie chiave-valore.
  2. Registra un gestore di tag di chiamata di funzione nella tua applicazione utilizzando 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.
        }
      }
    });

Impostazione di un periodo di aggiornamento personalizzato

L'SDK Google Tag Manager tenterà di recuperare un nuovo contenitore se l'età del contenitore corrente supera le 12 ore. Per impostare un periodo di aggiornamento del container personalizzato, utilizza Timer, come nell'esempio seguente:

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

Debug con Logger

Per impostazione predefinita, l'SDK Google Tag Manager stampa errori e avvisi nei log. L'attivazione di un logging più dettagliato può essere utile per il debug ed è possibile implementando il tuo Logger con TagManager.setLogger, come in questo esempio:

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.

});

In alternativa, puoi impostare il LogLevel del Logger esistente utilizzando TagManager.getLogger().setLogLevel(LogLevel) , come in questo esempio:

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