Android 3. (starsza wersja) – omówienie

W tym przewodniku opisano interfejsy API należące do starszej wersji pakietu SDK. Nowi użytkownicy powinni Wypróbuj najnowszy pakiet SDK.

.

Uwaga: W tym przewodniku opisano starą implementację tagu Google Menedżer w aplikacjach na Androida. Nowi użytkownicy powinni używać narzędzia Menedżer tagów + Firebase do wdrożenia Menedżera tagów Google w ich aplikacjach na iOS.

Z tego przewodnika dla programistów dowiesz się, jak wdrożyć Menedżera tagów Google w aplikacji mobilnej.

Wprowadzenie

Menedżer tagów Google umożliwia programistom zmianę konfiguracji w aplikacjach mobilnych za pomocą Menedżera tagów Google. interfejsu bez konieczności ponownego kompilowania i ponownego przesyłania plików binarnych aplikacji do aplikacji na platformach handlowych.

Przydaje się to do zarządzania wartościami konfiguracyjnymi lub flagi w aplikacji, które być może trzeba będzie zmienić w przyszłości, w tym:

• Różne ustawienia interfejsu i ciągi znaków do wyświetlenia
• Rozmiary, lokalizacje lub typy reklam wyświetlanych w Twojej aplikacji
• Ustawienia gier

Wartości konfiguracji mogą być również oceniane w czasie działania za pomocą reguł, włączenie konfiguracji dynamicznych, takich jak:

• Określanie rozmiaru banera reklamowego na podstawie rozmiaru ekranu
• Używanie języka i lokalizacji do konfigurowania elementów interfejsu

Menedżer tagów Google umożliwia również dynamiczną implementację tagów śledzenia i pikseli w aplikacjach. Deweloperzy mogą umieszczać ważne zdarzenia w danych i zdecydować, które tagi śledzenia lub piksele mają być uruchamiane. Menedżer tagów obsługuje obecnie następujące tagi:

• Google Analytics dla aplikacji mobilnych
• Tag wywołania funkcji niestandardowej

Zanim zaczniesz

Zanim zaczniesz korzystać z tego przewodnika dla początkujących, musisz mieć:

• konto Menedżera tagów Google,
• Nowy Menedżer tagów kontener i makro kolekcji wartości
• Aplikacja mobilna na Androida, w której można wdrożyć Menedżera tagów Google
• Usługi Google Analytics SDK, który zawiera bibliotekę Menedżera tagów.

Jeśli dopiero zaczynasz korzystać z Menedżera tagów Google, zalecamy dowiedz się więcej o kontenerach, makrach i regułach (Centrum pomocy), zanim przejdziesz dalej w tym przewodniku.

Pierwsze kroki

W tej sekcji omawiamy typowy przepływ pracy w Menedżerze tagów:

1. Dodaj do projektu pakiet SDK Menedżera tagów Google
2. Ustaw domyślne wartości kontenerów
3. Otwórz kontener
4. Pobieranie wartości konfiguracyjnych z kontenera
5. Przekazywanie zdarzeń do warstwy danych
6. Podgląd Publikowanie kontenera

1. Dodawanie pakietu SDK Menedżera tagów Google do projektu

Zanim zaczniesz używać pakietu SDK Menedżera tagów Google, musisz go rozpakować i dodaj bibliotekę do ścieżki kompilacji projektu oraz dodaj uprawnienia do pliku AndroidManifest.xml.

Najpierw dodaj bibliotekę Menedżera tagów Google do folderu /libs do swojego projektu.

Następnie zaktualizuj plik AndroidManifest.xml, podając uprawnienia:

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

2. Dodawanie domyślnego pliku kontenera do projektu

Uwaga: jeśli nie masz skonfiguruj kontener w interfejsie internetowym Menedżera tagów Google, Gdy już to zrobisz, wróć do tego kroku.

Menedżer tagów Google używa kontenera domyślnego przy pierwszym uruchomieniu aplikacji. Domyślny kontener będzie używany, dopóki aplikacja nie pobierze nowego kontenera nad

Aby pobrać domyślny plik binarny kontenera i dodać go do swojej aplikacji, wykonaj te czynności:

1. Zaloguj się w interfejsie internetowym Menedżera tagów Google.
2. Wybierz wersję kontenera, który chcesz pobrać.
3. Kliknij przycisk Pobierz, aby pobrać plik binarny kontenera.
4. Dodaj plik binarny do ta ścieżka: <project-root>/assets/tagmanager/

Domyślną nazwą pliku powinien być identyfikator kontenera (np. GTM-1234). Po wykonaniu został pobrany plik binarny, pamiętaj o usunięciu z nazwy pliku sufiksu wersji aby zachować prawidłową konwencję nazewnictwa.

Chociaż zalecamy używanie pliku binarnego, jeśli Twój kontener nie zawiera reguł ani tagów, możesz użyć prostego JSON . Plik musi znajdować się w nowym folderze /assets/tagmanager w Twoim projekcie Androida i powinna być zgodna z tą konwencją nazewnictwa: <Container_ID>.json Jeśli na przykład identyfikator kontenera to GTM-1234, domyślne wartości kontenera należy dodać do /assets/tagmanager/GTM-1234.json

3. Otwieranie kontenera

Przed pobraniem wartości z kontenera musisz otworzyć aplikację kontener. Otwarcie kontenera spowoduje jego wczytanie z dysku (jeśli jest dostępny) lub w razie potrzeby zażąda go od sieci.

Najprostszym sposobem na otwarcie 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) jest używana do: zażądać zapisanego kontenera z pamięci lokalnej. Odpowiadając na przypisanie mContainer w wywołaniu zwrotnym containerAvailable, upewniamy się, że para klucz-wartość wątek główny nie jest zablokowany. Jeśli zapisany kontener jest starszy niż 12 godzin, parametr zaplanuje również żądanie asynchronicznego pobrania nowego kontenera w sieci komórkowej.

Ta przykładowa implementacja to najprostszy sposób otwierania i pobierania z kontenera za pomocą klasy wygodnej ContainerOpener. Bardziej zaawansowane opcje implementacji znajdziesz w sekcji Konfiguracja zaawansowana.

4. Pobieranie wartości konfiguracyjnych z kontenera

Po otwarciu kontenera możesz pobrać wartości konfiguracyjne za pomocą: get<type>Value() metody:

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

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

Żądania wysłane przy użyciu nieistniejącego klucza zwracają odpowiednią wartość domyślną do żą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 włączenie informacji o aplikacji w czasie działania, takich jak dotyk zdarzeń lub wyświetleń ekranu, by były dostępne dla makr i tagów Menedżera tagów kontenera.

Na przykład przesyłając informacje o wyświetleniach ekranu do mapy DataLayer, możesz skonfigurować tagi w interfejsie internetowym Menedżera tagów, by uruchamiać piksele konwersji i śledzić połączenia w odpowiedzi na wyświetlenia ekranu bez konieczności zakodować je w aplikacji.

Zdarzenia są przekazywane do warstwy danych za pomocą metod push() i Metoda pomocnicza 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) uruchamiana przy każdym wyświetleniu ekranu, tworząc tę regułę: równa się "openScreen". Przekazywanie nazwy ekranu do jednego z tych tagów, utwórz makro warstwy danych, które odwołuje się do parametru „screenName” w warstwie danych. Możesz też utworzyć tag (np. piksel konwersji Google Ads), aby uruchamiały się tylko w przypadku określonych wyświetleń ekranu, przez tworzę regułę, w której równa się „openScreen” && równa się "ConfirmationScreen".

Uwaga: klucze i wartości zdarzeń DataLayer powinny być używane w sposób możliwie spójny, tak aby w tym przykładzie wyświetleń ekranu ma ustawienie „openScreen” jako wartość zdarzenia oraz „screenName”, jako klawisz nazwy ekranowej. Dzięki temu dostęp do warstwy danych i tworzenia o jak najprostsze tagi w przyszłości.

6. Podgląd i Publikowanie kontenera

Wartości makr zawsze będą odpowiadały aktualnie opublikowanej wersji. Zanim opublikujesz najnowszą wersję kontenera, możesz wyświetlić jego podgląd kontenera wersji roboczej.

Aby wyświetlić podgląd kontenera, wygeneruj adres URL podglądu w Google Interfejs internetowy Menedżera tagów poprzez wybór wersji kontenera których podgląd chcesz wyświetlić, a następnie wybierz Preview. Zaczekaj adresu URL podglądu, ponieważ będziesz go potrzebować w kolejnych krokach.

Rys. 1. Uzyskiwanie adresu URL podglądu z tagu Interfejs internetowy Menedżera tagów.

Następnie dodaj następujące działanie do sekcji Plik AndroidManifest.xml:

<!-- 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>
  

Uwaga: application_package_name musi odpowiadać nazwie aplikacji użytej do wygenerowania adresu URL podglądu (ilustracja 1).

Otwórz link w emulatorze lub na urządzeniu fizycznym, aby: wyświetl podgląd wersji roboczej kontenera w aplikacji.

Gdy wszystko będzie gotowe do udostępnienia roboczych wartości konfiguracji w aplikacji, i opublikuj kontener.

Konfiguracja zaawansowana

Menedżer tagów Google do aplikacji mobilnych ma wiele zaawansowanych opcji konfiguracji które pozwalają wybierać wartości na podstawie warunków działania za pomocą reguły, ręcznie odświeżyć kontener i wyświetlić dodatkowe opcje kontenery. W dalszej części opisujemy kilka najczęstszych z zaawansowanych funkcji konfiguracji.

Opcje zaawansowane otwierania kontenerów

Pakiet SDK Menedżera tagów Google udostępnia kilka metod otwierania kontenery, 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. Wraca natychmiast z domyślnym kontenerem, asynchronicznie wczytuje kontener z dysku lub sieci, jeśli nie ma zapisanych kontener lub zapisany kontener jest nieaktualny (ma ponad 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.
  }

W trakcie procesu wczytywania TagManager.openContainer() problemów kilka wywołań zwrotnych cyklu życia, tak aby Twój kod mógł określić, kiedy rozpoczyna się żądanie wczytywania, informuje o tym, czy i dlaczego kończy się niepowodzeniem, czy też pomyślnie, a także czy kontener został wczytany z dysku lub sieci.

Jeśli nie możesz używać wartości domyślnych, musisz użyć tych wywołań zwrotnych, aby wiedzieć, kiedy zostały zapisane kontener został wczytany. Pamiętaj, że nie będzie można wczytać zapisanych ani kontenera sieci, jeśli aplikacja jest uruchamiana po raz pierwszy i nie ma i połączenia z siecią.

TagManager.openContainer() przechodzi przez enum jako argumenty w tych wywołaniach zwrotnych:

RefreshType

Wartość	Opis
Container.Callback.SAVED	Żądanie odświeżania wczytuje lokalnie zapisany kontener.
Container.Callback.NETWORK	Żądanie odświeżenia wczytuje kontener przez sieć.

RefreshFailure

Wartość	Opis
Container.Callback.NO_SAVED_CONTAINER	Brak dostępnego 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	Na serwerze wystąpił błąd.
Container.Callback.UNKNOWN_ERROR	Wystąpił błąd, którego nie można sklasyfikować.

Metody otwierania nowych kontenerów niestandardowych lub innych

ContainerOpener obejmuje TagManager.openContainer() i zapewnia dwie wygodne metody otwierania kontenerów: ContainerOpener.openContainer(..., Notifier notifier) i ContainerOpener.openContainer(..., Long timeoutInMillis)

Każda z tych metod wykorzystuje wyliczenie, żądając albo wartości innej niż domyślna, nowego kontenera.

OpenType.PREFER_NON_DEFAULT jest zalecany w większości aplikacji i próbuje zwrócić pierwszy dostępny kontener inny niż domyślny w danym z dysku lub sieci, nawet jeśli ten kontener ma większy limit czasu. starsze niż 12 godzin. Jeśli zwróci on nieaktualny zapisany kontener, spowoduje to również asynchroniczne żądanie sieciowe dla nowego. Jeśli nie ma dostępnego innego kontenera lub przekroczony jest czas oczekiwania, podczas korzystania z parametru OpenType.PREFER_NON_DEFAULT zwrócony zostanie kontener domyślny.

OpenType.PREFER_FRESH próbuje zwrócić nowy kontener z z dysku lub sieci w danym okresie oczekiwania. Zwraca zapisany kontener, jeśli sieć połączenie jest niedostępne lub przekroczono limit czasu oczekiwania.

Nie zalecamy używania atrybutu OpenType.PREFER_FRESH w miejscach, w których dłuższy czas realizacji żądania może znacząco wpłynąć na wrażenia użytkownika, np. flag interfejsu lub ciągów wyświetlania. Możesz też użyć Container.refresh() w dowolnym momencie wymuszanie żądania kontenera sieci.

Obie te wygodne metody nie blokują dostępu. ContainerOpener.openContainer(..., Long timeoutInMillis) zwraca błąd obiekt ContainerOpener.ContainerFuture, którego metoda get zwraca błąd Container zaraz po jej wczytaniu (ale do tego czasu będzie to zablokowane). Metoda ContainerOpener.openContainer(..., Notifier notifier) przyjmuje pojedyncze wywołanie zwrotne, jest wywoływane, gdy kontener jest dostępny, które mogą zapobiec blokowaniu wątku głównego. Dla obu metod domyślny limit czasu wynosi 2000 milisekund.

Ocenianie makr w czasie wykonywania za pomocą reguł

Kontenery mogą oceniać wartości w czasie działania za pomocą reguł. Reguły mogą być oparte na od takich kryteriów jak język urządzenia, platforma czy inne wartości makro. Dla: reguł mogą być używane do wyboru przetłumaczonego wyświetlanego ciągu znaków na podstawie język urządzenia w czasie działania. Można to skonfigurować za pomocą ta reguła:

Rysunek 1.Dodawanie reguły w celu włączenia makra zbierania wartości tylko dla urządzeń skonfigurowany pod kątem używania języka hiszpańskiego.

Następnie możesz utworzyć makra kolekcji wartości dla każdego języka i dodać je do każdego makra, dodając odpowiedni kod języka. Gdy ten kontener zostanie opublikowana, aplikacja będzie mogła wyświetlać zlokalizowane treści w zależności od języka używanego na urządzeniu użytkownika w czasie działania.

Jeśli domyślny kontener wymaga reguł, musisz użyć plik kontenera binarnego jako domyślny kontenera.

Więcej informacji o konfigurowaniu reguł (Centrum pomocy)

Domyślne pliki binarne kontenerów

Domyślne kontenery, które wymagają reguł, powinny używać pliku binarnego kontenera zamiast JSON . Kontenery binarne ułatwiają określanie wartości makr w środowisku wykonawczym za pomocą reguł Menedżera tagów Google. JSON plików tak nie jest.

Pliki kontenerów binarnych można pobierać ze strony Menedżera tagów Google interfejsu należy dodać do /assets/tagmanager/ folder i postępuj według tego wzorca: /assets/tagmanager/GTM-XXXX, gdzie nazwa pliku reprezentuje kontenera.

Gdy plik JSON oraz plik kontenera binarnego, SDK użyje kontenera binarnego jako kontenera domyślnego.

Używanie makr wywołania funkcji

Makra wywołania funkcji to makra ustawione na wartość zwrotną z określoną funkcją w aplikacji. Makra wywołania funkcji mogą być wykorzystywane do Uwzględnij wartości czasu działania w regułach Menedżera tagów Google, takich jak: określać w czasie działania, jaka cena ma się wyświetlać użytkownikowi na podstawie skonfigurowanego język i waluta urządzenia.

Aby skonfigurować makro wywołania funkcji:

1. Definiowanie makra wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie konfigurować jako pary klucz-wartość.
2. Zarejestruj FunctionCallMacroHandler w aplikacji za pomocą Container.registerFunctionCallMacroHandler() i nazwa skonfigurowanej funkcji. w interfejsie internetowym Menedżera tagów Google, zastępując jego Metoda 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;
     }
   });
   

Korzystanie z tagów wywołań funkcji

Tagi wywołania funkcji umożliwiają wykonywanie wcześniej zarejestrowanych funkcji za każdym razem, gdy zdarzenie jest przekazywane do warstwy danych i do reguł tagów zwraca wartość true.

Aby skonfigurować tag wywołania funkcji:

1. Definiowanie tagu wywołania funkcji w interfejsie internetowym Menedżera tagów Google. Argumenty można opcjonalnie konfigurować jako pary klucz-wartość.
2. Zarejestruj moduł obsługi tagu wywołania funkcji w aplikacji za pomocą 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ć dane nowego kontenera, jeśli jego aktualny wiek przekracza 12 godzin. Aby ustawić niestandardowy okres odświeżania kontenera, użyj Timer , na przykład następujący przykład:

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

Debugowanie z użyciem Loggera

Pakiet SDK Menedżera tagów Google domyślnie wyświetla w dziennikach błędy i ostrzeżenia. Włączenie bardziej szczegółowego logowania może być pomocne przy debugowaniu i jest możliwe dzięki implementujesz własną Logger w: 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żna też ustawić poziom LogLevel istniejącego dziennika za pomocą funkcji 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);