Android v3 (legacy) - Panoramica

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

di Gemini Advanced.

Nota: Questa guida descrive la vecchia implementazione del tag Google Manager nelle app per Android. I nuovi utenti dovrebbero 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 app mobile.

Introduzione

Google Tag Manager consente agli sviluppatori di modificare la configurazione nelle proprie app mobile utilizzando Google Tag Manager senza dover ricreare e inviare nuovamente i file binari delle applicazioni all'app marketplace.

È utile per gestire i valori di configurazione o ai flag nella tua 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 nella tua applicazione.
• Impostazioni di gioco

I valori di configurazione possono essere valutati anche in fase di runtime tramite regole, l'attivazione di configurazioni dinamiche, ad esempio:

• 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 dei tag di monitoraggio e pixel nelle applicazioni. Gli sviluppatori possono eseguire il push di eventi importanti e decidi in seguito quali tag o pixel di monitoraggio attivare. Al momento TagManager supporta i seguenti tag:

• Google Analytics per app mobile
• Tag chiamata funzione personalizzata

Prima di iniziare

Prima di utilizzare questa guida introduttiva, avrai bisogno di quanto segue:

• Un account Google Tag Manager.
• Un nuovo contenitore e una nuova macro di raccolta dei valori di Tag Manager
• Un'applicazione mobile per Android in cui implementare Google Tag Manager
• I servizi Google Analytics SDK, che contiene la libreria di Tag Manager.

Se non hai mai utilizzato Google Tag Manager, ti consigliamo di scopri 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. Aggiungi l'SDK Google Tag Manager al progetto
2. Impostazione dei valori predefiniti del contenitore
3. Apri il container
4. Recuperare i valori di configurazione dal container
5. Eseguire il push degli eventi al livello dati
6. Anteprima e Pubblica il container

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

Prima di utilizzare l'SDK di Google Tag Manager, devi decomprimere il pacchetto SDK e aggiungi la libreria al percorso di build del progetto, quindi aggiungi le autorizzazioni al tuo file AndroidManifest.xml.

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

Dopodiché aggiorna il file AndroidManifest.xml in modo da utilizzare quanto segue: 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 e tornare a questo passaggio dopo averlo fatto.

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

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

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 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 del file per assicurarti di seguire la convenzione di denominazione corretta.

Sebbene sia consigliabile utilizzare il file binario, se il container non contiene regole o tag, puoi scegliere di usare una semplice JSON . Il file deve trovarsi in un nuovo /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 del contenitore predefiniti a /assets/tagmanager/GTM-1234.json.

3. Apertura di un container

Prima di recuperare i valori da un container, l'applicazione deve aprire nel container. L'apertura di un container lo caricherà dal disco (se disponibile) oppure lo richiederà alla 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) è utilizzato per richiedere un container salvato dallo spazio di archiviazione locale. Gestire l'assegnazione mContainer nel callback containerAvailable, ci assicuriamo che il thread principale non sia bloccato. Se il contenitore salvato risale a più di 12 ore fa, il valore pianifica una richiesta per recuperare in modo asincrono un nuovo sulla rete.

Questa implementazione di esempio rappresenta il modo più semplice per aprire e recuperare 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 contenitore, puoi recuperare i valori di configurazione utilizzando get<type>Value() metodo:

// 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 strato dati

Il strato dati è una mappa che consente le informazioni di runtime dell'app, ad esempio eventi o visualizzazioni di schermata di Tag Manager in un containerizzato.

Ad esempio, trasferendo le informazioni sulle visualizzazioni di schermata alla mappa Livelli dati, puoi configurare i tag nell'interfaccia web di Tag Manager per attivare i pixel di conversione e il monitoraggio delle chiamate in risposta alle visualizzazioni di schermata senza la necessità codificali nella tua app.

Gli eventi vengono inviati al strato dati utilizzando push() e 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
}

Ora nell'interfaccia web puoi creare tag, ad esempio quelli di Google Analytics. per l'attivazione per ogni visualizzazione di schermata mediante la creazione di questa regola: è uguale a "openScreen". Trasmettere il nome della schermata a uno di questi tag, crea una macro livello dati che faccia riferimento a "screenName" nel livello dati. Puoi anche creare un tag (ad esempio un pixel di conversione di Google Ads) affinché si attivi solo per visualizzazioni di schermata specifiche, creazione di una regola in cui è uguale a "openScreen" && è uguale a "ConfirmationScreen".

Nota: valori e chiavi degli eventi Datalayer devono essere utilizzate nel modo più coerente possibile, in modo che in questo esempio visualizzazioni di schermata utilizzano "openScreen" come valore evento e "screenName" come la chiave del nome della schermata. In questo modo, l'accesso al strato dati e la creazione il più semplice possibile in futuro.

6. Anteprima e Pubblicazione di un container

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

Per visualizzare l'anteprima di un contenitore, genera un URL di anteprima nella Interfaccia web di Tag Manager selezionando la versione del contenitore vuoi visualizzare l'anteprima, poi seleziona Preview. Attendi questo URL di anteprima perché ne avrai bisogno nei passaggi successivi.

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

Poi, aggiungi la seguente attività al File AndroidManifest.xml:

<!-- 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 del contenitore della bozza nell'app.

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

Configurazione avanzata

Google Tag Manager per dispositivi mobili offre diverse che consentono di selezionare i valori in base alle condizioni di runtime utilizzando aggiornare manualmente il container e visualizzare opzioni aggiuntive per l'apertura containerizzati. Le seguenti sezioni descrivono alcuni dei metodi avanzati più comuni configurazioni.

Opzioni avanzate per l'apertura di container

L'SDK di Google Tag Manager offre diversi metodi per aprire di container che possono darti maggiore controllo sul processo di caricamento:

TagManager.openContainer()

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

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

A meno che non sia accettabile per la tua applicazione di utilizzare i valori predefiniti, dovrai utilizzare questi callback per sapere quando una rete il container è stato caricato. Tieni presente che non potrai caricare un file di rete se è la prima volta che viene eseguita l'app e non vengono 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 container salvato localmente.
Container.Callback.NETWORK	La richiesta di aggiornamento sta caricando un container sulla rete.

RefreshFailure

Valore	Descrizione
Container.Callback.NO_SAVED_CONTAINER	Nessun contenitore 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 categorizzato.

Metodi per l'apertura di container non predefiniti e nuovi

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

Ognuno di questi metodi richiede un'enumerazione che richiede un valore non predefinito nuovo container.

OpenType.PREFER_NON_DEFAULT è consigliato per la maggior parte delle applicazioni tenta di restituire il primo container non predefinito disponibile all'interno di un determinato periodo di timeout, dal disco o dalla rete, anche se il container è maggiore più di 12 ore fa. Se restituisce un container salvato inattivo, una richiesta di rete asincrona per una nuova query. Quando utilizzi OpenType.PREFER_NON_DEFAULT, un valore predefinito verrà restituito se non sono disponibili altri container o se il periodo di timeout è superato.

OpenType.PREFER_FRESH tenta di restituire un container nuovo da il disco o la rete entro un determinato periodo di timeout. Restituisce un container salvato se una rete la connessione non è disponibile e/o il periodo di timeout è stato superato.

Non è consigliabile utilizzare OpenType.PREFER_FRESH in cui una richiesta più lunga può influire notevolmente sull'esperienza utente, ad esempio con flag UI o stringhe di visualizzazione. Puoi inoltre utilizzare Container.refresh() in qualsiasi momento per forzare una richiesta di container di rete.

Entrambi questi metodi non comportano il blocco. ContainerOpener.openContainer(..., Long timeoutInMillis) restituisce un Oggetto ContainerOpener.ContainerFuture, il cui metodo get restituisce un Container non appena viene caricato (che fino ad allora verrà bloccato). Il metodo ContainerOpener.openContainer(..., Notifier notifier) richiede un singolo callback, quando il container è disponibile, che può essere utilizzato per evitare il blocco del thread principale. Entrambi i metodi hanno un periodo di timeout predefinito 2000 millisecondi

Valutazione delle macro in fase di runtime mediante regole

I container possono valutare i valori in fase di runtime tramite le regole. Le regole possono essere basate in base a criteri come lingua del dispositivo, piattaforma o qualsiasi altro valore macro. Per esempio, è possibile utilizzare le regole per selezionare una stringa di visualizzazione localizzata in base al lingua del dispositivo in fase di runtime. Può essere configurato utilizzando regola seguente:

Figura 1: aggiunta di una regola per attivare una macro raccolta valori solo per i dispositivi configurate per l'uso della lingua spagnola.

Puoi quindi creare macro per la raccolta dei valori per ogni lingua e aggiungere a ogni macro, inserendo il codice lingua appropriato. Quando il container è stata pubblicata, la tua applicazione potrà mostrare una visualizzazione localizzata stringhe, 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 container binario come predefinito containerizzato.

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

File container binari predefiniti

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 esecuzione con le regole di Google Tag Manager, mentre JSON al contrario.

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

Nei casi in cui un file JSON e un file del container binario, l'SDK utilizzerà il container binario predefinito è il container.

Utilizzo delle macro chiamata funzione

Le macro chiamata di funzione sono macro impostate sul valore restituito a una funzione specificata nell'applicazione. Le macro chiamata di funzione possono essere usate per incorporare i valori di runtime con le regole di Google Tag Manager, ad esempio determinare in fase di runtime quale prezzo mostrare a un utente in base al lingua e valuta di un dispositivo.

Per configurare una macro di chiamata di funzione:

1. Definisci la macro di 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 dei suoi 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 l'esecuzione di funzioni preregistrate ogni volta viene inviato un evento al livello dati e alle regole dei tag restituisce 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 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.
       }
     }
   });
   

Impostazione di un periodo di aggiornamento personalizzato

L'SDK di Google Tag Manager tenterà di recuperare un nuovo contenitore se l'attuale età del contenitore supera le 12 ore. Per impostare un il periodo di aggiornamento del container personalizzato, Timer , come nella 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 un logging più dettagliato può essere utile per il debug e può essere 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 valore 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);