- Вы отправляете статистику поставщику или кому-то внутри компании?
- Определение данных конфигурации
- Проверка
- Аналитика для компонентов AMP
amp-analytics
Получает статистические данные из AMP-документа.
Скрипт | <script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script> |
Примеры | См. пример на сайте ampbyexample.com. |
Вы отправляете статистику поставщику или кому-то внутри компании?
Прежде чем изучать показатели AMP на своем сайте, определитесь, какие инструменты для анализа поведения пользователей вы будете применять: сторонние или собственные.
приведена в руководстве по настройке на сайте для разработчиков.
Отправка данных поставщику
Сервис Google Analytics для AMP специально создан, чтобы можно было проанализировать данные один раз и отправить отчет всем заинтересованным лицам. Если вы уже сотрудничаете с одним или несколькими поставщиками аналитических решений, убедитесь, что они есть в нашем списке тех, кто поддерживает технологию AMP.
Если все в порядке, выполните следующие действия:
- Добавьте в тег
<amp-analytics>
атрибутtype
и в качестве значения укажите название поставщика. - Определитесь с тем, какие данные вы хотите отслеживать, и соответствующим образом настройте конфигурацию. Более подробную информацию можно найти в документации поставщика.
Если ваш поставщик не поддерживает AMP, обратитесь за помощью к его представителям. Мы также рекомендуем вам сообщить авторам проекта AMP о том, что необходимо добавить нового поставщика. Ознакомьтесь с руководством по интеграции аналитических инструментов с AMPHTML. Кроме того, вы можете совместно с поставщиком настроить отправку данных на определенный URL. См. раздел Отправка данных внутри компании ниже.
Пример: отправка данных стороннему поставщику аналитических решений
Предположим, мы отправляем данные компании Nielsen, у которой налажена интеграция с AMP. Более подробные сведения о конфигурации приведены в документации Nielsen.
<amp-analytics type="nielsen"> <script type="application/json"> { "vars": { "apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "apv": "1.0", "apn": "My AMP Website", "section": "Entertainment", "segA": "Music", "segB": "News", "segC": "Google AMP" } } </script> </amp-analytics>
Отправка данных внутри компании
Если у вас есть собственное решение для анализа взаимодействия с пользователями, то для интеграции этого решения с Google Analytics для AMP будет достаточно одного URL. Это ссылка, по которой необходимо отправлять данные. Таких URL может быть и несколько: например, отдельные ссылки для статистики о просмотрах страницы и о поведении пользователей в социальных сетях.
Если ваше внутреннее решение предполагает работу с поставщиком, который не поддерживает AMP, обратитесь за помощью к его представителям. Уточните, какие сведения нужны для конфигурации.
Чтобы настроить отправку данных по определенному URL, выполните следующие действия:
- Определитесь с тем, какие данные вы хотите отслеживать, и соответствующим образом настройте конфигурацию.
- В объекте конфигурации
requests
укажите, какие типы запросов вы хотите отслеживать (например, просмотры страниц или конкретные события с триггерами), а также URL, куда следует отправлять полученные данные.
Игнорируйте параметр usqp
при обработке URL в заголовке запроса. Этот параметр используется Google для запуска экспериментов в Google AMP Cache.
Пример: отправка данных по определенному URL
Рассмотрим простой пример: отслеживание просмотров страницы. Каждый раз, когда страница отображается, активируется триггер события. Данные о просмотре определяются по указанному URL, при этом им случайным образом присваивается идентификатор.
<amp-analytics> <script type="application/json"> { "requests": { "pageview": "https://foo.com/pixel?RANDOM" }, "triggers": { "trackPageview": { "on": "visible", "request": "pageview" } } } </script> </amp-analytics>
О распространенных вариантах отслеживания, таких как просмотры, клики, прокрутка и т. д., читайте в этом руководстве.
Определение данных конфигурации
В элементе <amp-analytics>
необходимо задать объект конфигурации JSON, в котором указано, какую статистику нужно собирать и куда ее отправлять.
Объект конфигурации <amp-analytics>
имеет следующий формат:
{ "requests": { request-name: request-value, ... }, "vars": { var-name: var-value, ... }, "extraUrlParams": { extraurlparam-name: extraurlparam-value, ... }, "triggers": { trigger-name: trigger-object, ... }, "transport": { "beacon": *boolean*, "xhrpost": *boolean*, "image": *boolean*, } }
Встроенная или удаленная конфигурация
Сведения о конфигурации можно указать непосредственно в коде или же добавить атрибут config
с URL, откуда система будет их извлекать. Кроме того, вы можете выбрать встроенную конфигурацию для популярных поставщиков аналитических решений с помощью атрибута type
.
Если используются сведения о конфигурации из нескольких источников, то объекты (переменные, запросы и триггеры) будут объединены таким образом:
- Удаленная конфигурация имеет приоритет над встроенной.
- Встроенная конфигурация имеет приоритет над конфигурацией поставщика.
Загрузка удаленной конфигурации
Чтобы загрузить удаленную конфигурацию, в элементе <amp-analytics>
разместите атрибут config
и добавьте URL данных конфигурации. URL должен начинаться с HTTPS и может включать переменные AMP. Чтобы получить доступ к файлам cookie, воспользуйтесь атрибутом data-credentials
. Ответ должен быть оформлен в соответствии с требованиями по безопасности в отношении CORS и AMP.
Вот пример атрибута config
для загрузки данных с указанного URL:
<amp-analytics config="https://example.com/analytics.account.config.json">
Функция перезаписи конфигурации
Функция перезаписи конфигурации позволяет поставщикам аналитических решений динамически вносить изменения в конфигурацию. Это похоже на удаленную конфигурацию, только в запрос, который отправляется на сервер, добавляются ещё пользовательские настройки. В настоящее время такую функцию может включить только поставщик.
Для этого поставщик указывает свойство configRewriter с URL сервера:
export const VENDOR_ANALYTICS_CONFIG = { ... 'configRewriter': { 'url': 'https://www.vendor.com/amp-config-rewriter', }, ... }
Среда выполнения отправляет запрос, где встроенная конфигурация объединена с удаленной, в конечную точку configRewriter, указанную поставщиком. На стороне сервера создается новая конфигурация, которая отправляется обратно.
Затем среда выполнения объединяет все предоставленные конфигурации, чтобы выбрать нужную с учетом приоритета:
- Переопределенная конфигурация.
- Встроенная конфигурация.
- Конфигурация, заданная поставщиком.
Группы переменных
Группы переменных – это функция, которая позволяет поставщикам аналитических решений группировать определенный набор переменных. Такие переменные может с легкостью включить пользователь. При этом они будут разрешены и отправлены в указанную конечную точку – configRewriter
.
Чтобы включить эту функцию, поставщикам необходимо создать новый объект varGroups
в конфигурации configRewriter
. После этого можно будет добавить в нее любые именованные группы varGroups
, созданные поставщиком. Поддерживаются все переменные, описанные в этом руководстве. Важно! Варианты в формате ${varName} не поддерживаются.
Рассмотрим пример конфигурации для поставщика:
// This is predefined by vendor. export const VENDOR_ANALYTICS_CONFIG = { ... 'configRewriter': { 'url': 'https://www.vendor.com/amp-config-rewriter', 'varGroups' : { 'group1': { 'referrer': 'DOCUMENT_REFERRER', 'source': 'SOURCE_URL', 'group2': { 'title': 'TITLE', }, }, }, }, ... }
Вы можете включить определенные группы переменных, добавив значение {enabled: true}
для объекта varGroups
в конфигурации <amp-analytics>
. Ключевое слово enabled
зарезервировано и его нельзя использовать в качестве названия переменной.
В примере ниже включены две группы: group1
и group2
. Если группа не указана в коде, она игнорируется. Среда выполнения разрешает все включенные переменные и объединяет их в объект configRewriter.vars
, который затем отправляется по URL для переопределения конфигурации.
/* Included on publisher page */ <amp-analytics type="myVendor" id="myVendor" data-credentials="include"> <script type="application/json"> { "configRewriter": { "varGroups": { "group1": { "enabled": true }, "group2": { "enabled": true } } } } </script> </amp-analytics>
В этом случае запрос будет выглядеть примерно так:
/* Sent to configuration rewriter server. */ "configRewriter": { "vars": { "referrer": "https://www.example.com", "source": "https://www.amp.dev", "title": "Cool Amp Tips" } }
Объекты данных для конфигурации
Запросы
Объект конфигурации requests
определяет URL для передачи данных на аналитическую платформу, а также массовой обработки данных запроса и создания отчета. Объект request-name
определяет, какой запрос следует отправить в ответ на конкретное событие (например, pageview
, event
и т. д.) . Объект request-value
содержит URL, защищенный протоколом HTTPS. Значение также может содержать токены-заполнители, ссылающиеся на другие запросы или переменные. Объект request-value
может включать необязательные конфигурации запроса.
Конфигурация запросов
Ресурсы для определения запроса с объектом:
baseUrl
: определяет URL запроса (обязательно).reportWindow
: определяет время, когда нужно прекратить запросы отчетов (в секундах, необязательно). Триггер со значениемimportant: true
переопределяет максимальный период для создания отчетов.
В этом примере все запросы действительны.
"requests": { "base": "https://example.com/analytics?a=${account}&u=${canonicalUrl}&t=${title}", "pageview": { "baseUrl": "${base}&type=pageview" }, "event": { "baseUrl": "${base}&type=event&eventId=${eventId}", "batchInterval": 5, "reportWindow" : 30 } }
У некоторых поставщиков аналитических решений есть готовая конфигурация, которой можно воспользоваться с помощью атрибута type
. В таких случаях информация о запросах требуется не всегда. Ознакомьтесь с документацией поставщика, чтобы узнать, нужно ли настраивать запросы и как это сделать.
Серийные запросы
Чтобы уменьшить количество запросов ping, вы можете настроить серийные запросы в конфигурации. Любые элементы extraUrlParams
из объекта triggers
, в которых используется тот же запрос, добавляются к адресу baseUrl
запроса.
Вот свойства серийных запросов
batchInterval
: это свойство определяет временной интервал (в секундах) для сброса запросов ping в серии. СвойствоbatchInterval
может представлять собой число или массив чисел. Минимальный интервал составляет 200 мс. Запрос учитывает каждое значение в массиве, а затем в самом конце повторяет последнее или единственное значение интервала.
Ниже приведен конфигурации, которая отправляет один запрос ping каждые 2 секунды, с одним примером такого запроса https://example.com/analytics?rc=1&rc=2
.
"requests": { "timer": { "baseUrl": "https://example.com/analytics?", "batchInterval": 2, } } "triggers": { "timer": { "on": "timer", "request" : "timer", "timerSpec": { "interval": 1 }, "extraUrlParams": { "rc": "${requestCount}" } } }
А вот пример, в котором первый запрос ping выполняется через 1 секунду, а последующие – каждые 3 секунды. Первый запрос при этом выглядит так: https://example.com/analytics?rc=1
, а второй – так: https://example.com/analytics?rc=2&rc=3&rc=4
.
"requests": { "timer": { "baseUrl": "https://example.com/analytics?", "batchInterval": [1, 3], } } "triggers": { "timer": { "on": "timer", "request" : "timer", "timerSpec": { "interval": 1 }, "extraUrlParams": { "rc": "${requestCount}" } } }
Переменные
Компонент amp-analytics
определяет многие основные переменные, которые можно использовать в запросах. Они перечислены в руководстве по переменным amp-analytics
. Поддерживаются также все переменные, описанные в этом руководстве.
С помощью объекта конфигурации vars
можно задать новые пары "ключ-значение" или переопределить существующие, которые используются в значениях request
. Новые переменные часто применяются для указания данных, касающихся издателя. Чтобы указать список значений, которые нужно отдельно закодировать в URL, но сохранить разделители-запятые, можно воспользоваться массивом.
"vars": { "account": "ABC123", "countryCode": "tr", "tags": ["Swift,Jonathan", "Gulliver's Travels"] }
Дополнительные параметры для URL
Объект extraUrlParams
в конфигурации определяет дополнительные параметры, которые необходимо включить в запрос. По умолчанию они добавляются в строку запроса в формате "&параметр=значение".
Вот пример, в котором к запросу добавляется строка &a=1&b=2&c=3
:
"extraUrlParams": { "a": "1", "b": "2", "c": "3" }
Объект extraUrlParams
может быть отправлен не в URL, а в теле запроса, если включена функция useBody
и запрос передается с помощью методов beacon
или xhrpost
. В этом случае параметры не кодируются и не преобразуются в строку. Подробнее об этом читайте в разделе Передача дополнительных параметров URL в теле запроса.
Атрибут extraUrlParamsReplaceMap
содержит карту ключей и значений, которые действуют как параметры для String.replace()
и используются для предварительной обработки ключей в конфигурации extraUrlParams
. Например, если конфигурация extraUrlParams
определяет "page.title": "The title of my page"
, а extraUrlParamsReplaceMap
определяет "page.": "_p_"
, то к запросу будет добавлена строка &_p_title=The%20title%20of%20my%20page%20
.
Атрибут extraUrlParamsReplaceMap
не обязателен для использования extraUrlParams
. Если он` не определен, то замены не происходит и строки, определенные в
extraUrlParams`, применяются как есть.
Если включен параметр useBody
и запрос отправлен методом beacon
или xhrpost
, то замена строки extraUrlParamsReplaceMap
будет использоваться только для ключей верхнего уровня в extraUrlParams
.
Триггеры
Объект triggers
в конфигурации определяет, когда должен быть отправлен запрос данных. Атрибут triggers
содержит пару "ключ-значение": название триггера и его конфигурацию. Названием триггера может быть любой текст из букв и цифр (a–z, A–Z, 0–9). Триггеры из конфигурации с меньшим приоритетом переопределяются одноименными триггерами из более приоритетной конфигурации.
on
– событие для прослушивания (обязательно). Допустимые значения:render-start
,ini-load
,click
,scroll
,timer
,visible
,hidden
,user-error
,access-*
иvideo-*
.request
– название отправляемого запроса в соответствии с разделомrequests
(обязательно).vars
– объект с парами "ключ-значение", которые переопределяют значенияvars
, заданные в конфигурации более высокого уровня. Также используется для указания уникальных переменных для данного триггера.important
– объект, который можно указать для работы с серийными запросами или отчетами за определенный период. Задайте дляimportant
значениеtrue
, чтобы сбросить очередь пакетных запросов с определенными триггерами. В данном случае вы можете сократить количество запросов ping, не теряя данных о важных событиях-триггерах. Таким же образом можно переопределить значение````reportWindow
и отправлять важные запросы ping независимо от него.selector
иselectionMethod
поддерживаются для некоторых триггеров, например для вариантовclick
иvisible
. Подробнее об этом вы можете узнать в разделе Селектор элементов ниже.scrollSpec
– конфигурация, которая используется вместе с триггеромscroll
(обязательно, если дляon
задано значениеscroll
). Ниже приведена более подробная информация.timerSpec
– конфигурация, которая используется вместе с триггеромtimer
(обязательно, если дляon
задано значениеtimer
). Ниже приведена более подробная информация.sampleSpec
– объект, который определяет, как выбираются запросы перед отправкой. Для создания выборки используется случайный ввод или другие переменные, которые поддерживаются платформой. Объект содержит конфигурацию для определения входных данных, которые используются для создания хеша, а также пороговое значение, которому хеш должен соответствовать.sampleOn
– шаблон строки, который расширяется за счет заполнения переменных платформы, а затем хешируется, чтобы сгенерировать число. Это число применяется при создании выборки с учетом порогового значения, описанного ниже.threshold
– конфигурация, которая применяется для фильтрования запросов, не соответствующих определенным критериям. Чтобы запрос прошел проверку поставщика, необходимо использовать следующую логику:HASH(sampleOn) < threshold
.
videoSpec
– конфигурация, которая используется вместе с триггерамиvideo-*
(обязательно, если дляon
задано значениеvideo-*
).
Вот пример конфигурации, которую можно использовать для отбора 50 % запросов с применением случайного ввода или 1 % запросов с учетом идентификаторов клиентов.
'triggers': { 'sampledOnRandom': { 'on': 'visible', 'request': 'request', 'sampleSpec': { 'sampleOn': '${random}', 'threshold': 50, }, }, 'sampledOnClientId': { 'on': 'visible', 'request': 'request', 'sampleSpec': { 'sampleOn': '${clientId(cookieName)}', 'threshold': 1, }, }, },
Селектор элементов
Некоторые триггеры, такие как click
и visible
, позволяют указать как один, так и несколько элементов. Для этого используются свойства-селекторы. В зависимости от типа триггера к выбранным элементам могут применяться различные ограничения и интерпретации. Например, селектор может затрагивать все подходящие элементы или только один, а в список подходящих могут попадать все элементы или только AMP. Подробнее о каждом типе триггера читайте ниже.
Свойства селектора:
selector
: свойство, которое используется для поиска элемента или подборки при помощи запроса CSS/DOM. Семантику соответствия элемента можно изменить с помощью атрибутаselectionMethod
. У этого свойства есть варианты значений:#ad1
илиamp-ad
;:root
(специальный селектор, соответствующий корню документа).
selectionMethod
: свойство с одним или двумя значениями (scope
и/илиclosest
). Значениеscope
позволяет выбрать элемент в родительском элементе тегаamp-analytics
. Значениеclosest
выполняет поиск ближайшего родительского значения для тегаamp-analytics
, который соответствует заданному селектору. Значение по умолчанию –scope
.
Встроенный триггер начала отрисовки
Элементы AMP, которые встраивают другие документы в окна iframe (например, объявления), могут сообщать о начале отрисовки ("on": "render-start"
). Как правило, это событие регистрируется при первой возможности подтвердить, что отрисовка встроенного документа началась. Чтобы узнать, генерирует ли определенный элемент AMP такое событие, обратитесь к документации.
Триггер для встроенного элемента должен включать свойство selector
, которое указывает на встроенный элемент:
"triggers": { "renderStart": { "on": "render-start", "request": "request", "selector": "#embed1" } }
Событие начала отрисовки также генерируется самим документом. Можно использовать следующую конфигурацию:
"triggers": { "renderStart": { "on": "render-start", "request": "request" } }
Триггер начальной загрузки
Событие начальной загрузки ("on": "ini-load"
) активируется, когда стартует загрузка контента в элементе или документе AMP.
"Начальная загрузка" определяется в зависимости от контейнера и его исходного размера. Особенности:
- Для документа: все элементы в первой области просмотра.
- Для встроенного элемента: все элементы контента во встроенном документе, которые расположены в пределах начального размера.
- Для простого элемента AMP (например,
amp-img
): сами ресурсы, такие как изображения и видео.
Триггер для встроенного или AMP-элемента должен включать свойство selector
, которое указывает на элемент:
"triggers": { "iniLoad": { "on": "ini-load", "request": "request", "selector": "#embed1" } }
Событие начальной загрузки также генерируется самим документом. Можно использовать следующую конфигурацию:
"triggers": { "iniLoad": { "on": "ini-load", "request": "request" } }
Триггер видимости страницы и элемента
Используйте триггер видимости ("on": "visible"
), чтобы активировать запрос, когда страница отображается. Настроить активацию этого триггера можно с помощью спецификации visibilitySpec
.
"triggers": { "defaultPageview": { "on": "visible", "request": "pageview", } }
Триггер видимости элемента можно с помощью селектора (selector
) настроить для любого элемента AMP или для корня документа. Триггер будет активироваться, когда указанный элемент соответствует параметрам видимости, заданным в visibilitySpec
.
"triggers": { "defaultPageview": { "on": "visible", "request": "elementview", "selector": "#ad1", "visibilitySpec": {/* optional visibility spec */} } }
Учтите, что с помощью селектора можно задать один элемент, но не подборку. Это может быть расширенный элемент AMP или корень документа.
Триггер видимости элемента активируется по сигналу, указанному в свойстве waitFor
спецификации visibilitySpec
. Если для waitFor
не задано значение, активация происходит по сигналу ini-load
. Более подробные сведения приведены в документации для waitFor
.
Если задано значение для reportWhen
, триггер отправляет данные о событии только после этого сигнала. Это полезно, например, если вам нужно получать данные о событиях, когда страница закрыта.
Триггер ошибки
Событие пользовательской ошибки ("on": "user-error"
) активируется, когда происходит ошибка, связанная с автором страницы или программным обеспечением, которое используется для публикации контента. Примеры: неверные настройки объявлений или компонента AMP, ошибка в утверждениях. Сведения о пользовательских ошибках также доступны в консоли разработки.
"triggers": { "userError": { "on": "user-error", "request": "error" } }
Существует известная проблема – триггер отправляет данные об ошибках из встроенных окон iframe A4A, которые не связаны со страницей.
Спецификация visibilitySpec
– это набор условий и свойств, которые можно задать для триггеров visible
и hidden
, чтобы изменить условия активации. Если задано несколько свойств, у всех них должно быть значение true, иначе запрос не активируется. Спецификация visibilitySpec
поддерживает следующие свойства:
waitFor
: это свойство указывает, что триггер видимости должен ждать определенного сигнала перед началом отслеживания. Допустимые значения:none
,ini-load
иrender-start
. Если селектор добавлен, но значение не задано, по умолчанию используется вариантini-load
, если же селектора нет –none
.reportWhen
: это свойство указывает, что триггер видимости должен ждать определенного сигнала перед отправкой данных. Единственное допустимое значение:documentExit
. СвойстваreportWhen
иrepeat
можно использовать в рамках одной спецификации. Учтите, что при наличии свойстваreportWhen
отчет отправляется тогда, когда регистрируется сигнал (даже если требования к видимости не были соблюдены в настоящий момент или ранее). Все соответствующие переменные (totalVisibleTime
и т. п.) будут сформированы с учетом требований к видимости в спецификацииvisibilitySpec
.continuousTimeMin
andcontinuousTimeMax
: свойства, которые указывают, что запрос должен быть активирован, если любая часть элемента непрерывно показывалась в области просмотра в течение любого времени между указанными пределами. Время выражается в миллисекундах. Если значение дляcontinuousTimeMin
не задано, по умолчанию используется 0.totalTimeMin
иtotalTimeMax
: свойства, которые указывают, что запрос должен быть активирован, если любая часть элемента показывалась в области просмотра в течение определенного времени между указанными пределами. Время выражается в миллисекундах. Если значение дляtotalTimeMin
не задано, по умолчанию используется 0.visiblePercentageMin
иvisiblePercentageMax
: свойства, которые указывают, что запрос должен быть активирован, когда в области просмотра показывается определенная доля элемента. Поддерживаются значения процентов от 0 до 100. Учтите, что верхняя граница (visiblePercentageMax
) используется включительно. Нижняя граница (visiblePercentageMin
) не включается в данные, если только оба свойства не равны 0 или 100. Если они равны 0, триггер активируется, когда элемент невидим. Если 100 – при полной видимости элемента. Если определены также и другие свойства, связанные со временем, учитывается только то время, когда они были соблюдены. Значения по умолчанию дляvisiblePercentageMin
иvisiblePercentageMax
– 0 и 100 соответственно.repeat
: если для этого свойства задано значениеtrue
, триггер активируется каждый раз, когда соблюдаются условия спецификацииvisibilitySpec
. В примере ниже триггер срабатывает дважды: элемент виден на 51 %, а потом на 49 % и снова на 50 %. Если было бы задано значениеfalse
, тег сработал бы только один раз. По умолчанию дляrepeat
задано значениеfalse
. СвойстваreportWhen
иrepeat
нельзя одновременно использовать в конфигурации visibilitySpec.
visibilitySpec: { visiblePercentageMin: 50, repeat: true, }
С помощью visiblePercentageThresholds
можно быстро создать несколько конфигураций visibilitySpec
, которые отличаются только значениями visiblePercentageMin
и visiblePercentageMax
. Пример:
// Два триггера с конфигурациями visibilitySpec, которые отличаются только значениями visiblePercentageMin и visiblePercentageMax: "triggers": { "pageView_30_to_40": { "on": "visible", "request": "pageview", "selector": "#ad1", "visibilitySpec": { "visiblePercentageMin": 30, "visiblePercentageMax": 40, "continuousTimeMin": 1000, } } "pageView_40_to_50": { "on": "visible", "request": "pageview", "selector": "#ad1", "visibilitySpec": { "visiblePercentageMin": 40, "visiblePercentageMax": 50, "continuousTimeMin": 1000, } } } // Один триггер, эквивалентный обоим, приведенным выше: "triggers": { "pageView": { "on": "visible", "request": "pageview", "selector": "#ad1", "visibilitySpec": { "visiblePercentageThresholds": [[30, 40], [40, 50]], "continuousTimeMin": 1000, } } }
Помимо условий, перечисленных выше, в visibilitySpec
также используются некоторые переменные. Прочитать о них можно здесь.
"triggers": { "defaultPageview": { "on": "visible", "request": "pageview", "selector": "#ad1", "visibilitySpec": { "waitFor": "ini-load", "reportWhen": "documentExit", "visiblePercentageMin": 20, "totalTimeMin": 500, "continuousTimeMin": 200 } } }
Помимо переменных, указанных в триггерах, вы можете также задать дополнительные свойства или переопределить переменные как атрибуты данных. Эти атрибуты должны быть частью элемента, заданного как selector
.
Триггер клика
Триггер клика ("on": "click"
) отправляет запрос, когда регистрируется нажатие на указанный элемент. Используйте selector
, чтобы обозначить, какие это будут элементы. Триггер будет активироваться для всех элементов, соответствующих условиям в селекторе.
"vars": { "id1": "#socialButtonId", "id2": ".shareButtonClass" }, "triggers": { "anchorClicks": { "on": "click", "selector": "a, ${id1}, ${id2}", "request": "event", "vars": { "eventId": 128 } } }
Помимо переменных, указанных в триггерах, вы можете также задать дополнительные свойства или переопределить переменные как атрибуты данных. Эти атрибуты должны быть частью элемента, заданного как selector
.
Триггер прокрутки
Триггер прокрутки ("on": "scroll"
) отправляет запрос, когда страница прокручивается при определенных условиях. Вы можете задать специальные переменные для этого. Используйте спецификацию scrollSpec
, чтобы настроить активацию:
- Спецификация
scrollSpec
может содержать свойстваverticalBoundaries
иhorizontalBoundaries
. Для активации тега прокрутки необходимо задать хотя бы одно свойство из двух. Значения в обоих случаях представляют собой массивы чисел, содержащие пределы, при которых происходит активация. В примере ниже событие регистрируется, когда страница прокручивается по вертикали на 25, 50 и 90 %, а также когда она прокручивается по горизонтали на 90% ширины. Для повышения эффективности числа округлены до кратных5
.
"triggers": { "scrollPings": { "on": "scroll", "scrollSpec": { "verticalBoundaries": [25, 50, 90], "horizontalBoundaries": [90] }, "request": "event" } }
Триггер таймера
Триггер таймера ("on": "timer"
) отправляет запросы с указанной регулярностью. Используйте спецификацию timerSpec
, чтобы настроить активацию:
- Спецификация
timerSpec
предназначена для триггеров типаtimer
. ЕслиstartSpec
отсутствует, таймер будет срабатывать сначала сразу же (по умолчанию, можно отменить), а затем с указанным интервалом.interval
: интервал для таймера, в секундах.maxTimerLength
: максимальный срок для активации таймера, в секундах. При достижении значенияmaxTimerLength
(по умолчанию 2 часа) будет отправлен дополнительный запрос. Если задан объектstopSpec
, но максимальный срок не указан, значением по умолчанию будет бесконечность.immediate
: указывает, должен ли таймер срабатывать сразу же. Значение типа Boolean, по умолчанию true.
"triggers": { "pageTimer": { "on": "timer", "timerSpec": { "interval": 10, "maxTimerLength": 600 }, "request": "pagetime" } }
Чтобы настроить таймер для пользовательских событий, используйте следующие объекты:
startSpec
: спецификация для начала отсчета по таймеру. Для отслеживания конкретных событий используйте свойстваon
иselector
. Конфигурация, где естьstartSpec
, но нетstopSpec
прекращает работу только по достижении значенияmaxTimerLength
.stopSpec
: спецификация для прекращения отсчета по таймеру. Конфигурация, где естьstartSpec
, но нетstopSpec
начинает работу сразу же, а прекращает только после наступления указанного события.
"triggers": { "videoPlayTimer": { "on": "timer", "timerSpec": { "interval": 5, "startSpec": { "on": "video-play", "selector": "amp-video" }, "stopSpec": { "on": "video-pause", "selector": "amp-video" } }, "request": "videoRequest" } }
Более подробная информация о создании вложенных триггеров для таймера приведена в спецификации. Учтите, что триггер для таймера нельзя использовать для начала или завершения отсчета по таймеру.
Триггер скрытия
Используйте триггер скрытия ("on": "hidden"
), чтобы активировать запрос, когда страница становится скрытой.
"triggers": { "defaultPageview": { "on": "hidden", "request": "pagehide", } }
Можно добавить спецификацию visibilitySpec
, чтобы запрос активировался только при выполнении условий по продолжительности периода видимости.
"triggers": { "defaultPageview": { "on": "hidden", "request": "pagehide", "visibilitySpec": { "selector": "#anim-id", "visiblePercentageMin": 20, "totalTimeMin": 3000, } } }
Конфигурация выше расшифровывается следующим образом:
Запрос активируется, когда страница становится скрытой, но только если элемент #anim-id был видимым (более 20 % в области просмотра) в течение более чем 3 секунд общего времени.
Триггеры доступа
Система доступа AMP генерирует множество событий для разных состояний в потоке доступа. Более подробные сведения о триггерах доступа ("on": "access-*"
) вы можете найти в статье Доступ и аналитика в AMP.
Триггеры для аналитики видео
Видеоаналитика поддерживает несколько триггеров ("on": "video-*"
) с помощью которых издатели могут отслеживать различные события, происходящие в жизненном цикле видео. Подробную информацию можно найти в статье Аналитика для видео в AMP.
Способ отправки запроса
Объект конфигурации transport
указывает, каким образом должен быть отправлен запрос. Его значение – объект с полями, где заданы допустимые способы передачи данных.
beacon
: указывает, что для передачи запроса может использоватьсяnavigator.sendBeacon
. При этом отправляется запрос POST с учетными данными. Если дляuseBody
не задано значение true, запрос отправляется с пустым телом. Подробные сведения оuseBody
приведены в разделе Передача дополнительных параметров URL в теле запроса.xhrpost
: указывает, что для передачи запроса может использоватьсяXMLHttpRequest
. При этом отправляется запрос POST с учетными данными. Если дляuseBody
не задано значение true, запрос отправляется с пустым телом. Подробные сведения оuseBody
приведены в разделе Передача дополнительных параметров URL в теле запроса.image
: указывает, что для передачи запроса может использоваться тегImage
. При этом отправляется запрос GET. Чтобы подавить консольные предупреждения о пустых запросах или ошибках, добавьте фрагмент"image": {"suppressWarnings": true}
.
Поставщики с аккредитацией MRC могут использовать четвертый способ передачи данных: через окна iframe. Для этого необходимо добавить в iframe-transport-vendors.js строку URL с указанием, что необходимо создать окно iframe. Для этого URL следует задать атрибут src
, и запросы будут отправляться в указанное окно с помощью window.postMessage()
. В таком случае запросы не обязательно должны быть полноценными URL. Способ iframe
нельзя задать в теге amp-analytics
или с помощью удаленной конфигурации. Необходимо использовать iframe-transport-vendors.js
. Более того, окно поставщика может отправить ответ, который будет использоваться в amp-ad-exit. Обратите внимание на файлы analytics-iframe-transport-remote-frame.html и fake_amp_ad_with_iframe_transport.html: первый из них отправляет в ответ объект JSON {'collected-data': 'abc'}, а второй использует этот объект для подстановки 'abc' вместо 'bar_' в элементе finalUrl.
Если задано несколько способов передачи данных, приоритет определяется следующим образом: iframe
> beacon
> xhrpost
> image
. В любом случае будет использован только один способ – наиболее приоритетный из доступных. Если агент пользователя на стороне клиента не поддерживает этот вариант, будет использован следующий из списка. По умолчанию включены все четыре перечисленных варианта.
В примере ниже для iframe
не указан URL, а для способов beacon
и xhrpost
задано значение false
. Поэтому они не будут использоваться, несмотря на более высокий приоритет, чем у image
. Для image
по умолчанию задано значение true
, но здесь оно обозначено специально. Если агент пользователя на стороне клиента поддерживает вариант image
, будет использован именно он. Если не поддерживает, запрос не отправится.
"transport": { "beacon": false, "xhrpost": false, "image": true }
Ознакомьтесь с примером использования клиентского API для передачи запроса через iframe и примером страницы с этим окном iframe. В этом примере загружается фиктивное объявление с тегом amp-analytics
. Учтите, что в описании фиктивного объявления есть дополнительные инструкции по конфигурации, которым необходимо следовать.
Передача дополнительных параметров URL в теле запроса
Конфигурация useBody
определяет, нужно ли добавлять параметры extraUrlParams
в тело запроса POST вместо URL.
Элемент useBody
поддерживается только для двух способов передачи данных: beacon
и xhrpost
. Если для useBody
задано значение true и при этом используется один из вышеперечисленных способов, в тело запроса POST будут добавлены параметры extraUrlParams
. В противном случае запрос отправляется с пустым телом, а extraUrlParams
указываются в URL.
При использовании useBody
вы можете добавить в extraUrlParams
вложенные объекты. Однако если запрос будет передан способом, не поддерживающим useBody
(например, image
), эти объекты будут преобразованы в строки URL в виде [object Object]
.
"transport": { "beacon": true, "xhrpost": true, "useBody": true, "image": false }
Правило для URL перехода
Правило для URL перехода можно задать в поле referrerPolicy
конфигурации transport
. В настоящее время поддерживается только значение no-referrer
,
а правила доступны исключительно для варианта image
. Если в коде есть фрагмент referrerPolicy: no-referrer
, для способов передачи данных beacon
и xhrpost
верным считается значение false
.
"transport": { "beacon": false, "xhrpost": false, "image": true, "referrerPolicy": "no-referrer" }
Установление связи
Функция linkers
позволяет установить связь между доменами по их идентификаторам. Объект конфигурации в amp-analytics
применяется, чтобы создать строку компоновщика, которая затем будет добавлена как параметр URL к указанным исходящим ссылкам на странице. Когда пользователь нажимает на одну из них, целевая страница считывает строку компоновщика из параметров URL, чтобы выполнить синхронизацию. Это обычно используется для объединения пользовательских сеансов, выполненных через домен прокси-сервера AMP и домен издателя.
Сведения о настройке конфигурации для установления связи приведены в статье Перенаправление идентификатора компоновщика.
Если вас интересует получение этого параметра, ознакомьтесь с примером в статье Получение идентификатора компоновщика.
Файлы cookie
Функция cookies
поддерживает запись файлов cookie для исходного домена путем извлечения параметров QUERY_PARAM
и LINKER_PARAM
из URL документа. Ее можно использовать вместе с функциями linkers
для синхронизации идентификаторов из прокси-домена AMP со страницами AMP в домене издателя.
Сведения о настройке конфигурации cookies
приведены в разделе Получение параметров компоновщика для AMP-страниц.
Проверка
См. раздел с правилами amp-analytics в спецификации валидатора AMP.
Допустимые атрибуты для <amp-analytics>
Ниже описаны допустимые атрибуты для компонента amp-analytics
.
type
Определяет тип поставщика. Более подробная информация представлена в списке поставщиков.
Пример:
<amp-analytics type="googleanalytics" config="https://example.com/analytics.account.config.json"></amp-analytics>
config
Это необязательный атрибут, который можно использовать для загрузки конфигурации с указанного удаленного URL, защищенного протоколом HTTPS. Ознакомьтесь также с описанием атрибута data-include-credentials
ниже. URL может включать переменные AMP. Ответ должен быть оформлен в соответствии с требованиями по безопасности в отношении CORS и AMP.
Пример:
<amp-analytics config="https://example.com/analytics.config.json"></amp-analytics>
Если задать значение include
, будет включена возможность чтения и записи файлов cookie по запросу, указанному в атрибуте config
. Это необязательный атрибут.
data-consent-notification-id
Если вы добавите этот атрибут, страница не будет обрабатывать аналитические запросы до тех пор, пока пользователь не подтвердит уведомление amp-user-notification с указанным идентификатором элемента HTML. Это необязательный атрибут.
Аналитика для компонентов AMP
Разработчики компонентов AMP могут добавлять наборы данных с помощью Google Analytics для AMP. Подробная информация приведена в этом руководстве.
You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.
Go to Stack Overflow Found a bug or missing a feature?The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
Go to GitHub