Android v4 – Начало работы

Примечание. В этом руководстве описывается старая реализация Диспетчера тегов Google в приложениях Android. Новым пользователям следует использовать Диспетчер тегов + Firebase для внедрения Диспетчера тегов Google в свои приложения для Android.

Введение

Диспетчер тегов Google позволяет разработчикам изменять значения конфигурации в своем мобильном приложении с помощью интерфейса Диспетчера тегов Google без необходимости пересобирать и повторно отправлять двоичные файлы приложений на торговые площадки приложений.

Это полезно для управления любыми значениями конфигурации или флагами в вашем приложении, которые вам, возможно, придется изменить в будущем, в том числе:

• Различные настройки пользовательского интерфейса и строки отображения.
• Размеры, местоположения или типы объявлений, показываемых в вашем приложении.
• Различные настройки игры

Значения конфигурации также могут оцениваться во время выполнения с использованием правил, позволяющих создавать такие динамические конфигурации, как:

• Использование размера экрана для определения размера рекламного баннера
• Использование языка и местоположения для настройки элементов пользовательского интерфейса

Google TagManager также обеспечивает динамическую реализацию тегов и пикселей отслеживания в приложениях. Разработчики могут перенести важные события на уровень данных и позже решить, какие теги отслеживания или пиксели следует активировать.

Прежде чем начать

Прежде чем приступить к работе с этим руководством по началу работы, выполните следующие действия:

• Установите Android SDK
• Загрузите SDK сервисов Google Play.
• Создайте учетную запись Диспетчера тегов Google.
• Настройка контейнера Диспетчера тегов Google

После того, как вы выполнили эти шаги, оставшаяся часть этого руководства расскажет вам, как настроить и использовать Диспетчер тегов Google в вашем приложении Android.

Начиная

Прочитав это руководство по началу работы, вы поймете, как:

• Добавьте Диспетчер тегов Google в свой проект
• Инициализируйте Диспетчер тегов в своем приложении.
• Получите значения конфигурации из контейнера Диспетчера тегов.
• Передача значений и событий в dataLayer
• Предварительный просмотр, отладка и публикация контейнера

В этом руководстве используются фрагменты кода из примера приложения Cute Animals , включенного в SDK Google Play Services . Полный исходный код этого проекта доступен в: < android-sdk-directory >/extras/google/google_play_services/tagmanager/cuteanimals .

1. Добавление Диспетчера тегов Google в ваш проект.

Чтобы добавить Диспетчер тегов Google в свой проект:

1. Настройте SDK сервисов Google Play .
2. Если вы используете IDE, отличную от Android Studio , добавьте следующие разрешения в файл AndroidManifest.xml :

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

3. Чтобы позволить InstallReferrerReceiver вызывать получатель Google Analytics для настройки данных кампании, добавьте в файл 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. Добавление файла контейнера по умолчанию в ваш проект

Примечание . Если вы еще не настроили свой контейнер в веб-интерфейсе Диспетчера тегов Google , вернитесь к этому шагу, как только вы это сделаете.

Диспетчер тегов Google использует контейнер по умолчанию при первом запуске вашего приложения. Контейнер по умолчанию перестанет использоваться, как только приложение сможет получить новый контейнер по сети.

Чтобы загрузить и добавить в приложение двоичный файл контейнера по умолчанию:

1. Войдите в веб-интерфейс Диспетчера тегов Google.
2. Выберите версию контейнера, который вы хотите загрузить.
3. Нажмите кнопку «Загрузить» , чтобы получить двоичный файл контейнера.
4. Добавьте загруженный двоичный файл контейнера в свой проект в качестве необработанного ресурса.
   1. Если подпапка raw в <project-root>/res/ не существует, создайте ее.
   2. При необходимости переименуйте двоичный файл контейнера. Он состоит только из строчных букв, цифр и подчеркиваний.
   3. Скопируйте двоичный файл контейнера в папку <project-root>/res/raw .

Несмотря на то, что рекомендуется использовать двоичный файл, если ваш контейнер не содержит правил или тегов, вы можете вместо этого использовать простой файл JSON.

3. Инициализация Диспетчера тегов Google

Чтобы инициализировать Диспетчер тегов Google в вашем приложении:

1. Получите синглтон TagManager :

   TagManager tagManager = TagManager.getInstance(this);
   

2. Используйте синглтон TagManager , чтобы отправить запрос на загрузку контейнера, указав идентификатор контейнера Диспетчера тегов Google, а также файл контейнера по умолчанию . Идентификатор контейнера должен быть в верхнем регистре и точно соответствовать идентификатору контейнера в веб-интерфейсе Диспетчера тегов Google. Вызов loadContainerPreferNonDefault() неблокирует и возвращает PendingResult :

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

3. Используйте ResultCallback для возврата ContainerHolder после завершения загрузки или истечения времени ожидания:

   // 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);
   

   Примечание . По умолчанию контейнер может обновляться по сети каждые 12 часов. Узнайте, как вручную обновить контейнер .

   Создание синглтона ContainerHolder

   Вам следует поддерживать только один экземпляр ContainerHolder за один запуск вашего приложения. Вот почему в приведенном выше примере используется служебный класс ContainerHolderSingleton для управления доступом к экземпляру ContainerHolder . Вот как выглядит этот класс 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;
       }
   }
   
   

См. фрагмент кода из примера приложения.

В следующем фрагменте показан полный шаблон, реализованный в методе onCreate() примера 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. Получение значений конфигурации из контейнера

После загрузки контейнера вы можете получить значения конфигурации, используя любой из методов Container.get <type> () . Значения конфигурации определяются с помощью переменных сбора значений Диспетчера тегов Google. Например, следующий метод извлекает последний цвет, который мы решили использовать для элемента пользовательского интерфейса, и возвращает его как целое число:

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

Этот код делает две вещи, чтобы получить имя цвета из контейнера:

1. Получает Container из ContainerHolder с помощью ContainerHolder.getContainer() .
2. Получает значение цвета с помощью Container.getString( key ) , где вы определили ключ и значение в веб-интерфейсе Диспетчера тегов Google.

5. Передача событий и значений на уровень данных

Google Tag Manager также предоставляет dataLayer , в который вы можете поместить информацию о своем приложении, которую можно будет прочитать в других частях вашего приложения или использовать для активации тегов, которые вы настроили в веб-интерфейсе Google Tag Manager.

Передача значений в dataLayer

dataLayer обеспечивает уровень сохраняемости, который вы можете использовать для хранения пар ключ-значение, которые вы, возможно, захотите использовать в других частях вашего приложения или в качестве входных данных для тегов Диспетчера тегов Google.

Чтобы отправить значение в dataLayer , следуйте следующему шаблону:

1. Получите синглтон DataLayer :

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

2. Отправьте событие с помощью DataLayer.push() :

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

Чтобы получить значение из dataLayer , используйте DataLayer.get( key ) .

Передача событий на уровень данных

Передача событий в dataLayer позволяет отделить код вашего приложения от тегов, которые вы, возможно, захотите активировать в ответ на эти события.

Например, вместо жесткого кодирования вызовов отслеживания просмотра экрана Google Analytics в вашем приложении вы можете перенести события экрана на dataLayer и определить теги отслеживания через веб-интерфейс Google Tag Manager. Это дает вам возможность изменять этот тег или добавлять дополнительные теги, реагирующие на события на экране, без обновления кода приложения.

Чтобы отправить событие в dataLayer , следуйте следующему шаблону:

1. Получите синглтон DataLayer :

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

2. Отправьте событие с помощью DataLayer.pushEvent() :

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

   DataLayer.mapOf() — это служебный метод, который можно использовать для простого создания карты пар ключ-значение, которая будет обновлять dataLayer одновременно с отправкой события.

См. фрагмент кода из примера приложения.

Следующий служебный класс демонстрирует, как передавать события, например информацию об открытии и закрытии экранов в вашем приложении, в 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. Предварительный просмотр, отладка и публикация

Прежде чем публиковать версию вашего контейнера, вам необходимо просмотреть ее, чтобы убедиться, что она работает должным образом. Диспетчер тегов Google дает вам возможность просматривать версии вашего контейнера, создавая ссылки и QR-коды в веб-интерфейсе и используя их для открытия вашего приложения. Вы также можете включить режим подробного журнала для отладки любого непредвиденного поведения.

Предварительный просмотр

Чтобы просмотреть версию вашего контейнера, выполните следующие действия:

1. Добавление этого Activity предварительного просмотра в файл 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>
   

   Обязательно измените эту строку, включив в нее имя пакета вашего приложения:

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

2. Создайте ссылку предварительного просмотра в веб-интерфейсе Диспетчера тегов Google.
   1. Войдите в Диспетчер тегов Google.
   2. Выберите версию контейнера для предварительного просмотра
   3. Нажмите кнопку предварительного просмотра
   4. Введите имя пакета вашего приложения и нажмите «Создать ссылку начала предварительного просмотра».
3. Используйте сгенерированную ссылку или QR-код для запуска приложения.
4. Выйти из режима предварительного просмотра можно, перейдя по ссылке, созданной с помощью параметра «Создать ссылку для завершения предварительного просмотра» в веб-интерфейсе.

Отладка

Если вам нужно устранить неполадки в реализации контейнера, включите подробное ведение журнала, вызвав 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);

Издательский

После того как вы просмотрели свой контейнер и убедились, что он работает должным образом, вы можете опубликовать свой контейнер . Значения конфигурации вашего контейнера, теги и события будут доступны пользователям при следующем обновлении их контейнеров. Узнайте больше об обновлении контейнеров .

Расширенная конфигурация

В следующих разделах описаны расширенные параметры конфигурации, которые вы хотите использовать для дальнейшей настройки реализации Диспетчера тегов Google.

Обновление контейнера

По умолчанию ваш контейнер может обновляться каждые 12 часов. Чтобы вручную обновить контейнер, используйте ContainerHolder.refresh() :

ContainerHolderSingleton.getContainerHolder().refresh();

Это асинхронный вызов, который не возвращает результат немедленно. Чтобы уменьшить сетевой трафик, refresh() можно вызывать только один раз каждые 15 минут, иначе она будет неактивна.

Примечание . В этом фрагменте используется служебный класс ContainerHolderSingleton , описанный в примере инициализации выше.

См. фрагмент кода из примера приложения.

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