Android v3 (alte Version) – Übersicht

In dieser Anleitung für Entwickler wird beschrieben, wie Sie Google Tag Manager in einer mobilen Anwendung implementieren.

Einführung

Mit Google Tag Manager können Entwickler Konfigurationswerte in ihren mobilen Anwendungen über die Google Tag Manager-Oberfläche ändern, ohne Anwendungsbinärdateien neu erstellen und an App-Marktplätze senden zu müssen.

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

  • Verschiedene UI-Einstellungen und Anzeigestrings
  • Größen, Standorte oder Arten von Anzeigen, die in Ihrer Anwendung ausgeliefert werden
  • Spieleinstellungen

Konfigurationswerte können auch zur Laufzeit mithilfe von Regeln ausgewertet werden, wodurch dynamische Konfigurationen möglich sind, z. B.:

  • Anzeigengröße anhand der Bildschirmgröße bestimmen
  • UI-Elemente anhand von Sprache und Standort konfigurieren

Mit Google Tag Manager können auch Tracking-Tags und ‑Pixel dynamisch in Anwendungen implementiert werden. Entwickler können wichtige Ereignisse in eine Daten schicht übertragen und später entscheiden, welche Tracking-Tags oder ‑Pixel ausgelöst werden sollen. Tag Manager unterstützt die folgenden Tags:

  • Google Mobile App Analytics
  • Benutzerdefiniertes Funktionsaufruf-Tag

Vorbereitung

Für diese Anleitung benötigen Sie Folgendes:

Wenn Sie noch nicht mit Google Tag Manager vertraut sind, empfehlen wir Ihnen, sich zuerst über Container, Makros und Regeln (Hilfe) zu informieren, bevor Sie mit dieser Anleitung fortfahren.

Erste Schritte

In diesem Abschnitt wird ein typischer Tag Manager-Workflow für Entwickler beschrieben:

  1. Google Tag Manager SDK zu Ihrem Projekt hinzufügen
  2. Standardcontainerwerte festlegen
  3. Container öffnen
  4. Konfigurationswerte aus dem Container abrufen
  5. Ereignisse an die Datenschicht übertragen
  6. Container als Vorschau ansehen und veröffentlichen

1. Google Tag Manager SDK zu Ihrem Projekt hinzufügen

Bevor Sie das Google Tag Manager SDK verwenden können, müssen Sie das SDK-Paket extrahieren, die Bibliothek zum Build-Pfad Ihres Projekts hinzufügen und Berechtigungen in Ihrer Datei AndroidManifest.xml hinzufügen.

Fügen Sie zuerst die Google Tag Manager-Bibliothek zum Ordner /libs Ihres Projekts hinzu.

Aktualisieren Sie dann die Datei „AndroidManifest.xml“, um die folgenden Berechtigungen zu verwenden:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

2. Standardcontainerdatei zu Ihrem Projekt hinzufügen

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

So laden Sie eine binäre Standardcontainerdatei herunter und fügen sie 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 die Schaltfläche Herunterladen , um die binäre Containerdatei abzurufen.
  4. Fügen Sie die Binärdatei dem folgenden Pfad hinzu: <project-root>/assets/tagmanager/

Der Standarddateiname sollte die Container-ID sein (z. B. GTM-1234). Nachdem Sie die Binärdatei heruntergeladen haben, entfernen Sie das Versionssuffix aus dem Dateinamen, um die richtige Namenskonvention einzuhalten.

Obwohl die Verwendung der Binärdatei empfohlen wird, können Sie stattdessen auch eine JSON-Datei verwenden, wenn Ihr Container keine Regeln oder Tags enthält, Die Datei muss sich in einem neuen /assets/tagmanager Ordner Ihres Android-Projekts befinden und dieser Namenskonvention folgen: <Container_ID>.json. Wenn Ihre Container-ID ist GTM-1234, sollten Sie die Standardcontainerwerte zu /assets/tagmanager/GTM-1234.json hinzufügen.

3. Container öffnen

Bevor Sie Werte aus einem Container abrufen können, muss Ihre Anwendung den Container öffnen. Wenn Sie einen Container öffnen, wird er von der Festplatte geladen (falls verfügbar) oder bei Bedarf aus dem Netzwerk angefordert.

Die einfachste Möglichkeit, einen Container unter Android zu öffnen, ist die Verwendung von ContainerOpener.openContainer(..., Notifier notifier), wie im folgenden Beispiel:

import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;

import android.app.Activity;
import android.os.Bundle;

public class RacingGame {

  // Add your public container ID.
  private static final String CONTAINER_ID = "GTM-YYYY";

  volatile private Container mContainer;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TagManager mTagManager = TagManager.getInstance(this);

    // The container is returned to containerFuture when available.
    ContainerOpener.openContainer(
        mTagManager,                            // TagManager instance.
        CONTAINER_ID,                           // Tag Manager Container ID.
        OpenType.PREFER_NON_DEFAULT,            // Prefer not to get the default container, but stale is OK.
        null,                                   // Time to wait for saved container to load (ms). Default is 2000ms.
        new ContainerOpener.Notifier() {        // Called when container loads.
          @Override
          public void containerAvailable(Container container) {
            // Handle assignment in callback to avoid blocking main thread.
            mContainer = container;
          }
        }
    );
    // Rest of your onCreate code.
  }
}

In diesem Beispiel wird ContainerOpener.openContainer(..., Notifier notifier) verwendet, um einen gespeicherten Container aus dem lokalen Speicher anzufordern. Durch die Verarbeitung der Zuweisung von mContainer im Callback containerAvailable wird verhindert, dass der Hauptthread blockiert wird. Wenn der gespeicherte Container älter als 12 Stunden ist, wird mit dem Aufruf auch eine Anfrage geplant, um einen neuen Container asynchron über das Netzwerk abzurufen.

Diese Beispielimplementierung ist die einfachste Möglichkeit, Werte mit der Hilfsklasse ContainerOpener aus einem Container zu öffnen und abzurufen. Weitere Informationen zu erweiterten Implementierungsoptionen finden Sie unter Erweiterte Konfiguration.

4. Konfigurationswerte aus dem Container abrufen

Sobald der Container geöffnet ist, können Konfigurationswerte mit den get<type>Value() Methoden abgerufen werden:

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

Anfragen mit einem nicht vorhandenen Schlüssel geben einen Standardwert zurück, der dem angeforderten Typ entspricht:

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.

5. Werte an die Datenschicht übertragen

Die Datenschicht ist eine Map, mit der Laufzeitinformationen zu Ihrer App, z. B. Touch Ereignisse oder Bildschirmansichten, für Tag Manager-Makros und ‑Tags in einem Container verfügbar gemacht werden können.

Wenn Sie beispielsweise Informationen zu Bildschirmansichten in die Datenschicht-Map übertragen, können Sie in der Tag Manager-Weboberfläche Tags einrichten, um Conversion-Pixel und Tracking-Aufrufe als Reaktion auf diese Bildschirmansichten auszulösen, ohne sie in Ihre App hart codieren zu müssen.

Ereignisse werden mit push() und der DataLayer.mapOf() Hilfsmethode an die Datenschicht übertragen:

//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//

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

import android.app.Activity;
import android.os.Bundle;

public MainActivity extends Activity {

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

  }

  // This screen becomes visible when Activity.onStart() is called.
  public void onStart() {
    super.onStart();

    // The container should have already been opened, otherwise events pushed to
    // the DataLayer will not fire tags in that container.
    DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
    dataLayer.push(DataLayer.mapOf("event",
                                   "openScreen",      // The event type. This value should be used consistently for similar event types.
                                   "screenName",      // Writes a key "screenName" to the dataLayer map.
                                   "Home Screen")     // Writes a value "Home Screen" for the "screenName" key.
    );
  }
  // Rest of the Activity implementation
}

In der Weboberfläche können Sie jetzt Tags (z. B. Google Analytics-Tags) erstellen, die für jeden Bildschirmaufruf ausgelöst werden, indem Sie diese Regel erstellen: equals "openScreen". Wenn Sie den Bildschirmnamen an eines dieser Tags übergeben möchten, erstellen Sie ein Datenschicht-Makro, das auf den Schlüssel „screenName“ in der Datenschicht verweist. Sie können auch ein Tag (z. B. ein Google Ads-Conversion-Pixel) erstellen, das nur für bestimmte Bildschirmansichten ausgelöst wird, indem Sie eine Regel erstellen, bei der equals "openScreen" && equals "ConfirmationScreen".

6. Container als Vorschau ansehen und veröffentlichen

Makrowerte entsprechen immer der aktuellen veröffentlichten Version. Bevor Sie die neueste Version eines Containers veröffentlichen, können Sie sich eine Vorschau Ihres Containerentwurfs ansehen.

Wenn Sie sich eine Vorschau eines Containers ansehen möchten, generieren Sie in der Google Tag Manager-Weboberfläche eine Vorschau-URL. Wählen Sie dazu die Version des Containers aus, die Sie sich ansehen möchten, und dann Preview. Speichern Sie diese Vorschau-URL, da Sie sie in späteren Schritten benötigen.

Vorschau-URLs sind im Vorschaufenster der Tag Manager-Weboberfläche verfügbar.
Abbildung 1: Vorschau-URL aus der Tag Manager-Weboberfläche abrufen

Fügen Sie dann die folgende Aktivität der Datei AndroidManifest.xml Ihrer Anwendung hinzu:

<!-- Google Tag Manager Preview Activity -->
<activity
  android:name="com.google.tagmanager.PreviewActivity"
  android:label="@string/app_name"
  android:noHistory="true" >  <!-- Optional, removes the PreviewActivity from activity stack. -->
  <intent-filter>
    <data android:scheme="tagmanager.c.application_package_name" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE"/>
  </intent-filter>
</activity>

Öffnen Sie den Link in einem Emulator oder auf einem physischen Gerät, um sich eine Vorschau des Containerentwurfs in Ihrer App anzusehen.

Wenn Sie die Konfigurationswerte Ihres Entwurfs für Ihre Anwendung verfügbar machen möchten, veröffentlichen Sie den Container.

Erweiterte Konfiguration

Google Tag Manager für mobile Apps bietet eine Reihe erweiterter Konfigurationsoptionen, mit denen Sie Werte basierend auf Laufzeitbedingungen mithilfe von Regeln auswählen, den Container manuell aktualisieren und zusätzliche Optionen zum Öffnen von Containern erhalten können. In den folgenden Abschnitten werden einige der häufigsten erweiterten Konfigurationen beschrieben.

Erweiterte Optionen zum Öffnen von Containern

Das Google Tag Manager SDK bietet mehrere Methoden zum Öffnen von Containern, mit denen Sie mehr Kontrolle über den Ladevorgang haben:

TagManager.openContainer()

TagManager.openContainer() ist die API der niedrigsten Ebene und die flexibelste API zum Öffnen eines Containers. Sie gibt sofort einen Standardcontainer zurück und lädt auch asynchron einen Container von der Festplatte oder aus dem Netzwerk, wenn kein gespeicherter Container vorhanden ist oder wenn der gespeicherte Container nicht aktuell ist (älter als 12 Stunden).

mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {

  // Called when a refresh is about to begin for the given refresh type.
  @Override
  public void containerRefreshBegin(Container container, RefreshType refreshType) {
    // Notify UI that the Container refresh is beginning.
   }

  // Called when a successful refresh occurred for the given refresh type.
  @Override
  public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
    // Notify UI that Container is ready.
  }

  // Called when a refresh failed for the given refresh type.
  @Override
  public void containerRefreshFailure(Container container,
                                      RefreshType refreshType,
                                      RefreshFailure refreshFailure) {
    // Notify UI that the Container refresh has failed.
  }

Während des Ladevorgangs gibt TagManager.openContainer() mehrere Lifecycle-Callbacks aus, damit Ihr Code ermitteln kann, wann die Ladeanfrage beginnt, ob und warum sie fehlschlägt oder erfolgreich ist und ob der Container letztendlich von der Festplatte oder aus dem Netzwerk geladen wurde.

Sofern es für Ihre Anwendung akzeptabel ist, die Standardwerte zu verwenden, müssen Sie diese Callbacks verwenden, um zu erfahren, wann ein gespeicherter oder Netzwerkcontainer geladen wurde. Wenn die App zum ersten Mal ausgeführt wird und keine Netzwerkverbindung besteht, können Sie keinen gespeicherten oder Netzwerkcontainer laden.

TagManager.openContainer() übergibt die folgenden enum-Werte als Argumente an diese Callbacks:

RefreshType

WertBeschreibung
Container.Callback.SAVED Mit der Aktualisierungsanfrage wird ein lokal gespeicherter Container geladen.
Container.Callback.NETWORK Mit der Aktualisierungsanfrage wird ein Container über das Netzwerk geladen.

RefreshFailure

WertBeschreibung
Container.Callback.NO_SAVED_CONTAINER Es ist kein gespeicherter Container verfügbar.
Container.Callback.IO_ERROR Ein E/A-Fehler hat die Aktualisierung des Containers verhindert.
Container.Callback.NO_NETWORK Es ist keine Netzwerkverbindung verfügbar.
Container.Callback.NETWORK_ERROR Ein Netzwerkfehler ist aufgetreten.
Container.Callback.SERVER_ERROR Auf dem Server ist ein Fehler aufgetreten.
Container.Callback.UNKNOWN_ERROR Ein Fehler, der nicht kategorisiert werden kann, ist aufgetreten.

Methoden zum Öffnen von nicht standardmäßigen und neuen Containern

ContainerOpener umschließt TagManager.openContainer() und bietet zwei Hilfsmethoden zum Öffnen von Containern: ContainerOpener.openContainer(..., Notifier notifier) und ContainerOpener.openContainer(..., Long timeoutInMillis).

Jede dieser Methoden verwendet eine Enumeration, mit der entweder ein nicht standardmäßiger oder ein neuer Container angefordert wird.

OpenType.PREFER_NON_DEFAULT wird für die meisten Anwendungen empfohlen und versucht, innerhalb eines bestimmten Zeitlimits den ersten verfügbaren nicht standardmäßigen Container von der Festplatte oder aus dem Netzwerk zurückzugeben, auch wenn dieser Container älter als 12 Stunden ist. Wenn ein veralteter gespeicherter Container zurückgegeben wird, wird auch eine asynchrone Netzwerkanfrage für einen neuen Container gestellt. Bei Verwendung von OpenType.PREFER_NON_DEFAULT wird ein Standardcontainer zurückgegeben, wenn kein anderer Container verfügbar ist oder das Zeitlimit überschritten wird.

OpenType.PREFER_FRESH versucht, innerhalb des angegebenen Zeitlimits einen neuen Container von der Festplatte oder aus dem Netzwerk zurückzugeben. Wenn keine Netzwerkverbindung verfügbar ist und/oder das Zeitlimit überschritten wird, wird ein gespeicherter Container zurückgegeben.

Es wird nicht empfohlen, OpenType.PREFER_FRESH an Stellen zu verwenden, an denen eine längere Anfragezeit die Nutzerfreundlichkeit spürbar beeinträchtigen kann, z. B. bei UI-Flags oder Anzeigestrings. Sie können auch jederzeit Container.refresh() verwenden , um eine Netzwerkanfrage für einen Container zu erzwingen.

Beide Hilfsmethoden sind nicht blockierend. ContainerOpener.openContainer(..., Long timeoutInMillis) gibt ein ContainerOpener.ContainerFuture-Objekt zurück, dessen Methode get ein Container zurückgibt, sobald es geladen wurde (bis dahin wird blockiert). Die Methode ContainerOpener.openContainer(..., Notifier notifier) verwendet einen einzelnen Callback, der aufgerufen wird, wenn der Container verfügbar ist. So kann verhindert werden, dass der Hauptthread blockiert wird. Beide Methoden haben ein Standardzeitlimit von 2000 Millisekunden.

Makros zur Laufzeit mithilfe von Regeln auswerten

Container können Werte zur Laufzeit mithilfe von Regeln auswerten. Regeln können auf Kriterien wie Gerätesprache, Plattform oder einem beliebigen anderen Makrowert basieren. Mit Regeln kann beispielsweise zur Laufzeit ein lokalisierter Anzeigestring basierend auf der Sprache des Geräts ausgewählt werden. Das kann mit der folgenden Regel konfiguriert werden:

Mit einer Regel werden zur Laufzeit Anzeigestrings basierend auf der Gerätesprache ausgewählt: language = es. Für diese Regel wird das vordefinierte Sprachmakro und ein zweistelliger ISO 639-1-Sprachcode verwendet.
Abbildung 1:Regel hinzufügen, um ein Makro zur Wertsammlung nur für Geräte zu aktivieren, die für die Verwendung der spanischen Sprache konfiguriert sind.

Sie können dann Makros zur Wertsammlung für jede Sprache erstellen und diese Regel zu jedem Makro hinzufügen, wobei Sie den entsprechenden Sprachcode einfügen. Wenn dieser Container veröffentlicht wird, kann Ihre Anwendung je nach Sprache des Geräts des Nutzers zur Laufzeit lokalisierte Anzeigestrings anzeigen.

Wenn Ihr Standardcontainer Regeln benötigt, müssen Sie eine binäre Containerdatei als Standard container verwenden.

Weitere Informationen zum Konfigurieren von Regeln (Hilfe)

Binäre Standardcontainerdateien

Für Standardcontainer, die Regeln benötigen, sollte eine binäre Containerdatei anstelle einer JSON Datei als Standardcontainer verwendet werden. Binäre Container unterstützen die Bestimmung von Makrowerten zur Laufzeit mit Google Tag Manager-Regeln, JSON Dateien jedoch nicht.

Binäre Containerdateien können über die Google Tag Manager-Web oberfläche heruntergeladen werden. Sie sollten dem Ordner Ihres Projekts /assets/tagmanager/ hinzugefügt werden und diesem Muster folgen: /assets/tagmanager/GTM-XXXX, wobei der Dateiname Ihre Container-ID darstellt.

Wenn sowohl eine JSON-Datei als auch eine binäre Containerdatei vorhanden sind, verwendet das SDK die binäre Containerdatei als Standardcontainer.

Funktionsaufruf-Makros verwenden

Funktionsaufruf-Makros sind Makros, die auf den Rückgabewert einer bestimmten Funktion in Ihrer Anwendung festgelegt sind. Funktionsaufruf-Makros können verwendet werden, um Laufzeitwerte in Ihre Google Tag Manager-Regeln einzubinden, z. B. um zur Laufzeit zu bestimmen, welcher Preis einem Nutzer basierend auf der konfigurierten Sprache und Währung eines Geräts angezeigt werden soll.

So konfigurieren Sie ein Funktionsaufruf-Makro:

  1. Definieren Sie das Funktionsaufruf-Makro in der Google Tag Manager-Weboberfläche. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
  2. Registrieren Sie in Ihrer Anwendung einen FunctionCallMacroHandler mit Container.registerFunctionCallMacroHandler() und dem Funktionsnamen, den Sie in der Google Tag Manager-Weboberfläche konfiguriert haben, und überschreiben Sie die Methode getValue(): 
    /**
 * Registers a function call macro handler.
 *
 * @param functionName The function name field, as defined in the Google Tag
 *     Manager web interface.
 */
mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() {

  /**
   * This code will execute when any custom macro's rule(s) evaluate to true.
   * The code should check the functionName and process accordingly.
   *
   * @param functionName Corresponds to the function name field defined
   *     in the Google Tag Manager web interface.
   * @param parameters An optional map of parameters
   *     as defined in the Google Tag Manager web interface.
   */
  @Override
  public Object getValue(String functionName, Map<String, Object> parameters)) {

    if (functionName.equals("myConfiguredFunctionName")) {
      // Process and return the calculated value of this macro accordingly.
      return macro_value
    }
    return null;
  }
});

Funktionsaufruf-Tags verwenden

Mit Funktionsaufruf-Tags können vorab registrierte Funktionen ausgeführt werden, wenn ein Ereignis in die Datenschicht übertragen wird und die Tag-Regeln `true` ergebentrue.

So konfigurieren Sie ein Funktionsaufruf-Tag:

  1. Definieren Sie das Funktionsaufruf-Tag in der Google Tag Manager-Weboberfläche. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
  2. Registrieren Sie in Ihrer Anwendung einen Handler für Funktionsaufruf-Tags mit Container.registerFunctionCallTagHandler(): 
    /**
 * Register a function call tag handler.
 *
 * @param functionName The function name, which corresponds to the function name field
 *     Google Tag Manager web interface.
 */
mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() {

  /**
   * This method will be called when any custom tag's rule(s) evaluates to true.
   * The code should check the functionName and process accordingly.
   *
   * @param functionName The functionName passed to the functionCallTagHandler.
   * @param parameters An optional map of parameters as defined in the Google
   *     Tag Manager web interface.
   */
  @Override
  public void execute(String functionName, Map<String, Object> parameters) {
    if (functionName.equals("myConfiguredFunctionName")) {
      // Process accordingly.
    }
  }
});

Benutzerdefinierten Aktualisierungszeitraum festlegen

Das Google Tag Manager SDK versucht, einen neuen Container abzurufen, wenn der aktuelle Container älter als 12 Stunden ist. Wenn Sie einen benutzerdefinierten Aktualisierungszeitraum für den Container festlegen möchten, verwenden Sie Timer, wie im folgenden Beispiel:

timer.scheduleTask(new TimerTask() {
  @Override
  public void run() {
    mContainer.refresh();
  }
}, delay, <new_period_in milliseconds>);

Fehlerbehebung mit Logger

Das Google Tag Manager SDK gibt standardmäßig Fehler und Warnungen in Logs aus. Eine ausführlichere Protokollierung kann bei der Fehlerbehebung hilfreich sein. Sie können sie aktivieren, indem Sie einen eigenen Logger mit TagManager.setLogger implementieren, wie in diesem Beispiel:

TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {

  final String TAG = "myGtmLogger";

  // Log output with verbosity level of DEBUG.
  @Override
  public void d(String arg0) {
    Log.d(TAG, arg0);
  }

  // Log exceptions when provided.
  @Override
  public void d(String arg0, Throwable arg1) {
    Log.d(TAG, arg0);
    arg1.printStackTrace();
  }

  // Rest of the unimplemented Logger methods.

});

Alternativ können Sie die Logebene des vorhandenen Loggers mit TagManager.getLogger().setLogLevel(LogLevel) festlegen, wie in diesem Beispiel:

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
TagManager tagManager = TagManager.getInstance(this);
tagManager.getLogger().setLogLevel(LogLevel.INFO);