Сопоставление спецификаций ECAPI

Это руководство поможет разработчикам, использующим спецификацию IAB Tech Lab Event and Conversion API (ECAPI), сопоставить данные о событиях и конверсиях со схемой передачи событий Data Manager API.

Обзор

ECAPI – это не зависящий от платформы стандарт данных с открытым исходным кодом, который определяет структуру событий и конверсий, связанных с маркетингом.

В таблице ниже приведено общее сравнение основных атрибутов и принципов разработки ECAPI и Data Manager API.

ECAPI Data Manager API
Дедупликация Зависит от id (идентификатор события) Зависит от transaction_id
Маршрутизация событий Поле data_set_id в полезной нагрузке события указывает на место назначения данных. Поле destinations запроса определяет целевые сервисы для событий.

Data Manager API также поддерживает маршрутизацию событий в несколько целевых сервисов в одном запросе.

Подробнее о том, как настроить целевые страницы и заголовки…
Поля для согласия и конфиденциальности Строки согласия Global Privacy Platform (GPP) Data Manager API не принимает и не анализирует строки согласия Global Privacy Platform (GPP). Задайте поля согласия в объекте Consent.

Статус согласия можно задать на уровне запроса (он будет применяться ко всем событиям в запросе) или на уровне события (это позволит указать разные настройки согласия для отдельных событий).

Сопоставление полей структуры

В таблицах ниже показано, как отдельные поля из спецификации ECAPI преобразуются в поля, принимаемые Data Manager API.

Сопоставление объектов событий

ECAPI (event) Data Manager API (Event) Примечания
data_set_id
  • destinations[].product_destination_id (на уровне запроса)
  • destination_references (на уровне события)
 Целевые сервисы можно задавать на следующих уровнях:
  • Уровень запроса (обязательно). Укажите список destinations в IngestEventsRequest.
  • На уровне события (необязательно): используйте поле destination_references в объекте Event. Добавьте запись, чтобы указать, в какой целевой сервис из списка destinations должно отправляться событие.

Подробнее о том, как определить Destination и идентификатор целевого сервиса, рассказывается в статье Как настроить целевые сервисы и заголовки.
id transaction_id Удаляет повторяющиеся события-конверсии. Узнайте, как Google обрабатывает данные из нескольких источников, в руководствах по отправке событий для Google Рекламы, Google Аналитики и Floodlight.
timestamp event_timestamp Обязательно. В API расширенного отслеживания конверсий для временных меток используется формат эпохи Unix (целое число). При сопоставлении с Data Manager API преобразуйте поле event_timestamp в один из следующих форматов:
  • Если вы используете формат JSON, задайте значение в формате RFC 3339.
  • Если вы используете буферы протокола, используйте Timestamp и задайте поля seconds и nanoseconds (необязательно).

Подробнее о формате временных меток…
event_type/custom_event event_name Это может быть название рекомендуемого события (например, purchase) или специального события. Подробнее о стандартных названиях событий…
user_data user_data Соответствует объекту UserData, который принимает список объектов UserIdentifier.
value conversion_value Сопоставляется напрямую как число с плавающей запятой, представляющее денежную ценность конверсии.
currency_code currency Сопоставьте с трехбуквенным кодом валюты, написанным заглавными буквами (например, USD).
source event_source Укажите значение из перечисления EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Сопоставьте товары на уровне транзакции с массивом cart_data.items в объекте CartData. API Менеджера данных поддерживает несколько необязательных полей Merchant Center для товаров, которые есть в аккаунтах Merchant Center.

Если целевой объект – действие-конверсия Google Рекламы, вы также можете добавить дополнительные специальные параметры в поле custom_variables в виде списка объектов CustomVariable.

Если целевой сервис – поток данных Google Аналитики, вы можете включить дополнительные параметры событий в поле additional_event_parameters в виде списка объектов AdditionalEventParameter.
ext Ранее такого отчета не существовало

Сопоставление объектов пользовательских данных

В Data Manager API поле user_data объекта Event принимает объект UserData. Ожидается список объектов UserIdentifier, которые могут содержать отдельные идентификаторы пользователей, например адреса электронной почты, номера телефонов или компоненты адресов.

ECAPI (user_data) Data Manager API (Event) Примечания
customer_identifier user_id (Google Аналитика) Для событий Google Аналитики поле user_id представляет идентификатор пользователя. Data Manager API не поддерживает общие поля идентификаторов клиентов для других целевых сервисов.
uids Ранее такого отчета не существовало API Менеджера данных не поддерживает структурированный массив uids, содержащий типы агентов и домены.
customer_segments user_properties Карта маршрута до UserProperties на Event.
email_address user_data.user_identifiers[].email_address Укажите отформатированный и хешированный адрес электронной почты. Вы также можете зашифровать хешированный адрес электронной почты.
phone_numbers user_data.user_identifiers[].phone_number Укажите отформатированный и хешированный номер телефона. Вы также можете зашифровать хешированный номер телефона.
utcoffset Ранее такого отчета не существовало Если вы используете формат JSON, то можете указать смещение часового пояса непосредственно в строке RFC 3339 event_timestamp.
Если вы используете буферы протоколов, то можете воспользоваться вспомогательными функциями, например Timestamps.parse(String), чтобы преобразовать часовой пояс в секунды и наносекунды.
Подробнее о формате временных меток…
address user_data.user_identifiers[].address Соответствует объекту AddressInfo. Подробнее о сопоставлении объектов адресов…
gpp_string Ранее такого отчета не существовало Сопоставьте согласие с объектом Consent на уровне запроса или события. Подробнее о конфиденциальности и согласии…
gpp_sid Ранее такого отчета не существовало Сопоставьте согласие с объектом Consent на уровне запроса или события. Подробнее о конфиденциальности и согласии…
mmt_only Ранее такого отчета не существовало
click_id ad_identifiers.gclid Сопоставьте с идентификатором клика Google (gclid). Подробнее читайте в статье AdIdentifiers.
impression_id ad_identifiers.impression_id Подробнее об элементе AdIdentifiers…
event_ip_address event_device_info.ip_address Доступные поля перечислены в DeviceInfo.
event_user_agent event_device_info.user_agent Доступные поля перечислены в DeviceInfo.
ifa ad_identifiers.mobile_device_id Сопоставляется с мобильным идентификатором для рекламодателей (IDFA на iOS, AdID на Android). Подробнее о AdIdentifiers…
landing_ip_address ad_identifiers.landing_page_device_info.ip_address Доступные поля перечислены в DeviceInfo.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent Список доступных полей приведен в разделе DeviceInfo.
age_range Ранее такого отчета не существовало
gender Ранее такого отчета не существовало
ext Ранее такого отчета не существовало

Сопоставление объектов адресов

ECAPI (address) Data Manager API (AddressInfo) Примечания
first_name given_name Сопоставляется с полем given_name в AddressInfo. Следуйте правилам форматирования и хеширования. Вы также можете зашифровать хешированные атрибуты адреса.
last_name family_name Соответствует полю family_name в AddressInfo. Следуйте правилам форматирования и хеширования. Вы также можете зашифровать хешированные атрибуты адреса.
street Ранее такого отчета не существовало Не поддерживается в Data Manager API.
city Ранее такого отчета не существовало Не поддерживается в Data Manager API.
state Ранее такого отчета не существовало Не поддерживается в Data Manager API.
country_code region_code Не хешируйте данные. Сопоставляется с полем region_code в AddressInfo. Соблюдайте правила форматирования.
postal_code postal_code Не хешируйте. Сопоставляется с полем postal_code в AddressInfo. Следуйте правилам форматирования.
address_type Ранее такого отчета не существовало Не поддерживается в Data Manager API.
ext Ранее такого отчета не существовало

Сопоставление объектов элементов

ECAPI (item) Data Manager API (Item) Примечания
id item_id Обязательно для событий Google Аналитики. Укажите стандартный уникальный идентификатор объекта.
Ранее такого отчета не существовало merchant_product_id Обязательный для конверсий Floodlight и конверсий Google Рекламы с данными корзины. Укажите идентификатор товара в аккаунте Merchant Center.
name additional_item_parameters Сопоставить как item_name в списке additional_item_parameters.
price unit_price
discount additional_item_parameters или custom_variables Сопоставьте как discount в additional_item_parameters (для Google Аналитики) или как пользовательскую переменную в custom_variables (для Google Рекламы).
quantity quantity Преобразуйте значение float в целое число (int64).
brand additional_item_parameters Карта как item_brand в списке additional_item_parameters.
affiliation additional_item_parameters Карта как affiliation в списке additional_item_parameters.
category additional_item_parameters Карта как item_category в списке additional_item_parameters.
cattax Ранее такого отчета не существовало
item_coupon additional_item_parameters Сопоставить как coupon в списке additional_item_parameters.
item_list_id additional_item_parameters Карта как item_list_id в списке additional_item_parameters.
item_list_name additional_item_parameters Сопоставить как item_list_name в списке additional_item_parameters.
item_item_variant additional_item_parameters Сопоставить как item_variant в списке additional_item_parameters.
item_location_id additional_item_parameters Карта location_id в additional_item_parameters.
ext Ранее такого отчета не существовало

Названия стандартных событий

Стандартные события ECAPI в основном соответствуют правилам именования Google Аналитики.

Большинство стандартных событий ECAPI (например, purchase, add_to_cart, begin_checkout, search и refund) имеют те же названия, что и рекомендуемые события Google Аналитики. Однако есть несколько исключений, когда Google Аналитика использует настоящее время вместо прошедшего:

  • viewed_item сопоставляется с view_item

  • viewed_item_list соответствует view_item_list

  • viewed_cart соответствует view_cart

Примеры запросов

На вкладках ниже показано сравнение полезной нагрузки события-конверсии ECAPI и ее представления в виде допустимого объекта IngestEventsRequest Data Manager API.

ECAPI

Ниже приведен пример полезной нагрузки JSON, соответствующей спецификации ECAPI:

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

Ниже приведен пример IngestEventsRequest для отформатированных, хешированных и закодированных данных о событии. Тип аккаунта GOOGLE_ADS в целевом сервисе указывает, что запрос предназначен для Google Рекламы:

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}