Android v3 (legacy) - Panoramica

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

Nota:questa guida descrive la vecchia implementazione di Google Tag Manager nelle applicazioni Android. I nuovi utenti devono utilizzare Tag Manager + Firebase per implementare Google Tag Manager nelle 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 proprie applicazioni mobile utilizzando l'interfaccia di Google Tag Manager senza dover ricompilare e inviare di nuovo i file binari dell'applicazione ai marketplace di app.

Questa funzionalità è utile per gestire eventuali valori o flag di configurazione nell'applicazione che potresti dover modificare in futuro, tra cui:

• Varie impostazioni dell'interfaccia utente e stringhe di visualizzazione
• Dimensioni, località o tipi di annunci pubblicati nell'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 pubblicitario
• Utilizzo della lingua e della località per configurare gli elementi dell'interfaccia utente

Google Tag Manager consente anche l'implementazione dinamica di tag e pixel di monitoraggio nelle applicazioni. Gli sviluppatori possono eseguire il push di eventi importanti in un livello dati e decidere in un secondo momento quali tag o pixel di monitoraggio devono essere attivati. Tag Manager supporta i seguenti tag:

• Google Analytics per app mobile
• Tag Chiamata funzione personalizzata

Prima di iniziare

Prima di utilizzare questa guida introduttiva, ti serviranno:

• Un account Google Tag Manager
• Un nuovo contenitore di Tag Manager e una macro di raccolta dei valori
• Un'applicazione mobile per Android in cui implementare Google Tag Manager
• L'SDK Google Analytics Services, 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 a leggere questa guida.

Per iniziare

Questa sezione illustra agli sviluppatori un flusso di lavoro tipico 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 contenitore
5. Esegui il push degli eventi nel 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 compilazione del progetto e aggiungere le autorizzazioni al file AndroidManifest.xml.

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

Poi, aggiorna il file AndroidManifest.xml in modo che utilizzi le seguenti autorizzazioni:

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

2. Aggiungere 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. Il contenitore predefinito verrà utilizzato finché l'app non sarà in grado di recuperare un nuovo contenitore tramite la rete.

Per scaricare e aggiungere un file binario del contenitore predefinito all'applicazione:

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 contenitore.
4. Aggiungi il file binario a il seguente percorso: <project-root>/assets/tagmanager/

Il nome file predefinito deve essere l'ID contenitore (ad esempio GTM-1234). Dopo aver scaricato il file binario, assicurati di rimuovere il suffisso della versione dal nome file per rispettare 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 /assets/tagmanager cartella del progetto Android e deve rispettare la seguente convenzione di denominazione: <Container_ID>.json. Ad esempio, se l'ID contenitore è GTM-1234, devi aggiungere i valori del contenitore predefinito a /assets/tagmanager/GTM-1234.json.

3. Aprire un contenitore

Prima di recuperare i valori da un contenitore, l'applicazione deve aprirlo. L'apertura di un contenitore lo carica dal disco (se disponibile) o lo richiede 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 contenitore 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 contenitore salvato ha più di 12 ore, la chiamata pianificherà anche una richiesta per recuperare in modo asincrono un nuovo contenitore tramite la 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. Recuperare i valori di configurazione dal contenitore

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

// 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. Eseguire il push dei valori nel livello dati

Il livello dati è una mappa che consente di rendere disponibili le informazioni di runtime sull'app, come gli eventi touch o le visualizzazioni di schermate, per le macro e i tag di Tag Manager in un contenitore.

Ad esempio, eseguendo il push delle informazioni sulle visualizzazioni di schermate nella mappa del livello dati, puoi configurare 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 schermate senza doverli codificare in modo hard coded nell'app.

Gli eventi vengono inseriti nel livello dati utilizzando push() e il DataLayer.mapOf() metodo helper:

//
// 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 (ad esempio tag Google Analytics) da attivare per ogni visualizzazione di schermata creando questa regola: equals "openScreen". Per trasmettere 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 equals "openScreen" && equals "ConfirmationScreen".

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

6. Visualizzare l'anteprima e pubblicare un contenitore

I valori delle macro corrispondono 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 selezionando Preview. Salva questo URL di anteprima perché ti servirà nei passaggi successivi.

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

Poi, 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 un dispositivo fisico per visualizzare l'anteprima della bozza del contenitore nell'app.

Quando la bozza dei valori di configurazione è pronta per essere resa disponibile per la tua applicazione, pubblica il contenitore.

Configurazione avanzata

Google Tag Manager per dispositivi mobile offre una serie di opzioni di configurazione avanzate che 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 contenitori

L'SDK Google Tag Manager fornisce diversi metodi per aprire i contenitori che possono darti un maggiore controllo sulla procedura 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 in modo asincrono un contenitore dal disco o dalla rete se non esiste un contenitore salvato o se il contenitore salvato non è nuovo (ha 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 la procedura di caricamento, TagManager.openContainer() emette diversi callback del ciclo di vita in modo che il codice possa scoprire quando inizia la richiesta di caricamento, se e perché non riesce o riesce e se il contenitore è 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

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 contenitore tramite la rete.

RefreshFailure

Valore	Descrizione
Container.Callback.NO_SAVED_CONTAINER	Non è disponibile alcun contenitore salvato.
Container.Callback.IO_ERROR	Un errore di I/O ha impedito l'aggiornamento del contenitore.
Container.Callback.NO_NETWORK	Non è disponibile alcuna connessione di rete.
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 l'apertura di contenitori non predefiniti e nuovi

ContainerOpener esegue il wrapping di TagManager.openContainer() e fornisce due metodi di utilità per l'apertura dei contenitori: 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 contenitore non predefinito disponibile entro un determinato periodo di timeout, dal disco o dalla rete, anche se il contenitore ha più di 12 ore. Se restituisce un contenitore salvato non aggiornato, effettuerà anche una richiesta di rete asincrona per uno nuovo. Quando utilizzi OpenType.PREFER_NON_DEFAULT, viene restituito un contenitore predefinito se non è disponibile nessun altro contenitore o se il periodo di timeout è scaduto.

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

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

Entrambi questi metodi di utilità non sono bloccanti. ContainerOpener.openContainer(..., Long timeoutInMillis) restituisce un oggetto ContainerOpener.ContainerFuture, il cui metodoget restituisce un Container non appena è stato caricato (ma fino ad allora sarà bloccato). Il metodo ContainerOpener.openContainer(..., Notifier notifier) accetta un singolo callback, chiamato quando il contenitore è disponibile, che può essere utilizzato per impedire il blocco del thread principale. Entrambi i metodi hanno un periodo di timeout predefinito di 2000 millisecondi.

Valutare le 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 come 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. Questa operazione può essere configurata utilizzando la seguente regola:

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

Poi, puoi 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 visualizzare le stringhe di visualizzazione localizzate, a seconda della lingua del dispositivo dell'utente in fase di runtime.

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

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

File contenitore predefinito binario

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

I file contenitore binari possono essere scaricati dall'interfaccia web di Google Tag Manager e devono essere aggiunti alla cartella del progetto /assets/tagmanager/e seguire 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 contenitore binario, l'SDK utilizzerà il file contenitore binario come contenitore predefinito.

Utilizzare le macro Chiamata funzione

Le macro Chiamata funzione sono macro impostate sul valore restituito di una funzione specificata nell'applicazione. Le macro Chiamata funzione possono essere utilizzate per incorporare i valori di runtime con le regole di Google Tag Manager, ad esempio per determinare in fase di runtime il prezzo da 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. Facoltativamente, gli argomenti possono essere configurati come coppie chiave-valore.
2. Registra un FunctionCallMacroHandler nell'applicazione utilizzando Container.registerFunctionCallMacroHandler() e il nome della funzione 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;
     }
   });

Utilizzare i tag Chiamata funzione

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

Per configurare un tag Chiamata funzione:

1. Definisci il tag Chiamata funzione nell'interfaccia web di Google Tag Manager. Facoltativamente, gli argomenti possono essere configurati come coppie chiave-valore.
2. Registra un gestore di tag Chiamata funzione nell'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.
       }
     }
   });

Impostare 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 contenitore personalizzato, utilizza Timer , come nell'esempio seguente:

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

Eseguire il 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);