Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ECAPI 规范映射

本指南可帮助使用 IAB Tech Lab Event and Conversion API (ECAPI) 规范的开发者将其事件和转化数据映射到 Data Manager API 事件提取架构。

概览

ECAPI 是一种与平台无关的开源数据标准，旨在定义与营销相关的事件和转化的结构。

下表简要介绍了 ECAPI 的关键属性和设计原则与 Data Manager API 的比较。

	ECAPI	Data Manager API
重复信息删除	依赖于 `id`（事件 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`（事件级）	可以在以下级别定义：请求级（必填）：在 `IngestEventsRequest`中指定 `destinations`列表。事件级：使用 `destination_references` 字段，位于 `Event` 对象中。添加一个条目，以指定应从 `destinations` 列表中接收事件的目标位置。如需详细了解如何定义 `Destination` 和确定商品目标位置 ID，请参阅配置目标位置和标头。
`id`	`transaction_id`	此值用于删除重复的转化事件。了解详情。
`timestamp`	`event_timestamp`	必填。ECAPI 使用 Unix 纪元格式（整数）表示时间戳。映射到 Data Manager API 时，`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` 对象。Data Manager API 支持多个可选 Merchant Center 字段，适用于 Merchant Center 账号中存在的商品。如果您的目标位置是 Google Ads 转化操作，您还可以在 `custom_variables` 字段中添加其他自定义参数，作为 `CustomVariable` 对象列表。如果您的目标位置是 Google Analytics 数据流，您可以在 `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 Analytics)	对于 Google Analytics 事件，`user_id` 字段表示 User-ID。Data Manager API 不支持其他目标位置的通用客户 ID 字段。
`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` 字符串中指定时区偏移量。如果您使用的是 Protocol Buffers，可以使用实用程序函数（例如 `Timestamps.parse(String)`）来处理时区到秒和纳秒的转换。如需了解详情，请参阅时间戳格式。
`address`	`user_data.user_identifiers[].address`	映射到 `AddressInfo` 对象。请参阅地址对象映射。
`gpp_string`	无对应字段	意见征求必须映射到请求级或事件级 `Consent` 对象。请参阅隐私权和意见征求概览。
`gpp_sid`	无对应字段	意见征求必须映射到请求级或事件级 `Consent` 对象。请参阅隐私权和意见征求概览。
`mmt_only`	无对应字段
`click_id`	`ad_identifiers.gclid`	映射到 Google 点击 ID (`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`	映射到广告客户的移动标识符（iOS 上的 IDFA，Android 上的 AdID）。如需了解详情，请参阅 `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 Analytics 事件，此字段必填。设置为商品的标准唯一标识符。
无对应字段	`merchant_product_id`	对于 Floodlight 转化和含购物车数据的 Google Ads 转化，此字段必填。设置为 Merchant Center 账号中的商品 ID。
`name`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_name`。
`price`	`unit_price`
`discount`	`additional_item_parameters` 或 `custom_variables`	在 `additional_item_parameters` 中映射为 `discount`（对于 Google Analytics），或在 `custom_variables` 中映射为自定义变量（对于 Google Ads）。
`quantity`	`quantity`	将 `float` 值转换为整数 (`int64`)。
`brand`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_brand`。
`affiliation`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `affiliation`。
`category`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_category`。
`cattax`	无对应字段
`item_coupon`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `coupon`。
`item_list_id`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_list_id`。
`item_list_name`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_list_name`。
`item_item_variant`	`additional_item_parameters`	在 `additional_item_parameters` 列表中映射为 `item_variant`。
`item_location_id`	`additional_item_parameters`	在 `additional_item_parameters` 中映射为 `location_id`。
`ext`	无对应字段

标准事件名称

ECAPI 标准事件与 Google Analytics 命名惯例高度一致。

如果您要将事件发送到 Google Analytics 数据流，则 event_name 字段必填。
请参阅 Google Analytics 推荐事件参考，了解每个事件的相关字段、参数和 Data Manager API 提取请求示例。
您还可以发送自定义事件，前提是这些事件遵循事件命名规则。

大多数 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 转化事件载荷与其作为有效的 Data Manager API IngestEventsRequest 的表示形式之间的比较。

ECAPI

以下是符合 ECAPI 规范的 JSON 载荷示例。

{
  "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 for 示例。这是针对 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
          }
        ]
      }
    }
  ]
}