Android v4 – Erste Schritte

Hinweis:In diesem Leitfaden wird die alte Implementierung von Google Tag Manager in Android-Apps beschrieben. Neue Nutzer sollten Tag Manager und Firebase verwenden, um Google Tag Manager in ihren Android-Apps zu implementieren.

Einführung

Mit Google Tag Manager können Entwickler Konfigurationswerte in ihrer mobilen App über die Google Tag Manager-Oberfläche ändern, ohne die Binärprogramme der Anwendung neu erstellen und an App-Marktplätze senden zu müssen.

Dies ist nützlich, um Konfigurationswerte oder Flags in Ihrer Anwendung zu verwalten, die Sie möglicherweise in Zukunft ändern müssen, einschließlich:

• Verschiedene UI-Einstellungen und Anzeigestrings
• Größen, Standorte oder Anzeigentypen, die in Ihrer App ausgeliefert werden
• Verschiedene Spieleinstellungen

Konfigurationswerte können auch zur Laufzeit mithilfe von Regeln ausgewertet werden, um dynamische Konfigurationen wie die folgenden zu ermöglichen:

• Verwendung der Bildschirmgröße zur Bestimmung der Größe von Anzeigenbannern
• UI-Elemente mit Sprache und Standort konfigurieren

Google Tag Manager ermöglicht außerdem die dynamische Implementierung von Tracking-Tags und -Pixeln in Anwendungen. Entwickler können wichtige Ereignisse in eine Datenschicht übertragen und später entscheiden, welche Tracking-Tags oder Pixel ausgelöst werden sollen.

Vorbereitung

Führen Sie die folgenden Schritte aus, bevor Sie mit diesem Startleitfaden beginnen:

• Installieren Sie das Android SDK.
• Laden Sie das Google Play Services SDK herunter.
• Erstellen Sie ein Google Tag Manager-Konto.
• Google Tag Manager-Container konfigurieren

Nachdem Sie diese Schritte ausgeführt haben, erhalten Sie im Folgenden eine Anleitung zum Konfigurieren und Verwenden von Google Tag Manager in Ihrer Android-App.

Erste Schritte

Nachdem Sie diese Anleitung durchgegangen sind, werden Sie mit folgenden Themen vertraut:

• Google Tag Manager in ein Projekt einbinden
• Tag Manager in der Anwendung initialisieren
• Konfigurationswerte aus einem Tag Manager-Container abrufen
• Werte und Ereignisse in die dataLayer übertragen
• Container als Vorschau ansehen, Fehler beheben und Container veröffentlichen

In diesem Leitfaden werden Code-Snippets aus der Beispielanwendung Cute Animals verwendet, die im Google Play Services SDK enthalten ist. Die vollständige Quelle für dieses Projekt ist hier verfügbar: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Google Tag Manager zu Ihrem Projekt hinzufügen

So fügen Sie Ihrem Projekt Google Tag Manager hinzu:

1. Google Play Services SDK einrichten
2. Wenn Sie eine andere IDE als Android Studio verwenden, fügen Sie der Datei AndroidManifest.xml die folgenden Berechtigungen hinzu:

   <!-- For TagManager SDK -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

3. Damit InstallReferrerReceiver den Google Analytics-Empfänger aufrufen kann, um die Kampagnendaten festzulegen, fügen Sie der Datei AndroidManifest.xml Folgendes hinzu:

   <!-- 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. Standardcontainerdatei zu Ihrem Projekt hinzufügen

Hinweis: Falls Sie Ihren Container noch nicht in der Weboberfläche von Google Tag Manager konfiguriert haben, kehren Sie anschließend zu diesem Schritt zurück.

Google Tag Manager verwendet bei der ersten Ausführung Ihrer Anwendung einen Standardcontainer. Der Standardcontainer wird nicht mehr verwendet, sobald die Anwendung einen neuen Container über das Netzwerk abrufen kann.

So laden Sie ein Standard-Binärprogramm für Container herunter und fügen es Ihrer Anwendung hinzu:

1. Melden Sie sich auf der Weboberfläche von Google Tag Manager an.
2. Wählen Sie die Version des Containers aus, den Sie herunterladen möchten.
3. Klicken Sie auf die Schaltfläche Herunterladen, um die Containerbinärdatei abzurufen.
4. Fügen Sie Ihrem Projekt die heruntergeladene Container-Binärdatei als Rohressource hinzu.
   1. Wenn der Unterordner raw unter <project-root>/res/ nicht vorhanden ist, erstellen Sie ihn.
   2. Benennen Sie die Binärdatei des Containers bei Bedarf um. Er besteht nur aus Kleinbuchstaben, Ziffern und Unterstrichen.
   3. Kopieren Sie die Binärdatei des Containers in den Ordner <project-root>/res/raw.

Obwohl die Verwendung der Binärdatei empfohlen wird, können Sie auch eine einfache JSON-Datei verwenden, wenn Ihr Container keine Regeln oder Tags enthält.

3. Google Tag Manager wird initialisiert

So initialisieren Sie Google Tag Manager in Ihrer Anwendung:

1. Rufen Sie das Singleton TagManager ab:

   TagManager tagManager = TagManager.getInstance(this);
   

2. Verwenden Sie das Singleton TagManager, um eine Anfrage zum Laden eines Containers zu stellen. Geben Sie dabei eine Google Tag Manager-Container-ID sowie Ihre Standardcontainerdatei an. Die Container-ID muss großgeschrieben werden und genau mit der Container-ID in der Google Tag Manager-Weboberfläche übereinstimmen. Der Aufruf von loadContainerPreferNonDefault() ist nicht blockierend und gibt ein PendingResult zurück:

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

3. Verwenden Sie einen ResultCallback, um ContainerHolder zurückzugeben, wenn der Ladevorgang abgeschlossen ist oder das Zeitlimit überschritten wurde:

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

   Hinweis: Standardmäßig kann ein Container alle 12 Stunden über das Netzwerk aktualisiert werden. Weitere Informationen zum manuellen Aktualisieren eines Containers

   ContainerHolder-Singleton erstellen

   Sie sollten nur eine Instanz von ContainerHolder pro Ausführung Ihrer Anwendung verwalten. Deshalb wird im obigen Beispiel die Dienstprogrammklasse ContainerHolderSingleton verwendet, um den Zugriff auf die Instanz ContainerHolder zu verwalten. So sieht die Klasse ContainerHolderSingleton aus:

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

Code-Snippet aus der Beispielanwendung ansehen

Das folgende Snippet zeigt das vollständige Muster, das in der Methode onCreate() einer Beispiel-Activity implementiert wurde:

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. Konfigurationswerte aus dem Container abrufen

Sobald der Container geladen ist, können Sie Konfigurationswerte mit einer der Container.get<type>()-Methoden abrufen. Konfigurationswerte werden mithilfe der Werterfassungsvariablen von Google Tag Manager definiert. Mit der folgenden Methode wird beispielsweise die zuletzt für ein UI-Element zu verwendende Farbe abgerufen und als Ganzzahl zurückgegeben:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Mit diesem Code wird der Farbname aus dem Container abgerufen:

1. Ruft die Container aus dem ContainerHolder mithilfe von ContainerHolder.getContainer() ab.
2. Ruft den Farbwert mit Container.getString(key) ab, wobei Sie den Schlüssel und den Wert in der Google Tag Manager-Weboberfläche definiert haben.

5. Ereignisse und Werte in die dataLayer-Datei übertragen

Google Tag Manager bietet auch eine dataLayer, in die Sie Informationen zu Ihrer Anwendung übertragen können, die in anderen Teilen der Anwendung gelesen oder zum Auslösen von Tags verwendet werden können, die Sie in der Weboberfläche von Google Tag Manager konfiguriert haben.

Werte in dataLayer übertragen

dataLayer bietet eine Persistenzebene, mit der Sie Schlüssel/Wert-Paare, die Sie in anderen Teilen Ihrer Anwendung verwenden möchten, oder als Eingaben für Google Tag Manager-Tags speichern können.

Folgen Sie diesem Muster, um einen Wert an dataLayer zu übertragen:

1. Rufen Sie das Singleton DataLayer ab:

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

2. Übertragen Sie das Ereignis mit DataLayer.push():

   // Put the image_name into the data layer for future use.
   TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
   

Verwenden Sie DataLayer.get(key), um einen Wert aus dataLayer abzurufen.

Ereignisse an dataLayer übertragen

Wenn Sie Ereignisse per Push an dataLayer senden, können Sie Ihren Anwendungscode von Tags trennen, die möglicherweise als Reaktion auf diese Ereignisse ausgelöst werden sollen.

Anstatt beispielsweise Google Analytics-Bildschirmaufrufe zum Tracking von Aufrufen in Ihrer Anwendung hartzucodieren, können Sie Bildschirmereignisse an dataLayer senden und Ihre Tracking-Tags über die Weboberfläche von Google Tag Manager definieren. So können Sie dieses Tag flexibel ändern oder zusätzliche Tags hinzufügen, die auf Bildschirmereignisse reagieren, ohne den Anwendungscode aktualisieren zu müssen.

Folgen Sie diesem Muster, um ein Ereignis an dataLayer zu übertragen:

1. Rufen Sie das Singleton DataLayer ab:

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

2. Übertragen Sie das Ereignis mit DataLayer.pushEvent():

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
   

   DataLayer.mapOf() ist eine Dienstprogrammmethode, mit der Sie auf einfache Weise eine Zuordnung von Schlüssel/Wert-Paaren generieren können, die dataLayer gleichzeitig mit der Übertragung des Ereignisses aktualisiert.

Code-Snippet aus der Beispielanwendung ansehen

Die folgende Dienstprogrammklasse zeigt, wie Ereignisse wie Informationen zum Öffnen und Schließen von Bildschirmen in Ihrer App an das dataLayer gesendet werden:

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. Vorschau, Fehlerbehebung und Veröffentlichung

Bevor Sie eine Version Ihres Containers veröffentlichen, sollten Sie in der Vorschau prüfen, ob er wie gewünscht funktioniert. Mit Google Tag Manager können Sie sich eine Vorschau der Versionen Ihres Containers ansehen. Dazu generieren Sie Links und QR-Codes in der Weboberfläche, um damit Ihre Anwendung zu öffnen. Sie können auch den ausführlichen Protokollierungsmodus aktivieren, um unerwartetes Verhalten zu beheben.

Vorschau wird angezeigt

So rufen Sie eine Vorschau einer Version Ihres Containers auf:

1. Der Datei AndroidManifest wird die Vorschau Activity hinzugefügt:

   <!--  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>
   

   Achten Sie darauf, diese Zeile so zu ändern, dass sie den Paketnamen Ihrer App enthält:

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

2. Erstellen Sie einen Vorschaulink in der Google Tag Manager-Weboberfläche.
   1. In Google Tag Manager anmelden
   2. Wählen Sie die Version des Containers für die Vorschau aus.
   3. Klicken Sie auf die Schaltfläche Vorschau
   4. Geben Sie den Paketnamen der App ein und klicken Sie auf Link zum Starten der Vorschau erstellen.
3. Verwenden Sie den generierten Link oder QR-Code, um Ihre App zu starten
4. Sie können den Vorschaumodus beenden, indem Sie einem Link folgen, der in der Weboberfläche mit der Option Link zum Beenden der Vorschau generieren generiert wurde.

Debugging

Wenn Sie Fehler an der Containerimplementierung beheben müssen, aktivieren Sie ausführliches Logging. Rufen Sie dazu TagManager.setVerboseLoggingEnabled(true) auf:

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

Wird veröffentlicht

Nachdem Sie sich eine Vorschau des Containers angesehen und sichergestellt haben, dass er wie vorgesehen funktioniert, können Sie den Container veröffentlichen. Die Werte, Tags und Ereignisse der Containerkonfiguration sind für Nutzer verfügbar, wenn die Container das nächste Mal aktualisiert werden. Weitere Informationen zum Aktualisieren von Containern

Erweiterte Konfiguration

In den folgenden Abschnitten werden erweiterte Konfigurationsoptionen beschrieben, mit denen Sie Ihre Google Tag Manager-Implementierung weiter anpassen können.

Container aktualisieren

Standardmäßig kann Ihr Container alle zwölf Stunden aktualisiert werden. Verwenden Sie ContainerHolder.refresh(), um den Container manuell zu aktualisieren:

ContainerHolderSingleton.getContainerHolder().refresh();

Dies ist ein asynchroner Aufruf, der nicht sofort zurückgegeben wird. Zur Reduzierung des Netzwerkverkehrs wird refresh() nur alle 15 Minuten aufgerufen. Andernfalls ist es ein managementfrei.

Hinweis: In diesem Snippet wird die Dienstprogrammklasse ContainerHolderSingleton verwendet, die im Initialisierungsbeispiel oben beschrieben wurde.

Code-Snippet aus der Beispielanwendung ansehen

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