Method: customers.uploadClickConversions

지정된 클릭 전환을 처리합니다.

발생한 오류 목록: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

HTTP 요청

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

URL은 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에 대한 클릭이 발견되지 않은 경우에도 성공을 반환합니다.

이 설정은 GCLID, GBRAID, WBRAID 대신 userIdentifiers를 사용하는 리드 확보용 향상된 전환 업로드에만 영향을 미칩니다. 리드 확보용 향상된 전환을 업로드할 때는 Google Ads 캠페인에서 발생하지 않을 수도 있는 이벤트를 포함하여 모든 전환 이벤트를 API에 업로드해야 합니다. 이 필드가 true로 설정되면 Google Ads 캠페인에서 발생하지 않은 이벤트를 업로드할 때 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가 비어 있습니다. validateOnly가 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부터 iOS 기기에서 발생한 클릭의 클릭 식별자입니다.
wbraid

string

웹 전환과 연결되어 있고 iOS 14부터 iOS 기기에서 발생한 클릭의 클릭 식별자입니다.
externalAttributionData

object (ExternalAttributionData)

외부 기여 전환에 대한 추가 데이터입니다. 이 필드는 외부 기여 전환 액션이 있는 전환에 필요하지만 달리 설정하면 안 됩니다.
customVariables[]

object (CustomVariable)

전환과 연결된 맞춤 변수입니다.
cartData

object (CartData)

이 전환과 연결된 장바구니 데이터입니다.
userIdentifiers[]

object (UserIdentifier)

이 전환과 연결된 사용자 식별자입니다. 전환 업로드에는 hashEmail 및 hashPhoneNumber만 지원됩니다. 각 전환의 최대 사용자 식별자 수는 5개입니다.
conversionEnvironment

enum (ConversionEnvironment)

전환이 기록된 환경(예: 앱 또는 웹)입니다.
consent

object (Consent)

이벤트에 대한 동의 설정입니다.
gclid

string

이 전환과 연결된 Google 클릭 ID (gclid)입니다.
conversionAction

string

이 전환과 연결된 전환 액션의 리소스 이름입니다. 참고: 이 리소스 이름은 고객 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)

상품이 업로드된 판매자 센터 ID입니다.
feedCountryCode

string

상품이 업로드된 피드와 연결된 국가 코드입니다.
feedLanguageCode

string

상품이 업로드된 피드와 연결된 언어 코드입니다.
localTransactionCost

number

전체 장바구니에 대한 무료 배송 및 쿠폰 할인과 같은 모든 거래별 할인 금액의 합계입니다. 통화 코드는 ClickConversion 메시지의 통화 코드와 동일합니다.
items[]

object (Item)

구매한 상품의 데이터입니다.

항목

구매한 항목의 데이터가 포함됩니다.

JSON 표현 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
입력란
productId

string

상품의 쇼핑 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부터 iOS 기기에서 발생한 클릭의 클릭 식별자입니다.
wbraid

string

웹 전환과 연결되어 있고 iOS 14부터 iOS 기기에서 발생한 클릭의 클릭 식별자입니다.
userIdentifiers[]

object (UserIdentifier)

이 전환과 연결된 사용자 식별자입니다. 전환 업로드에는 hashEmail 및 hashPhoneNumber만 지원됩니다. 각 전환의 최대 사용자 식별자 수는 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').