Method: customers.uploadClickConversions

Xử lý các lượt chuyển đổi lượt nhấp đã cho.

Danh sách các lỗi đã xảy ra: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Các tham số
customerId

string

Bắt buộc. Mã của khách hàng thực hiện quá trình tải lên.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "conversions": [
    {
      object (ClickConversion)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "debugEnabled": boolean,
  "jobId": integer
}
Các trường
conversions[]

object (ClickConversion)

Bắt buộc. Lượt chuyển đổi đang được tải lên.
partialFailure

boolean

Bắt buộc. Nếu đúng, các thao tác thành công sẽ được thực hiện và các thao tác không hợp lệ sẽ trả về lỗi. Nếu giá trị là false, tất cả các thao tác sẽ được thực hiện trong một giao dịch với điều kiện và chỉ khi tất cả các thao tác đó đều hợp lệ. Bạn phải luôn đặt giá trị này thành true. Hãy truy cập https://developers.google.com/google-ads/api/docs/best-practices/partial-failures để biết thêm thông tin về lỗi một phần.
validateOnly

boolean

Nếu đúng thì yêu cầu sẽ được xác thực nhưng không được thực thi. Chỉ có lỗi được trả về, chứ không phải kết quả.
debugEnabled

boolean

Nếu đúng, API sẽ thực hiện tất cả các bước kiểm tra tệp tải lên và trả về lỗi nếu tìm thấy lỗi. Nếu giá trị là false, thì thao tác này sẽ chỉ thực hiện xác thực dữ liệu đầu vào cơ bản, bỏ qua các bước kiểm tra tải lên tiếp theo và trả về kết quả thành công ngay cả khi không tìm thấy lượt nhấp nào cho userIdentifiers đã cung cấp.

Chế độ cài đặt này chỉ ảnh hưởng đến tính năng Lượt chuyển đổi nâng cao cho những nội dung tải lên về khách hàng tiềm năng sử dụng userIdentifiers thay vì GCLID, GBRAID hoặc WBRAID. Khi tải lượt chuyển đổi nâng cao cho khách hàng tiềm năng lên, bạn nên tải tất cả các sự kiện chuyển đổi lên API, bao gồm cả những sự kiện có thể không đến từ các chiến dịch trên Google Ads. Nếu bạn đặt trường này thành true, thì việc tải lên một sự kiện không phải từ một chiến dịch trên Google Ads sẽ dẫn đến lỗi CLICK_NOT_FOUND. Vì những lỗi này là bình thường đối với những sự kiện như vậy, hãy đặt trường này thành false để bạn có thể xác nhận rằng các tệp tải lên được định dạng đúng cách nhưng bỏ qua CLICK_NOT_FOUND lỗi trên tất cả các lượt chuyển đổi không phải của một chiến dịch trên Google Ads. Việc này giúp bạn chỉ tập trung vào những lỗi mà bạn có thể xử lý.

Mặc định là sai.
jobId

integer

Không bắt buộc. Giá trị đầu vào không bắt buộc để đặt mã công việc. Phải là số không âm và nhỏ hơn 2^31 nếu được cung cấp. Nếu trường này không được cung cấp, API sẽ tạo mã công việc trong phạm vi [2^31, (2^63)-1]. API sẽ trả về giá trị của yêu cầu này trong trường jobId của UploadClickConversionsResponse.

Nội dung phản hồi

Tin nhắn trả lời cho ConversionUploadService.UploadClickConversions.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ClickConversionResult)
    }
  ],
  "jobId": string
}
Các trường
partialFailureError

object (Status)

Các lỗi liên quan đến lượt chuyển đổi bị lỗi ở chế độ lỗi một phần. Được trả về khi tất cả lỗi xảy ra trong lượt chuyển đổi. Nếu có lỗi xảy ra bên ngoài lượt chuyển đổi (ví dụ: lỗi xác thực), chúng tôi sẽ trả về lỗi cấp RPC. Hãy truy cập https://developers.google.com/google-ads/api/docs/best-practices/partial-failures để biết thêm thông tin về lỗi một phần.
results[]

object (ClickConversionResult)

Đã trả lại cho các lượt chuyển đổi được xử lý thành công. Proto sẽ trống đối với các hàng nhận lỗi. Kết quả không được trả về khi validationOnly là true.
jobId

string (int64 format)

Mã công việc cho lô tải lên.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem Tổng quan về OAuth 2.0.

ClickConversion

Lượt chuyển đổi từ lượt nhấp.

Biểu diễn dưới dạng 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
}
Các trường
gbraid

string

Giá trị nhận dạng lượt nhấp cho các lượt nhấp liên quan đến lượt chuyển đổi ứng dụng và bắt nguồn từ các thiết bị iOS bắt đầu bằng iOS14.
wbraid

string

Giá trị nhận dạng lượt nhấp cho các lượt nhấp được liên kết với lượt chuyển đổi trên web và bắt nguồn từ các thiết bị iOS bắt đầu bằng iOS14.
externalAttributionData

object (ExternalAttributionData)

Dữ liệu bổ sung về lượt chuyển đổi được phân bổ bên ngoài. Trường này là bắt buộc cho các lượt chuyển đổi có hành động chuyển đổi được phân bổ bên ngoài, nhưng bạn không nên đặt trường này theo cách khác.
customVariables[]

object (CustomVariable)

Các biến tuỳ chỉnh được liên kết với lượt chuyển đổi này.
cartData

object (CartData)

Dữ liệu giỏ hàng được liên kết với lượt chuyển đổi này.
userIdentifiers[]

object (UserIdentifier)

Giá trị nhận dạng người dùng được liên kết với lượt chuyển đổi này. Hệ thống chỉ hỗ trợ hashedEmail và hashedPhoneNumber cho tính năng tải lượt chuyển đổi lên. Số lượng giá trị nhận dạng người dùng tối đa cho mỗi lượt chuyển đổi là 5.
conversionEnvironment

enum (ConversionEnvironment)

Môi trường mà lượt chuyển đổi này được ghi lại, ví dụ: Ứng dụng hoặc Web.
consent

object (Consent)

Chế độ cài đặt về sự đồng ý cho sự kiện.
gclid

string

Mã lượt nhấp của Google (gclid) được liên kết với lượt chuyển đổi này.
conversionAction

string

Tên tài nguyên của hành động chuyển đổi được liên kết với lượt chuyển đổi này. Lưu ý: Mặc dù tên tài nguyên này bao gồm mã khách hàng và mã hành động chuyển đổi, nhưng việc xác thực sẽ bỏ qua mã khách hàng và sử dụng mã hành động chuyển đổi làm giá trị nhận dạng duy nhất của hành động chuyển đổi đó.
conversionDateTime

string

Ngày giờ xảy ra lượt chuyển đổi. Phải sau thời gian nhấp. Bạn phải chỉ định múi giờ. Định dạng là "yyyy-mm-dd hh:mm:ss+|-hh:mm", ví dụ: "2019-01-01 12:32:45-08:00".
conversionValue

number

Giá trị của lượt chuyển đổi đối với nhà quảng cáo.
currencyCode

string

Đơn vị tiền tệ được liên kết với giá trị chuyển đổi. Đây là mã tiền tệ gồm 3 ký tự theo ISO 4217. Ví dụ: USD, EUR.
orderId

string

Mã đơn hàng được liên kết với lượt chuyển đổi. Bạn chỉ có thể sử dụng một mã đơn hàng cho một lượt chuyển đổi trên mỗi hành động chuyển đổi.

ExternalAttributionData

Chứa thông tin bổ sung về lượt chuyển đổi được phân bổ bên ngoài.

Biểu diễn dưới dạng JSON 
{
  "externalAttributionCredit": number,
  "externalAttributionModel": string
}
Các trường
externalAttributionCredit

number

Đại diện cho một phần của lượt chuyển đổi được phân bổ cho lượt nhấp trên Google Ads.
externalAttributionModel

string

Chỉ định tên mô hình phân bổ.

CartData

Chứa thông tin bổ sung về dữ liệu giỏ hàng.

Biểu diễn dưới dạng JSON 
{
  "merchantId": string,
  "feedCountryCode": string,
  "feedLanguageCode": string,
  "localTransactionCost": number,
  "items": [
    {
      object (Item)
    }
  ]
}
Các trường
merchantId

string (int64 format)

Mã truy cập Merchant Center, nơi các mặt hàng được tải lên.
feedCountryCode

string

Mã quốc gia liên kết với nguồn cấp dữ liệu chứa mặt hàng mà bạn tải lên.
feedLanguageCode

string

Mã ngôn ngữ liên kết với nguồn cấp dữ liệu chứa mặt hàng mà bạn tải lên.
localTransactionCost

number

Tổng tất cả ưu đãi giảm giá cấp giao dịch, chẳng hạn như ưu đãi vận chuyển miễn phí và ưu đãi chiết khấu bằng phiếu giảm giá cho toàn bộ giỏ hàng. Mã đơn vị tiền tệ giống với mã trong thông báo Lượt chuyển đổi theo lượt nhấp.
items[]

object (Item)

Dữ liệu của các mặt hàng đã mua.

Mục

Chứa dữ liệu của các mặt hàng đã mua.

Biểu diễn dưới dạng JSON 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
Các trường
productId

string

Mã mua sắm của mặt hàng. Phải bằng với mã nhận dạng sản phẩm trong Merchant Center.
quantity

integer

Số lượng mặt hàng đã bán ra.
unitPrice

number

Đơn giá, chưa bao gồm thuế, phí vận chuyển và mọi khoản chiết khấu ở cấp giao dịch. Mã đơn vị tiền tệ giống với mã trong thông báo Lượt chuyển đổi theo lượt nhấp.

ConversionEnvironment

Môi trường chuyển đổi của lượt chuyển đổi được tải lên.

Enum
UNSPECIFIED Chưa xác định.
UNKNOWN Chỉ dùng cho giá trị trả về. Đại diện cho giá trị không xác định trong phiên bản này.
APP Lượt chuyển đổi này được ghi lại trên một ứng dụng.
WEB Lượt chuyển đổi được ghi lại trên một trang web.

ClickConversionResult

Thông tin xác định cho một lượt chuyển đổi lượt nhấp được xử lý thành công.

Biểu diễn dưới dạng JSON 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
Các trường
gbraid

string

Giá trị nhận dạng lượt nhấp cho các lượt nhấp liên quan đến lượt chuyển đổi ứng dụng và bắt nguồn từ các thiết bị iOS bắt đầu bằng iOS14.
wbraid

string

Giá trị nhận dạng lượt nhấp cho các lượt nhấp được liên kết với lượt chuyển đổi trên web và bắt nguồn từ các thiết bị iOS bắt đầu bằng iOS14.
userIdentifiers[]

object (UserIdentifier)

Giá trị nhận dạng người dùng được liên kết với lượt chuyển đổi này. Hệ thống chỉ hỗ trợ hashedEmail và hashedPhoneNumber cho tính năng tải lượt chuyển đổi lên. Số lượng giá trị nhận dạng người dùng tối đa cho mỗi lượt chuyển đổi là 5.
gclid

string

Mã lượt nhấp của Google (gclid) được liên kết với lượt chuyển đổi này.
conversionAction

string

Tên tài nguyên của hành động chuyển đổi được liên kết với lượt chuyển đổi này.
conversionDateTime

string

Ngày giờ xảy ra lượt chuyển đổi. Định dạng là "yyyy-mm-dd hh:mm:ss+|-hh:mm", ví dụ: "2019-01-01 12:32:45-08:00".