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`列表。事件级（可选）：使用 `destination_references` 字段在 `Event` 对象中。添加条目以指定 `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`	将交易级商品映射到 `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` 字符串中指定时区偏移量。如果您使用的是协议缓冲区，可以使用实用函数（例如 `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 字段是必需的 。
如需了解每个事件的相关字段、参数和 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
          }
        ]
      }
    }
  ]
}