Method: customers.uploadClickConversions

處理指定點擊轉換。

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

HTTP 要求

POST https://googleads.googleapis.com/v16/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 會是空白的。VerifyOnly 為 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

與應用程式轉換相關的點擊 ID，可來自 iOS 14 之後的 iOS 裝置。
wbraid

string

與網站轉換相關的點擊 ID，可來自 iOS 14 之後的 iOS 裝置。
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

與應用程式轉換相關的點擊 ID，可來自 iOS 14 之後的 iOS 裝置。
wbraid

string

與網站轉換相關的點擊 ID，可來自 iOS 14 之後的 iOS 裝置。
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」。