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 Epoch 格式 (整數) 做為時間戳記。對應至 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`	直接對應為 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 物件清單，其中可包含個別使用者 ID，例如電子郵件地址、電話號碼或地址元件。

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`	前往 `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`	對應至廣告主適用的行動 ID (iOS 的廣告識別碼、Android 的廣告 ID)。詳情請參閱 `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 事件必須提供這個參數。設為商品的標準專屬 ID。
無對應報告	`merchant_product_id`	透過購物車資料回報的 Floodlight 轉換和 Google Ads 轉換必須提供這項資料。設為 Merchant Center 帳戶中的產品 ID。
`name`	`additional_item_parameters`	`item_name` `additional_item_parameters` 清單中的地圖。
`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`	`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`	地圖 (`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。如目的地中的 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
          }
        ]
      }
    }
  ]
}