Android 3. (starsza wersja) – omówienie

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ć:

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:

  1. Dodawanie pakietu SDK Menedżera tagów Google do projektu
  2. Ustawianie domyślnych wartości kontenera
  3. Otwieranie kontenera
  4. Pobieranie wartości konfiguracji z kontenera
  5. Przekazywanie zdarzeń do warstwy danych
  6. 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:

  1. Zaloguj się w interfejsie internetowym Menedżera tagów Google.
  2. Wybierz wersję kontenera, którą chcesz pobrać.
  3. Kliknij przycisk Pobierz, aby pobrać plik binarny kontenera.
  4. 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.

Adresy URL podglądu są dostępne w oknie podglądu w interfejsie internetowym Menedżera tagów.
Rysunek 1. Pobieranie adresu URL podglądu z interfejsu internetowego Menedżera tagów

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:

Reguła służy do wybierania ciągów znaków do wyświetlenia na podstawie języka urządzenia w czasie działania: język to es. Ta reguła używa wstępnie zdefiniowanego makra języka i dwuznakowego kodu języka ISO 639-1.
Ilustracja 1. Dodawanie reguły, która włącza makro zbierania wartości tylko na urządzeniach skonfigurowanych do używania języka hiszpańskiego.

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:

  1. Zdefiniuj makro wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie skonfigurować jako pary klucz-wartość.
  2. Zarejestruj FunctionCallMacroHandler w aplikacji, używając Container.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:

  1. Zdefiniuj tag wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie skonfigurować jako pary klucz-wartość.
  2. 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);