Android v3 (legacy) - Panoramica

Questa guida descrive le API appartenenti a una versione precedente dell'SDK. I nuovi utenti devono iniziare a utilizzare l'SDK più recente.

Nota: questa guida descrive la vecchia implementazione di Google Tag Manager nelle app per Android. I nuovi utenti devono utilizzare Tag Manager + Firebase per implementare Google Tag Manager nelle loro applicazioni iOS.

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 programmi binari delle applicazioni ai marketplace delle app.

Questo è utile per gestire i valori o i flag di configurazione nell'applicazione che potresti dover modificare in futuro, ad esempio:

• Varie impostazioni dell'interfaccia utente e stringhe di visualizzazione
• Dimensioni, posizioni o tipi di annunci pubblicati nella tua applicazione
• Impostazioni di gioco

I valori di configurazione possono essere valutati anche in fase di runtime utilizzando regole, abilitando configurazioni dinamiche quali:

• Utilizzare le dimensioni dello schermo per determinare le dimensioni del banner dell'annuncio
• Utilizzo della lingua e della posizione per configurare gli elementi dell'interfaccia utente

Google TagManager consente inoltre l'implementazione dinamica di tag e pixel di monitoraggio nelle applicazioni. Gli sviluppatori possono inviare eventi importanti a un livello dati e decidere in un secondo momento quali tag o pixel di monitoraggio devono essere attivati. Al momento TagManager supporta i seguenti tag:

• Google Analytics per app mobili
• Tag chiamata funzione personalizzata

Prima di iniziare

Prima di utilizzare questa guida introduttiva, devi disporre di:

• Un account Google Tag Manager.
• Una nuova macro Raccolta valori e contenitore di Tag Manager
• Un'app mobile per Android in cui implementare Google Tag Manager
• Google Analytics Services SDK, che contiene la libreria di Tag Manager.

Se non hai mai utilizzato Google Tag Manager, ti consigliamo di scoprire di più su contenitori, macro e regole (Centro assistenza) prima di continuare questa guida.

Per iniziare

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

1. Aggiungere l'SDK di Google Tag Manager al progetto
2. Impostare valori predefiniti per il contenitore
3. Apri il contenitore
4. Recupero dei valori di configurazione dal contenitore
5. Eseguire il push degli eventi al livello dati
6. Visualizzare l'anteprima del contenitore e pubblicarlo

1. Aggiunta dell'SDK di Google Tag Manager al progetto

Prima di utilizzare l'SDK di Google Tag Manager, devi decomprimere il pacchetto 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 progetto.

Successivamente, aggiorna il file AndroidManifest.xml in modo da 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 contenitore predefinito al progetto

Nota: se non hai ancora configurato il contenitore nell'interfaccia web di Google Tag Manager, torna a questo passaggio dopo averlo fatto.

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

Per scaricare e aggiungere un programma binario del container predefinito alla tua applicazione:

1. Accedi all'interfaccia web di Google Tag Manager.
2. Seleziona la Versione del contenitore da scaricare.
3. Fai clic sul pulsante Scarica per recuperare il programma 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 di versione dal nome del file per assicurarti di seguire la convenzione di denominazione corretta.

Sebbene sia consigliato utilizzare il file binario, se il container non contiene regole o tag, puoi scegliere di utilizzare un semplice 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. Quando apri un container, questo viene caricato dal disco (se disponibile) o richiesto dalla rete (se necessario).

Il modo più semplice per aprire un contenitore 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 sia bloccato. Se il container salvato risale a più di 12 ore fa, 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 container utilizzando la classe di convenienza ContainerOpener. Per opzioni di implementazione più avanzate, consulta Configurazione avanzata.

4. Recupero dei valori di configurazione dal container

Una volta aperto il container, 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 al 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. Invio dei valori al livello dati

Il Datalayer è una mappa che consente di rendere disponibili informazioni di runtime sulla tua app, come eventi di tocco o visualizzazioni di schermata, alle macro e ai tag di Tag Manager in un contenitore.

Ad esempio, inserendo le informazioni sulle visualizzazioni di schermata nella mappa Datalayer, puoi impostare i tag nell'interfaccia web di Tag Manager per attivare i pixel di conversione e monitorare le chiamate in risposta a queste visualizzazioni di schermata, senza doverli codificare nella tua app.

Gli eventi vengono inviati al livello dati 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 quelli di Google Analytics) da attivare per ogni visualizzazione di schermata creando questa regola: è uguale a "openScreen". Per passare il nome 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 determinate visualizzazioni di schermata, creando una regola in cui uguale a "openScreen" && è uguale a "ConfirmationScreen".

Nota: i valori e le chiavi degli eventi Datalayer devono essere utilizzati nel modo più coerente possibile in modo che in questo esempio tutte le visualizzazioni di schermata utilizzino "openScreen" come valore dell'evento e "screenName" come chiave del nome schermata. In questo modo, l'accesso al Datalayer e la creazione di altri tag in futuro sarà più semplice possibile.

6. Visualizzazione dell'anteprima e pubblicazione di un contenitore

I valori delle macro corrisponderanno sempre alla versione pubblicata corrente. Prima di pubblicare la versione più recente di un contenitore, puoi visualizzare l'anteprima del contenitore in versione bozza.

Per visualizzare l'anteprima di un contenitore, genera un URL di anteprima nell'interfaccia web di Google Tag Manager selezionando la versione del contenitore da visualizzare in anteprima e poi selezionando Preview. Aspetta a questo URL di anteprima che ti servirà nei passaggi successivi.

Figura 1: ottenimento di un URL di anteprima dall'interfaccia web di Tag Manager.

Dopodiché 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>
  

Nota: application_package_name deve corrispondere al nome dell'app utilizzata per generare l'URL di anteprima (Figura 1).

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

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

Configurazione avanzata

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

Opzioni avanzate per l'apertura dei container

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

TagManager.openContainer()

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

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() invia diversi callback del ciclo di vita in modo che il codice possa scoprire quando inizia la richiesta di caricamento, se e perché ha esito negativo o positivo e se il container è stato caricato dal disco o dalla rete.

A meno che l'applicazione non utilizzi i valori predefiniti, dovrai utilizzare questi callback per sapere quando è stato caricato un container di rete o salvato. 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

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

RefreshFailure

Valore	Descrizione
Container.Callback.NO_SAVED_CONTAINER	Non è disponibile alcun contenitore salvato.
Container.Callback.IO_ERROR	Un errore 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 aggiornati

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

Ciascuno di questi metodi richiede un'enumerazione che richiede un container non predefinito o aggiornato.

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 risale a più di 12 ore prima. Se restituisce un container salvato inattivo, effettua anche una richiesta di rete asincrona per uno nuovo. Quando utilizzi OpenType.PREFER_NON_DEFAULT, verrà restituito un container predefinito se non sono disponibili altri container o se il periodo di timeout è stato superato.

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

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 UI o stringhe di visualizzazione. Puoi anche utilizzare Container.refresh() in qualsiasi momento per forzare una richiesta del container di rete.

Entrambi questi metodi di praticità non bloccano la migrazione. ContainerOpener.openContainer(..., Long timeoutInMillis) restituisce un oggetto ContainerOpener.ContainerFuture, il cui metodo get restituisce un oggetto Container non appena è stato caricato (ma questo bloccherà fino ad allora). Il metodo ContainerOpener.openContainer(..., Notifier notifier) prevede un singolo callback, chiamato quando il container è disponibile, che può essere utilizzato per evitare il blocco del thread principale. Entrambi i metodi hanno un periodo di timeout predefinito di 2000 millisecondi.

Valutazione delle macro durante il runtime utilizzando le regole

I container possono valutare i valori in fase di runtime utilizzando le regole. Le regole possono basarsi su criteri come la lingua del dispositivo, la piattaforma o qualsiasi altro valore macro. Ad esempio, è possibile utilizzare le regole per selezionare una stringa di visualizzazione localizzata in base alla lingua del dispositivo in fase di runtime. Questa regola può essere configurata utilizzando la regola seguente:

Figura 1:aggiunta di una regola per attivare una macro di raccolta valori solo per i dispositivi configurati per utilizzare la lingua spagnola.

Puoi quindi creare macro di raccolta valori per ogni lingua e aggiungere questa regola a ogni macro, inserendo il codice lingua appropriato. Quando questo container sarà pubblicato, la tua applicazione sarà in grado di visualizzare 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 di container binario come contenitore predefinito.

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

File container predefiniti binari

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

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

Nei casi in cui siano presenti sia un file JSON sia un file di container binario, l'SDK utilizzerà il file container binario come container predefinito.

Utilizzo delle macro Chiamata funzione

Le macro di chiamata funzione sono macro impostate sul valore restituito di una funzione specificata nell'applicazione. Le macro delle chiamate 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 chiamata funzione:

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

I tag di chiamata funzione consentono l'esecuzione di funzioni preregistrate ogni volta che viene eseguito il push di un evento al livello dati e il valore delle regole tag viene valutato a true.

Per configurare un tag di chiamata funzione:

1. Definisci il tag di chiamata funzione nell'interfaccia web di Google Tag Manager. Gli argomenti possono facoltativamente essere configurati come coppie chiave-valore.
2. Registra un gestore di tag delle chiamate 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 di Google Tag Manager tenterà di recuperare un contenitore nuovo se l'età del contenitore attuale supera le 12 ore. Per impostare un periodo di aggiornamento dei 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 di Google Tag Manager stampa errori e avvisi nei log. L'attivazione di log più dettagliati 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 livello di log del logger esistente utilizzando TagManager.getLogger().setLogLevel(LogLevel), come nell'esempio seguente:

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