amp-analytics

Получает статистические данные из AMP-документа.

Вы отправляете статистику поставщику или кому-то внутри компании?

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

Отправка данных поставщику

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

Если все в порядке, выполните следующие действия:

1. Добавьте в тег <amp-analytics> атрибут type и в качестве значения укажите название поставщика.
2. Определитесь с тем, какие данные вы хотите отслеживать, и соответствующим образом настройте конфигурацию. Более подробную информацию можно найти в документации поставщика.

Если ваш поставщик не поддерживает 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 может быть и несколько: например, отдельные ссылки для статистики о просмотрах страницы и о поведении пользователей в социальных сетях.

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

1. Определитесь с тем, какие данные вы хотите отслеживать, и соответствующим образом настройте конфигурацию.
2. В объекте конфигурации requests укажите, какие типы запросов вы хотите отслеживать (например, просмотры страниц или конкретные события с триггерами), а также URL, куда следует отправлять полученные данные.

Пример: отправка данных по определенному 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.

Если используются сведения о конфигурации из нескольких источников, то объекты (переменные, запросы и триггеры) будут объединены таким образом:

1. Удаленная конфигурация имеет приоритет над встроенной.
2. Встроенная конфигурация имеет приоритет над конфигурацией поставщика.

Загрузка удаленной конфигурации

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

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

1. Переопределенная конфигурация.
2. Встроенная конфигурация.
3. Конфигурация, заданная поставщиком.

Группы переменных

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

Спецификация visibilitySpec – это набор условий и свойств, которые можно задать для триггеров visible и hidden, чтобы изменить условия активации. Если задано несколько свойств, у всех них должно быть значение true, иначе запрос не активируется. Спецификация visibilitySpec поддерживает следующие свойства:

• waitFor: это свойство указывает, что триггер видимости должен ждать определенного сигнала перед началом отслеживания. Допустимые значения: none, ini-load и render-start. Если селектор добавлен, но значение не задано, по умолчанию используется вариант ini-load, если же селектора нет – none.
• reportWhen: это свойство указывает, что триггер видимости должен ждать определенного сигнала перед отправкой данных. Единственное допустимое значение: documentExit. Свойства reportWhen и repeat можно использовать в рамках одной спецификации. Учтите, что при наличии свойства reportWhen отчет отправляется тогда, когда регистрируется сигнал (даже если требования к видимости не были соблюдены в настоящий момент или ранее). Все соответствующие переменные (totalVisibleTime и т. п.) будут сформированы с учетом требований к видимости в спецификации visibilitySpec.
• continuousTimeMin and continuousTimeMax: свойства, которые указывают, что запрос должен быть активирован, если любая часть элемента непрерывно показывалась в области просмотра в течение любого времени между указанными пределами. Время выражается в миллисекундах. Если значение для 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>

data-credentials

Если задать значение include, будет включена возможность чтения и записи файлов cookie по запросу, указанному в атрибуте config. Это необязательный атрибут.

data-consent-notification-id

Если вы добавите этот атрибут, страница не будет обрабатывать аналитические запросы до тех пор, пока пользователь не подтвердит уведомление amp-user-notification с указанным идентификатором элемента HTML. Это необязательный атрибут.

Аналитика для компонентов AMP

Разработчики компонентов AMP могут добавлять наборы данных с помощью Google Analytics для AMP. Подробная информация приведена в этом руководстве.