Эта страница переведена с помощью Cloud Translation API.

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

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

Обзор

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

В приведенной ниже таблице представлен общий обзор того, как ключевые атрибуты и принципы проектирования ECAPI соотносятся с API Data Manager.

	ЭКАПИ	API менеджера данных
Дедупликация	Зависит от `id` (ID события).	Зависит от `transaction_id`
маршрутизация событий	Место назначения данных указывается полем `data_set_id` в полезной нагрузке события.	Поле `destinations` в запросе определяет место назначения для событий. API Data Manager также поддерживает маршрутизацию событий в несколько пунктов назначения в рамках одного запроса. Более подробную информацию можно найти в путеводителе по направлениям.
Поля конфиденциальности и согласия	Строки согласия Глобальной платформы конфиденциальности (GPP)	API Data Manager не принимает и не анализирует строки согласия Global Privacy Platform (GPP). Поля согласия должны быть заданы в объекте `Consent` . Вы можете установить согласие либо на уровне запроса (что применяется ко всем событиям в запросе), либо на уровне события (что позволяет указать различные параметры согласия для отдельных событий).

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

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

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

ECAPI ( `event` )	API менеджера данных ( `Event` )	Примечания
`data_set_id`	`destinations[].product_destination_id` (Уровень запроса) `destination_references` (Уровень события)	Может быть определено на следующих уровнях: Уровень запроса (обязательно) : Укажите список `destinations` в запросе `IngestEventsRequest` . На уровне события: используйте поле `destination_references` в объекте `Event` . Добавьте запись, указывающую, какой из пунктов `destinations` из списка должен получить событие. Для получения дополнительной информации о том, как определить `Destination` и идентификатор пункта назначения продукта, см. раздел «Настройка пунктов назначения и заголовков» .
`id`	`transaction_id`	Это значение используется для удаления дубликатов событий конверсии. Подробнее .
`timestamp`	`event_timestamp`	Обязательно. ECAPI использует формат Unix epoch (целое число) для временных меток. При сопоставлении с API Data Manager поле `event_timestamp` необходимо преобразовать в один из следующих форматов: При использовании формата JSON задайте значение в формате RFC 3339 . При использовании протокола Protocol Buffers используйте метку `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 Data Manager поддерживает несколько необязательных полей Merchant Center для товаров, существующих в учетных записях Merchant Center. Если ваша цель — действие конверсии в Google Ads, вы также можете добавить дополнительные пользовательские параметры в поле `custom_variables` в виде списка объектов `CustomVariable` . Если в качестве целевого источника данных используется поток Google Analytics, вы можете добавить дополнительные параметры событий в поле `additional_event_parameters` в виде списка объектов `AdditionalEventParameter` .
`ext`	Нет эквивалента

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

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

ECAPI ( `user_data` )	API менеджера данных ( `Event` )	Примечания
`customer_identifier`	`user_id` (Google Analytics)	Для событий Google Analytics поле `user_id` представляет собой идентификатор пользователя . API Data Manager не поддерживает общие поля идентификаторов клиентов для других целевых систем.
`uids`	Нет эквивалента	API Data Manager не поддерживает структурированный массив `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, вы можете указать смещение часового пояса непосредственно в строке `event_timestamp` из RFC 3339. Если вы используете протокол Protocol Buffers, вы можете воспользоваться вспомогательными функциями, такими как `Timestamps.parse(String)` для преобразования часовых поясов в секунды и наносекунды. Подробности см. в формате временной метки .
`address`	`user_data.user_identifiers[].address`	Сопоставляется с объектом `AddressInfo` . См. раздел «Сопоставление объектов Address» .
`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` )	API менеджера данных ( `AddressInfo` )	Примечания
`first_name`	`given_name`	Соответствует полю `given_name` в `AddressInfo` . Следуйте рекомендациям по форматированию и хешированию . Вы также можете зашифровать хешированные атрибуты адреса .
`last_name`	`family_name`	Сопоставляется с полем `family_name` в `AddressInfo` . Следуйте рекомендациям по форматированию и хешированию . Вы также можете зашифровать хешированные атрибуты адреса .
`street`	Нет эквивалента	Не поддерживается в API менеджера данных.
`city`	Нет эквивалента	Не поддерживается в API менеджера данных.
`state`	Нет эквивалента	Не поддерживается в API менеджера данных.
`country_code`	`region_code`	Не используйте хеширование . Соответствует полю `region_code` в `AddressInfo` . Следуйте рекомендациям по форматированию .
`postal_code`	`postal_code`	Не используйте хеширование . Соответствует полю `postal_code` в `AddressInfo` . Следуйте рекомендациям по форматированию .
`address_type`	Нет эквивалента	Не поддерживается в API менеджера данных.
`ext`	Нет эквивалента

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

ECAPI ( `item` )	API менеджера данных ( `Item` )	Примечания
`id`	`item_id`	Обязателен для событий Google Analytics. Задается стандартный уникальный идентификатор элемента.
Нет эквивалента	`merchant_product_id`	Обязательно для конверсий Floodlight и конверсий Google Ads с данными корзины. Установите значение, соответствующее идентификатору товара в учетной записи 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 Analytics) или как пользовательскую переменную в `custom_variables` (для Google Ads).
`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 Analytics.

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

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

viewed_item соответствует view_item
viewed_item_list соответствует view_item_list
viewed_cart соответствует view_cart

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

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

ЭКАПИ

Вот пример полезной нагрузки 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
      }
    ]
  }
}

API менеджера данных

Вот пример IngestEventsRequest для отформатированных, хешированных и закодированных данных события. Он предназначен для целевого объекта Google Ads, как указано в типе учетной записи 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
          }
        ]
      }
    }
  ]
}