Эта страница переведена с помощью Cloud Translation API.

Как создать тег сервера

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

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

Серверные контейнеры имеют три встроенных тега, готовых к использованию без дополнительной настройки:

Google Аналитика 4
Google Analytics: универсальная аналитика
HTTP-запрос

Если вы хотите отправить данные в другое место, кроме Google Analytics, или вам нужно больше функций, чем предоставляет тег HTTP-запроса, вам нужно использовать другой тег. Вы можете найти дополнительные теги в галерее шаблонов сообщества или написать свои собственные. Этот учебник научит вас основам написания собственных тегов для серверного контейнера.

Цели

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

Предпосылки

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

Тег Baz Analytics

В этом руководстве вы создадите тег, который отправляет данные измерений в службу под названием Baz Analytics.

Baz Analytics — это простая гипотетическая аналитическая служба, которая получает данные через HTTP-запросы GET на https://example.com/baz_analytics . Он имеет следующие параметры:

Параметр	Пример	Описание
я бы	БА-1234	Идентификатор вашей учетной записи Baz Analytics.
en	нажмите	Название события.
л	`https://www.google.com/search?q=sgtm`	URL страницы, на которой произошло событие.
ты	2384294892	ID пользователя, выполняющего действие. Используется для привязки нескольких действий к одному пользователю.

Конфигурация тега

Первое, что нужно сделать, это создать шаблон тега. Перейдите в раздел « Шаблоны » вашего контейнера и нажмите « Создать » в разделе « Шаблоны тегов ». Добавьте имя и описание к тегу.

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

Общая конфигурация : добавьте поле конфигурации для каждого параметра. Требовать, чтобы пользователь устанавливал все явно.
Нет конфигурации : нет никаких параметров для настройки тега. Все данные берутся непосредственно из события.
Некоторая конфигурация : есть поля для одних параметров, а не для других.

Наличие полей для каждого параметра очень гибко и дает пользователю полный контроль над конфигурацией своего тега. Однако на практике это обычно приводит к большому количеству дублированной работы. В частности, такие вещи, как параметр Baz Analytics l , который содержит URL-адрес страницы, являются однозначными и универсальными. Ввод одних и тех же неизменных данных каждый раз при настройке тега лучше оставить на усмотрение компьютера.

Возможно, ответ заключается в том, чтобы иметь тег, который берет данные только из события. Это самый простой из возможных тегов для настройки пользователем, поскольку на самом деле ему нечего делать. С другой стороны, это также самый ограничительный и хрупкий вариант. Пользователи не могут изменить поведение тега, даже если им это необходимо. Например, может быть, они называют это событие purchase на своем веб-сайте и в Google Analytics, но Baz Analytics называет это buy . Или, возможно, предположения, которые тег делает о структуре входящих данных события, на самом деле не соответствуют действительности. В любом случае пользователь застревает.

Как и во многих других случаях, ответ лежит где-то между двумя крайностями. Некоторые данные имеет смысл всегда брать с мероприятия. Другие данные должны быть настроены пользователем. Как вы решаете, что есть что? Чтобы ответить на этот вопрос, нам нужно более внимательно изучить данные, поступающие в контейнер.

Откуда берутся данные?

Данные, поступающие в серверный контейнер из тега Google Analytics 4, можно условно разделить на две категории: указанные пользователем данные и автоматически собираемые данные.

Указанные пользователем данные — это все, что пользователь вводит в команду event gtag.js. Например, такая команда:

gtag('event', 'search', {
  search_term: 'beets',
});

Приведет к следующим параметрам в контейнере сервера:

{
  event_name: 'search',
  search_term: 'beets',
}

Это достаточно просто, но с точки зрения тега с этим очень сложно работать. Поскольку эти данные вводятся пользователем, это может быть что угодно. Возможно, как указано выше, пользователь отправляет только рекомендуемые события и параметры, но это не обязательно. За важным исключением расположения (но не значения!) параметра event_name нет никаких гарантий относительно формы или структуры данных пользователя.

К счастью, введенные пользователем данные — не единственное, что получит контейнер. Он также получит кучу данных, которые автоматически собираются тегом Google Analytics 4 в браузере. Это включает:

ip_override
language
page_location
page_referrer
page_title
screen_resolution
user_agent

Кроме того, если запрос к серверу поступает из веб-браузера, данные cookie браузера также могут быть доступны через API getCookieValue .

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

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

Имея это в виду, еще раз взгляните на параметры тега Baz Analytics.

Идентификатор измерения, id : поскольку он не собирается автоматически, это наглядный пример значения, которое пользователь должен ввести при настройке тега.
Название события, en : Как упоминалось выше, имя события всегда можно взять непосредственно из параметра event_name . Однако, поскольку его значение определяется пользователем, хорошей идеей будет предложить возможность переопределения имени, если это необходимо.
URL страницы, l : это значение можно взять из параметра page_location , который автоматически собирается тегом браузера Google Analytics GA4 при каждом событии. Поэтому не следует требовать от пользователя ввода значения вручную.
Идентификатор пользователя, u : в серверном теге Baz Analytics параметр u не указывается пользователем и не собирается тегом на странице автоматически. Вместо этого он сохраняется в файле cookie браузера, чтобы пользователи могли быть идентифицированы при многократном посещении веб-сайта. Как вы увидите в приведенной ниже реализации , именно серверный тег Baz Analytics использует API setCookie для установки файла cookie. Это означает, что тег Baz Analytics — единственное, что знает, где и как хранится файл cookie. Как и l , параметр u должен собираться автоматически.

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

Снимок конфигурации тега для тега Baz Analytics.

Реализация тега

Теперь, когда конфигурация тега определена, вы готовы перейти к реализации его поведения в изолированном JavaScript.

Тег должен делать четыре вещи:

Получите имя события из конфигурации тега.
Получите URL-адрес страницы из свойства page_location события.
Вычислить идентификатор пользователя. Тег будет искать идентификатор пользователя в файле cookie с именем _bauid . Если этот файл cookie отсутствует, тег вычислит новое значение и сохранит его для последующих запросов.
Создайте URL-адрес и отправьте запрос на сервер сбора данных Baz Analytics.

Также стоит подумать о том, как тег вписывается в контейнер в целом. Разные компоненты контейнера играют разные роли, поэтому есть вещи, которые тег не делает или не должен делать. Ваш тег:

Не следует проверять событие, чтобы выяснить, должно ли оно выполняться. Вот для чего нужен триггер.
Не следует запускать контейнер с помощью runContainer API. Это работа клиента.
За исключением важных файлов cookie, он не должен пытаться напрямую взаимодействовать с запросом или ответом. Это тоже работа клиента.

Написание шаблона тега, который делает любую из этих вещей, может привести к запутанному поведению пользователей вашего тега. Например, тег, который отправляет ответ на входящий запрос, не позволит клиенту сделать то же самое. Это нарушит ожидания пользователей относительно того, как должен вести себя контейнер.

Имея все это в виду, ниже приведена аннотированная реализация тега в изолированной программной среде JS.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

При этом тег реализован. Прежде чем вы сможете использовать тег, вам необходимо правильно установить его разрешения API. Перейдите на вкладку « Разрешения » редактора шаблонов и укажите следующие разрешения:

Читает значения cookie: _bauid
Читает данные события: event_name и page_location
Отправляет HTTP-запросы: https://www.example.com/*
Устанавливает куки: _bauid

Вы также должны написать тесты для своего тега. Чтобы узнать больше о тестировании шаблонов, прочтите раздел тестов в руководстве разработчика шаблонов.

Наконец, не забудьте хотя бы один раз запустить свой тег с помощью кнопки « Выполнить код» . Это предотвратит попадание многих простых ошибок на ваш сервер.

Отправьте свой тег в галерею шаблонов сообщества

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

Вывод

В этом руководстве вы изучили основы написания тега для серверного контейнера. Ты выучил:

Какие API использовать для чтения данных о событиях, отправки HTTP-запросов и установки файлов cookie в браузере.
Рекомендации по разработке параметров конфигурации для тега.
Разница между данными, указанными пользователем, и автоматически собираемыми данными и почему это различие важно.
Роль тега в контейнере; что он должен и не должен делать.
Когда и как отправлять шаблоны тегов в галерею шаблонов сообщества .