Android v4 (Legacy) – Erste Schritte

Einführung

Mit Google Tag Manager können Entwickler Konfigurationswerte in ihrer mobilen App über die Google Tag Manager-Oberfläche ändern, ohne dass sie die Binärdateien der App neu erstellen und noch einmal bei App-Marktplätzen einreichen 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, Positionen oder Typen von Anzeigen, die in Ihrer App ausgeliefert werden
  • Verschiedene Spieleinstellungen

Konfigurationswerte können auch zur Laufzeit mithilfe von Regeln ausgewertet werden, was dynamische Konfigurationen ermöglicht, z. B.:

  • Bannergröße anhand der Bildschirmgröße bestimmen
  • Sprache und Standort zum Konfigurieren von UI-Elementen verwenden

Google Tag Manager ermöglicht auch 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:

Nachdem Sie diese Schritte ausgeführt haben, erfahren Sie im weiteren Verlauf dieses Leitfadens, wie Sie Google Tag Manager in Ihrer Android-App konfigurieren und verwenden.

Erste Schritte

In diesem Startleitfaden erfahren Sie, wie Sie:

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

1. Google Tag Manager zu Ihrem Projekt hinzufügen

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

  1. Google Play-Dienste 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. Ihrem Projekt eine Standard-Containerdatei hinzufügen

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

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

  1. Melden Sie sich in der Google Tag Manager-Weboberfläche an.
  2. Wählen Sie die Version des Containers aus, die Sie herunterladen möchten.
  3. Klicken Sie auf den Button Herunterladen, um die Container-Binärdatei abzurufen.
  4. Fügen Sie die heruntergeladene Container-Binärdatei als Rohressource zu Ihrem Projekt 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 stattdessen 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 in Großbuchstaben angegeben 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 ein ResultCallback, um die ContainerHolder zurückzugeben, sobald sie vollständig geladen wurde oder ein 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);

    ContainerHolder-Singleton erstellen

    Sie sollten pro Ausführung Ihrer Anwendung nur eine Instanz von ContainerHolder beibehalten. Aus diesem Grund wird im obigen Beispiel eine ContainerHolderSingleton-Dienstprogrammklasse verwendet, um den Zugriff auf die ContainerHolder-Instanz 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;
        }
    }

4. Konfigurationswerte aus dem Container abrufen

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

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

Dieser Code führt zwei Schritte aus, um den Farbnamen aus dem Container abzurufen:

  1. Ruft den Container aus dem ContainerHolder mit 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 an das dataLayer-Objekt senden

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

Werte an die Datenschicht übergeben

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

Wenn Sie einen Wert an die dataLayer übertragen möchten, folgen Sie diesem Muster:

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

Wenn Sie einen Wert aus dem dataLayer abrufen möchten, verwenden Sie DataLayer.get(key).

Ereignisse an dataLayer senden

Wenn Sie Ereignisse an die dataLayer senden, können Sie Ihren Anwendungscode von Tags trennen, die Sie als Reaktion auf diese Ereignisse auslösen möchten.

Anstatt beispielsweise Google Analytics-Tracking-Aufrufe für Bildschirmaufrufe in Ihrer Anwendung hartzucodieren, können Sie Bildschirmereignisse in die dataLayer übertragen und Ihre Tracking-Tags über die Google Tag Manager-Weboberfläche 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.

So übertragen Sie ein Ereignis an die dataLayer:

  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 Hilfsmethode, mit der Sie ganz einfach eine Zuordnung von Schlüssel/Wert-Paaren generieren können, die die dataLayer aktualisieren, wenn das Ereignis übertragen wird.

6. Vorschau, Fehlerbehebung und Veröffentlichung

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

Vorschau wird angezeigt

So rufen Sie eine Vorschau einer Containerversion auf:

  1. Fügen Sie diese Vorabversion Activity in die Datei AndroidManifest ein:
    <!--  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>

    Ändern Sie diese Zeile so, dass sie den Paketnamen Ihrer Anwendung enthält:

    <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
  2. Vorschaulink in der Google Tag Manager-Weboberfläche generieren
    1. Melden Sie sich in Google Tag Manager an.
    2. Wählen Sie die Version des Containers aus, die Sie sich in der Vorschau ansehen möchten.
    3. Klicken Sie auf den Button Vorschau
    4. Geben Sie den Paketnamen Ihrer Anwendung ein und klicken Sie auf Vorschau-Link generieren.
  3. Verwenden Sie den generierten Link oder QR-Code, um Ihre Anwendung zu starten.
  4. Sie können den Vorschaumodus beenden, indem Sie einem Link folgen, der über die Option Link zum Beenden der Vorschau generieren in der Weboberfläche generiert wurde.

Debugging

Wenn Sie Probleme mit Ihrer Containerimplementierung beheben müssen, aktivieren Sie das ausführliche Logging, indem Sie TagManager.setVerboseLoggingEnabled(true) aufrufen:

// 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 Ihres Containers angesehen und überprüft haben, ob er wie gewünscht funktioniert, können Sie den Container veröffentlichen. Ihre Containerkonfigurationswerte, Tags und Ereignisse sind für Nutzer verfügbar, wenn ihre 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 12 Stunden aktualisiert werden. Wenn Sie den Container manuell aktualisieren möchten, verwenden Sie ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Dies ist ein asynchroner Aufruf, der nicht sofort zurückgegeben wird. Um den Netzwerkverkehr zu reduzieren, darf refresh() nur einmal alle 15 Minuten aufgerufen werden. Andernfalls wird der Aufruf ignoriert.