Android версии 4 (устаревшая) – начало работы

Введение

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

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

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

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

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

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

Подготовка

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

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

Начало работы

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

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

1. Как добавить Google Менеджер тегов в проект

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

  1. Настройте SDK сервисов Google Play.
  2. Если вы используете другую интегрированную среду разработки, а не 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 Аналитики для настройки данных кампании, добавьте в файл 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 Менеджер тегов использует контейнер по умолчанию. Контейнер по умолчанию перестанет использоваться, как только приложение сможет получить новый контейнер по сети.

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

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

    Создание синглтона 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;
        }
    }

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. Передача событий и значений в dataLayer

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

Передача значений в 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

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

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

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

  1. Получите одиночный объект DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Передайте событие с помощью DataLayer.pushEvent():
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

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

6. Предварительный просмотр, отладка и публикация

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

Предпросмотр

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

  1. Добавьте в файл AndroidManifest следующий код Activity:
    <!--  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 минут. В противном случае он не будет работать.