Сопоставление спецификаций 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 также поддерживает маршрутизацию событий в несколько пунктов назначения в одном запросе.

Подробнее о целевых сервисах…
Поля для согласия и конфиденциальности Строки согласия глобальной платформы конфиденциальности (GPP) Data Manager API не принимает и не анализирует строки согласия, полученные с помощью глобальной платформы конфиденциальности (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 Это значение используется для дедупликации событий-конверсий. Подробнее…
timestamp event_timestamp Обязательно. В API расширенного отслеживания конверсий для временных меток используется формат Unix epoch (целое число). При сопоставлении с 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 представляет собой идентификатор User-ID. Data Manager API не поддерживает поля идентификаторов клиентов для других целевых сервисов.
uids Ранее такого отчета не существовало Data Manager 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 представлена в виде действительного объекта Data Manager API IngestEventsRequest.

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 Рекламы, о чем свидетельствует тип аккаунта GOOGLE_ADS в целевом аккаунте.

{
  "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
          }
        ]
      }
    }
  ]
}