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` 的列表。事件级：使用 `Event` 对象中的 `destination_references` 字段。添加一个条目，以指定 `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`	直接映射为表示转化货币价值的 double 或 float。
`currency_code`	`currency`	映射到由三个字母组成的大写货币代码（例如 `USD`）。
`source`	`event_source`	设置为 EventSource 枚举中的某个值。
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	交易级商品可以映射到 `CartData` 对象中的 `cart_data.items` 数组。Data Manager API 支持 Merchant Center 账号中存在的商品的多个可选 Merchant Center 字段。如果目的地是 Google Ads 转化操作，您还可以在 `custom_variables` 字段中添加其他自定义参数，作为 `CustomVariable` 对象的列表。如果您的目的地是 Google Analytics 数据流，则可以在 `additional_event_parameters` 字段中以 `AdditionalEventParameter` 对象列表的形式添加其他事件参数。
`ext`	无对应报告

用户数据对象映射

在 Data Manager API 中，Event 对象的 user_data 字段接受 UserData 对象。此对象需要包含 UserIdentifier 对象的列表，这些对象可以包含电子邮件地址、电话号码或地址组成部分等个人用户标识符。

ECAPI (`user_data`)	Data Manager API (`Event`)	备注
`customer_identifier`	`user_id`（Google Analytics）	对于 Google Analytics 事件，`user_id` 字段表示用户 ID。Data Manager API 不支持其他目标平台的通用客户 ID 字段。
`uids`	无对应报告	Data Manager API 不支持包含代理类型和网域的结构化 `uids` 数组。
`customer_segments`	`user_properties`	映射到 `Event` 上的 `UserProperties`。
`email_address`	`user_data.user_identifiers[].email_address`	设置为经过格式化和哈希处理的电子邮件地址。您还可以加密经过哈希处理的电子邮件地址。
`phone_numbers`	`user_data.user_identifiers[].phone_number`	设置为已格式化和哈希处理的电话号码。您还可以加密哈希处理后的电话号码。
`utcoffset`	无对应报告	如果您使用 JSON 格式，可以直接在 RFC 3339 `event_timestamp` 字符串中指定时区偏移量。如果您使用的是 Protocol Buffer，则可以使用 `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`	映射到 `AddressInfo` 中的 `given_name` 字段。遵循格式设置和哈希处理指南。您还可以加密地址的哈希属性。
`last_name`	`family_name`	映射到 `AddressInfo` 中的 `family_name` 字段。遵循格式设置和哈希处理指南。您还可以加密地址的哈希属性。
`street`	无对应报告	Data Manager API 不支持
`city`	无对应报告	Data Manager API 不支持
`state`	无对应报告	Data Manager API 不支持
`country_code`	`region_code`	请勿进行哈希处理。映射到 `AddressInfo` 中的 `region_code` 字段。请遵循格式设置指南。
`postal_code`	`postal_code`	请勿进行哈希处理。映射到 `AddressInfo` 中的 `postal_code` 字段。请遵循格式设置指南。
`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`（对于 Google Analytics）中映射为 `discount`，或在 `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 字段。
如需查看每个事件的相关字段、参数和示例 Data Manager API 提取请求，请参阅 Google Analytics 推荐的事件参考。
您还可以发送自定义事件，前提是这些事件遵循事件命名规则。

大多数 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 示例。此示例适用于 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
          }
        ]
      }
    }
  ]
}