Bạn có thể sử dụng API Google Ads để tải lượt chuyển đổi từ lượt nhấp ngoại tuyến lên Google Ads nhằm theo dõi những quảng cáo đã dẫn đến lượt bán hàng trong thế giới thực, chẳng hạn như qua điện thoại hoặc thông qua nhân viên bán hàng.
Thiết lập
Có một số điều kiện tiên quyết để thiết lập tính năng lượt chuyển đổi ngoại tuyến hoạt động. Hãy đảm bảo bạn đáp ứng tất cả các điều kiện tiên quyết trước khi tiến hành triển khai:
Bật tính năng theo dõi lượt chuyển đổi trong khách hàng chuyển đổi trên Google Ads.
Định cấu hình tính năng gắn thẻ và lưu mã lượt nhấp.
1. Bật tính năng theo dõi lượt chuyển đổi trong khách hàng chuyển đổi trên Google Ads
Nếu đã hoàn tất hướng dẫn bắt đầu về lượt chuyển đổi và đã bật tính năng theo dõi lượt chuyển đổi, bạn có thể chuyển sang bước hai: định cấu hình tính năng gắn thẻ.
Truy xuất thông tin về chế độ thiết lập tính năng theo dõi lượt chuyển đổi
Bạn có thể kiểm tra chế độ thiết lập tính năng theo dõi lượt chuyển đổi của tài khoản và xác nhận tính năng theo dõi lượt chuyển đổi đã được bật hay chưa bằng cách truy vấn tài nguyên Customer cho ConversionTrackingSetting.
Thực hiện truy vấn sau bằng GoogleAdsService.SearchStream:
SELECT
customer.conversion_tracking_setting.google_ads_conversion_customer,
customer.conversion_tracking_setting.conversion_tracking_status,
customer.conversion_tracking_setting.conversion_tracking_id,
customer.conversion_tracking_setting.cross_account_conversion_tracking_id
FROM customer
Trường google_ads_conversion_customer cho biết tài khoản Google Ads tạo và quản lý lượt chuyển đổi cho khách hàng này. Đối với những khách hàng sử dụng tính năng theo dõi lượt chuyển đổi trên nhiều tài khoản, đây là mã nhận dạng của tài khoản người quản lý. Bạn nên cung cấp mã khách hàng chuyển đổi của Google Ads dưới dạng customer_id trong các yêu cầu API Google Ads để tạo và quản lý lượt chuyển đổi.
Xin lưu ý rằng trường này sẽ được điền ngay cả khi bạn chưa bật tính năng theo dõi lượt chuyển đổi.
Trường conversion_tracking_status cho biết liệu tính năng theo dõi lượt chuyển đổi có được bật hay không và liệu tài khoản có đang sử dụng tính năng theo dõi lượt chuyển đổi trên nhiều tài khoản hay không.
Tạo hành động chuyển đổi trong khách hàng chuyển đổi trên Google Ads
Nếu giá trị conversion_tracking_status là NOT_CONVERSION_TRACKED, thì tính năng theo dõi lượt chuyển đổi sẽ không được bật cho tài khoản. Bật tính năng theo dõi lượt chuyển đổi bằng cách tạo ít nhất một ConversionAction trong tài khoản chuyển đổi Google Ads, như trong ví dụ sau. Ngoài ra, bạn có thể tạo hành động chuyển đổi trong giao diện người dùng bằng cách làm theo hướng dẫn trong Trung tâm trợ giúp cho loại lượt chuyển đổi mà bạn muốn bật.
Xin lưu ý rằng tính năng lượt chuyển đổi nâng cao sẽ tự động bật khi được gửi thông qua API Google Ads, nhưng bạn có thể tắt tính năng này thông qua giao diện người dùng Google Ads.
Ví dụ về mã
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
// Creates a ConversionAction.
ConversionAction conversionAction =
ConversionAction.newBuilder()
// Note that conversion action names must be unique. If a conversion action already
// exists with the specified conversion_action_name the create operation will fail with
// a ConversionActionError.DUPLICATE_NAME error.
.setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime())
.setCategory(ConversionActionCategory.DEFAULT)
.setType(ConversionActionType.WEBPAGE)
.setStatus(ConversionActionStatus.ENABLED)
.setViewThroughLookbackWindowDays(15L)
.setValueSettings(
ValueSettings.newBuilder()
.setDefaultValue(23.41)
.setAlwaysUseDefaultValue(true)
.build())
.build();
// Creates the operation.
ConversionActionOperation operation =
ConversionActionOperation.newBuilder().setCreate(conversionAction).build();
try (ConversionActionServiceClient conversionActionServiceClient =
googleAdsClient.getLatestVersion().createConversionActionServiceClient()) {
MutateConversionActionsResponse response =
conversionActionServiceClient.mutateConversionActions(
Long.toString(customerId), Collections.singletonList(operation));
System.out.printf("Added %d conversion actions:%n", response.getResultsCount());
for (MutateConversionActionResult result : response.getResultsList()) {
System.out.printf(
"New conversion action added with resource name: '%s'%n", result.getResourceName());
}
}
}
C#
public void Run(GoogleAdsClient client, long customerId)
{
// Get the ConversionActionService.
ConversionActionServiceClient conversionActionService =
client.GetService(Services.V18.ConversionActionService);
// Note that conversion action names must be unique.
// If a conversion action already exists with the specified name the create operation
// will fail with a ConversionAction.DUPLICATE_NAME error.
string ConversionActionName = "Earth to Mars Cruises Conversion #"
+ ExampleUtilities.GetRandomString();
// Add a conversion action.
ConversionAction conversionAction = new ConversionAction()
{
Name = ConversionActionName,
Category = ConversionActionCategory.Default,
Type = ConversionActionType.Webpage,
Status = ConversionActionStatus.Enabled,
ViewThroughLookbackWindowDays = 15,
ValueSettings = new ConversionAction.Types.ValueSettings()
{
DefaultValue = 23.41,
AlwaysUseDefaultValue = true
}
};
// Create the operation.
ConversionActionOperation operation = new ConversionActionOperation()
{
Create = conversionAction
};
try
{
// Create the conversion action.
MutateConversionActionsResponse response =
conversionActionService.MutateConversionActions(customerId.ToString(),
new ConversionActionOperation[] { operation });
// Display the results.
foreach (MutateConversionActionResult newConversionAction in response.Results)
{
Console.WriteLine($"New conversion action with resource name = " +
$"'{newConversionAction.ResourceName}' was added.");
}
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
// Creates a conversion action.
$conversionAction = new ConversionAction([
// Note that conversion action names must be unique.
// If a conversion action already exists with the specified conversion_action_name
// the create operation will fail with a ConversionActionError.DUPLICATE_NAME error.
'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
'category' => ConversionActionCategory::PBDEFAULT,
'type' => ConversionActionType::WEBPAGE,
'status' => ConversionActionStatus::ENABLED,
'view_through_lookback_window_days' => 15,
'value_settings' => new ValueSettings([
'default_value' => 23.41,
'always_use_default_value' => true
])
]);
// Creates a conversion action operation.
$conversionActionOperation = new ConversionActionOperation();
$conversionActionOperation->setCreate($conversionAction);
// Issues a mutate request to add the conversion action.
$conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
$response = $conversionActionServiceClient->mutateConversionActions(
MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
);
printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);
foreach ($response->getResults() as $addedConversionAction) {
/** @var ConversionAction $addedConversionAction */
printf(
"New conversion action added with resource name: '%s'%s",
$addedConversionAction->getResourceName(),
PHP_EOL
);
}
}
Python
def main(client, customer_id):
conversion_action_service = client.get_service("ConversionActionService")
# Create the operation.
conversion_action_operation = client.get_type("ConversionActionOperation")
# Create conversion action.
conversion_action = conversion_action_operation.create
# Note that conversion action names must be unique. If a conversion action
# already exists with the specified conversion_action_name, the create
# operation will fail with a ConversionActionError.DUPLICATE_NAME error.
conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}"
conversion_action.type_ = (
client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS
)
conversion_action.category = (
client.enums.ConversionActionCategoryEnum.DEFAULT
)
conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED
conversion_action.view_through_lookback_window_days = 15
# Create a value settings object.
value_settings = conversion_action.value_settings
value_settings.default_value = 15.0
value_settings.always_use_default_value = True
# Add the conversion action.
conversion_action_response = (
conversion_action_service.mutate_conversion_actions(
customer_id=customer_id,
operations=[conversion_action_operation],
)
)
print(
"Created conversion action "
f'"{conversion_action_response.results[0].resource_name}".'
)
Ruby
def add_conversion_action(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Add a conversion action.
conversion_action = client.resource.conversion_action do |ca|
ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
ca.type = :UPLOAD_CLICKS
ca.category = :DEFAULT
ca.status = :ENABLED
ca.view_through_lookback_window_days = 15
# Create a value settings object.
ca.value_settings = client.resource.value_settings do |vs|
vs.default_value = 15
vs.always_use_default_value = true
end
end
# Create the operation.
conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action)
# Add the ad group ad.
response = client.service.conversion_action.mutate_conversion_actions(
customer_id: customer_id,
operations: [conversion_action_operation],
)
puts "New conversion action with resource name = #{response.results.first.resource_name}."
end
Perl
sub add_conversion_action {
my ($api_client, $customer_id) = @_;
# Note that conversion action names must be unique.
# If a conversion action already exists with the specified conversion_action_name,
# the create operation fails with error ConversionActionError.DUPLICATE_NAME.
my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid();
# Create a conversion action.
my $conversion_action =
Google::Ads::GoogleAds::V18::Resources::ConversionAction->new({
name => $conversion_action_name,
category => DEFAULT,
type => WEBPAGE,
status => ENABLED,
viewThroughLookbackWindowDays => 15,
valueSettings =>
Google::Ads::GoogleAds::V18::Resources::ValueSettings->new({
defaultValue => 23.41,
alwaysUseDefaultValue => "true"
})});
# Create a conversion action operation.
my $conversion_action_operation =
Google::Ads::GoogleAds::V18::Services::ConversionActionService::ConversionActionOperation
->new({create => $conversion_action});
# Add the conversion action.
my $conversion_actions_response =
$api_client->ConversionActionService()->mutate({
customerId => $customer_id,
operations => [$conversion_action_operation]});
printf "New conversion action added with resource name: '%s'.\n",
$conversion_actions_response->{results}[0]{resourceName};
return 1;
}
Đảm bảo rằng conversion_action_type được đặt thành giá trị ConversionActionType chính xác.
Để biết thêm hướng dẫn về cách tạo hành động chuyển đổi trong API Google Ads, hãy xem bài viết Tạo hành động chuyển đổi.
Truy xuất hành động chuyển đổi hiện có
Bạn có thể truy xuất thông tin chi tiết về một hành động chuyển đổi hiện có bằng cách đưa ra truy vấn sau. Đảm bảo rằng mã khách hàng trong yêu cầu được đặt thành khách hàng chuyển đổi Google Ads mà bạn đã xác định ở trên và loại hành động chuyển đổi được đặt thành giá trị ConversionActionType chính xác.
SELECT
conversion_action.resource_name,
conversion_action.name,
conversion_action.status
FROM conversion_action
WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'
2. Định cấu hình tính năng gắn thẻ và lưu trữ mã lượt nhấp
Làm theo hướng dẫn để xác nhận rằng bạn đã bật tính năng tự động gắn thẻ, đồng thời thiết lập tài khoản Google Ads, trang web và hệ thống theo dõi khách hàng tiềm năng để ghi lại và lưu trữ GCLID, GBRAID hoặc WBRAID của mỗi lượt hiển thị và lượt nhấp cho quảng cáo của bạn. Theo mặc định, tính năng tự động gắn thẻ được bật cho những tài khoản mới.
Tạo yêu cầu
Hãy làm theo hướng dẫn bên dưới để tạo UploadClickConversionsRequest và đặt các trường của lớp này thành các giá trị thích hợp.
customer_idXác định tài khoản Google Ads của tệp tải lên. Đặt giá trị này thành khách hàng chuyển đổi trên Google Ads của tài khoản là nguồn của các lượt nhấp.
job_idCung cấp cơ chế liên kết các yêu cầu tải lên của bạn với thông tin cho mỗi công việc trong chẩn đoán dữ liệu ngoại tuyến.
Nếu bạn không đặt trường này, API Google Ads sẽ gán cho mỗi yêu cầu một giá trị duy nhất trong phạm vi
[2^31, 2^63). Nếu bạn muốn nhóm nhiều yêu cầu vào một công việc logic, hãy đặt trường này thành cùng một giá trị trong phạm vi[0, 2^31)trên mọi yêu cầu trong công việc.job_idtrong phản hồi chứa mã công việc cho yêu cầu, bất kể bạn đã chỉ định giá trị hay để API Google Ads chỉ định giá trị.partial_failure_enabledXác định cách API Google Ads xử lý lỗi từ các thao tác.
Bạn phải đặt trường này thành
true. Tuân theo nguyên tắc về lỗi một phần khi xử lý phản hồi.debug_enabledXác định hành vi báo cáo lỗi đối với tệp tải lên lượt chuyển đổi nâng cao cho khách hàng tiềm năng. API Google Ads bỏ qua trường này khi xử lý các lượt tải lên cho lượt chuyển đổi từ lượt nhấp bằng
gclid,gbraidhoặcwbraid.
Tạo thao tác chuyển đổi lượt nhấp
Tập hợp các đối tượng ClickConversion trong UploadClickConversionRequest xác định nhóm lượt chuyển đổi mà bạn muốn tải lên. Hãy làm theo hướng dẫn bên dưới để tạo từng ClickConversion và đặt các trường của lớp này thành các giá trị thích hợp.
Đặt các trường bắt buộc của mỗi phép toán chuyển đổi
Hãy làm theo hướng dẫn bên dưới để đặt các trường bắt buộc của ClickConversion thành các giá trị thích hợp.
gclid,gbraid,wbraid- Giá trị nhận dạng mà bạn đã thu thập tại thời điểm lượt nhấp hoặc lượt hiển thị dẫn đến lượt chuyển đổi. Chỉ đặt một trong số các trường này.
conversion_date_timeNgày và giờ chuyển đổi.
Giá trị phải có múi giờ được chỉ định và định dạng phải là
yyyy-mm-dd HH:mm:ss+|-HH:mm, ví dụ:2022-01-01 19:32:45-05:00(bỏ qua giờ mùa hè).Múi giờ có thể là bất kỳ giá trị hợp lệ nào: không phải khớp với múi giờ của tài khoản. Tuy nhiên, nếu bạn dự định so sánh dữ liệu lượt chuyển đổi đã tải lên với dữ liệu trong giao diện người dùng Google Ads, bạn nên sử dụng cùng múi giờ với tài khoản Google Ads để số lượt chuyển đổi khớp nhau. Bạn có thể xem thêm thông tin chi tiết và ví dụ trong Trung tâm trợ giúp, đồng thời kiểm tra phần Mã và định dạng để xem danh sách mã múi giờ hợp lệ.
user_identifiersĐừng đặt trường này khi tải lượt chuyển đổi lên chỉ bằng mã lượt nhấp. Nếu bạn đặt trường này, Google Ads sẽ coi thao tác tải lên là một thao tác tải lên cho lượt chuyển đổi nâng cao cho khách hàng tiềm năng.
conversion_actionTên tài nguyên của
ConversionActioncho lượt chuyển đổi từ lượt nhấp.Hành động chuyển đổi phải có
typelàUPLOAD_CLICKSvà phải tồn tại trong khách hàng chuyển đổi Google Ads của tài khoản Google Ads được liên kết với lượt nhấp.conversion_valueGiá trị của lượt chuyển đổi.
currency_codeMã đơn vị tiền tệ của
conversion_value.
Đặt các trường không bắt buộc của mỗi phép toán chuyển đổi
Xem danh sách các trường không bắt buộc bên dưới và thiết lập các trường đó trên ClickConversion nếu cần.
order_id- Mã giao dịch của lượt chuyển đổi. Trường này không bắt buộc nhưng bạn nên sử dụng. Nếu đặt giá trị này trong quá trình tải lên, bạn phải sử dụng giá trị này cho mọi mức điều chỉnh đối với lượt chuyển đổi.
external_attribution_dataNếu sử dụng các công cụ của bên thứ ba hoặc giải pháp tự phát triển để theo dõi lượt chuyển đổi, bạn có thể chỉ cấp cho Google Ads một phần giá trị đóng góp cho lượt chuyển đổi hoặc phân bổ giá trị đóng góp cho một lượt chuyển đổi trên nhiều lượt nhấp. Tính năng nhập lượt chuyển đổi được phân bổ bên ngoài cho phép bạn tải các lượt chuyển đổi lên với giá trị đóng góp theo tỷ lệ được chỉ định cho từng lượt nhấp.
Để tải khoản tín dụng phân đoạn lên, hãy đặt trường này thành đối tượng
ExternalAttributionDatacó giá trị choexternal_attribution_modelvàexternal_attribution_credit.custom_variablesGiá trị của biến tuỳ chỉnh cho lượt chuyển đổi.
Google Ads không hỗ trợ biến tuỳ chỉnh của lượt chuyển đổi kết hợp với
wbraidhoặcgbraid.cart_dataBạn có thể thêm thông tin giỏ hàng cho
ClickConversiontrong trườngcart_data. Trường này bao gồm các thuộc tính sau:merchant_id: Mã của tài khoản Merchant Center được liên kết.feed_country_code: Mã khu vực gồm hai ký tự theo tiêu chuẩn ISO 3166 của nguồn cấp dữ liệu Merchant Center.feed_language_code: Mã ngôn ngữ ISO 639-1 của nguồn cấp dữ liệu Merchant Center.local_transaction_cost: Tổng tất cả các khoản chiết khấu ở cấp giao dịch, trongcurrency_codecủaClickConversion.items: Các mặt hàng trong giỏ hàng.
Mỗi mục trong
itemsbao gồm các thuộc tính sau:product_id: Mã nhận dạng của sản phẩm, đôi khi được gọi là mã mặt hàng hoặc mã mặt hàng.quantity: Số lượng mặt hàng.unit_price: Giá đơn vị của mặt hàng.
conversion_environment
Cho biết môi trường nơi ghi nhận lượt chuyển đổi này. Ví dụ: Ứng dụng hoặc Web.
Ví dụ về mã
Java
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long conversionActionId,
String gclid,
String gbraid,
String wbraid,
String conversionDateTime,
Double conversionValue,
Long conversionCustomVariableId,
String conversionCustomVariableValue,
String orderId,
ConsentStatus adUserDataConsent)
throws InvalidProtocolBufferException {
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
long numberOfIdsSpecified =
Arrays.asList(gclid, gbraid, wbraid).stream().filter(idField -> idField != null).count();
if (numberOfIdsSpecified != 1) {
throw new IllegalArgumentException(
"Exactly 1 of gclid, gbraid, or wbraid is required, but "
+ numberOfIdsSpecified
+ " ID values were provided");
}
// Constructs the conversion action resource name from the customer and conversion action IDs.
String conversionActionResourceName =
ResourceNames.conversionAction(customerId, conversionActionId);
// Creates the click conversion.
ClickConversion.Builder clickConversionBuilder =
ClickConversion.newBuilder()
.setConversionAction(conversionActionResourceName)
.setConversionDateTime(conversionDateTime)
.setConversionValue(conversionValue)
.setCurrencyCode("USD");
// Sets the single specified ID field.
if (gclid != null) {
clickConversionBuilder.setGclid(gclid);
} else if (gbraid != null) {
clickConversionBuilder.setGbraid(gbraid);
} else {
clickConversionBuilder.setWbraid(wbraid);
}
if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
// Sets the custom variable and value, if provided.
clickConversionBuilder.addCustomVariables(
CustomVariable.newBuilder()
.setConversionCustomVariable(
ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
.setValue(conversionCustomVariableValue));
}
if (orderId != null) {
// Sets the order ID (unique transaction ID), if provided.
clickConversionBuilder.setOrderId(orderId);
}
// Sets the consent information, if provided.
if (adUserDataConsent != null) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
clickConversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent));
}
ClickConversion clickConversion = clickConversionBuilder.build();
// Creates the conversion upload service client.
try (ConversionUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
// Uploads the click conversion. Partial failure should always be set to true.
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
UploadClickConversionsResponse response =
conversionUploadServiceClient.uploadClickConversions(
UploadClickConversionsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.addConversions(clickConversion)
// Enables partial failure (must be true).
.setPartialFailure(true)
.build());
// Prints any partial errors returned.
if (response.hasPartialFailureError()) {
GoogleAdsFailure googleAdsFailure =
ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
// Constructs a protocol buffer printer that will print error details in a concise format.
Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace();
for (int operationIndex = 0;
operationIndex < response.getResultsCount();
operationIndex++) {
ClickConversionResult conversionResult = response.getResults(operationIndex);
if (ErrorUtils.getInstance().isPartialFailureResult(conversionResult)) {
// Prints the errors for the failed operation.
System.out.printf("Operation %d failed with the following errors:%n", operationIndex);
for (GoogleAdsError resultError :
ErrorUtils.getInstance().getGoogleAdsErrors(operationIndex, googleAdsFailure)) {
// Prints the error with newlines and extra spaces removed.
System.out.printf(" %s%n", errorPrinter.print(resultError));
}
} else {
// Prints the information about the successful operation.
StringBuilder clickInfoBuilder =
new StringBuilder("conversion that occurred at ")
.append(String.format("'%s' ", conversionResult.getConversionDateTime()))
.append("with ");
if (conversionResult.hasGclid()) {
clickInfoBuilder.append(String.format("gclid '%s'", conversionResult.getGclid()));
} else if (!conversionResult.getGbraid().isEmpty()) {
clickInfoBuilder.append(String.format("gbraid '%s'", conversionResult.getGbraid()));
} else if (!conversionResult.getWbraid().isEmpty()) {
clickInfoBuilder.append(String.format("wbraid '%s'", conversionResult.getWbraid()));
} else {
clickInfoBuilder.append("no click ID");
}
System.out.printf("Operation %d for %s succeeded.%n", operationIndex, clickInfoBuilder);
}
}
}
}
}
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
string gclid, string gbraid, string wbraid, string conversionTime,
double conversionValue, ConsentStatus? adUserDataConsent)
{
// Get the ConversionActionService.
ConversionUploadServiceClient conversionUploadService =
client.GetService(Services.V18.ConversionUploadService);
// Creates a click conversion by specifying currency as USD.
ClickConversion clickConversion = new ClickConversion()
{
ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
ConversionValue = conversionValue,
ConversionDateTime = conversionTime,
CurrencyCode = "USD",
};
// Sets the consent information, if provided.
if (adUserDataConsent != null)
{
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy
// for details.
clickConversion.Consent = new Consent()
{
AdUserData = (ConsentStatus)adUserDataConsent
};
}
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks
// for details.
string[] ids = { gclid, gbraid, wbraid };
int idCount = ids.Where(id => !string.IsNullOrEmpty(id)).Count();
if (idCount != 1)
{
throw new ArgumentException($"Exactly 1 of gclid, gbraid, or wbraid is " +
$"required, but {idCount} ID values were provided");
}
// Sets the single specified ID field.
if (!string.IsNullOrEmpty(gclid))
{
clickConversion.Gclid = gclid;
}
else if (!string.IsNullOrEmpty(wbraid))
{
clickConversion.Wbraid = wbraid;
}
else if (!string.IsNullOrEmpty(gbraid))
{
clickConversion.Gbraid = gbraid;
}
try
{
// Issues a request to upload the click conversion.
UploadClickConversionsResponse response =
conversionUploadService.UploadClickConversions(
new UploadClickConversionsRequest()
{
CustomerId = customerId.ToString(),
Conversions = { clickConversion },
PartialFailure = true,
ValidateOnly = false
});
// Prints the result.
ClickConversionResult uploadedClickConversion = response.Results[0];
Console.WriteLine($"Uploaded conversion that occurred at " +
$"'{uploadedClickConversion.ConversionDateTime}' from Google " +
$"Click ID '{uploadedClickConversion.Gclid}' to " +
$"'{uploadedClickConversion.ConversionAction}'.");
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $conversionActionId,
?string $gclid,
?string $gbraid,
?string $wbraid,
?string $orderId,
string $conversionDateTime,
float $conversionValue,
?string $conversionCustomVariableId,
?string $conversionCustomVariableValue,
?int $adUserDataConsent
) {
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
$nonNullFields = array_filter(
[$gclid, $gbraid, $wbraid],
function ($field) {
return !is_null($field);
}
);
if (count($nonNullFields) !== 1) {
throw new \UnexpectedValueException(
sprintf(
"Exactly 1 of gclid, gbraid or wbraid is required, but %d ID values were "
. "provided",
count($nonNullFields)
)
);
}
// Creates a click conversion by specifying currency as USD.
$clickConversion = new ClickConversion([
'conversion_action' =>
ResourceNames::forConversionAction($customerId, $conversionActionId),
'conversion_value' => $conversionValue,
'conversion_date_time' => $conversionDateTime,
'currency_code' => 'USD'
]);
// Sets the single specified ID field.
if (!is_null($gclid)) {
$clickConversion->setGclid($gclid);
} elseif (!is_null($gbraid)) {
$clickConversion->setGbraid($gbraid);
} else {
$clickConversion->setWbraid($wbraid);
}
if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
$clickConversion->setCustomVariables([new CustomVariable([
'conversion_custom_variable' => ResourceNames::forConversionCustomVariable(
$customerId,
$conversionCustomVariableId
),
'value' => $conversionCustomVariableValue
])]);
}
// Sets the consent information, if provided.
if (!empty($adUserDataConsent)) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
$clickConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent]));
}
if (!empty($orderId)) {
// Sets the order ID (unique transaction ID), if provided.
$clickConversion->setOrderId($orderId);
}
// Issues a request to upload the click conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
/** @var UploadClickConversionsResponse $response */
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
$response = $conversionUploadServiceClient->uploadClickConversions(
// Uploads the click conversion. Partial failure should always be set to true.
UploadClickConversionsRequest::build($customerId, [$clickConversion], true)
);
// Prints the status message if any partial failure error is returned.
// Note: The details of each partial failure error are not printed here, you can refer to
// the example HandlePartialFailure.php to learn more.
if ($response->hasPartialFailureError()) {
printf(
"Partial failures occurred: '%s'.%s",
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
// Prints the result if exists.
/** @var ClickConversionResult $uploadedClickConversion */
$uploadedClickConversion = $response->getResults()[0];
printf(
"Uploaded click conversion that occurred at '%s' from Google Click ID '%s' " .
"to '%s'.%s",
$uploadedClickConversion->getConversionDateTime(),
$uploadedClickConversion->getGclid(),
$uploadedClickConversion->getConversionAction(),
PHP_EOL
);
}
}
Python
def main(
client,
customer_id,
conversion_action_id,
gclid,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
gbraid,
wbraid,
order_id,
ad_user_data_consent,
):
"""Creates a click conversion with a default currency of USD.
Args:
client: An initialized GoogleAdsClient instance.
customer_id: The client customer ID string.
conversion_action_id: The ID of the conversion action to upload to.
gclid: The Google Click Identifier ID. If set, the wbraid and gbraid
parameters must be None.
conversion_date_time: The the date and time of the conversion (should be
after the click time). The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
e.g. '2021-01-01 12:32:45-08:00'.
conversion_value: The conversion value in the desired currency.
conversion_custom_variable_id: The ID of the conversion custom
variable to associate with the upload.
conversion_custom_variable_value: The str value of the conversion custom
variable to associate with the upload.
gbraid: The GBRAID for the iOS app conversion. If set, the gclid and
wbraid parameters must be None.
wbraid: The WBRAID for the iOS app conversion. If set, the gclid and
gbraid parameters must be None.
order_id: The order ID for the click conversion.
ad_user_data_consent: The ad user data consent for the click.
"""
click_conversion = client.get_type("ClickConversion")
conversion_upload_service = client.get_service("ConversionUploadService")
conversion_action_service = client.get_service("ConversionActionService")
click_conversion.conversion_action = (
conversion_action_service.conversion_action_path(
customer_id, conversion_action_id
)
)
# Sets the single specified ID field.
if gclid:
click_conversion.gclid = gclid
elif gbraid:
click_conversion.gbraid = gbraid
else:
click_conversion.wbraid = wbraid
click_conversion.conversion_value = float(conversion_value)
click_conversion.conversion_date_time = conversion_date_time
click_conversion.currency_code = "USD"
if conversion_custom_variable_id and conversion_custom_variable_value:
conversion_custom_variable = client.get_type("CustomVariable")
conversion_custom_variable.conversion_custom_variable = (
conversion_upload_service.conversion_custom_variable_path(
customer_id, conversion_custom_variable_id
)
)
conversion_custom_variable.value = conversion_custom_variable_value
click_conversion.custom_variables.append(conversion_custom_variable)
if order_id:
click_conversion.order_id = order_id
# Sets the consent information, if provided.
if ad_user_data_consent:
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
ad_user_data_consent
]
# Uploads the click conversion. Partial failure must be set to True here.
#
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's most efficient to upload them in a
# single request. See the following for per-request limits for reference:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
request = client.get_type("UploadClickConversionsRequest")
request.customer_id = customer_id
request.conversions.append(click_conversion)
request.partial_failure = True
conversion_upload_response = (
conversion_upload_service.upload_click_conversions(
request=request,
)
)
uploaded_click_conversion = conversion_upload_response.results[0]
print(
f"Uploaded conversion that occurred at "
f'"{uploaded_click_conversion.conversion_date_time}" from '
f'Google Click ID "{uploaded_click_conversion.gclid}" '
f'to "{uploaded_click_conversion.conversion_action}"'
)
Ruby
def upload_offline_conversion(
customer_id,
conversion_action_id,
gclid,
gbraid,
wbraid,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
ad_user_data_consent)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
# See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
identifiers_specified = [gclid, gbraid, wbraid].reject {|v| v.nil?}.count
if identifiers_specified != 1
raise "Must specify exactly one of GCLID, GBRAID, and WBRAID. " \
"#{identifiers_specified} values were provided."
end
click_conversion = client.resource.click_conversion do |cc|
cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
# Sets the single specified ID field.
if !gclid.nil?
cc.gclid = gclid
elsif !gbraid.nil?
cc.gbraid = gbraid
else
cc.wbraid = wbraid
end
cc.conversion_value = conversion_value.to_f
cc.conversion_date_time = conversion_date_time
cc.currency_code = 'USD'
if conversion_custom_variable_id && conversion_custom_variable_value
cc.custom_variables << client.resource.custom_variable do |cv|
cv.conversion_custom_variable = client.path.conversion_custom_variable(
customer_id, conversion_custom_variable_id)
cv.value = conversion_custom_variable_value
end
end
# Sets the consent information, if provided.
unless ad_user_data_consent.nil?
cc.consent = client.resource.consent do |c|
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
c.ad_user_data = ad_user_data_consent
end
end
end
response = client.service.conversion_upload.upload_click_conversions(
customer_id: customer_id,
# NOTE: This request contains a single conversion as a demonstration.
# However, if you have multiple conversions to upload, it's best to upload
# multiple conversions per request instead of sending a separate request per
# conversion. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
conversions: [click_conversion],
partial_failure: true,
)
if response.partial_failure_error.nil?
result = response.results.first
puts "Uploaded conversion that occurred at #{result.conversion_date_time} " \
"from Google Click ID #{result.gclid} to #{result.conversion_action}."
else
failures = client.decode_partial_failure_error(response.partial_failure_error)
puts "Request failed. Failure details:"
failures.each do |failure|
failure.errors.each do |error|
puts "\t#{error.error_code.error_code}: #{error.message}"
end
end
end
end
Perl
sub upload_offline_conversion {
my (
$api_client, $customer_id,
$conversion_action_id, $gclid,
$gbraid, $wbraid,
$conversion_date_time, $conversion_value,
$conversion_custom_variable_id, $conversion_custom_variable_value,
$order_id, $ad_user_data_consent
) = @_;
# Verify that exactly one of gclid, gbraid, and wbraid is specified, as required.
# See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
my $number_of_ids_specified = grep { defined $_ } ($gclid, $gbraid, $wbraid);
if ($number_of_ids_specified != 1) {
die sprintf "Exactly 1 of gclid, gbraid, or wbraid is required, " .
"but %d ID values were provided.\n",
$number_of_ids_specified;
}
# Create a click conversion by specifying currency as USD.
my $click_conversion =
Google::Ads::GoogleAds::V18::Services::ConversionUploadService::ClickConversion
->new({
conversionAction =>
Google::Ads::GoogleAds::V18::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
),
conversionDateTime => $conversion_date_time,
conversionValue => $conversion_value,
currencyCode => "USD"
});
# Set the single specified ID field.
if (defined $gclid) {
$click_conversion->{gclid} = $gclid;
} elsif (defined $gbraid) {
$click_conversion->{gbraid} = $gbraid;
} else {
$click_conversion->{wbraid} = $wbraid;
}
if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
$click_conversion->{customVariables} = [
Google::Ads::GoogleAds::V18::Services::ConversionUploadService::CustomVariable
->new({
conversionCustomVariable =>
Google::Ads::GoogleAds::V18::Utils::ResourceNames::conversion_custom_variable(
$customer_id, $conversion_custom_variable_id
),
value => $conversion_custom_variable_value
})];
}
if (defined $order_id) {
# Set the order ID (unique transaction ID), if provided.
$click_conversion->{orderId} = $order_id;
}
# Set the consent information, if provided.
if ($ad_user_data_consent) {
# Specify whether user consent was obtained for the data you are uploading.
# See https://www.google.com/about/company/user-consent-policy for details.
$click_conversion->{consent} =
Google::Ads::GoogleAds::V18::Common::Consent->new({
adUserData => $ad_user_data_consent
});
}
# Issue a request to upload the click conversion. Partial failure should
# always be set to true.
#
# NOTE: This request contains a single conversion as a demonstration.
# However, if you have multiple conversions to upload, it's best to
# upload multiple conversions per request instead of sending a separate
# request per conversion. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
my $upload_click_conversions_response =
$api_client->ConversionUploadService()->upload_click_conversions({
customerId => $customer_id,
conversions => [$click_conversion],
partialFailure => "true"
});
# Print any partial errors returned.
if ($upload_click_conversions_response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$upload_click_conversions_response->{partialFailureError}{message};
}
# Print the result if valid.
my $uploaded_click_conversion =
$upload_click_conversions_response->{results}[0];
if (%$uploaded_click_conversion) {
printf
"Uploaded conversion that occurred at '%s' from Google Click ID '%s' " .
"to the conversion action with resource name '%s'.\n",
$uploaded_click_conversion->{conversionDateTime},
$uploaded_click_conversion->{gclid},
$uploaded_click_conversion->{conversionAction};
}
return 1;
}
Khắc phục sự cố
Thông tin chẩn đoán về dữ liệu ngoại tuyến cung cấp một tài nguyên duy nhất để liên tục xem xét tình trạng tổng thể của nội dung tải lên. Tuy nhiên, trong quá trình triển khai, bạn có thể sử dụng thông tin trong phần này để điều tra mọi lỗi được báo cáo trong trường partial_failure_error của phản hồi.
Một số lỗi thường gặp nhất khi tải hành động chuyển đổi lên là lỗi uỷ quyền, chẳng hạn như USER_PERMISSION_DENIED. Kiểm tra kỹ để đảm bảo rằng bạn đã đặt mã khách hàng trong yêu cầu thành khách hàng chuyển đổi trên Google Ads sở hữu hành động chuyển đổi. Hãy truy cập vào hướng dẫn uỷ quyền để biết thêm thông tin chi tiết và xem hướng dẫn về các lỗi thường gặp để biết các mẹo gỡ lỗi cho những lỗi này.
Gỡ lỗi các lỗi thường gặp
| Lỗi | |
|---|---|
ConversionUploadError.INVALID_CONVERSION_ACTION_TYPE
|
Hành động chuyển đổi được chỉ định có loại không hợp lệ để tải lượt chuyển đổi từ lượt nhấp lên. Đảm bảo ConversionAction được chỉ định trong yêu cầu tải lên có loại UPLOAD_CLICKS.
|
ConversionUploadError.NO_CONVERSION_ACTION_FOUND
|
Hành động chuyển đổi được chỉ định không được bật hoặc không tìm thấy trong customer_id đang tải lên. Đảm bảo rằng hành động chuyển đổi trong tệp tải lên của bạn đã được bật và thuộc quyền sở hữu của customer_id của yêu cầu tải lên.
|
ConversionUploadError.TOO_RECENT_CONVERSION_ACTION
|
Hành động chuyển đổi này mới được tạo. Hãy đợi ít nhất 6 giờ sau khi tạo hành động trước khi thử lại các lượt chuyển đổi không thành công. |
ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK
|
customer_id của yêu cầu không phải là mã khách hàng
là tài khoản chuyển đổi API Google Ads
tại thời điểm nhấp. Cập nhật customer_id của yêu cầu cho đúng khách hàng.
|
ConversionUploadError.EVENT_NOT_FOUND
|
Google Ads không tìm thấy tổ hợp mã lượt nhấp và customer_id. Xem lại các yêu cầu đối với customer_id và xác nhận rằng bạn đang tải lên bằng đúng tài khoản Google Ads.
|
ConversionUploadError.DUPLICATE_CLICK_CONVERSION_IN_REQUEST
|
Nhiều lượt chuyển đổi trong yêu cầu có cùng một tổ hợp mã lượt nhấp, conversion_date_time và conversion_action. Xoá các lượt chuyển đổi trùng lặp khỏi yêu cầu của bạn.
|
ConversionUploadError.CLICK_CONVERSION_ALREADY_EXISTS
|
Một lượt chuyển đổi có cùng tổ hợp mã lượt nhấp, conversion_date_time và conversion_action đã được tải lên trước đó. Bỏ qua lỗi này nếu bạn đang thử tải lên lại và lượt chuyển đổi này đã thành công trước đó. Nếu bạn muốn thêm một lượt chuyển đổi khác ngoài lượt chuyển đổi đã tải lên trước đó, hãy điều chỉnh conversion_date_time của ClickConversion để tránh trùng lặp lượt chuyển đổi đã tải lên trước đó.
|
ConversionUploadError.EVENT_NOT_FOUND
|
Google Ads không tìm thấy tổ hợp mã lượt nhấp và customer_id. Xem lại các yêu cầu đối với customer_id và xác nhận rằng bạn đang tải lên bằng đúng tài khoản Google Ads.
|
ConversionUploadError.EXPIRED_EVENT
|
Lượt nhấp được nhập đã xảy ra trước khung thời gian được chỉ định trong trường click_through_lookback_window_days. Việc thay đổi click_through_lookback_window_days chỉ ảnh hưởng đến các lượt nhấp được ghi lại sau khi thay đổi, vì vậy, việc thay đổi giai đoạn xem lại sẽ không giải quyết được lỗi này cho một lượt nhấp cụ thể. Nếu thích hợp, hãy thay đổi conversion_action thành một hành động khác có giai đoạn xem lại dài hơn. |
ConversionUploadError.CONVERSION_PRECEDES_EVENT
|
conversion_date_time nằm trước ngày và giờ của lượt nhấp. Cập nhật conversion_date_time thành một giá trị sau đó.
|
ConversionUploadError.GBRAID_WBRAID_BOTH_SET
|
ClickConversion có một giá trị được đặt cho cả gbraid và wbraid. Cập nhật lượt chuyển đổi để chỉ sử dụng một mã lượt nhấp và đảm bảo bạn không kết hợp nhiều lượt nhấp vào cùng một lượt chuyển đổi. Mỗi lượt nhấp chỉ có một mã lượt nhấp.
|
FieldError.VALUE_MUST_BE_UNSET
|
Kiểm tra location của GoogleAdsError để xác định vấn đề nào sau đây dẫn đến lỗi.
|
Lượt chuyển đổi trong báo cáo
Các lượt chuyển đổi đã tải lên sẽ được phản ánh trong báo cáo theo ngày hiển thị của lượt nhấp ban đầu, chứ không phải ngày của yêu cầu tải lên hoặc ngày của conversion_date_time của ClickConversion.
Sẽ mất tối đa 3 giờ để số liệu thống kê về lượt chuyển đổi được nhập xuất hiện trong tài khoản Google Ads của bạn theo mô hình phân bổ lượt nhấp cuối cùng. Đối với các mô hình phân bổ tìm kiếm khác, có thể mất nhiều hơn 3 giờ. Hãy tham khảo hướng dẫn về độ mới của dữ liệu để biết thêm thông tin.