Introduzione
Google Tag Manager consente agli sviluppatori di modificare i valori di configurazione nella loro applicazione mobile utilizzando l'interfaccia di Google Tag Manager senza dover ricreare e inviare nuovamente i file binari dell'applicazione ai marketplace di app.
Ciò è utile per gestire i valori o i flag di configurazione 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
- Varie impostazioni di gioco
I valori di configurazione possono anche essere valutati in fase di runtime utilizzando 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 tracker o pixel attivare.
Prima di iniziare
Completa i seguenti passaggi prima di iniziare questa guida introduttiva:
- Installa l'SDK Android
- Scarica l'SDK Google Play Services
- Crea un account Google Tag Manager
- Configura un contenitore Google Tag Manager
Una volta completati questi passaggi, il resto di questa guida ti spiegherà come configurare e utilizzare Google Tag Manager all'interno della tua app per Android.
Per iniziare
Dopo aver seguito questa guida introduttiva, saprai come:
- Aggiungi Google Tag Manager al progetto
- Inizializza Tag Manager nella tua applicazione
- Recupera i valori di configurazione da un contenitore di Tag Manager
- Invia valori ed eventi al
dataLayer - Visualizza l'anteprima, esegui il debug e pubblica il contenitore
Questa guida utilizza snippet di codice dell'applicazione di esempio Cute Animals inclusa nell'SDK Google Play Services.
Il codice sorgente completo di questo progetto è disponibile in: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.
1. Aggiungi Google Tag Manager al tuo progetto
Per aggiungere Google Tag Manager al tuo progetto:
- Configura l'SDK Google Play Services.
- Se utilizzi un IDE diverso da Android Studio, aggiungi le seguenti autorizzazioni al file
AndroidManifest.xml:<!-- For TagManager SDK --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
- Per consentire a
InstallReferrerReceiverdi chiamare il ricevitore di Google Analytics per impostare i dati della campagna, aggiungi quanto segue al fileAndroidManifest.xml:<!-- Used for install referrer tracking--> <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" /> <receiver android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver>
2. Aggiunta di un file del contenitore predefinito al progetto
Google Tag Manager utilizza un contenitore predefinito alla prima esecuzione dell'applicazione. Il contenitore predefinito non verrà più utilizzato non appena l'app sarà in grado di recuperare un nuovo contenitore sulla rete.
Per scaricare e aggiungere un file binario del contenitore predefinito alla tua applicazione:
- Accedi all'interfaccia web di Google Tag Manager.
- Seleziona la versione del contenitore che vuoi scaricare.
- Fai clic sul pulsante Scarica per recuperare il file binario del container.
- Aggiungi il file binario del container scaricato al progetto come risorsa non elaborata.
- Se la sottocartella
rawin<project-root>/res/non esiste, creala. - Se necessario, rinomina il file binario del container. È composto solo da lettere minuscole, numeri e trattini bassi.
- Copia il file binario del container nella cartella
<project-root>/res/raw.
- Se la sottocartella
Sebbene sia consigliabile utilizzare il file binario, se il contenitore non contiene regole o tag, puoi scegliere di utilizzare un semplice file JSON.
3. Inizializzazione di Google Tag Manager
Per inizializzare Google Tag Manager nella tua applicazione:
- Ottieni il singleton
TagManager:TagManager tagManager = TagManager.getInstance(this);
- Utilizza il singleton
TagManagerper effettuare una richiesta di caricamento di un contenitore, specificando un ID contenitore di Google Tag Manager e il file del contenitore predefinito. L'ID contenitore deve essere in lettere maiuscole e corrispondere esattamente all'ID contenitore nell'interfaccia web di Google Tag Manager. La chiamata aloadContainerPreferNonDefault()non è bloccante e restituisce unPendingResult:PendingResult<ContainerHolder> pending = tagManager.loadContainerPreferNonDefault(CONTAINER_ID, R.raw.defaultcontainer_binary);
- Utilizza un
ResultCallbackper restituireContainerHolderuna volta terminato il caricamento o scaduto il timeout:// The onResult method will be called as soon as one of the following happens: // 1. a saved container is loaded // 2. if there is no saved container, a network container is loaded // 3. the 2-second timeout occurs pending.setResultCallback(new ResultCallback<ContainerHolder>() { @Override public void onResult(ContainerHolder containerHolder) { ContainerHolderSingleton.setContainerHolder(containerHolder); Container container = containerHolder.getContainer(); if (!containerHolder.getStatus().isSuccess()) { Log.e("CuteAnimals", "failure loading container"); displayErrorToUser(R.string.load_error); return; } ContainerLoadedCallback.registerCallbacksForContainer(container); containerHolder.setContainerAvailableListener(new ContainerLoadedCallback()); startMainActivity(); } }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
Creazione di un singleton ContainerHolder
Devi mantenere una sola istanza di
ContainerHolderper ogni esecuzione della tua applicazione. Ecco perché l'esempio precedente utilizza una classe di utilitàContainerHolderSingletonper gestire l'accesso all'istanzaContainerHolder. Ecco come si presenta la classeContainerHolderSingleton:package com.google.android.tagmanager.examples.cuteanimals; import com.google.android.gms.tagmanager.ContainerHolder; /** * Singleton to hold the GTM Container (since it should be only created once * per run of the app). */ public class ContainerHolderSingleton { private static ContainerHolder containerHolder; /** * Utility class; don't instantiate. */ private ContainerHolderSingleton() { } public static ContainerHolder getContainerHolder() { return containerHolder; } public static void setContainerHolder(ContainerHolder c) { containerHolder = c; } }
4. Recupero dei valori di configurazione dal container
Una volta caricato il container, puoi recuperare i valori di configurazione utilizzando uno dei metodi Container.get<type>(). I valori di configurazione vengono definiti utilizzando le variabili di raccolta dei valori di Google Tag Manager. Ad esempio, il seguente metodo recupera l'ultimo colore che abbiamo deciso di utilizzare per un elemento UI e lo restituisce come numero intero:
/** * Returns an integer representing a color. */ private int getColor(String key) { return colorFromColorName(containerHolder.getContainer().getString(key)); }
Questo codice esegue due operazioni per recuperare il nome del colore dal container:
- Recupera
ContainerdaContainerHolderutilizzandoContainerHolder.getContainer(). - Recupera il valore del colore utilizzando
Container.getString(key), dove hai definito la chiave e il valore nell'interfaccia web di Google Tag Manager.
5. Push di eventi e valori nel dataLayer
Google Tag Manager fornisce anche un dataLayer, in cui puoi inserire informazioni sulla tua applicazione che possono essere lette in altre parti dell'applicazione o utilizzate per attivare i tag che hai configurato nell'interfaccia web di Google Tag Manager.
Push dei valori nel dataLayer
dataLayer fornisce un livello di persistenza che puoi utilizzare per memorizzare coppie chiave-valore che potresti voler utilizzare in altre parti della tua applicazione o come input per i tag di Google Tag Manager.
Per eseguire il push di un valore nel dataLayer, segui questo pattern:
- Recupera il singleton
DataLayer:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- Invia l'evento utilizzando
DataLayer.push():// Put the image_name into the data layer for future use. TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
Per ottenere un valore da dataLayer, utilizza
DataLayer.get(key).
Push degli eventi nel dataLayer
L'invio di eventi al dataLayer ti consente di separare il codice dell'applicazione dai tag che potresti voler attivare in risposta a questi eventi.
Ad esempio, anziché impostare come hardcoded le chiamate di monitoraggio delle visualizzazioni di schermata di Google Analytics nella tua applicazione,
puoi eseguire il push degli eventi di schermata nel dataLayer e definire i tag di monitoraggio tramite l'interfaccia web di Google Tag Manager. In questo modo, puoi modificare il tag o aggiungere altri tag che rispondono agli eventi della schermata senza aggiornare il codice dell'applicazione.
Per eseguire il push di un evento al dataLayer, segui questo pattern:
- Recupera il singleton
DataLayer:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- Invia l'evento utilizzando
DataLayer.pushEvent():dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));DataLayer.mapOf()è un metodo di utilità che puoi utilizzare per generare facilmente una mappa di coppie chiave-valore che aggiorneràdataLayercontemporaneamente all'invio dell'evento.
6. Anteprima, debug e pubblicazione
Prima di pubblicare una versione del contenitore, visualizzane l'anteprima per assicurarti che funzioni come previsto. Google Tag Manager ti consente di visualizzare l'anteprima delle versioni di anteprima del tuo contenitore generando link e codici QR nell'interfaccia web e utilizzandoli per aprire l'applicazione. Puoi anche attivare una modalità di logging dettagliato per eseguire il debug di eventuali comportamenti imprevisti.
Visualizzazione dell'anteprima in corso…
Per visualizzare l'anteprima di una versione del contenitore:
- Aggiungi questa anteprima
Activityal fileAndroidManifest:<!-- Add preview activity. --> <activity android:name="com.google.android.gms.tagmanager.PreviewActivity" android:label="@string/app_name" android:noHistory="true"> <!-- optional, removes the previewActivity from the activity stack. --> <intent-filter> <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" /> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE"/> </intent-filter> </activity>
Assicurati di modificare questa riga per includere il nome del pacchetto della tua applicazione:
<data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
- Genera un link di anteprima nell'interfaccia web di Google Tag Manager
- Accedi a Google Tag Manager
- Seleziona la versione del contenitore da visualizzare in anteprima.
- Fai clic sul pulsante Anteprima
- Inserisci il nome del pacchetto della tua applicazione e fai clic su Genera link di inizio anteprima.
- Utilizza il link o il codice QR generato per avviare l'applicazione
- Puoi uscire dalla modalità di anteprima seguendo un link generato dall'opzione Genera link di fine anteprima nell'interfaccia web.
Debug
Se devi risolvere i problemi relativi all'implementazione del container, attiva il logging dettagliato chiamando
TagManager.setVerboseLoggingEnabled(true):
// Modify the log level of the logger to print out not only // warning and error messages, but also verbose, debug, info messages. tagManager.setVerboseLoggingEnabled(true);
Pubblicazione
Dopo aver visualizzato l'anteprima del contenitore e aver verificato che funzioni come previsto, puoi pubblicarlo. I valori di configurazione, i tag e gli eventi del contenitore saranno attivi per gli utenti al successivo aggiornamento dei contenitori. Scopri di più sull'aggiornamento dei container.
Configurazione avanzata
Le sezioni seguenti descrivono le opzioni di configurazione avanzate che puoi utilizzare per personalizzare ulteriormente l'implementazione di Google Tag Manager.
Aggiornamento del contenitore
Per impostazione predefinita, il container diventa idoneo per l'aggiornamento ogni 12 ore. Per aggiornare manualmente il container, utilizza ContainerHolder.refresh():
ContainerHolderSingleton.getContainerHolder().refresh();
Si tratta di una chiamata asincrona che non restituirà immediatamente un risultato. Per ridurre il traffico di rete, refresh() può essere chiamato solo una volta ogni 15 minuti, altrimenti non verrà eseguita alcuna operazione.