Questa pagina è stata tradotta dall'API Cloud Translation.

Android v4 - Per iniziare

Introduzione

Google Tag Manager consente agli sviluppatori di modificare i valori di configurazione nella propria applicazione per dispositivi mobili utilizzando l'interfaccia di Google Tag Manager senza dover ricreare e inviare nuovamente i programmi binari delle applicazioni ai relativi marketplace.

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
Varie impostazioni di gioco

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

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.

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.
Configurare un contenitore di Google Tag Manager

Una volta completati questi passaggi, nella parte restante di questa guida verrà spiegato come configurare e utilizzare Google Tag Manager nella tua applicazione per Android.

Per iniziare

Dopo avere seguito questa Guida introduttiva, sarai in grado di:

Aggiungere Google Tag Manager al progetto
Inizializzare Tag Manager nell'applicazione
Ottenere i valori di configurazione da un contenitore Tag Manager
Eseguire il push di valori ed eventi in dataLayer
Visualizzare l'anteprima del contenitore, eseguirne il debug e pubblicarlo

Questa guida utilizza gli snippet di codice dell'applicazione di esempio Cute Animals inclusa nell'SDK Google Play Services. L'origine completa per questo progetto è disponibile in: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Aggiunta di Google Tag Manager al 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 InstallReferrerReceiver di chiamare il destinatario 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 contenitore predefinito al progetto

Google Tag Manager utilizza un contenitore predefinito alla prima esecuzione dell'applicazione. Il container predefinito non verrà più utilizzato non appena l'app sarà in grado di recuperare un nuovo container sulla rete.

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

Accedi all'interfaccia web di Google Tag Manager.
Seleziona la Versione del contenitore da scaricare.
Fai clic sul pulsante Scarica per recuperare il programma binario del container.
Aggiungi il file binario del container scaricato al tuo progetto come risorsa non elaborata.
1. Se la sottocartella raw in <project-root>/res/ non esiste, creala.
2. Rinomina il file binario del container, se necessario. È composto solo da lettere minuscole, numeri e trattini bassi.
3. Copia il file binario del container nella cartella <project-root>/res/raw.

Sebbene sia consigliato utilizzare il file binario, se il container non contiene regole o tag, puoi scegliere di utilizzare un semplice file JSON.

3. Inizializzazione di Google Tag Manager

Per inizializzare Google Tag Manager nell'applicazione:

Prendi il singleton TagManager:

TagManager tagManager = TagManager.getInstance(this);

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 maiuscolo e corrispondere esattamente all'ID contenitore nell'interfaccia web di Google Tag Manager. La chiamata a loadContainerPreferNonDefault() non sta bloccando e restituisce un PendingResult:
```
PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
```

Utilizza ResultCallback per restituire ContainerHolder al termine del caricamento o al 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 gestire una sola istanza di ContainerHolder per 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 il corso 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;
    }
}

Visualizza uno snippet di codice dall'applicazione di esempio

Lo snippet seguente mostra il pattern completo implementato nel metodo onCreate() di un esempio di Activity:

package com.google.android.tagmanager.examples.cuteanimals;

import java.util.concurrent.TimeUnit;
import java.util.Map;

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.ResultCallback;
import com.google.android.gms.tagmanager.Container;
import com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback;
import com.google.android.gms.tagmanager.Container.FunctionCallTagCallback;
import com.google.android.gms.tagmanager.ContainerHolder;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Displays simple splash screen while GTM container is loading. Once the container is loaded,
 * launches the {@link MainActivity}.
 */
public class SplashScreenActivity extends Activity {
    private static final long TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS = 2000;
    private static final String CONTAINER_ID = "GTM-XXXX";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_splashscreen);

        TagManager tagManager = TagManager.getInstance(this);

        // 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);

        PendingResult<ContainerHolder> pending =
                tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
                R.raw.defaultcontainer_binary);

        // 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);
  // Rest of the Activity definition.
}

4. Recupero dei valori di configurazione dal container

Dopo aver 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 valori di Google Tag Manager. Ad esempio, il seguente metodo recupera il colore più recente 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 consente di recuperare il nome del colore dal container in due modi:

Recupera Container da ContainerHolder utilizzando ContainerHolder.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. Inviare eventi e valori al dataLayer

Google Tag Manager fornisce anche un dataLayer, in cui è possibile inviare informazioni sulla tua applicazione che possono essere lette in altre parti dell'applicazione o utilizzate per attivare i tag configurati nell'interfaccia web di Google Tag Manager.

Trasferimento dei valori al dataLayer

dataLayer fornisce un livello di persistenza che puoi utilizzare per memorizzare le coppie chiave-valore che potresti voler utilizzare in altre parti dell'applicazione o come input per i tag di Google Tag Manager.

Per inviare un valore a dataLayer, segui questo schema:

Prendi il singleton DataLayer:

DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();

Esegui il push dell'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).

Trasferimento degli eventi al dataLayer

Il push degli eventi a dataLayer ti consente di separare il codice dell'applicazione dai tag che potresti voler attivare in risposta a questi eventi.

Ad esempio, invece di impostare come hardcoded le chiamate di monitoraggio delle visualizzazioni di schermata di Google Analytics nella tua applicazione, puoi inviare gli eventi della schermata a dataLayer e definire i tag di monitoraggio tramite l'interfaccia web di Google Tag Manager. In questo modo hai la flessibilità di modificare il tag o di aggiungere altri tag in grado di rispondere agli eventi della schermata, senza aggiornare il codice dell'applicazione.

Per inviare un evento a dataLayer, segui questo schema:

Prendi il singleton DataLayer:

DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();

Esegui il push dell'evento utilizzando DataLayer.pushEvent():
```
dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
```
DataLayer.mapOf() è un metodo di utilità che puoi usare per generare facilmente una mappa di coppie chiave-valore che aggiornerà dataLayer nello stesso momento in cui viene eseguito il push dell'evento.

Visualizza uno snippet di codice dall'applicazione di esempio

La seguente classe di utilità mostra come eseguire il push di eventi, ad esempio informazioni sulle schermate che si aprono e chiudono nell'app, su dataLayer:

package com.google.android.tagmanager.examples.cuteanimals;

import android.content.Context;

import com.google.android.gms.tagmanager.DataLayer;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Utility class.
 */
public class Utils {
    private Utils() {
        // private constructor.
    }

    /**
     * Push an "openScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushOpenScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    }

    /**
     * Push a "closeScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushCloseScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("closeScreen", DataLayer.mapOf("screenName", screenName));
    }
}

6. Anteprima, debug e pubblicazione

Prima di pubblicare una versione del contenitore, è consigliabile visualizzarne l'anteprima per verificare che funzioni come previsto. Google Tag Manager ti offre la possibilità di visualizzare l'anteprima delle versioni del tuo contenitore generando link e codici QR nell'interfaccia web e utilizzandoli per aprire l'applicazione. Puoi anche attivare una modalità di logging dettagliata per eseguire il debug di qualsiasi comportamento imprevisto.

Visualizzazione dell'anteprima in corso…

Per visualizzare l'anteprima di una versione del contenitore:

Aggiunta di 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 dell'applicazione:

<data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />

Generare un link di anteprima nell'interfaccia web di Google Tag Manager
1. Accedi a Google Tag Manager.
2. Seleziona la Versione del contenitore di cui visualizzare l'anteprima
3. Fai clic sul pulsante Anteprima
4. Inserisci il nome del pacchetto dell'applicazione e fai clic su Genera link di anteprima iniziale
Usa 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 anteprima finale nell'interfaccia web.

Debug

Se devi risolvere i problemi di 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);

In fase di pubblicazione

Dopo aver visualizzato l'anteprima del contenitore e verificato che funzioni come previsto, puoi pubblicare il contenitore. I valori di configurazione dei contenitori, i tag e gli eventi saranno disponibili per gli utenti al successivo aggiornamento dei contenitori. Scopri di più sull'aggiornamento dei contenitori.

Configurazione avanzata

Le seguenti sezioni descrivono le opzioni di configurazione avanzate da utilizzare per personalizzare ulteriormente l'implementazione di Google Tag Manager.

Aggiornamento del container

Per impostazione predefinita, il contenitore diventa idoneo per essere aggiornato ogni 12 ore. Per aggiornare manualmente il contenitore, utilizza ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Si tratta di una chiamata asincrona che non viene restituita immediatamente. Per ridurre il traffico di rete, è possibile che refresh() venga chiamato solo una volta ogni 15 minuti, altrimenti non sarà operativo.

Visualizza uno snippet di codice dall'applicazione di esempio

public void refreshButtonClicked(@SuppressWarnings("unused") View view) {
    Log.i(TAG, "refreshButtonClicked");
    ContainerHolderSingleton.getContainerHolder().refresh();

    // Push the "refresh" event to trigger firing an analytics tag.
    TagManager.getInstance(this).getDataLayer().push("event", "refresh");
    // Push the "custom tag" event to trigger firing a custom function call tag.
    TagManager.getInstance(this).getDataLayer().push("event", "custom_tag");
    updateCategories();
}