Android v4 – pierwsze kroki

Uwaga: w tym przewodniku opisano starą implementację Menedżera tagów Google w aplikacjach na Androida. Nowi użytkownicy powinni wdrożyć Menedżera tagów Google w aplikacjach na Androida za pomocą Menedżera tagów i Firebase.

Wstęp

Menedżer tagów Google umożliwia programistom zmianę wartości konfiguracji w aplikacji mobilnej za pomocą interfejsu Menedżera tagów Google bez konieczności ponownego kompilowania i ponownego przesyłania plików binarnych aplikacji do sklepów z aplikacjami.

Przydaje się to do zarządzania w aplikacji wartościami konfiguracyjnymi lub flagami, które w przyszłości mogą wymagać zmiany, takimi jak:

• Różne ustawienia interfejsu i wyświetlane ciągi znaków
• rozmiary, lokalizacje lub typy reklam wyświetlanych w Twojej aplikacji;
• Różne ustawienia gier

Wartości konfiguracji mogą być też oceniane w czasie działania za pomocą reguł, które włączają konfiguracje dynamiczne, 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ż dynamiczną implementację tagów i pikseli śledzenia w aplikacjach. Deweloperzy mogą przekazywać ważne zdarzenia do warstwy danych i później zdecydować, które tagi śledzenia lub piksele mają być uruchamiane.

Zanim zaczniesz

Zanim zaczniesz korzystać z tego przewodnika, wykonaj następujące czynności:

• Zainstaluj pakiet SDK na Androida.
• Pobierz pakiet SDK Usług Google Play
• Utwórz konto Menedżera tagów Google.
• Konfigurowanie kontenera Menedżera tagów Google

Po wykonaniu tych czynności w dalszej części tego przewodnika dowiesz się, jak skonfigurować Menedżera tagów Google i korzystać z niego w aplikacji na Androida.

Pierwsze kroki

Z tego przewodnika dla początkujących dowiesz się, jak:

• Dodawanie Menedżera tagów Google do projektu
• Inicjowanie Menedżera tagów w aplikacji
• Pobieranie wartości konfiguracyjnych z kontenera Menedżera tagów
• Przekazywanie wartości i zdarzeń do interfejsu dataLayer
• Podgląd, debugowanie i publikowanie kontenera

W tym przewodniku używane są fragmenty kodu z przykładowej aplikacji w usłudze Cute Animals dołączonej do pakietu SDK Usług Google Play. Pełne źródło tego projektu jest dostępne w: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

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

Aby dodać Menedżera tagów Google do projektu:

1. Skonfiguruj pakiet SDK Usług Google Play.
2. Jeśli używasz IDE innego niż Android Studio, dodaj do pliku AndroidManifest.xml te uprawnienia:

   <!-- For TagManager SDK -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

3. Aby umożliwić InstallReferrerReceiver wywoływanie odbiornika Google Analytics w celu ustawiania danych kampanii, dodaj ten kod do pliku AndroidManifest.xml:

   <!-- Used for install referrer tracking-->
   <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
   <receiver
     android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
     android:exported="true">
     <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
     </intent-filter>
   </receiver>
   

2. Dodawanie domyślnego pliku kontenera do projektu

Uwaga: jeśli kontener nie jest jeszcze skonfigurowany w interfejsie internetowym Menedżera tagów Google, wróć do tego kroku.

Menedżer tagów Google używa domyślnego kontenera przy pierwszym uruchomieniu aplikacji. Domyślny kontener przestanie być używany, gdy tylko aplikacja pobierze nowy kontener przez sieć.

Aby pobrać domyślny plik binarny kontenera i dodać go do aplikacji:

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 pobrany plik binarny kontenera do projektu jako nieprzetworzony zasób.
   1. Jeśli podfolder raw w sekcji <project-root>/res/ nie istnieje, utwórz go.
   2. W razie potrzeby zmień nazwę pliku binarnego kontenera. Składa się tylko z małych liter, cyfr i podkreśleń.
   3. Skopiuj plik binarny kontenera do folderu <project-root>/res/raw.

Zalecamy użycie pliku binarnego, ale jeśli Twój kontener nie zawiera reguł ani tagów, możesz użyć prostego pliku JSON.

3. Inicjuję Menedżera tagów Google

Aby zainicjować Menedżera tagów Google w aplikacji:

1. Znajdź singiel TagManager:

   TagManager tagManager = TagManager.getInstance(this);
   

2. Użyj singletonu TagManager, aby wysłać żądanie wczytania kontenera, podając identyfikator kontenera Menedżera tagów Google oraz plik kontenera domyślnego. Identyfikator kontenera powinien być pisany wielkimi literami i dokładnie taki sam jak identyfikator kontenera w interfejsie internetowym Menedżera tagów Google. Wywołanie loadContainerPreferNonDefault() nie blokuje i zwraca wartość PendingResult:

   PendingResult<ContainerHolder> pending =
           tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
           R.raw.defaultcontainer_binary);
   

3. Użyj ResultCallback, aby zwrócić ContainerHolder po zakończeniu wczytywania lub przekroczeniu limitu czasu:

   // The onResult method will be called as soon as one of the following happens:
   //     1. a saved container is loaded
   //     2. if there is no saved container, a network container is loaded
   //     3. the 2-second timeout occurs
   pending.setResultCallback(new ResultCallback<ContainerHolder>() {
       @Override
       public void onResult(ContainerHolder containerHolder) {
           ContainerHolderSingleton.setContainerHolder(containerHolder);
           Container container = containerHolder.getContainer();
           if (!containerHolder.getStatus().isSuccess()) {
               Log.e("CuteAnimals", "failure loading container");
               displayErrorToUser(R.string.load_error);
               return;
           }
           ContainerLoadedCallback.registerCallbacksForContainer(container);
           containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
           startMainActivity();
       }
   }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
   

   Uwaga: domyślnie kontener może być odświeżany w sieci co 12 godzin. Dowiedz się, jak ręcznie odświeżać kontener.

   Tworzenie singletonu ContainerHolder

   Powinno się utrzymywać tylko 1 instancję ContainerHolder na każde uruchomienie aplikacji. Dlatego w powyższym przykładzie do zarządzania dostępem do instancji ContainerHolder użyto klasy narzędzia ContainerHolderSingleton. Tak wygląda klasa ContainerHolderSingleton:

   package com.google.android.tagmanager.examples.cuteanimals;
   
   import com.google.android.gms.tagmanager.ContainerHolder;
   
   /**
    * Singleton to hold the GTM Container (since it should be only created once
    * per run of the app).
    */
   public class ContainerHolderSingleton {
       private static ContainerHolder containerHolder;
   
       /**
        * Utility class; don't instantiate.
        */
       private ContainerHolderSingleton() {
       }
   
       public static ContainerHolder getContainerHolder() {
           return containerHolder;
       }
   
       public static void setContainerHolder(ContainerHolder c) {
           containerHolder = c;
       }
   }
   
   

Zobacz fragment kodu z przykładowej aplikacji

Ten fragment kodu pokazuje pełny wzorzec zaimplementowany w metodzie onCreate() w przykładowym Activity:

package com.google.android.tagmanager.examples.cuteanimals;

import java.util.concurrent.TimeUnit;
import java.util.Map;

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.ResultCallback;
import com.google.android.gms.tagmanager.Container;
import com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback;
import com.google.android.gms.tagmanager.Container.FunctionCallTagCallback;
import com.google.android.gms.tagmanager.ContainerHolder;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Displays simple splash screen while GTM container is loading. Once the container is loaded,
 * launches the {@link MainActivity}.
 */
public class SplashScreenActivity extends Activity {
    private static final long TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS = 2000;
    private static final String CONTAINER_ID = "GTM-XXXX";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_splashscreen);

        TagManager tagManager = TagManager.getInstance(this);

        // Modify the log level of the logger to print out not only
        // warning and error messages, but also verbose, debug, info messages.
        tagManager.setVerboseLoggingEnabled(true);

        PendingResult<ContainerHolder> pending =
                tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
                R.raw.defaultcontainer_binary);

        // The onResult method will be called as soon as one of the following happens:
        //     1. a saved container is loaded
        //     2. if there is no saved container, a network container is loaded
        //     3. the 2-second timeout occurs
        pending.setResultCallback(new ResultCallback<ContainerHolder>() {
            @Override
            public void onResult(ContainerHolder containerHolder) {
                ContainerHolderSingleton.setContainerHolder(containerHolder);
                Container container = containerHolder.getContainer();
                if (!containerHolder.getStatus().isSuccess()) {
                    Log.e("CuteAnimals", "failure loading container");
                    displayErrorToUser(R.string.load_error);
                    return;
                }
                ContainerLoadedCallback.registerCallbacksForContainer(container);
                containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
                startMainActivity();
            }
        }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
  // Rest of the Activity definition.
}

4. Pobieranie wartości konfiguracyjnych z kontenera

Po załadowaniu kontenera możesz pobrać wartości konfiguracyjne za pomocą dowolnej metody Container.get<type>(). Wartości konfiguracji są definiowane za pomocą zmiennych zbierania wartości w Menedżerze tagów Google. Na przykład ta metoda pobiera najnowszy kolor, którego chcemy użyć w elemencie interfejsu, i zwraca go jako liczbę całkowitą:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Ten kod pobiera z kontenera nazwę koloru na 2 sposoby:

1. Pobiera Container z ContainerHolder za pomocą ContainerHolder.getContainer().
2. Pobiera wartość koloru z parametru Container.getString(key), gdzie w interfejsie internetowym Menedżera tagów Google zostały zdefiniowane klucz i wartość.

5. Przekazywanie zdarzeń i wartości do obiektu dataLayer

Menedżer tagów Google udostępnia też interfejs dataLayer, do którego możesz przekazywać informacje o aplikacji, które można odczytać w innych częściach aplikacji lub wykorzystać do uruchamiania tagów skonfigurowanych w interfejsie internetowym Menedżera tagów Google.

Przekazywanie wartości do obiektu dataLayer

dataLayer zapewnia warstwę trwałości, której można używać do przechowywania par klucz-wartość, których możesz chcieć użyć w innych częściach aplikacji, lub jako danych wejściowych do tagów Menedżera tagów Google.

Aby przekazać wartość do dataLayer, postępuj zgodnie z tym wzorcem:

1. Pobierz singleton DataLayer:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. Przekaż zdarzenie za pomocą funkcji DataLayer.push():

   // Put the image_name into the data layer for future use.
   TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
   

Aby uzyskać wartość z dataLayer, użyj funkcji DataLayer.get(key).

Przekazywanie zdarzeń do obiektu dataLayer

Przekazywanie zdarzeń do interfejsu dataLayer umożliwia oddzielenie kodu aplikacji od tagów, które chcesz uruchamiać w odpowiedzi na te zdarzenia.

Na przykład zamiast umieszczać na stałe w kodzie aplikacji wywołania śledzenia wyświetleń ekranu Google Analytics, możesz przekazywać zdarzenia ekranu do obiektu dataLayer i definiować tagi śledzenia w interfejsie internetowym Menedżera tagów Google. Dzięki temu możesz modyfikować ten tag lub dodawać kolejne tagi, które reagują na zdarzenia ekranu bez aktualizowania kodu aplikacji.

Aby przekazać zdarzenie do dataLayer, postępuj zgodnie z tym wzorcem:

1. Pobierz singleton DataLayer:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. Przekaż zdarzenie za pomocą funkcji DataLayer.pushEvent():

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
   

   DataLayer.mapOf() to użyteczna metoda pozwalająca łatwo wygenerować mapę par klucz-wartość, która będzie aktualizować dataLayer w momencie przekazywania zdarzenia.

Zobacz fragment kodu z przykładowej aplikacji

Poniższa klasa narzędzi pokazuje, jak przekazywać zdarzenia, takie jak informacje o otwieraniu i zamykaniu ekranów w aplikacji, na dataLayer:

package com.google.android.tagmanager.examples.cuteanimals;

import android.content.Context;

import com.google.android.gms.tagmanager.DataLayer;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Utility class.
 */
public class Utils {
    private Utils() {
        // private constructor.
    }

    /**
     * Push an "openScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushOpenScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    }

    /**
     * Push a "closeScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushCloseScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("closeScreen", DataLayer.mapOf("screenName", screenName));
    }
}

6. Podgląd, debugowanie i publikowanie

Zanim opublikujesz wersję kontenera, wyświetl jego podgląd, aby sprawdzić, czy działa poprawnie. Menedżer tagów Google umożliwia wyświetlanie podglądu wersji kontenera przez generowanie linków i kodów QR w interfejsie internetowym oraz używanie ich do otwierania aplikacji. Możesz też włączyć tryb szczegółowego rejestrowania, aby debugować wszelkie nieoczekiwane zachowania.

Wyświetlam podgląd

Aby wyświetlić podgląd wersji kontenera:

1. Dodaję podgląd Activity do pliku AndroidManifest:

   <!--  Add preview activity. -->
   <activity
       android:name="com.google.android.gms.tagmanager.PreviewActivity"
       android:label="@string/app_name"
       android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
       <intent-filter>
         <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE"/>
       </intent-filter>
   </activity>
   

   Zmodyfikuj ten wiersz, aby zawierał nazwę pakietu Twojej aplikacji:

   <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
   

2. Wygenerować link do podglądu w interfejsie internetowym Menedżera tagów Google.
   1. Zaloguj się w Menedżerze tagów Google
   2. Wybierz wersję kontenera, do której chcesz wyświetlić podgląd
   3. Kliknij przycisk Podgląd
   4. Wpisz nazwę pakietu aplikacji i kliknij Wygeneruj link do rozpoczęcia podglądu.
3. Uruchom aplikację, używając wygenerowanego linku lub kodu QR.
4. Możesz wyjść z trybu podglądu, klikając link wygenerowany za pomocą opcji Wygeneruj link do zakończenia podglądu w interfejsie internetowym.

Debugowanie

Jeśli musisz rozwiązać problemy z implementacją kontenera, włącz logowanie szczegółowe, wywołując metodę TagManager.setVerboseLoggingEnabled(true):

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

Publikuję

Po wyświetleniu podglądu kontenera i sprawdzeniu, czy działa on prawidłowo, możesz opublikować kontener. Wartości konfiguracyjne, tagi i zdarzenia kontenerów zostaną udostępnione użytkownikom po kolejnym odświeżeniu ich kontenerów. Więcej informacji o odświeżaniu kontenerów

Konfiguracja zaawansowana

W kolejnych sekcjach opisano zaawansowane opcje konfiguracji, których możesz użyć, aby jeszcze bardziej dostosować implementację Menedżera tagów Google.

Odświeżanie kontenera

Domyślnie kontener może być odświeżany co 12 godzin. Aby ręcznie odświeżyć kontener, użyj ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Jest to wywołanie asynchroniczne, które nie jest zwracane natychmiast. Aby zmniejszyć ruch sieciowy, funkcję refresh() można wywoływać tylko raz na 15 minut. W przeciwnym razie nie będzie działać.

Uwaga: w tym fragmencie kodu używana jest klasa narzędzia ContainerHolderSingleton opisana w powyższym przykładzie inicjowania.

Zobacz fragment kodu z przykładowej aplikacji

public void refreshButtonClicked(@SuppressWarnings("unused") View view) {
    Log.i(TAG, "refreshButtonClicked");
    ContainerHolderSingleton.getContainerHolder().refresh();

    // Push the "refresh" event to trigger firing an analytics tag.
    TagManager.getInstance(this).getDataLayer().push("event", "refresh");
    // Push the "custom tag" event to trigger firing a custom function call tag.
    TagManager.getInstance(this).getDataLayer().push("event", "custom_tag");
    updateCategories();
}