Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Сопоставление спецификаций 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`. Data Manager 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 Аналитики.

Если вы отправляете события в поток данных Google Аналитики, поле event_name является обязательным.
В справочнике по рекомендуемым событиям Google Аналитики вы найдете связанные поля, параметры и примеры запросов на передачу данных в Data Manager API для каждого события.
Вы также можете отправлять специальные события, если они соответствуют правилам присвоения названий событий.

Большинство стандартных событий 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
          }
        ]
      }
    }
  ]
}