傳送事件

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

在下列任一情境中，使用 Data Manager API：

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

    所有 Google Ads 帳戶都能使用這項功能，但只有在許可清單上的 Google Analytics 資源才能使用。如有意將 Google Analytics 資源加入允許清單，請填寫這份表單。

  • 傳送 Google Ads 離線轉換或待開發客戶強化轉換的事件資料。

選擇要查看的指南版本：

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

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

準備目的地

傳送資料前，您必須先準備至少一個資料的 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 必須是下列其中一項：

  1. Google Ads 轉換的 ID，其中 type 設為 WEBPAGE。在 Google Ads 使用者介面中，WEBPAGE 轉換動作的「轉換來源」為「網站」。

  2. 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。請按照指示填入下列欄位：

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

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

  2. 根據用途設定必填欄位。

    用途 ID transactionId eventSource
    離線轉換或待開發客戶強化轉換 必填。設定至少下列其中一項： 選用 必填。設為 EventSource 的其中一個列舉值。
    傳送至 Google Ads 目的地做為額外資料來源的事件 必填。設定至少下列其中一項： 必要 (選用步驟) 如要設定，必須為 WEB。
    傳送至 Google Analytics 目的地的事件，做為額外資料來源 必填。設定至少下列其中一項： 必要 (選用步驟) 如要設定，必須為 WEB。

  3. 如果您將事件做為額外資料來源傳送至 Google Ads 目的地，請參閱「Google 如何處理額外資料來源的資料」。

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

Google 如何處理額外資料來源的資料

在同一個轉換動作中，Google 會使用 transactionId，將不同來源 (例如網站代碼和 Data Manager API 擷取要求) 傳送的轉換事件重複資料刪除。下表說明系統如何處理擷取要求中的資料。

情境 資料欄位 處理方式
transactionId 與現有代碼事件相符 conversionValue (含 currencyCode)

已更新。conversionValue (含 currencyCode) 中的值會Event覆寫代碼記錄的原始值。

注意：轉換動作的初始 14 天試用期內，系統會停用價值更新功能。試用期結束前，系統不會在 Google Ads 報表中覆寫代碼價值。
transactionId 符合現有代碼事件 conversionValue 或 currencyCode 以外的其他欄位 (例如 adIdentifiers.gclid) 已忽略。其他資料來源的其他欄位值不會覆寫 Google 代碼原本為比對相符交易記錄的欄位值。
transactionId 與任何現有事件都「不」相符 所有提供的資料 (例如 userData、 conversionValue、currencyCode)

用於建立新的轉換事件。Google 接著會嘗試使用您提供的 ID (例如 adIdentifiers.gclid 或 userData)，將這項新轉換歸因於廣告點擊。

注意：在最初的 14 天試用期內，這些新建立的轉換會顯示在報表中，但不會用於出價。試用期結束後，這些轉換就會自動用於出價。

新增工作階段屬性

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

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

在 Data Manager API 中，您可以使用兩種方法傳送工作階段屬性：

  1. 建議：將 adIdentifiers 的 sessionAttributes 欄位設為採用 Base64 編碼的工作階段屬性字串。請按照「如何擷取 session_attributes」一文中的操作說明，修改表單提交頁面，擷取編碼字串。

  2. 如果無法使用 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

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

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 的 parameterName Google Analytics 參數名稱。

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

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

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

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

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 中的任何項目。

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

{
  "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
}
  1. 更新主體中的預留位置，例如 OPERATING_ACCOUNT_ID 和 PRODUCT_DESTINATION_ID，並填入帳戶和目的地的相關值。
  2. 將 validateOnly 設為 true，即可驗證要求，但不會套用變更。準備好套用變更時，請將 validateOnly 設為 false。
  3. 請注意，這個範例並未使用加密。

傳送要求

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

成功回應

如果要求成功，回應會傳回包含 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 目的地時，加入 clientId 或 eventName 等 Google Analytics 欄位，並在將事件傳送至 Google Ads 目的地時，加入 customVariables 等 Google Ads 欄位。

後續步驟

上一頁
事件總覽