← Cloudflare Zaraz / zaraz

HTTP Events API

Zaraz HTTP Events API позволяет отправлять информацию в Zaraz из мест, где невозможно выполнить Web API, например ваш сервер или мобильное приложение. Это полезно для отслеживания событий, которые происходят вне браузера, например успешных транзакций, регистраций и других. API также позволяет отправлять несколько событий пакетами.

API отключён, пока для него не настроена конечная точка. Конечная точка определяет URL, по которому будет доступен API. Например, если указать в качестве конечной точки /zaraz/api, а ваш домен: example.com, запросы к API будут отправляться на https://example.com/zaraz/api.

Чтобы включить конечную точку API:

1. На панели управления Cloudflare перейдите к разделу Настройки страницу.

   Перейдите в Настройки ↗

2. В разделе Конечные точки > HTTP Events API, укажите нужный путь. Помните, что путь указывается относительно вашего домена и должен начинаться с /.

Настроенная вами конечная точка API будет получать POST запросы с JSON payload. Ниже приведён пример payload:

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      }
    }
  ]
}

Полезная нагрузка должна содержать events массив. Каждый объект Event Object в этом массиве соответствует одному событию, которое должен обработать Zaraz. Приведенный выше пример аналогичен вызову zaraz.track('transaction successful', { value: "200" }) с помощью Web API.

Event Object содержит client объект, в котором можно передать информацию о самом событии. Каждый ключ, добавленный в Event Object, будет доступен как Track Property в панели Zaraz.

Есть два зарезервированных ключа:

• __zarazTrack: Значение этого ключа будет доступно как Имя события. Именно на этом обычно строятся ваши триггеры. В приведённом выше примере, если задать значение transaction successful совпадает с с помощью Web API и вызов zaraz.track("transaction successful").
• __zarazEcommerce: Этот ключ должен быть установлен в значение true если хотите, чтобы Zaraz обработал событие как событие электронной коммерции.

Помимо client ключ, вы можете использовать system ключ, чтобы включить информацию об устройстве, с которого произошло событие. Например, вы можете отправить User-Agent строку, куки и разрешение экрана. Zaraz будет использовать эту информацию при подключении к различным сторонним инструментам. Поскольку некоторые инструменты зависят от определённых полей, часто полезно указывать всю доступную информацию.

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

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      },
      "system": {
        "page": {
          "url": "https://example.com",
          "title": "My website"
        },
        "device": {
          "language": "en-US",
          "ip": "192.168.0.1"
        }
      }
    }
  ]
}

Все доступные системные ключи перечислены в таблице ниже:

На каждый Event Object в вашей полезной нагрузке Zaraz отвечает объектом Result Object. Порядок объектов Result Object соответствует порядку объектов Event Object.

В зависимости от того, какие инструменты загружаются через Zaraz, тело ответа от API может содержать данные, которые стоит обработать. Это связано с тем, что некоторые инструменты не имеют полной серверной реализации и по-прежнему полагаются на cookie, клиентский JavaScript или похожие механизмы. Каждый Result Object может включать следующую информацию:

Обрабатывать указанную выше информацию не обязательно, но от этого может зависеть корректная работа некоторых инструментов. Вы можете начать использовать HTTP Events API, не обрабатывая данные из таблицы выше, и настроить это позже.