Android v4 – pierwsze kroki

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 aplikacjach na Androida.

Wprowadzenie

Menedżer tagów Google umożliwia programistom zmianę wartości konfiguracyjnych w aplikacjach mobilnych za pomocą interfejsu Menedżera tagów Google bez konieczności ponownego tworzenia i ponownego tworzenia plików binarnych aplikacji. na platformach handlowych.

Jest to przydatne do zarządzania wartościami konfiguracyjnymi lub flagami w aplikacji, których możesz potrzebować co można zmienić w przyszłości. Należą do nich:

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

Wartości konfiguracji mogą być również oceniane w czasie działania za pomocą reguł, co pozwala na konfiguracji, 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 aplikacji. Deweloperzy mogą przekazywać ważne zdarzenia do warstwy danych i później decydować, tagów śledzenia czy pikseli.

Zanim zaczniesz

Przed rozpoczęciem tego przewodnika wykonaj następujące czynności:

• Zainstaluj pakiet SDK do 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 pozostała część tego przewodnika zawiera informacje o tym, konfigurowania Menedżera tagów Google i korzystania 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
• Zainicjowanie Menedżera tagów w aplikacji
• Pobieranie wartości konfiguracyjnych z kontenera Menedżera tagów
• Przekazywanie wartości i zdarzeń do elementu dataLayer
• Wyświetlanie podglądu, debugowanie i publikowanie kontenera

W tym przewodniku używamy fragmentów kodu z Cute Animals przykładowej aplikacji dołączonej do Pakiet SDK Usług Google Play. Pełne źródło tego projektu jest dostępne w tych językach: <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 te uprawnienia Plik AndroidManifest.xml:

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

3. Aby włączyć usługę InstallReferrerReceiver, aby wywołać odbiornik Google Analytics. aby skonfigurować dane kampanii, dodaj poniższe elementy do Plik 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 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 przestanie być używany, gdy tylko aplikacja będzie w stanie pobrać nowy kontener nad

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

Chociaż zalecamy używanie pliku binarnego, jeśli Twój kontener nie zawiera reguł ani tagów, możesz używać prostego pliku JSON.

3. Inicjowanie Menedżera tagów Google

Aby uruchomić Menedżera tagów Google w swojej aplikacji:

1. Pobierz singleton TagManager:

   TagManager tagManager = TagManager.getInstance(this);

2. Używaj metody singletonowej TagManager, aby wysłać żądanie wczytania kontenera, określając identyfikator kontenera Menedżera tagów Google oraz kontener domyślny; . Identyfikator kontenera powinien być zapisany wielkimi literami i musi być identyczny z identyfikatorem kontenera w tagu Google Interfejs internetowy menedżera. Połączenie z numerem loadContainerPreferNonDefault() nie jest blokowane i zwraca błąd 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żna odświeżyć. jest przesyłane w ciągu 12 godzin. Dowiedz się, jak ręcznie odświeżyć kontener

   Tworzenie elementu Singleton ContainerHolder

   Zalecamy utrzymywanie tylko jednego wystąpienia ContainerHolder na uruchomienie aplikacji. Dlatego w powyższym przykładzie użyto klasy narzędzia ContainerHolderSingleton w celu zarządzania dostępem do instancji ContainerHolder. Oto co ContainerHolderSingleton zajęcia wygląda jak:

   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;
       }
   }

Wyświetlanie fragmentu kodu z przykładowej aplikacji

Ten fragment kodu pokazuje pełny wzorzec zaimplementowany w metodzie onCreate() przykładowego 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 przy użyciu dowolnej Container.get<type>() metody. Wartości konfiguracyjne definiuje się za pomocą zmiennych kolekcji wartości w Menedżerze tagów Google, Na przykład ta metoda pobiera najnowszy kolor, który postanowiliśmy zastosować dla elementu interfejsu, i zwraca go jako Liczba całkowita:

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

Ten kod wykonuje 2 czynności, aby pobrać nazwę koloru z kontenera:

1. Pobiera Container z: ContainerHolder za pomocą ContainerHolder.getContainer().
2. Pobiera wartość koloru za pomocą funkcji Container.getString(key), gdzie masz zdefiniować klucz i wartość w interfejsie internetowym Menedżera tagów Google.

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

Menedżer tagów Google udostępnia też dataLayer, do którego możesz przekazywać informacje o aplikacji, które mogą być odczytywane w innych jej częściach lub używane do uruchamiania tagów skonfigurowany w interfejsie internetowym Menedżera tagów Google.

Przekazywanie wartości do obiektu dataLayer

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

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

1. Pobierz DataLayer singleton:

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

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

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

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

Przekazywanie zdarzeń do obiektu dataLayer

Przekazywanie zdarzeń do interfejsu dataLayer pozwala oddzielić kod aplikacji od które możesz uruchamiać w odpowiedzi na te zdarzenia.

Na przykład zamiast kodować na stałe w aplikacji wywołania śledzenia wyświetleń ekranu Google Analytics, możesz przekazywać zdarzenia związane z ekranem do interfejsu dataLayer i definiować tagi śledzenia w interfejsie Interfejs internetowy Menedżera tagów Google. Dzięki temu możesz go zmodyfikować lub dodać innych tagów, które reagują na zdarzenia związane z ekranem, bez konieczności aktualizowania kodu aplikacji.

Aby przekazać zdarzenie do dataLayer, korzystaj z tego wzorca:

1. Pobierz DataLayer singleton:

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

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

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

   DataLayer.mapOf() to metoda użytkowa, której możesz użyć do łatwego wygenerowania mapy które będą aktualizować wartość dataLayer wraz z przekazywaniem zdarzenia.

Wyświetlanie fragmentu kodu z przykładowej aplikacji

Poniższa klasa narzędziowa pokazuje, jak przekazywać zdarzenia, takie jak informacje o ekranach otwieranie i zamykanie 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

Przed opublikowaniem wersji kontenera warto wyświetlić jej podgląd, aby upewnić się, że wszystko działa zgodnie z oczekiwaniami. Menedżer tagów Google umożliwia wyświetlanie podglądu wersji kontenera przez generowanie linków i kodów QR w interfejsie internetowym i 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, wykonaj te czynności:

1. Dodaję ten 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>

   Pamiętaj, aby zmodyfikować ten wiersz, tak aby zawierał nazwę pakietu aplikacji:

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

2. Generowanie linku do podglądu w interfejsie internetowym Menedżera tagów Google
   1. Zaloguj się w Menedżerze tagów Google
   2. Wybierz wersję kontenera, aby wyświetlić podgląd.
   3. Kliknij przycisk Podgląd
   4. Wpisz nazwę pakietu aplikacji i kliknij Wygeneruj link do rozpoczęcia podglądu.
3. Użyj wygenerowanego linku lub kodu QR, aby uruchomić aplikację
4. Aby wyjść z trybu podglądu, kliknij link wygenerowany przez Wygeneruj link do końca podglądu w interfejsie internetowym.

Debugowanie

Jeśli musisz rozwiązać problemy z implementacją kontenera, włącz szczegółowe logowanie, wywołując 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);

Publikowanie

Po wyświetleniu podglądu kontenera i sprawdzeniu, czy działa on prawidłowo, możesz opublikuj kontener. Twoje wartości konfiguracji kontenera, tagi i zdarzenia będą dostępne dla użytkowników, kontenery zostaną odświeżone. Dowiedz się więcej o odświeżaniu kontenerów

Konfiguracja zaawansowana

W poniższych sekcjach opisano zaawansowane opcje konfiguracji, których możesz używać do dalszego dostosowywania Implementacja za pomocą Menedżera tagów Google.

Odświeżanie kontenera

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

ContainerHolderSingleton.getContainerHolder().refresh();

Jest to wywołanie asynchroniczne, które nie zostanie zwrócone natychmiast. Aby ograniczyć ruch w sieci, refresh() może tylko raz na 15 minut, w przeciwnym razie będzie wykonywana bez operacji.

Uwaga: ten fragment kodu używa Klasa użyteczności ContainerHolderSingleton opisana w przykładzie inicjowania powyżej.

Wyświetlanie fragmentu 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();
}