Android v4 (Legacy) - Getting Started

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:

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:

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:

  1. Configura l'SDK Google Play Services.
  2. 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" />
  3. Per consentire a InstallReferrerReceiver di chiamare il ricevitore di Google Analytics per impostare i dati della campagna, aggiungi quanto segue al file AndroidManifest.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:

  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 del container scaricato al progetto come risorsa non elaborata.
    1. Se la sottocartella raw in <project-root>/res/ non esiste, creala.
    2. Se necessario, rinomina il file binario del container. È composto solo da lettere minuscole, numeri e trattini bassi.
    3. Copia il file binario del container nella cartella <project-root>/res/raw.

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:

  1. Ottieni il singleton TagManager:
    TagManager tagManager = TagManager.getInstance(this);
  2. Utilizza il singleton TagManager per 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 a loadContainerPreferNonDefault() non è bloccante e restituisce un PendingResult:
    PendingResult<ContainerHolder> pending =
            tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
            R.raw.defaultcontainer_binary);
  3. Utilizza un ResultCallback per restituire ContainerHolder una 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 ContainerHolder per ogni esecuzione della tua applicazione. Ecco perché l'esempio precedente utilizza una classe di utilità ContainerHolderSingleton per gestire l'accesso all'istanza ContainerHolder. Ecco come si presenta la classe ContainerHolderSingleton:

    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:

  1. Recupera Container da ContainerHolder utilizzando ContainerHolder.getContainer().
  2. 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:

  1. Recupera il singleton DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 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:

  1. Recupera il singleton DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. 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à dataLayer contemporaneamente 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:

  1. Aggiungi questa anteprima Activity al file AndroidManifest:
    <!--  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" />
  2. Genera un link di anteprima nell'interfaccia web di Google Tag Manager
    1. Accedi a Google Tag Manager
    2. Seleziona la versione del contenitore da visualizzare in anteprima.
    3. Fai clic sul pulsante Anteprima
    4. Inserisci il nome del pacchetto della tua applicazione e fai clic su Genera link di inizio anteprima.
  3. Utilizza il link o il codice QR generato per avviare l'applicazione
  4. 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.