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ä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. Dazu gehören:
- Verschiedene UI-Einstellungen und Anzeigestrings
- Größen, Standorte oder Anzeigentypen, die in Ihrer App ausgeliefert werden
- Spieleinstellungen
Konfigurationswerte können auch zur Laufzeit mithilfe von Regeln ausgewertet werden, um dynamische Konfigurationen wie die folgenden zu aktivieren:
- 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. In Tag Manager werden derzeit die folgenden Tags unterstützt:
- Google Analytics für mobile Apps
- Aufruf-Tag für benutzerdefinierte Funktionen
Vorbereitung
Um diesen Startleitfaden verwenden zu können, benötigen Sie Folgendes:
- Ein Google Tag Manager-Konto
- Neues Tag Manager-Makro für Container und Werterfassung
- Eine mobile App für Android zur Implementierung von Google Tag Manager
- Das Google Analytics Services SDK, das die Tag Manager-Bibliothek enthält.
Wenn Sie Google Tag Manager zum ersten Mal verwenden, sollten Sie sich in der Hilfe über Container, Makros und Regeln informieren, bevor Sie mit dieser Anleitung fortfahren.
Erste Schritte
In diesem Abschnitt werden Entwickler durch einen typischen Tag Manager-Workflow geführt:
- Einem Projekt das Google Tag Manager SDK hinzufügen
- Standardwerte für Container festlegen
- Container öffnen
- Konfigurationswerte aus dem Container abrufen
- Ereignisse in die DataLayer übertragen
- Container als Vorschau ansehen und veröffentlichen
1. Ihrem Projekt das Google Tag Manager SDK hinzufügen
Bevor Sie das Google Tag Manager SDK verwenden können, müssen Sie das SDK-Paket entpacken, die Bibliothek dem Build-Pfad Ihres Projekts hinzufügen und der Datei AndroidManifest.xml Berechtigungen hinzufügen.
Fügen Sie zuerst die Google Tag Manager-Bibliothek zum Ordner /libs Ihres Projekts hinzu.
Aktualisieren Sie als Nächstes Ihre AndroidManifest.xml-Datei, 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 bei der ersten Ausführung Ihrer Anwendung einen Standardcontainer. Der Standardcontainer wird so lange verwendet, bis die Anwendung einen neuen Container über das Netzwerk abrufen kann.
So laden Sie eine Standardbinärdatei für Container herunter und fügen sie zu Ihrer Anwendung hinzu:
- Melden Sie sich auf der Weboberfläche von Google Tag Manager an.
- Wählen Sie die Version des Containers aus, den Sie herunterladen möchten.
- Klicken Sie auf die Schaltfläche Herunterladen, um die Containerbinä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). Entfernen Sie nach dem Herunterladen der Binärdatei das Versionssuffix aus dem Dateinamen, damit die korrekte Namenskonvention eingehalten wird.
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.
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 /assets/tagmanager/GTM-1234.json die Standardcontainerwerte hinzufügen.
3. Container öffnen
Bevor Werte aus einem Container abgerufen werden können, muss die Anwendung den Container öffnen. Wenn Sie einen Container öffnen, wird er vom Laufwerk geladen (falls verfügbar) oder er wird beim Netzwerk angefordert (falls erforderlich).
Am einfachsten lassen sich Container unter Android mithilfe von ContainerOpener.openContainer(..., Notifier notifier) wie im folgenden Beispiel öffnen:
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 Zuweisung von mContainer im containerAvailable-Callback wird sichergestellt, dass der Hauptthread nicht blockiert wird. Wenn der gespeicherte Container älter als 12 Stunden ist, wird durch den Aufruf auch eine Anfrage geplant, um asynchron einen neuen Container über das Netzwerk abzurufen.
Diese Beispielimplementierung stellt die einfachste Möglichkeit dar, mit der Convenience-Klasse ContainerOpener Werte aus einem Container zu öffnen und abzurufen.
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");
Bei Anfragen mit einem nicht vorhandenen Schlüssel wird ein Standardwert zurückgegeben, 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 in die DataLayer übertragen
Ein DataLayer ist eine Karte, mit der Laufzeitinformationen zu Ihrer App, z. B. Touchereignisse oder Bildschirmaufrufe, für Tag Manager-Makros und -Tags in einem Container verfügbar sind.
Wenn Sie beispielsweise Informationen zu Bildschirmaufrufen in die DataLayer-Karte übertragen, können Sie Tags in der Tag Manager-Weboberfläche einrichten, um als Reaktion auf diese Bildschirmaufrufe Conversion-Pixel auszulösen und Aufrufe zu erfassen, ohne sie in Ihrer App hart codieren zu müssen.
Ereignisse werden mit push() und der Hilfsmethode DataLayer.mapOf() an die DataLayer ü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 (wie Google Analytics-Tags) erstellen, die für jeden Bildschirmaufruf 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. Dazu erstellen Sie eine Regel, bei der gleich "openScreen" && ist gleich "ConfirmationScreen" ist.
6. Container in der Vorschau ansehen und veröffentlichen
Makrowerte entsprechen immer der aktuell veröffentlichten Version. Bevor Sie die neueste Version eines Containers veröffentlichen, können Sie sich eine Vorschau des Containerentwurfs ansehen.
Wenn Sie sich einen Container als Vorschau ansehen möchten, können Sie auf der Weboberfläche von Google Tag Manager eine Vorschau-URL erstellen. Wählen Sie dazu die gewünschte Containerversion und dann Preview aus. Behalten Sie diese Vorschau-URL bei, da Sie sie in späteren Schritten benötigen.
Fügen Sie als Nächstes die folgende Activity 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 anzusehen.
Wenn Sie bereit sind, die Entwurfskonfigurationswerte für Ihre Anwendung verfügbar zu machen, veröffentlichen Sie den Container.
Erweiterte Konfiguration
Google Tag Manager für Mobilgeräte bietet eine Reihe erweiterter Konfigurationsoptionen, mit denen Sie Werte anhand von 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 unterste und flexibelste API zum Öffnen eines Containers. Es wird sofort mit einem Standardcontainer zurückgegeben und ein Container auch asynchron vom Laufwerk oder aus dem Netzwerk geladen, wenn kein gespeicherter Container vorhanden ist oder der gespeicherte Container nicht aktuell ist (mehr als 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 gesamten Ladevorgangs gibt TagManager.openContainer() mehrere Lebenszyklus-Callbacks aus, damit Ihr Code herausfinden kann, wann die Ladeanfrage beginnt, ob und warum sie fehlschlägt oder erfolgreich ist und ob der Container letztendlich vom Laufwerk oder Netzwerk geladen wurde.
Sofern Ihre Anwendung die Standardwerte nicht verwenden kann, 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 Anwendung 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
|
Mit der Aktualisierungsanfrage wird ein lokal gespeicherter Container geladen. |
Container.Callback.NETWORK
|
Mit 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
|
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 nicht standardmäßiger und aktueller Container
ContainerOpener umschließt TagManager.openContainer() und bietet zwei praktische Methoden zum Öffnen von Containern: ContainerOpener.openContainer(..., Notifier notifier) und ContainerOpener.openContainer(..., Long timeoutInMillis).
Bei jeder dieser Methoden wird eine Aufzählung verwendet, um entweder einen nicht standardmäßigen oder einen neuen Container anzufordern.
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 vom Netzwerk, auch wenn dieser Container älter als 12 Stunden ist. Wenn ein veralteter gespeicherter Container zurückgegeben wird, wird ebenfalls eine asynchrone Netzwerkanfrage für einen neuen gesendet.
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 einem Laufwerk oder 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 Orten 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 Methoden sind nicht blockierend.
ContainerOpener.openContainer(..., Long timeoutInMillis) gibt ein ContainerOpener.ContainerFuture-Objekt zurück, dessen get-Methode ein Container zurückgibt, sobald es geladen wurde (aber das blockiert bis dahin).
Die Methode ContainerOpener.openContainer(..., Notifier notifier) verwendet einen einzelnen Callback, der aufgerufen wird, wenn der Container verfügbar ist. Damit lässt sich verhindern, dass der Hauptthread blockiert wird.
Beide Methoden haben standardmäßig ein Zeitlimit von 2000 Millisekunden.
Makros zur Laufzeit mithilfe von Regeln bewerten
Container können Werte zur Laufzeit mithilfe von Regeln auswerten. Regeln können auf Kriterien wie Gerätesprache, Plattform oder einem anderen Makrowert basieren. Regeln können beispielsweise verwendet werden, um einen lokalisierten Anzeigestring basierend auf der Sprache des Geräts zur Laufzeit auszuwählen. Dies kann mit der folgenden Regel konfiguriert werden:
Sie können dann Makros zur Werterfassung für jede Sprache erstellen und diese Regel jedem Makro hinzufügen, indem Sie den entsprechenden Sprachcode einfügen. Wenn dieser Container veröffentlicht wird, kann Ihre Anwendung je nach der Sprache des Nutzergeräts zur Laufzeit lokalisierte Anzeigestrings anzeigen.
Wenn für Ihren Standardcontainer Regeln erforderlich sind, müssen Sie eine binäre Containerdatei als Standardcontainer verwenden.
Weitere Informationen zum Konfigurieren von Regeln (Analytics-Hilfe).
Binäre Standard-Containerdateien
Standardcontainer, für die Regeln erforderlich sind, sollten anstelle einer JSON-Datei eine binäre Containerdatei als Standardcontainer verwenden. Binäre Container bieten Unterstützung zum Ermitteln von Makrowerten zur Laufzeit mit Google Tag Manager-Regeln, im Gegensatz zu JSON-Dateien.
Binär-Containerdateien können über die Weboberfläche von Google Tag Manager heruntergeladen werden. Fügen Sie sie dem Ordner /assets/tagmanager/ Ihres Projekts hinzu. Folgen Sie dem Muster /assets/tagmanager/GTM-XXXX, wobei der Dateiname die Container-ID darstellt.
In Fällen, in denen sowohl eine JSON-Datei als auch eine binäre Containerdatei vorhanden ist, 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 gesetzt werden. Funktionsaufruf-Makros können verwendet werden, um Laufzeitwerte in Ihre Google Tag Manager-Regeln zu integrieren. So lässt sich beispielsweise anhand der konfigurierten Sprache und Währung eines Geräts ermitteln, welcher Preis einem Nutzer zur Laufzeit angezeigt werden soll.
So konfigurieren Sie ein Funktionsaufrufmakro:
- Definieren Sie das Funktionsaufruf-Makro auf der Weboberfläche des Google Tag Managers. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
- Registrieren Sie ein
FunctionCallMacroHandlerin Ihrer Anwendung mitContainer.registerFunctionCallMacroHandler()und dem Funktionsnamen, den Sie in der Weboberfläche von Google Tag Manager konfiguriert haben. Dabei wird die zugehörige MethodegetValue()überschrieben:/** * 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 vorregistrierte Funktionen ausgeführt werden, wenn ein Ereignis in die Datenschicht übertragen wird und die Tag-Regeln true ergeben.
So konfigurieren Sie ein Funktionsaufruf-Tag:
- Definieren Sie das Funktionsaufruf-Tag auf der Google Tag Manager-Weboberfläche. Argumente können optional als Schlüssel/Wert-Paare konfiguriert werden.
- Registrieren Sie mit
Container.registerFunctionCallTagHandler()einen Tag-Handler für Funktionsaufrufe in Ihrer Anwendung:/** * 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 das aktuelle Containeralter 12 Stunden überschreitet. Verwenden Sie Timer wie im folgenden Beispiel, um einen benutzerdefinierten Aktualisierungszeitraum für Container festzulegen:
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 und ist möglich, wenn Sie wie in diesem Beispiel mit TagManager.setLogger einen eigenen Logger implementieren:
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 mithilfe von TagManager.getLogger().setLogLevel(LogLevel) wie in diesem Beispiel festlegen:
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);