本頁面由 Cloud Translation API 翻譯而成。

傳送事件

您可以完成本快速入門導覽課程，熟悉如何傳送事件資料。

在下列任一情境中，使用資料管理工具 API：

將 Google Ads 代碼轉換或 Google Analytics 重要事件做為代碼轉換的額外資料來源，提升廣告互動信號、強化資料和整體成效。

這項功能僅適用於許可清單中的帳戶。如有意新增 Google Ads 帳戶或 Google Analytics 資源，請填寫表單。

注意： 在 14 天試用期內，您連結的其他資料來源資料不會流向轉換出價。此限制不適用於現有的 Google 代碼資料來源。
傳送 Google Ads 離線轉換或待開發客戶強化轉換的事件資料。

選擇要查看的指南版本：

在本快速入門導覽課程中，您將完成下列步驟：

準備Destination接收事件資料。
準備要傳送的事件資料。
為事件建立 IngestionService 要求。
使用 Google APIs Explorer 傳送要求。
瞭解成功和失敗的回應。

準備目的地

傳送資料前，您必須先準備至少一個資料的 Destination。以下是可供使用的 Destination 範例：

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

以下是 Destination 的欄位。如需更多詳細資料和不同情境的目標範例，請參閱「設定目的地」。

operatingAccount

接收事件的帳戶。

如果是以額外資料來源傳送的事件，作業帳戶可以是 Google Ads 帳戶或 Google Analytics 資源。

如果 accountType 為 GOOGLE_ANALYTICS_PROPERTY，要求憑證必須屬於具有資源編輯者或管理員角色的 Google Analytics 使用者。

如果是離線轉換和待開發客戶強化轉換，則運作中的帳戶必須是 Google Ads 帳戶。

loginAccount: 憑證的 Google 帳戶所屬帳戶。

productDestinationId

接收事件的 operatingAccount 中實體的 ID。

如果事件是做為額外資料來源傳送，productDestinationId必須是下列其中一項：

Google Ads 轉換的 ID，其中 type 設為 WEBPAGE。在 Google Ads 使用者介面中，轉換來源為WEBPAGE轉換動作的網站。
Google Analytics 網站串流的評估 ID。您無法將事件做為額外資料來源，傳送至 Google Analytics iOS 應用程式或 Android 應用程式串流。

如果是離線轉換或待開發客戶強化轉換，productDestinationId 必須是 Google Ads 轉換動作的 ID，且 type 設為 UPLOAD_CLICKS。在 Google Ads 使用者介面中，UPLOAD_CLICKS 轉換動作的「轉換來源」為「網站 (從點擊匯入)」。

本指南中的範例說明如何建構要求，將所有事件傳送至相同目的地。如要在同一個要求中傳送多個目的地的事件，請參閱「傳送多個目的地的事件」。

準備事件資料

請參考下列事件資料。每個表格都對應一個轉換事件。每個轉換事件都有事件的時間戳記、轉換動作和轉換價值。

每個事件可能都有廣告 ID (例如 gclid) 或使用者 ID (例如電子郵件地址、電話號碼和地址資訊)。事件也可以包含：

評估事件發生時的使用者資訊，例如顧客價值，或是新顧客、回訪顧客或重新參與的顧客。
購物車資料。
目的地適用的其他事件參數或使用者屬性，例如 Google Analytics 的 client_id 或 user_id。

以下是活動資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

設定資料格式

按照格式設定指南的規定設定欄位格式。以下是格式化後的事件資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

雜湊並編碼資料

此外，格式化後的電子郵件地址、名字和姓氏必須使用 SHA-256 演算法進行雜湊處理，並使用十六進位或 Base64 編碼。以下是經過格式化、雜湊處理和編碼 (使用十六進位編碼) 的事件資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

將資料轉換為 `Event` 物件

將每個事件的格式化和雜湊處理資料轉換為 Event。按照指示填入下列欄位：

將 eventTimestamp 設為事件發生的時間。

Google Analytics 事件的 eventTimestamp 必須在過去 72 小時內。

根據用途設定必填欄位。

用途	ID	`transactionId`	`eventSource`
離線轉換或待開發客戶強化轉換	必填。設定至少下列其中一項： `adIdentifiers` 至少設定一個 `gclid`、`gbraid` 或 `wbraid` 工作階段屬性 `userData`	選用	必填。設為 `EventSource` 的其中一個列舉值。
傳送至 Google Ads 目的地做為額外資料來源的事件	必填。設定至少下列其中一項： `adIdentifiers` 至少要設定 `gclid`、`gbraid` 或 `wbraid` `userData`	必要	選用。如要設定，必須為 `WEB`。
傳送至 Google Analytics 目的地的事件，做為額外資料來源	必填。設定至少下列其中一項： `clientId` `adIdentifiers` 已設定 `gclid` `userData`	必要	選用。如要設定，必須為 `WEB`。

填入事件的其他欄位值。如需可用欄位的完整清單，請參閱Event參考說明文件。

新增工作階段屬性

如果您要傳送離線轉換或待開發客戶強化轉換，請在沒有其他廣告 ID (例如 Google 點擊 ID 或 WBRAID) 時，加入工作階段屬性。除了其他廣告 ID 之外，您也可以納入工作階段屬性。

工作階段屬性可提供使用者與網站互動相關額外資訊和信號，有助提升轉換評估、報表和出價的準確度。

在 Data Manager API 中，您可以透過兩種方式傳送工作階段屬性：

建議：將 adIdentifiers 的 sessionAttributes 欄位設為採用 Base64 編碼的工作階段屬性字串。請按照「如何擷取 session_attributes」一文中的操作說明，修改表單提交頁面，擷取編碼字串。
如果無法使用 JavaScript，請擷取個別工作階段屬性欄位，並將每個欄位以個別 ExperimentalField 的形式新增至 experimentalFields 清單：
- gad_campaignid
- session_start_time_usec
- gad_source
- landing_page_url
- landing_page_referrer
如果 landing_page_user_agent 工作階段屬性有值，請在 adIdentifiers.landingPageDeviceInfo 的 userAgent 欄位中傳送。

傳送個別鍵值組時，請遵循下列最佳做法：
- 持續傳送 gad_campaignid 和 session_start_time_usec。這些欄位對準確歸因至關重要。
- 請勿提供不準確或不完整的 landing_page_url 值，例如預留位置字串、內部應用程式路徑或不完整的網址。如果沒有準確的完整網址，請省略 landing_page_url。
以下是範例事件的部分內容，其中包含 experimentalFields 中的項目 (適用於 gad_campaignid 和 session_start_time_usec)，以及 landingPageDeviceInfo 欄位中的使用者代理程式：
```
{
  ...,
  "experimentalFields": [
    {
      "field": "gad_campaignid",
      "value": "21288051566"
    },
    {
      "field": "session_start_time_usec",
      "value": "1767711548052000"
    }
  ],
  "adIdentifiers": {
    "landingPageDeviceInfo": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    }
  }
}
```

新增 Google Analytics 資訊

如果以額外資料來源傳送的事件目的地包含 Google Analytics 資源，請按照指示填寫下列欄位：

eventName

必填。Google Analytics 事件的名稱。

transactionId

必要。事件的專屬 ID。

至少一個 ID

必須設定下列至少一個欄位：

clientId：網頁用戶端使用者執行個體的專屬 ID。請參閱「將事件傳送至 Measurement Protocol」。
adIdentifiers.gclid：Google 點擊 ID。
userData：使用者的 ID，例如電子郵件地址、電話號碼或地址資訊。

destinationReferences

如果要求層級 destinations 清單包含多個 Google Analytics Destination，則為必填。在 destinationReferences 中新增項目，指定應接收事件的 Google Analytics 目的地。如要進一步瞭解目的地參照，請參閱「將事件傳送至多個目的地」。

如果未設定 destinationReferences，或有多個參照 Google Analytics 目的地的項目，Data Manager API 會拒絕事件，並傳回 MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT 錯誤。

userId

選用。使用者的 User-ID。

additionalEventParameters

(選填，但建議使用) 填入這份清單時，請使用其他 Event 欄位未擷取的任何 Google Analytics 事件參數。參數可以包含purchase事件中的其他建議參數，或是您想擷取的其他參數。使用 EventParameter 的 Google Analytics 參數名稱。parameterName

舉例來說，如果交易有相關稅金，請在 additionalEventParameters 中新增項目，並將 parameterName 設為 tax，以及將 value 設為稅金費用。

我們不建議為 transactionId、currency 或 value Google Analytics 事件參數新增項目。請改為填入 Event 的 transactionId、currency 和 conversionValue，這些屬性的優先順序高於 additionalEventParameters 中的任何項目。

為購買事件新增購物車資料

在 Event 的 cartData 欄位中，填入所購商品的相關資訊。為每項購買的商品，將 Item 物件新增至 CartData 的 items 清單，並填入下列欄位 (如所示)：

itemId

必要。商品的專屬 ID。

unitPrice

必填。此為單位價格，不含稅金、運費和事件範圍 (交易層級) 折扣。

如果商品有商品範圍折扣，請使用折扣單價。舉例來說，如果商品的單價為 27.67，單一折扣為 6.66，則請將 unitPrice 設為 21.01。

quantity

必填。這項特定商品的購買單位數。

additionalItemParameters

請在其他 Item 欄位中未擷取的任何項目範圍參數，填入這份清單。使用 parameterName 的 Google Analytics 項目參數名稱，適用於 ItemParameter。

舉例來說，如果項目有品牌和類別，請在項目的 additionalItemParameters 中新增項目，並將 parameterName 設為 item_brand，value 設為品牌名稱；另一個項目的 parameterName 則設為 item_category，value 設為項目的類別。

我們不建議為 quantity、price 或 item_id Google Analytics 項目參數新增項目。請改為填入 Item 的 itemId、unitPrice 和 quantity，這些屬性的優先順序高於 additionalItemParameters 中的任何項目。

以下是第二個事件中，經過格式化、雜湊處理和編碼的資料範例 Event，其中包含 Google Analytics 的額外資料：

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

建立要求主體

將 Destination 和 Events 合併為要求主體：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

更新郵件內文中的預留位置，例如 OPERATING_ACCOUNT_ID 和 PRODUCT_DESTINATION_ID，並填入帳戶和目的地的值。
將 validateOnly 設為 true，即可驗證要求，但不會套用變更。準備好套用變更時，請將 validateOnly 設為 false。
請注意，這個範例並未使用加密。

傳送要求

使用範本右上角的複製按鈕，複製要求主體。
按一下工具列中的「API」按鈕。
將複製的要求主體貼到「Request body」方塊。
按一下「執行」按鈕，完成授權提示，然後查看回覆。

成功回應

如果要求成功，回應會傳回包含 requestId 的物件。

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

記錄傳回的 requestId，以便在處理要求中的每個目的地時，擷取診斷資訊。

失敗回應

如果要求失敗，系統會傳回錯誤回應狀態碼 (例如 400 Bad Request)，以及包含錯誤詳細資料的回應。

舉例來說，如果 emailAddress 包含純文字字串，而非十六進位編碼值，則會產生下列回應：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

未經過雜湊處理且僅經過十六進位編碼的 emailAddress 會產生下列回應：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

將事件傳送至多個目的地

如果資料包含不同目的地的事件，您可以使用目的地參照，在同一個要求中傳送這些事件。

舉例來說，如果您有轉換動作 ID 123456789 的事件，以及轉換動作 ID 777111122 的另一個事件，請設定每個 Destination 的 reference，在單一要求中傳送這兩個事件。reference 是使用者定義的。唯一的要求是每個 Destination 都必須有專屬的 reference。以下是要求的修改後 destinations 清單：

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

設定每個 Event 的 destinationReferences，將其傳送至一或多個特定目的地。舉例來說，以下 Event 只適用於第一個 Destination，因此其 destinationReferences 清單只包含第一個 Destination 的 reference：

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

destinationReferences 欄位是清單，因此您可以為事件指定多個目的地。如果未設定 Event 的 destinationReferences，Data Manager API 會將事件傳送至要求中的所有目的地。

如果事件有多個目的地，Data Manager API 會將相關欄位傳送至每個目的地。舉例來說，如果事件有 Google Ads 目的地和 Google Analytics 目的地，當 API 將事件傳送至 Google Analytics 目的地時，會加入 Google Analytics 欄位，例如 clientId 或 eventName；將事件傳送至 Google Ads 目的地時，則會加入 Google Ads 欄位，例如 customVariables。

後續步驟

設定驗證機制，並透過用戶端程式庫設定環境。
瞭解各類資料的格式、雜湊和編碼規定。
瞭解如何加密使用者資料。
瞭解如何擷取要求診斷資訊。
瞭解最佳做法。
瞭解限制和配額。

事件總覽

傳送事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

準備目的地

準備事件資料

事件 1

事件 2

設定資料格式

事件 1

事件 2

雜湊並編碼資料

事件 1

事件 2

將資料轉換為 Event 物件

新增工作階段屬性

新增 Google Analytics 資訊

為購買事件新增購物車資料

建立要求主體

傳送要求

成功回應

失敗回應

將事件傳送至多個目的地

後續步驟

傳送事件

將資料轉換為 `Event` 物件