In diesem Entwicklerleitfaden wird beschrieben, wie Sie Google Tag Manager in einer mobilen App implementieren.
Einführung
Mit Google Tag Manager können Entwickler Konfigurationswerte in ihren mobilen Apps über die Google Tag Manager-Oberfläche ändern, ohne die Binärdateien der App neu erstellen und noch einmal an App-Marktplätze senden zu müssen.
Dies ist nützlich, um 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, Positionen oder Typen von Anzeigen, die in Ihrer App ausgeliefert werden
- 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. TagManager unterstützt die folgenden Tags:
- Google Mobile App Analytics
- Tag für benutzerdefinierten Funktionsaufruf
Vorbereitung
Bevor Sie diesen Startleitfaden verwenden, benötigen Sie Folgendes:
- Ein Google Tag Manager-Konto
- Ein neuer Tag Manager-Container und ein Makro zur Werterfassung
- Eine mobile Android-Anwendung, in der Google Tag Manager implementiert werden soll
- Das Google Analytics Services SDK, das die Tag Manager-Bibliothek enthält.
Wenn Sie Google Tag Manager noch nicht kennen, sollten Sie sich in der Hilfe über Container, Makros und Regeln informieren, bevor Sie mit diesem Leitfaden fortfahren.
Erste Schritte
In diesem Abschnitt wird ein typischer Tag Manager-Workflow für Entwickler beschrieben:
- Google Tag Manager SDK zu Ihrem Projekt hinzufügen
- Standard-Containerwerte festlegen
- Container öffnen
- Konfigurationswerte aus dem Container abrufen
- Ereignisse an die Datenschicht übertragen
- Vorschau des Containers ansehen und Container 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 dem Build-Pfad Ihres Projekts hinzufügen und Berechtigungen in der Datei AndroidManifest.xml festlegen.
Fügen Sie zuerst die Google Tag Manager-Bibliothek dem Ordner /libs Ihres Projekts hinzu.
Aktualisieren Sie als Nächstes 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. Ihrem Projekt eine Standard-Containerdatei hinzufügen
Google Tag Manager verwendet beim ersten Ausführen Ihrer Anwendung einen Standardcontainer. Der Standardcontainer wird verwendet, bis die App einen neuen Container über das Netzwerk abrufen kann.
So laden Sie eine Standard-Container-Binärdatei herunter und fügen sie Ihrer Anwendung hinzu:
- Melden Sie sich in der Google Tag Manager-Weboberfläche an.
- Wählen Sie die Version des Containers aus, die Sie herunterladen möchten.
- Klicken Sie auf den Button Herunterladen, um die Container-Binärdatei abzurufen.
- 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, müssen Sie das Versionssuffix aus dem Dateinamen entfernen, um die richtige Namenskonvention einzuhalten.
Die Verwendung der Binärdatei wird empfohlen. Wenn Ihr Container jedoch keine Regeln oder Tags enthält, können Sie stattdessen eine JSON-Datei verwenden. Die Datei muss sich in einem neuen /assets/tagmanager-Ordner Ihres Android-Projekts befinden und der folgenden Namenskonvention entsprechen: <Container_ID>.json. Wenn Ihre Container-ID beispielsweise GTM-1234 lautet, sollten Sie die Standardcontainerwerte zu /assets/tagmanager/GTM-1234.json hinzufügen.
3. Container öffnen
Bevor Ihre Anwendung Werte aus einem Container abrufen kann, muss sie den Container öffnen. Wenn Sie einen Container öffnen, wird er vom Laufwerk geladen (falls verfügbar) oder bei Bedarf über das Netzwerk angefordert.
Am einfachsten lässt sich ein Container unter Android mit ContainerOpener.openContainer(..., Notifier notifier) öffnen, wie im folgenden Beispiel gezeigt:
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. Wenn die Zuweisung von mContainer im containerAvailable-Callback erfolgt, wird der Hauptthread nicht blockiert. Wenn der gespeicherte Container älter als 12 Stunden ist, wird durch den Aufruf auch eine Anfrage zum asynchronen Abrufen eines neuen Containers über das Netzwerk geplant.
Diese Beispielimplementierung ist die einfachste Möglichkeit, einen Container mit der Convenience-Klasse ContainerOpener zu öffnen und Werte daraus 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 übergeben
Die Datenschicht ist eine Zuordnung, mit der Laufzeitinformationen zu Ihrer App, z. B. Touch-Events oder Bildschirmaufrufe, für Tag Manager-Makros und -Tags in einem Container verfügbar gemacht werden.
Wenn Sie beispielsweise Informationen zu Bildschirmaufrufen in die DataLayer-Zuordnung übertragen, können Sie in der Tag Manager-Weboberfläche Tags einrichten, um Conversion-Pixel und Tracking-Aufrufe als Reaktion auf diese Bildschirmaufrufe auszulösen, ohne sie in Ihrer App hartcodieren zu müssen.
Ereignisse werden mit push() und der Hilfsmethode DataLayer.mapOf() 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 jede Bildschirmansicht ausgelöst werden, indem Sie die folgende Regel erstellen: ist gleich „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 Bildschirmaufrufe ausgelöst wird. Erstellen Sie dazu eine Regel, bei der gleich „openScreen“ und gleich „ConfirmationScreen“ ist.
6. Vorschau und Veröffentlichung eines Containers
Makrowerte entsprechen immer der aktuellen veröffentlichten Version. Bevor Sie die aktuelle Version eines Containers veröffentlichen, können Sie sich eine Vorschau des 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, für die Sie eine Vorschau anzeigen möchten, und wählen Sie dann Preview aus. Speichern Sie diese Vorschau-URL, da Sie sie in späteren Schritten benötigen.
Fügen Sie als Nächstes die folgende Aktivität in die Datei AndroidManifest.xml Ihrer Anwendung ein:
<!-- 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 eine Vorschau des Containerentwurfs in Ihrer App zu sehen.
Wenn Sie die Konfigurationswerte im Entwurf für Ihre Anwendung verfügbar machen möchten, veröffentlichen Sie den Container.
Erweiterte Konfiguration
Google Tag Manager für Mobilgeräte 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 gängigsten erweiterten Konfigurationen beschrieben.
Erweiterte Optionen zum Öffnen von Containern
Das Google Tag Manager SDK bietet mehrere Methoden zum Öffnen von Containern, mit denen Sie den Ladevorgang besser steuern können:
TagManager.openContainer()
TagManager.openContainer() ist die niedrigste und flexibelste API zum Öffnen eines Containers. Es wird sofort ein Standardcontainer zurückgegeben. Außerdem wird ein Container asynchron vom Laufwerk oder aus dem Netzwerk geladen, wenn kein gespeicherter Container vorhanden ist oder wenn der gespeicherte Container nicht aktuell ist (> 12 Stunden alt).
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 Lebenszyklus-Callbacks aus, damit Ihr Code erkennen kann, wann die Ladeanfrage beginnt, ob und warum sie fehlschlägt oder erfolgreich ist und ob der Container letztendlich vom Laufwerk oder aus dem Netzwerk geladen wurde.
Wenn es für Ihre Anwendung nicht akzeptabel ist, die Standardwerte zu verwenden, müssen Sie diese Callbacks verwenden, um zu erfahren, wann ein gespeicherter oder Netzwerkcontainer geladen wurde. Beachten Sie, dass Sie einen gespeicherten oder Netzwerkcontainer nicht laden können, wenn die App zum ersten Mal ausgeführt wird und keine Netzwerkverbindung besteht.
TagManager.openContainer() übergibt die folgenden enum-Werte als Argumente an diese Callbacks:
RefreshType
| Wert | Beschreibung |
|---|---|
Container.Callback.SAVED
|
Bei der Aktualisierungsanfrage wird ein lokal gespeicherter Container geladen. |
Container.Callback.NETWORK
|
Bei der Aktualisierungsanfrage wird ein Container über das Netzwerk geladen. |
RefreshFailure
| Wert | Beschreibung |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
Es ist kein gespeicherter Container verfügbar. |
Container.Callback.IO_ERROR
|
Der Container konnte aufgrund eines E/A-Fehlers nicht aktualisiert werden. |
Container.Callback.NO_NETWORK
|
Es ist keine Netzwerkverbindung verfügbar. |
Container.Callback.NETWORK_ERROR
|
Es ist ein Netzwerkfehler aufgetreten. |
Container.Callback.SERVER_ERROR
|
Auf dem Server ist ein Fehler aufgetreten. |
Container.Callback.UNKNOWN_ERROR
|
Es ist ein Fehler aufgetreten, der nicht kategorisiert werden kann. |
Methoden zum Öffnen von nicht standardmäßigen und neuen Containern
ContainerOpener umschließt TagManager.openContainer() und bietet zwei praktische Methoden zum Öffnen von Containern: ContainerOpener.openContainer(..., Notifier notifier) und ContainerOpener.openContainer(..., Long timeoutInMillis).
Jede dieser Methoden verwendet eine Aufzählung, die entweder einen nicht standardmäßigen oder einen neuen Container anfordert.
OpenType.PREFER_NON_DEFAULT wird für die meisten Anwendungen empfohlen und versucht, den ersten verfügbaren nicht standardmäßigen Container innerhalb eines bestimmten Zeitlimits zurückzugeben, entweder vom Laufwerk oder aus dem Netzwerk, 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.
Wenn Sie OpenType.PREFER_NON_DEFAULT verwenden, wird ein Standardcontainer zurückgegeben, wenn kein anderer Container verfügbar ist oder wenn die Zeitüberschreitung erreicht ist.
OpenType.PREFER_FRESH versucht, innerhalb des angegebenen Zeitlimits einen neuen Container entweder vom Laufwerk 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 merklich beeinträchtigen kann, z. B. bei UI-Flags oder Anzeigestrings. Sie können auch jederzeit Container.refresh() verwenden, um eine Netzwerkcontaineranfrage zu erzwingen.
Beide Komfortmethoden sind nicht blockierend.
ContainerOpener.openContainer(..., Long timeoutInMillis) gibt ein ContainerOpener.ContainerFuture-Objekt zurück, dessen get-Methode ein Container-Objekt zurückgibt, sobald es geladen wurde. Bis dahin wird der Ablauf blockiert.
Die Methode ContainerOpener.openContainer(..., Notifier notifier) verwendet einen einzelnen Callback, der aufgerufen wird, wenn der Container verfügbar ist. Dadurch kann verhindert werden, dass der Haupt-Thread blockiert wird.
Beide Methoden haben eine Standardzeitüberschreitung von 2000 Millisekunden.
Makros zur Laufzeit mithilfe von Regeln auswerten
In Containern können Werte zur Laufzeit mithilfe von Regeln ausgewertet werden. Regeln können auf Kriterien wie Gerätesprache, Plattform oder anderen Makrowerten basieren. Beispielsweise können Regeln verwendet werden, um zur Laufzeit einen lokalisierten Anzeigestring basierend auf der Sprache des Geräts auszuwählen. Dies kann mit der folgenden Regel konfiguriert werden:
Anschließend können Sie für jede Sprache ein Makro zur Werterfassung erstellen und diese Regel jedem Makro hinzufügen, wobei Sie den entsprechenden Sprachcode einfügen. Wenn dieser Container veröffentlicht wird, kann Ihre Anwendung lokalisierte Anzeigestrings anzeigen, je nach Sprache des Geräts des Nutzers zur Laufzeit.
Wenn Ihr Standardcontainer Regeln benötigt, müssen Sie eine binäre Containerdatei als Standardcontainer verwenden.
Weitere Informationen zum Konfigurieren von Regeln (Hilfe)
Binäre Standard-Containerdateien
Für Standardcontainer, die Regeln erfordern, sollte anstelle einer JSON-Datei eine binäre Containerdatei als Standardcontainer verwendet werden. Binäre Container unterstützen die Bestimmung von Makrowerten zur Laufzeit mit Google Tag Manager-Regeln, JSON-Dateien dagegen nicht.
Binäre Containerdateien können über die Google Tag Manager-Weboberfläche heruntergeladen werden. Sie sollten dem Ordner /assets/tagmanager/ Ihres Projekts hinzugefügt werden und dem folgenden Muster entsprechen: /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. Mit Funktionsaufruf-Makros können Sie Laufzeitwerte in Ihre Google Tag Manager-Regeln einbinden, 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:
- Definieren Sie das Funktionsaufruf-Makro in der Google Tag Manager-Weboberfläche. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
- Registrieren Sie in Ihrer Anwendung einen
FunctionCallMacroHandlermitContainer.registerFunctionCallMacroHandler()und dem Funktionsnamen, den Sie in der Google Tag Manager-Weboberfläche konfiguriert haben. Überschreiben Sie dabei die MethodegetValue():/** * 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 als true ausgewertet werden.
So konfigurieren Sie ein Tag für Funktionsaufrufe:
- Definieren Sie das Funktionsaufruf-Tag in der Google Tag Manager-Weboberfläche. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
- Registrieren Sie in Ihrer Anwendung einen Tag-Handler für Funktionsaufrufe 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 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>);
Debugging mit Logger
Das Google Tag Manager SDK gibt standardmäßig Fehler und Warnungen in Logs aus.
Das Aktivieren eines ausführlicheren Loggings kann für die Fehlerbehebung hilfreich sein. Sie können dazu 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 den LogLevel 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);