Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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`	对转化事件进行去重。请参阅 Google Ads、Google Analytics 和 Floodlight 的发送事件指南中的 Google 如何处理多来源数据。
`timestamp`	`event_timestamp`	必需。ECAPI 使用 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`	将交易级商品映射到 `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` 字段表示 User-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` 字符串中指定时区偏移量。如果您使用的是协议缓冲区，则可以使用 `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` 中映射为 `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 字段是必需的。
如需了解每个事件的相关字段、参数和 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
          }
        ]
      }
    }
  ]
}