В этом руководстве для разработчиков описано, как внедрить Google Менеджер тегов в мобильное приложение.
Введение
Google Менеджер тегов позволяет разработчикам изменять значения конфигурации в мобильных приложениях через интерфейс Google Менеджера тегов без необходимости повторно компилировать и отправлять в магазины исполняемые файлы.
Это полезно для управления любыми значениями конфигурации или флагами в вашем приложении, которые вам может потребоваться изменить в будущем, в том числе:
- Различные настройки интерфейса и строки отображения
- размеры, местоположение или типы объявлений, которые показываются в вашем приложении;
- Настройки игр
Значения конфигурации также могут оцениваться во время выполнения с помощью правил, что позволяет использовать динамические конфигурации, например:
- Как определить размер рекламного баннера по размеру экрана
- Как настроить элементы интерфейса с учетом языка и местоположения
Google Менеджер тегов также позволяет динамически внедрять в приложения теги и пиксели отслеживания. Разработчики могут передавать важные события на уровень данных, чтобы позже решить, какие теги или пиксели отслеживания следует активировать. Менеджер тегов поддерживает следующие теги:
- Google Аналитика мобильных приложений
- Тег вызова пользовательской функции
Подготовка
Прежде чем использовать это краткое руководство [по началу работы], вам потребуется следующее:
- Аккаунт Google Менеджера тегов.
- Новый контейнер Менеджера тегов и макрос сбора значений.
- Мобильное приложение для Android, в котором будет реализован Google Менеджер тегов.
- Google Analytics Services SDK, который содержит библиотеку Менеджера тегов.
Если вы не знакомы с Google Менеджером тегов, рекомендуем вам прочитать о контейнерах, макросах и правилах в Справочном центре, прежде чем продолжить работу с этим руководством.
Начало работы
В этом разделе описывается типичный рабочий процесс в Менеджере тегов.
- Добавьте SDK Google Менеджера тегов в проект
- Как задать значения по умолчанию для контейнера
- Как открыть контейнер
- Как получить значения конфигурации из контейнера
- Передача событий в dataLayer
- Как проверить и опубликовать контейнер
1. Как добавить SDK Google Менеджера тегов в проект
Прежде чем использовать Google Менеджер тегов SDK, распакуйте пакет SDK, добавьте библиотеку в путь сборки проекта и добавьте разрешения в файл AndroidManifest.xml.
Сначала добавьте библиотеку Google Менеджера тегов в папку /libs проекта.
Затем обновите файл AndroidManifest.xml, чтобы использовать следующие разрешения:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
2. Как добавить файл контейнера по умолчанию в проект
При первом запуске приложения Google Менеджер тегов использует контейнер по умолчанию. Контейнер по умолчанию будет использоваться до тех пор, пока приложение не сможет получить новый контейнер по сети.
Чтобы скачать и добавить в приложение двоичный файл контейнера по умолчанию, выполните следующие действия:
- Войдите в веб-интерфейс Google Менеджера тегов.
- Выберите версию контейнера, которую хотите скачать.
- Нажмите кнопку Скачать, чтобы получить двоичный файл контейнера.
- Добавьте двоичный файл по следующему пути:
<project-root>/assets/tagmanager/.
По умолчанию название файла должно совпадать с идентификатором контейнера (например, GTM-1234). После скачивания двоичного файла удалите суффикс версии из его названия, чтобы оно соответствовало правилам.
Хотя рекомендуется использовать двоичный файл, если в контейнере нет правил или тегов, вы можете использовать файл JSON. Файл должен находиться в новой папке /assets/tagmanager проекта для Android и называться <Container_ID>.json. Например, если идентификатор контейнера – GTM-1234, то значения по умолчанию нужно добавить в файл /assets/tagmanager/GTM-1234.json.
3. Открытие контейнера
Прежде чем извлекать значения из контейнера, приложение должно открыть его. При открытии контейнера он загружается с диска (если доступен) или запрашивается из сети (если необходимо).
Проще всего открыть контейнер на устройстве Android с помощью метода ContainerOpener.openContainer(..., Notifier notifier), как показано в примере ниже.
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. } }
В этом примере ContainerOpener.openContainer(..., Notifier notifier) используется для запроса сохраненного контейнера из локального хранилища. Обрабатывая назначение mContainer в обратном вызове containerAvailable, мы гарантируем, что основной поток не будет заблокирован. Если сохраненный контейнер старше 12 часов, вызов также запланирует асинхронный запрос на получение нового контейнера по сети.
В приведенном ниже примере кода показано, как открыть контейнер и получить из него значения с помощью вспомогательного класса ContainerOpener.
Дополнительные варианты реализации описаны в разделе Расширенная настройка.
4. Получение значений конфигурации из контейнера
После открытия контейнера значения конфигурации можно получить с помощью методов get<type>Value():
// Retrieving a configuration value from a Tag Manager Container. // Get the configuration value by key. String title = mContainer.getStringValue("title_string");
Если в запросе указан несуществующий ключ, возвращается значение по умолчанию, соответствующее запрошенному типу:
// 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. Передача значений на уровень данных
DataLayer – это карта, которая позволяет макросам и тегам Менеджера тегов в контейнере получать информацию о работе приложения, например о событиях касания или просмотрах экрана.
Например, если вы передаете информацию о просмотрах экранов в карту DataLayer, то можете настроить в веб-интерфейсе Менеджера тегов активацию пикселей конверсии и вызовы отслеживания в ответ на эти просмотры. При этом вам не нужно будет добавлять их в код приложения.
События передаются на уровень данных с помощью push() и вспомогательного метода 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 }
В веб-интерфейсе можно создать теги (например, теги Google Аналитики), которые будут активироваться при каждом просмотре экрана. Для этого нужно создать следующее правило: равно "openScreen". Чтобы передать название экрана в один из этих тегов, создайте макрос уровня данных, который ссылается на ключ screenName на уровне данных. Вы также можете создать тег (например, пиксель конверсии Google Рекламы), который будет активироваться только при просмотре определенных экранов. Для этого создайте правило, в котором равно "openScreen" && равно "ConfirmationScreen".
6. Предварительный просмотр и публикация контейнера
Значения макросов всегда будут соответствовать текущей опубликованной версии. Перед публикацией последней версии контейнера вы можете посмотреть его проект.
Чтобы просмотреть контейнер, создайте URL предварительного просмотра в веб-интерфейсе Google Менеджера тегов. Для этого выберите версию контейнера, которую вы хотите просмотреть, и нажмите Preview. Сохраните этот URL для последующих этапов.
Затем добавьте в файл AndroidManifest.xml приложения следующий объект Activity:
<!-- 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>
Откройте ссылку на эмуляторе или физическом устройстве, чтобы посмотреть предварительную версию контейнера в приложении.
Когда вы будете готовы сделать значения конфигурации черновика доступными для приложения, опубликуйте контейнер.
Расширенная конфигурация
В Google Менеджере тегов для мобильных приложений есть ряд расширенных настроек, которые позволяют выбирать значения на основе условий выполнения с помощью правил, вручную обновлять контейнер и использовать дополнительные параметры для открытия контейнеров. В следующих разделах описаны некоторые из наиболее распространенных расширенных конфигураций.
Дополнительные параметры для открытия контейнеров
SDK Google Менеджера тегов предоставляет несколько методов открытия контейнеров, которые позволяют лучше контролировать процесс загрузки.
TagManager.openContainer()
TagManager.openContainer() – это самый низкий уровень и наиболее гибкий API для открытия контейнера. Он сразу возвращает контейнер по умолчанию, а также асинхронно загружает контейнер с диска или из сети, если сохраненного контейнера нет или он устарел (сохранен более 12 часов назад).
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. }
В процессе загрузки TagManager.openContainer() выполняет несколько обратных вызовов жизненного цикла, чтобы ваш код мог определить, когда начинается запрос на загрузку, завершается ли он успешно или нет и по какой причине, а также был ли контейнер в конечном итоге загружен с диска или из сети.
Если для вашего приложения не подходят значения по умолчанию, используйте эти обратные вызовы, чтобы узнавать, когда загружен сохраненный или сетевой контейнер. Обратите внимание, что вы не сможете загрузить сохраненный или сетевой контейнер, если приложение запускается впервые и нет подключения к сети.
TagManager.openContainer() передает следующие значения enum в качестве аргументов для этих обратных вызовов:
RefreshType
| Значение | Описание |
|---|---|
Container.Callback.SAVED
|
Запрос на обновление загружает локально сохраненный контейнер. |
Container.Callback.NETWORK
|
Запрос на обновление загружает контейнер по сети. |
RefreshFailure
| Значение | Описание |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
Нет сохраненных контейнеров. |
Container.Callback.IO_ERROR
|
Не удалось обновить контейнер из-за ошибки ввода-вывода. |
Container.Callback.NO_NETWORK
|
Нет подключения к сети. |
Container.Callback.NETWORK_ERROR
|
Произошла ошибка сети. |
Container.Callback.SERVER_ERROR
|
Произошла ошибка сервера. |
Container.Callback.UNKNOWN_ERROR
|
Произошла ошибка, которую не удалось классифицировать. |
Как открыть контейнер, который не используется по умолчанию, или новый контейнер
ContainerOpener является оболочкой для TagManager.openContainer() и предоставляет два удобных метода для открытия контейнеров: ContainerOpener.openContainer(..., Notifier notifier) и ContainerOpener.openContainer(..., Long timeoutInMillis).
Каждый из этих методов принимает перечисление, запрашивающее контейнер, который не является контейнером по умолчанию, или новый контейнер.
Метод OpenType.PREFER_NON_DEFAULT рекомендуется для большинства приложений. Он пытается вернуть первый доступный контейнер, не используемый по умолчанию, в течение заданного периода ожидания (с диска или из сети), даже если этот контейнер был создан более 12 часов назад. Если возвращается устаревший сохраненный контейнер, то также будет выполнен асинхронный сетевой запрос на получение нового контейнера.
Если при использовании OpenType.PREFER_NON_DEFAULT контейнер недоступен или время ожидания истекло, будет возвращен контейнер по умолчанию.
OpenType.PREFER_FRESH пытается вернуть новый контейнер с диска или из сети в течение заданного периода ожидания.
Если сетевое подключение недоступно и/или время ожидания истекло, возвращается сохраненный контейнер.
Не рекомендуется использовать OpenType.PREFER_FRESH в тех случаях, когда более длительное время запроса может заметно повлиять на удобство использования, например при работе с флагами интерфейса или строками отображения. Вы также можете в любой момент использовать Container.refresh(), чтобы принудительно отправить запрос сетевого контейнера.
Оба этих метода не блокируют выполнение кода.
ContainerOpener.openContainer(..., Long timeoutInMillis) возвращает объект ContainerOpener.ContainerFuture, метод get которого возвращает Container сразу после загрузки (но до этого момента блокирует).
Метод ContainerOpener.openContainer(..., Notifier notifier) принимает один обратный вызов, который выполняется, когда контейнер становится доступен. Это позволяет избежать блокировки основного потока.
Для обоих методов период ожидания по умолчанию составляет 2000 мс.
Как оценивать макросы во время выполнения с помощью правил
Контейнеры могут оценивать значения во время выполнения с помощью правил. Правила могут основываться на таких критериях, как язык устройства, платформа или любое другое значение макроса. Например, правила можно использовать для выбора локализованной строки отображения на основе языка устройства во время выполнения. Это можно настроить с помощью следующего правила:
Затем вы можете создать макросы сбора значений для каждого языка и добавить это правило в каждый макрос, вставив соответствующий код языка. После публикации контейнера приложение сможет показывать локализованные строки в зависимости от языка устройства пользователя.
Если для контейнера по умолчанию требуются правила, используйте двоичный файл контейнера.
Подробнее о настройке правил (Справочный центр)…
Двоичные файлы контейнера по умолчанию
Если для контейнеров по умолчанию требуются правила, используйте двоичный файл контейнера вместо файла JSON. В отличие от файлов JSON, двоичные контейнеры поддерживают определение значений макросов во время выполнения с помощью правил Google Менеджера тегов.
Двоичные файлы контейнеров можно скачать из веб-интерфейса Google Менеджера тегов и добавить в папку /assets/tagmanager/ проекта. Название файла должно соответствовать шаблону /assets/tagmanager/GTM-XXXX, где вместо идентификатора контейнера указывается его значение.
Если в приложении есть и JSON-файл, и двоичный файл контейнера, SDK будет использовать двоичный файл контейнера по умолчанию.
Как использовать макросы вызова функций
Макросы вызова функции – это макросы, которые задаются для возвращаемого значения определенной функции в вашем приложении. Макросы вызова функций можно использовать для включения значений времени выполнения в правила Google Менеджера тегов, например для определения того, какую цену показывать пользователю в зависимости от настроенного языка и валюты устройства.
Чтобы настроить макрос вызова функции, выполните следующие действия:
- Определите макрос вызова функции в веб-интерфейсе Google Менеджера тегов. Аргументы можно настроить как пары "ключ-значение".
- Зарегистрируйте
FunctionCallMacroHandlerв приложении с помощьюContainer.registerFunctionCallMacroHandler()и названия функции, заданного в веб-интерфейсе Google Менеджера тегов, переопределив метод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; } });
Как использовать теги вызова функции
Теги вызова функций позволяют выполнять предварительно зарегистрированные функции, когда событие передается на уровень данных и правила тега возвращают значение true.
Чтобы настроить тег вызова функции, выполните следующие действия:
- Определите тег вызова функции в веб-интерфейсе Google Менеджера тегов. Аргументы можно настроить как пары "ключ-значение".
- Зарегистрируйте обработчик тегов вызова функции в приложении с помощью
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. } } });
Как задать собственный период обновления
Если контейнер не обновлялся более 12 часов, SDK Google Менеджера тегов попытается получить новую версию. Чтобы задать собственный период обновления контейнера, используйте Timer, как в следующем примере:
timer.scheduleTask(new TimerTask() { @Override public void run() { mContainer.refresh(); } }, delay, <new_period_in milliseconds>);
Отладка с помощью Logger
По умолчанию SDK Google Менеджера тегов записывает ошибки и предупреждения в журналы.
Чтобы включить ведение подробных журналов, которое может быть полезно для отладки, реализуйте собственный класс Logger с помощью TagManager.setLogger, как показано в примере ниже.
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. });
Вы также можете задать LogLevel для существующего Logger с помощью TagManager.getLogger().setLogLevel(LogLevel), как в этом примере:
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);