Method: customers.uploadClickConversions

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

Danh sách các lỗi đã gửi: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

Yêu cầu HTTP

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

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

Tham số đường dẫn

Tham số
customerId

string

Bắt buộc. Mã của khách hàng thực hiện việc 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
}
Trường
conversions[]

object (ClickConversion)

Bắt buộc. Những 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 khi 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 (đúng). Hãy tham khảo 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, yêu cầu sẽ được xác thực nhưng không được thực thi. Chỉ trả về lỗi, không trả về 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ề các lỗi nếu tìm thấy lỗi. Nếu sai, 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ề 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 lượt tải dữ liệu khách hàng tiềm năng lên 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ả 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. 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 nếu bạn đặt trường này thành true. Vì đây là những lỗi có thể xảy ra đối với những sự kiện như vậy, nên 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 trong tất cả lượt chuyển đổi không phải của một chiến dịch trên Google Ads. Nhờ đó, bạn chỉ cần tập trung vào những lỗi mà bạn có thể giải quyết.

Mặc định là sai.
jobId

integer

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

Nội dung phản hồi

Tin nhắn phản hồ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
}
Trường
partialFailureError

object (Status)

Lỗi liên quan đến lượt chuyển đổi không thành công ở chế độ lỗi một phần. Được trả về khi tất cả lỗi xảy ra trong các lượt chuyển đổi. Nếu có lỗi xảy ra 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 tham khảo 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)

Được trả về 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 được lỗi. Kết quả không được trả về khi AuthenticationOnly 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
}
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à được 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 liên quan đến lượt chuyển đổi trên web và được 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 không nên đặt trong trường hợp 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 liên kết với lượt chuyển đổi này. Hệ thống chỉ hỗ trợ hashEmail và hashedPhoneNumber cho hoạt độ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. 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ị chuyển đổi cho nhà quảng cáo.
currencyCode

string

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

string

Mã đơn hàng 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
}
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)
    }
  ]
}
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 miễn phí vận chuyển và chiết khấu 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 nhấp chuột.
items[]

object (Item)

Dữ liệu của những mặt hàng được mua.

Mục

Chứa dữ liệu về mặt hàng đã mua.

Biểu diễn dưới dạng JSON 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
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 nhấp chuột.

ConversionEnvironment

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

Enum
UNSPECIFIED Chưa chỉ đị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 này được ghi lại trên một trang web.

ClickConversionResult

Thông tin nhận dạng 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
}
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à được 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 liên quan đến lượt chuyển đổi trên web và được 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 liên kết với lượt chuyển đổi này. Hệ thống chỉ hỗ trợ hashEmail và hashedPhoneNumber cho hoạt độ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".