Method: customers.uploadClickConversions

處理指定的點擊轉換。

擲回錯誤清單：AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

HTTP 要求

POST https://googleads.googleapis.com/v15/customers/{customerId}:uploadClickConversions

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
customerId

string

必要欄位。執行上傳作業的客戶 ID。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "conversions": [
    {
      object (ClickConversion)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "debugEnabled": boolean,
  "jobId": integer
}
欄位
conversions[]

object (ClickConversion)

必要欄位。上傳的轉換資料。
partialFailure

boolean

必要欄位。如果為 true，系統就會執行成功的作業，且無效的作業會傳回錯誤。如果為 false，只有在所有作業皆有效的情況下，系統才會在單筆交易中執行所有作業。這個欄位必須一律設為 true。如要進一步瞭解部分失敗，請參閱 https://developers.google.com/google-ads/api/docs/best-practices/partial-failures。
validateOnly

boolean

如果為 true，則驗證要求但尚未執行。系統只會傳回錯誤，而非傳回結果。
debugEnabled

boolean

如果為 true，API 將會執行所有上傳檢查，並傳回錯誤訊息 (如有)。如果設為 False，系統只會執行基本輸入驗證、略過後續上傳檢查，即使在提供的 userIdentifiers 中找不到點擊，也不會傳回成功。

這項設定只會影響使用 userIdentifiers (而非 GCLID、GBRAID 或 WBRAID) 的待開發客戶上傳強化轉換。上傳待開發客戶強化轉換時，您應將所有轉換事件上傳至 API，包括可能不是來自 Google Ads 廣告活動的轉換事件。如果上傳的事件不是來自 Google Ads 廣告活動，如果這個欄位設為 true，就會導致 CLICK_NOT_FOUND 錯誤。這類事件應該有這類錯誤，因此請將這個欄位設為 false 以便確認上傳資料格式正確，但可以忽略所有非 Google Ads 廣告活動的轉換中的 CLICK_NOT_FOUND 項錯誤。這樣就能只專心處理可解決的錯誤。

預設值為 false。
jobId

integer

選用設定。選填的輸入內容，用於設定工作 ID。如有提供，必須是小於 2^31 的非負數。如未提供這個欄位，API 會產生在 [2^31, (2^63)-1] 範圍內的工作 ID。API 會在 UploadClickConversionsResponse 的 jobId 欄位中傳回這項要求的值。

回應主體

ConversionUploadService.UploadClickConversions 的回應訊息。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ClickConversionResult)
    }
  ],
  "jobId": string
}
欄位
partialFailureError

object (Status)

在部分失敗模式下發生轉換失敗的相關錯誤。轉換內發生所有錯誤時，系統會傳回這個編號。如果轉換以外發生任何錯誤 (例如驗證錯誤)，我們會傳回遠端程序呼叫 (RPC) 層級錯誤。如要進一步瞭解部分失敗，請參閱 https://developers.google.com/google-ads/api/docs/best-practices/partial-failures。
results[]

object (ClickConversionResult)

成功處理的轉換會傳回。若發生錯誤的資料列，Proto 將為空白。validationOnly 為 true 時，不會傳回結果。
jobId

string (int64 format)

上傳批次的工作 ID。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/adwords

詳情請參閱 OAuth 2.0 總覽。

ClickConversion

點擊轉換。

JSON 表示法 
{
  "gbraid": string,
  "wbraid": string,
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "conversionEnvironment": enum (ConversionEnvironment),
  "consent": {
    object (Consent)
  },
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}
欄位
gbraid

string

與應用程式轉換 (自 iOS 14 以上版本) 相關的點擊 ID。
wbraid

string

與網站轉換 (自 iOS 14 以上版本) 相關的點擊 ID。
externalAttributionData

object (ExternalAttributionData)

外部歸因轉換的其他資料。對於包含外部歸因轉換動作的轉換，此為必要欄位，但請勿設定其他欄位。
customVariables[]

object (CustomVariable)

與這次轉換相關聯的自訂變數。
cartData

object (CartData)

與這項轉換相關聯的購物車資料。
userIdentifiers[]

object (UserIdentifier)

與這次轉換相關聯的使用者 ID。上傳轉換資料時，只能使用 hashedEmail 和 hashedPhoneNumber。每次轉換的使用者 ID 數量上限為 5 個。
conversionEnvironment

enum (ConversionEnvironment)

記錄到這項轉換的環境，例如應用程式或網站。
consent

object (Consent)

事件的同意聲明設定。
gclid

string

與這個轉換相關聯的 Google 點擊 ID (gclid)。
conversionAction

string

與這個轉換相關聯的轉換動作資源名稱。注意：雖然這個資源名稱是由客戶 ID 和轉換動作 ID 組成，但驗證作業會忽略客戶 ID，並使用轉換動作 ID 做為轉換動作的唯一 ID。
conversionDateTime

string

轉換發生的日期。必須晚於點擊時間。必須指定時區。格式為「yyyy-mm-dd hh:mm:ss+|-hh:mm」，例如「2019-01-01 12:32:45-08:00」。
conversionValue

number

廣告客戶的轉換價值。
currencyCode

string

與轉換價值相關聯的貨幣。這是 ISO 4217 3 字元的貨幣代碼。例如：USD、EUR。
orderId

string

與轉換相關聯的訂單 ID。每個轉換動作只能有一個訂單 ID。

ExternalAttributionData

包含外部歸因轉換的其他資訊。

JSON 表示法 
{
  "externalAttributionCredit": number,
  "externalAttributionModel": string
}
欄位
externalAttributionCredit

number

代表歸給 Google Ads 點擊的轉換比例。
externalAttributionModel

string

指定歸因模式名稱。

CartData

包含購物車資料的其他相關資訊。

JSON 表示法 
{
  "merchantId": string,
  "feedCountryCode": string,
  "feedLanguageCode": string,
  "localTransactionCost": number,
  "items": [
    {
      object (Item)
    }
  ]
}
欄位
merchantId

string (int64 format)

上傳商品的 Merchant Center ID。
feedCountryCode

string

與上傳商品所在動態饋給相關聯的國家/地區代碼。
feedLanguageCode

string

與上傳項目所屬動態饋給相關聯的語言代碼。
localTransactionCost

number

所有交易折扣的總和，例如整個購物車的免運費和優待券折扣。貨幣代碼與 ClickConversion 訊息中的貨幣代碼相同。
items[]

object (Item)

購買的商品資料。

項目

包含購買項目的資料。

JSON 表示法 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
欄位
productId

string

商品的購物 ID。必須與 Merchant Center 產品 ID 相同。
quantity

integer

此為售出項目的數量。
unitPrice

number

不含稅金、運費和任何交易層級折扣的單價。貨幣代碼與 ClickConversion 訊息中的貨幣代碼相同。

ConversionEnvironment

上傳轉換的轉換環境。

列舉
UNSPECIFIED 未指定。
UNKNOWN 僅適用於傳回值。代表此版本中未知的值。
APP 轉換記錄在應用程式中。
WEB 轉換記錄在網站上。

ClickConversionResult

識別成功處理 ClickConversion 的資訊。

JSON 表示法 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
欄位
gbraid

string

與應用程式轉換 (自 iOS 14 以上版本) 相關的點擊 ID。
wbraid

string

與網站轉換 (自 iOS 14 以上版本) 相關的點擊 ID。
userIdentifiers[]

object (UserIdentifier)

與這次轉換相關聯的使用者 ID。上傳轉換資料時，只能使用 hashedEmail 和 hashedPhoneNumber。每次轉換的使用者 ID 數量上限為 5 個。
gclid

string

與這個轉換相關聯的 Google 點擊 ID (gclid)。
conversionAction

string

與這個轉換相關聯的轉換動作資源名稱。
conversionDateTime

string

轉換發生的日期。格式為「yyyy-mm-dd hh:mm:ss+|-hh:mm」，例如「2019-01-01 12:32:45-08:00」。