Ten przewodnik dla programistów opisuje, jak wdrożyć Menedżera tagów Google w aplikacji mobilnej.
Wprowadzenie
Menedżer tagów Google umożliwia deweloperom zmianę wartości konfiguracji w aplikacjach mobilnych za pomocą interfejsu Menedżera tagów Google bez konieczności ponownego kompilowania i przesyłania plików binarnych aplikacji na platformy handlowe.
Jest to przydatne do zarządzania wartościami konfiguracji lub flagami w aplikacji, które mogą wymagać zmiany w przyszłości, takimi jak:
- Różne ustawienia interfejsu i ciągi znaków wyświetlania
- rozmiary, lokalizacje lub typy reklam wyświetlanych w aplikacji;
- Ustawienia gier
Wartości konfiguracji mogą być też oceniane w czasie działania za pomocą reguł, co umożliwia dynamiczne konfiguracje, takie jak:
- Używanie rozmiaru ekranu do określania rozmiaru banera reklamowego
- Używanie języka i lokalizacji do konfigurowania elementów interfejsu
Menedżer tagów Google umożliwia też dynamiczne wdrażanie tagów śledzenia i pikseli w aplikacjach. Deweloperzy mogą przekazywać ważne zdarzenia do warstwy danych i później decydować, które tagi śledzenia lub piksele mają być uruchamiane. Menedżer tagów obsługuje te tagi:
- Google Mobile App Analytics
- Tag niestandardowego wywołania funkcji
Zanim zaczniesz
Zanim skorzystasz z tego przewodnika dla początkujących, musisz mieć:
- konto Menedżera tagów Google,
- Nowy kontener Menedżera tagów i makro zbierania wartości
- aplikację mobilną na Androida, w której chcesz wdrożyć Menedżera tagów Google;
- Pakiet SDK usług Google Analytics, który zawiera bibliotekę Menedżera tagów.
Jeśli dopiero zaczynasz korzystać z Menedżera tagów Google, zanim przejdziesz do dalszej części tego przewodnika, dowiedz się więcej o kontenerach, makrach i regułach (Centrum pomocy).
Pierwsze kroki
W tej sekcji dowiesz się, jak wygląda typowy przepływ pracy w Menedżerze tagów:
- Dodawanie pakietu SDK Menedżera tagów Google do projektu
- Ustawianie domyślnych wartości kontenera
- Otwieranie kontenera
- Pobieranie wartości konfiguracji z kontenera
- Przekazywanie zdarzeń do warstwy danych
- Wyświetlanie podglądu i publikowanie kontenera
1. Dodawanie pakietu SDK Menedżera tagów Google do projektu
Zanim zaczniesz korzystać z pakietu SDK Menedżera tagów Google, musisz wyodrębnić pakiet SDK i dodać bibliotekę do ścieżki kompilacji projektu oraz dodać uprawnienia do pliku AndroidManifest.xml.
Najpierw dodaj bibliotekę Menedżera tagów Google do folderu /libs projektu.
Następnie zaktualizuj plik AndroidManifest.xml, aby używać tych uprawnień:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
2. Dodawanie domyślnego pliku kontenera do projektu
Menedżer tagów Google używa domyślnego kontenera przy pierwszym uruchomieniu aplikacji. Domyślny kontener będzie używany, dopóki aplikacja nie będzie mogła pobrać nowego kontenera przez sieć.
Aby pobrać i dodać do aplikacji domyślny plik binarny kontenera, wykonaj te czynności:
- Zaloguj się w interfejsie internetowym Menedżera tagów Google.
- Wybierz wersję kontenera, którą chcesz pobrać.
- Kliknij przycisk Pobierz, aby pobrać plik binarny kontenera.
- Dodaj plik binarny do tej ścieżki:
<project-root>/assets/tagmanager/
Domyślna nazwa pliku powinna być identyfikatorem kontenera (np. GTM-1234). Po pobraniu pliku binarnego usuń z jego nazwy sufiks wersji, aby zachować prawidłową konwencję nazewnictwa.
Zalecamy używanie pliku binarnego, ale jeśli kontener nie zawiera reguł ani tagów, możesz zamiast niego użyć pliku JSON. Plik musi znajdować się w nowym folderze /assets/tagmanager projektu aplikacji na Androida i być nazwany zgodnie z tą konwencją: <Container_ID>.json. Jeśli na przykład identyfikator kontenera to GTM-1234, domyślne wartości kontenera należy dodać do pliku /assets/tagmanager/GTM-1234.json.
3. Otwieranie kontenera
Zanim aplikacja będzie mogła pobrać wartości z kontenera, musi go otworzyć. Otwarcie kontenera spowoduje wczytanie go z dysku (jeśli jest dostępny) lub zażądanie go z sieci (jeśli jest to konieczne).
Najprostszym sposobem otwarcia kontenera na Androidzie jest użycie ContainerOpener.openContainer(..., Notifier notifier), jak w tym przykładzie:
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. } }
W tym przykładzie ContainerOpener.openContainer(..., Notifier notifier) służy do żądania zapisanego kontenera z pamięci lokalnej. Dzięki obsłudze przypisania mContainer w wywołaniu zwrotnym containerAvailable mamy pewność, że wątek główny nie jest zablokowany. Jeśli zapisany kontener jest starszy niż 12 godzin, wywołanie zaplanuje też żądanie asynchronicznego pobrania nowego kontenera przez sieć.
Ta przykładowa implementacja przedstawia najprostszy sposób otwierania kontenera i pobierania z niego wartości za pomocą klasy pomocniczej ContainerOpener.
Więcej informacji o zaawansowanych opcjach implementacji znajdziesz w artykule Konfiguracja zaawansowana.
4. Pobieranie wartości konfiguracji z kontenera
Po otwarciu kontenera wartości konfiguracji można pobrać za pomocą metod get<type>Value():
// Retrieving a configuration value from a Tag Manager Container. // Get the configuration value by key. String title = mContainer.getStringValue("title_string");
Żądania wysłane z nieistniejącym kluczem zwracają wartość domyślną odpowiednią dla żądanego typu:
// 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. Przekazywanie wartości do warstwy danych
DataLayer to mapa, która umożliwia udostępnianie makrom i tagom Menedżera tagów w kontenerze informacji o aplikacji w czasie działania, takich jak zdarzenia dotknięcia czy wyświetlenia ekranu.
Jeśli na przykład prześlesz informacje o wyświetleniach ekranu do mapy DataLayer, możesz skonfigurować tagi w interfejsie internetowym Menedżera tagów, aby uruchamiać piksele śledzenia konwersji i wywołania śledzenia w odpowiedzi na te wyświetlenia ekranu bez konieczności kodowania ich na stałe w aplikacji.
Zdarzenia są przekazywane do warstwy danych za pomocą metody pomocniczej push() i DataLayer.mapOf():
// // 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 }
W interfejsie internetowym możesz teraz tworzyć tagi (np. tagi Google Analytics), które będą się uruchamiać przy każdym wyświetleniu ekranu, przez utworzenie tej reguły: równa się „openScreen”. Aby przekazać nazwę ekranu do jednego z tych tagów, utwórz makro warstwy danych, które odwołuje się do klucza „screenName” w warstwie danych. Możesz też utworzyć tag (np. piksel konwersji Google Ads), który będzie się uruchamiał tylko w przypadku określonych wyświetleń ekranu. W tym celu utwórz regułę, w której równa się „openScreen” i równa się „ConfirmationScreen”.
6. Wyświetlanie podglądu i publikowanie kontenera
Wartości makr zawsze odpowiadają aktualnie opublikowanej wersji. Przed opublikowaniem najnowszej wersji kontenera możesz wyświetlić podgląd jego wersji roboczej.
Aby wyświetlić podgląd kontenera, wygeneruj URL podglądu w interfejsie internetowym Menedżera tagów Google, wybierając wersję kontenera, której podgląd chcesz wyświetlić, a następnie klikając Preview. Zapisz ten URL podglądu, ponieważ będzie Ci potrzebny w późniejszych krokach.
Następnie dodaj do pliku AndroidManifest.xml aplikacji tę aktywność:
<!-- 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>
Otwórz link w emulatorze lub na urządzeniu fizycznym, aby wyświetlić podgląd wersji roboczej kontenera w aplikacji.
Gdy chcesz udostępnić aplikacji wartości konfiguracji wersji roboczej, opublikuj kontener.
Konfiguracja zaawansowana
Menedżer tagów Google na urządzenia mobilne ma wiele zaawansowanych opcji konfiguracji, które umożliwiają wybieranie wartości na podstawie warunków środowiska wykonawczego za pomocą reguł, ręczne odświeżanie kontenera i uzyskiwanie dodatkowych opcji otwierania kontenerów. W poniższych sekcjach opisano kilka najczęstszych konfiguracji zaawansowanych.
Zaawansowane opcje otwierania kontenerów
Pakiet SDK Menedżera tagów Google udostępnia kilka metod otwierania kontenerów, które dają większą kontrolę nad procesem wczytywania:
TagManager.openContainer()
TagManager.openContainer() to najniższy poziom i najbardziej elastyczny interfejs API do otwierania kontenera. Natychmiast zwraca domyślny kontener i asynchronicznie wczytuje kontener z dysku lub sieci, jeśli nie ma zapisanego kontenera lub jeśli zapisany kontener nie jest aktualny (ma więcej niż 12 godzin).
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. }
Podczas procesu wczytywania TagManager.openContainer() wysyła kilka wywołań zwrotnych cyklu życia, dzięki czemu kod może dowiedzieć się, kiedy rozpoczyna się żądanie wczytywania, czy i dlaczego się nie powiodło lub powiodło oraz czy kontener został ostatecznie wczytany z dysku czy z sieci.
Jeśli nie chcesz, aby aplikacja używała wartości domyślnych, musisz użyć tych wywołań zwrotnych, aby wiedzieć, kiedy zapisany lub sieciowy kontener został wczytany. Pamiętaj, że nie możesz wczytać zapisanego kontenera ani kontenera sieciowego, jeśli aplikacja jest uruchamiana po raz pierwszy i nie ma połączenia sieciowego.
TagManager.openContainer() przekazuje te wartości enum jako argumenty do tych wywołań zwrotnych:
RefreshType
| Wartość | Opis |
|---|---|
Container.Callback.SAVED
|
Żądanie odświeżenia wczytuje zapisany lokalnie kontener. |
Container.Callback.NETWORK
|
Żądanie odświeżenia wczytuje kontener przez sieć. |
RefreshFailure
| Wartość | Opis |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
Brak zapisanego kontenera. |
Container.Callback.IO_ERROR
|
Błąd wejścia-wyjścia uniemożliwił odświeżenie kontenera. |
Container.Callback.NO_NETWORK
|
Brak dostępnego połączenia sieciowego. |
Container.Callback.NETWORK_ERROR
|
Wystąpił błąd sieci. |
Container.Callback.SERVER_ERROR
|
Wystąpił błąd serwera. |
Container.Callback.UNKNOWN_ERROR
|
Wystąpił błąd, którego nie można sklasyfikować. |
Metody otwierania kontenerów innych niż domyślne i nowych kontenerów
ContainerOpener opakowuje TagManager.openContainer() i udostępnia 2 wygodne metody otwierania kontenerów: ContainerOpener.openContainer(..., Notifier notifier) i ContainerOpener.openContainer(..., Long timeoutInMillis).
Każda z tych metod przyjmuje wyliczenie, które żąda kontenera innego niż domyślny lub nowego kontenera.
OpenType.PREFER_NON_DEFAULT jest zalecany w przypadku większości aplikacji i próbuje zwrócić pierwszy dostępny kontener inny niż domyślny w określonym czasie oczekiwania, z dysku lub sieci, nawet jeśli ten kontener ma więcej niż 12 godzin. Jeśli zwróci nieaktualny zapisany kontener, wyśle też asynchroniczne żądanie sieciowe o nowy kontener.
Jeśli używasz metody OpenType.PREFER_NON_DEFAULT, zwracany jest domyślny kontener, gdy nie jest dostępny żaden inny kontener lub gdy upłynie limit czasu.
OpenType.PREFER_FRESH próbuje zwrócić nowy kontener z dysku lub sieci w określonym czasie.
Jeśli połączenie sieciowe jest niedostępne lub upłynął limit czasu, zwraca zapisany kontener.
Nie zalecamy używania OpenType.PREFER_FRESH w miejscach, w których dłuższy czas żądania może zauważalnie wpłynąć na wrażenia użytkownika, np. w przypadku flag interfejsu lub ciągów znaków wyświetlania. Możesz też w dowolnym momencie użyć parametru Container.refresh(), aby wymusić żądanie kontenera sieci.
Obie te metody są nieblokujące.
ContainerOpener.openContainer(..., Long timeoutInMillis) zwraca obiekt ContainerOpener.ContainerFuture, którego metoda get zwraca Container, gdy tylko zostanie wczytany (ale do tego czasu będzie blokowany).
Metoda ContainerOpener.openContainer(..., Notifier notifier) przyjmuje pojedyncze wywołanie zwrotne, które jest wywoływane, gdy kontener jest dostępny. Można go użyć, aby zapobiec blokowaniu głównego wątku.
W obu metodach domyślny czas oczekiwania wynosi 2000 milisekund.
Ocena makr w czasie działania za pomocą reguł
Kontenery mogą oceniać wartości w czasie działania za pomocą reguł. Reguły mogą być oparte na kryteriach takich jak język urządzenia, platforma lub dowolna inna wartość makra. Reguły mogą na przykład służyć do wybierania zlokalizowanego ciągu znaków na podstawie języka urządzenia w czasie działania. Można to skonfigurować za pomocą tej reguły:
Następnie możesz utworzyć makra zbierania wartości dla każdego języka i dodać tę regułę do każdego makra, wstawiając odpowiedni kod języka. Po opublikowaniu tego kontenera aplikacja będzie mogła wyświetlać zlokalizowane ciągi znaków w zależności od języka urządzenia użytkownika w czasie działania.
Pamiętaj, że jeśli domyślny kontener wymaga reguł, musisz użyć pliku kontenera binarnego jako kontenera domyślnego.
Więcej informacji o konfigurowaniu reguł (Centrum pomocy)
Pliki domyślnego kontenera binarnego
Domyślne kontenery, które wymagają reguł, powinny używać pliku kontenera binarnego zamiast pliku JSON jako kontenera domyślnego. Kontenery binarne obsługują określanie wartości makr w czasie działania za pomocą reguł Menedżera tagów Google, czego nie można powiedzieć o plikach JSON.
Pliki kontenera binarnego można pobrać z interfejsu internetowego Menedżera tagów Google i dodać do folderu /assets/tagmanager/ projektu zgodnie z tym wzorcem: /assets/tagmanager/GTM-XXXX, gdzie nazwa pliku reprezentuje identyfikator kontenera.
Jeśli obecny jest zarówno plik JSON, jak i plik kontenera binarnego, pakiet SDK użyje pliku kontenera binarnego jako kontenera domyślnego.
Korzystanie z makr wywołania funkcji
Makra wywołania funkcji to makra, które są ustawione na wartość zwracaną przez określoną funkcję w aplikacji. Makra wywołania funkcji mogą służyć do uwzględniania wartości czasu działania w regułach Menedżera tagów Google, np. do określania w czasie działania, jaką cenę wyświetlić użytkownikowi na podstawie skonfigurowanego języka i waluty urządzenia.
Aby skonfigurować makro wywołania funkcji:
- Zdefiniuj makro wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie skonfigurować jako pary klucz-wartość.
- Zarejestruj
FunctionCallMacroHandlerw aplikacji, używającContainer.registerFunctionCallMacroHandler()i nazwy funkcji skonfigurowanej w interfejsie internetowym Menedżera tagów Google, zastępując metodę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; } });
Używanie tagów wywołania funkcji
Tagi wywołania funkcji umożliwiają wykonywanie zarejestrowanych wcześniej funkcji za każdym razem, gdy zdarzenie jest przekazywane do warstwy danych, a reguły tagu mają wartość true.
Aby skonfigurować tag wywołania funkcji:
- Zdefiniuj tag wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie skonfigurować jako pary klucz-wartość.
- Zarejestruj moduł obsługi tagu wywołania funkcji w aplikacji, używając
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. } } });
Ustawianie niestandardowego okresu odświeżania
Pakiet SDK Menedżera tagów Google spróbuje pobrać nowy kontener, jeśli bieżący kontener ma więcej niż 12 godzin. Aby ustawić niestandardowy okres odświeżania kontenera, użyj Timer, jak w tym przykładzie:
timer.scheduleTask(new TimerTask() { @Override public void run() { mContainer.refresh(); } }, delay, <new_period_in milliseconds>);
Debugowanie za pomocą Loggera
Pakiet SDK Menedżera tagów Google domyślnie zapisuje błędy i ostrzeżenia w logach.
Włączenie logowania szczegółowego może być przydatne podczas debugowania. Można to zrobić, implementując własny obiekt Logger za pomocą TagManager.setLogger, jak w tym przykładzie:
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. });
Możesz też ustawić LogLevel istniejącego obiektu Logger, używając TagManager.getLogger().setLogLevel(LogLevel), jak w tym przykładzie:
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);