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 mobile utilizzando l'interfaccia di Google Tag Manager senza dover ricreare e inviare nuovamente i file binari delle applicazioni nei marketplace di app.

È utile per gestire eventuali valori o flag di configurazione nell'applicazione di cui potresti aver bisogno modifiche in futuro, tra cui:

Varie impostazioni dell'interfaccia utente e stringhe di visualizzazione
Dimensioni, località o tipi di annunci pubblicati nella tua applicazione.
Varie impostazioni dei giochi

I valori di configurazione possono essere valutati anche in fase di runtime tramite regole, abilitando le configurazioni 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 in diverse applicazioni. Gli sviluppatori possono eseguire il push degli eventi importanti in un livello dati e decidere in un secondo momento quali i tag o i 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, il resto di questa guida ti illustrerà come configurare e utilizzare Google Tag Manager nella tua applicazione Android.

Per iniziare

Dopo aver seguito questa Guida introduttiva, saprai come:

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

Questa guida utilizza snippet di codice dell'Cute Animals dell'applicazione di esempio inclusa SDK Google Play Services. L'origine completa di 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 attivare InstallReferrerReceiver per chiamare il destinatario Google Analytics per impostare i dati della campagna, aggiungi quanto segue alla AndroidManifest.xml file:

<!-- 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 valore predefinito smetterà di essere utilizzato non appena l'app sarà in grado di recuperare un nuovo contenitore tramite in ogni 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. Crealo.
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 consigliabile utilizzare il file binario, se il container non contiene regole o tag, puoi scegliere di usare un semplice file JSON.

3. Inizializzazione di Google Tag Manager

Per inizializzare Google Tag Manager nella tua applicazione:

Prendi il singleton TagManager:

TagManager tagManager = TagManager.getInstance(this);

Utilizza il singleton TagManager per effettuare una richiesta di caricamento di un container, specificando un L'ID contenitore di Google Tag Manager e il contenitore predefinito. . L'ID contenitore deve essere in maiuscolo e corrispondere esattamente all'ID contenitore nel tag Google. Interfaccia web di Manager. La chiamata a loadContainerPreferNonDefault() non blocca e restituisce un PendingResult:
```
PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
```

Utilizza un ResultCallback per restituire ContainerHolder al termine del caricamento o in 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 del tuo un'applicazione. Ecco perché l'esempio precedente utilizza una classe di utilità ContainerHolderSingleton per gestire l'accesso all'istanza ContainerHolder. Ecco di cosa si tratta ContainerHolderSingleton corso ha il seguente aspetto:

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

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

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

Una volta caricato il container, puoi recuperare i valori di configurazione utilizzando uno qualsiasi dei Container.get<type>() metodi. I valori di configurazione vengono definiti Variabili per la raccolta di 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 un 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 contenitore:

Ottiene Container da ContainerHolder utilizzando . ContainerHolder.getContainer()
Ottiene il valore del colore utilizzando Container.getString(key), dove si trovano definito la chiave e il valore nell'interfaccia web di Google Tag Manager.

5. Invio di eventi e valori al dataLayer

Google Tag Manager fornisce anche un dataLayer in cui puoi trasferire le informazioni sull'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.

Invio dei valori al dataLayer

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

Per eseguire il push di un valore a dataLayer, segui questo pattern:

Ottieni lo 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).

Invio degli eventi al dataLayer

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

Ad esempio, anziché impostare come hardcoded le chiamate di monitoraggio delle visualizzazioni di schermata di Google Analytics nella tua applicazione, puoi inviare eventi schermata a dataLayer e definire i tag di monitoraggio tramite Interfaccia web di Google Tag Manager. Questo ti offre la flessibilità di modificare il tag o aggiungere tag aggiuntivi che rispondono agli eventi della schermata, senza aggiornare il codice dell'applicazione.

Per eseguire il push di un evento a dataLayer, segui questo pattern:

Ottieni lo 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 utilizzare per generare facilmente una mappa coppie chiave-valore che aggiorneranno dataLayer nel momento in cui viene inviato l'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 apertura e chiusura nella tua 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, ti consigliamo di visualizzarne l'anteprima per assicurarti che funzioni come previsto. Google Tag Manager offre la possibilità di visualizzare in anteprima le versioni del 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:

Aggiunta di questa anteprima Activity al tuo 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>

Accertati di modificare questa riga in modo da 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 inizio anteprima.
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, abilita 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 verificato che funzioni come previsto, puoi: pubblica il contenitore. Il tuo i valori, i tag e gli eventi della configurazione del contenitore saranno disponibili per gli utenti la volta successiva i container vengono aggiornati. Scopri di più sull'aggiornamento dei contenitori.

Configurazione avanzata

Le seguenti sezioni descrivono le opzioni di configurazione avanzate che vuoi utilizzare per personalizzare ulteriormente Implementazione di Google Tag Manager.

Aggiornamento del container

Per impostazione predefinita, il contenitore diventa idoneo per l'aggiornamento ogni 12 ore. Per aggiornare manualmente il container, usa ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Si tratta di una chiamata asincrona che non verrà restituita immediatamente. Per ridurre il traffico di rete, refresh() potrebbe verrà chiamato solo una volta ogni 15 minuti, altrimenti si tratterà di autonomo.

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();
}