Sau khi một lượt chuyển đổi được báo cáo cho Google Ads, bạn có thể điều chỉnh chuyển đổi ở thời điểm sau đó trong thời gian trong API Google Ads.
Để điều chỉnh lượt chuyển đổi, trước tiên bạn phải đặt một lượt chuyển đổi và bạn cũng phải ghi lại các lượt chuyển đổi mà bạn sắp điều chỉnh.
Ví dụ về mã
API Google Ads hỗ trợ việc sử dụng order_id
, còn gọi là mã giao dịch, để xác định lượt chuyển đổi cần điều chỉnh bằng ConversionAdjustmentUploadService
.
Để lấy conversion_action_id
cần thiết để điều chỉnh lượt chuyển đổi, bạn có thể làm theo một trong những cách sau:
Lấy giá trị từ tham số
ctId
có trong URL khi bạn nhấp vào thông tin về lượt chuyển đổi trong giao diện người dùng Google Ads.Truy vấn API Google Ads cho
conversion_action.id
trongconversion_action
báo cáo.
Java
private void runExample( GoogleAdsClient googleAdsClient, long customerId, long conversionActionId, String orderId, String adjustmentType, String adjustmentDateTime, @Nullable Float restatementValue) throws InvalidProtocolBufferException { // Gets the conversion adjustment enum value from the adjustmentType String. ConversionAdjustmentType conversionAdjustmentType = ConversionAdjustmentType.valueOf(adjustmentType); // Applies the conversion adjustment to the existing conversion. ConversionAdjustment conversionAdjustment = ConversionAdjustment.newBuilder() .setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId)) .setAdjustmentType(conversionAdjustmentType) // Sets the orderId to identify the conversion to adjust. .setOrderId(orderId) // As an alternative to setting orderId, you can provide a GclidDateTimePair, but // setting orderId instead is strongly recommended. // .setGclidDateTimePair( // GclidDateTimePair.newBuilder() // .setGclid(gclid) // .setConversionDateTime(conversionDateTime) // .build()) .setAdjustmentDateTime(adjustmentDateTime) .build(); // Sets adjusted value for adjustment type RESTATEMENT. if (restatementValue != null && conversionAdjustmentType == ConversionAdjustmentType.RESTATEMENT) { conversionAdjustment = conversionAdjustment.toBuilder() .setRestatementValue( RestatementValue.newBuilder().setAdjustedValue(restatementValue).build()) .build(); } // Creates the conversion upload service client. try (ConversionAdjustmentUploadServiceClient conversionUploadServiceClient = googleAdsClient.getLatestVersion().createConversionAdjustmentUploadServiceClient()) { // Uploads the click conversion. Partial failure should always be set to true. UploadConversionAdjustmentsRequest request = UploadConversionAdjustmentsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) // Enables partial failure (must be true). .setPartialFailure(true) .addConversionAdjustments(conversionAdjustment) .build(); UploadConversionAdjustmentsResponse response = conversionUploadServiceClient.uploadConversionAdjustments(request); // Extracts the partial failure error if present on the response. ErrorUtils errorUtils = ErrorUtils.getInstance(); GoogleAdsFailure googleAdsFailure = response.hasPartialFailureError() ? errorUtils.getGoogleAdsFailure(response.getPartialFailureError()) : null; // Constructs a protocol buffer printer that will print error details in a concise format. final Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace(); // Prints the results for each adjustment, including any partial errors returned. for (int opIndex = 0; opIndex < request.getConversionAdjustmentsCount(); opIndex++) { ConversionAdjustmentResult result = response.getResults(opIndex); if (errorUtils.isPartialFailureResult(result)) { // The operation failed. Prints the error details. for (GoogleAdsError googleAdsError : errorUtils.getGoogleAdsErrors(opIndex, googleAdsFailure)) { System.out.printf( "%4d: Partial failure occurred: %s%n", opIndex, errorPrinter.print(googleAdsError)); } } else { System.out.printf( "%4d: Uploaded conversion adjustment for conversion action '%s' and order ID '%s'.%n", opIndex, result.getConversionAction(), result.getOrderId()); } } } }
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId, string orderId, string adjustmentDateTime, ConversionAdjustmentType adjustmentType, double? restatementValue) { // Get the ConversionAdjustmentUploadService. ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService = client.GetService(Services.V18.ConversionAdjustmentUploadService); // Associate conversion adjustments with the existing conversion action. ConversionAdjustment conversionAdjustment = new ConversionAdjustment() { ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId), AdjustmentType = adjustmentType, // Sets the orderId to identify the conversion to adjust. OrderId = orderId, // As an alternative to setting orderId, you can provide a GclidDateTimePair, // but setting orderId instead is strongly recommended. //GclidDateTimePair = new GclidDateTimePair() //{ // Gclid = gclid, // ConversionDateTime = conversionDateTime, //}, AdjustmentDateTime = adjustmentDateTime, }; // Set adjusted value for adjustment type RESTATEMENT. if (adjustmentType == ConversionAdjustmentType.Restatement) { conversionAdjustment.RestatementValue = new RestatementValue() { AdjustedValue = restatementValue.Value }; } try { // Issue a request to upload the conversion adjustment. UploadConversionAdjustmentsResponse response = conversionAdjustmentUploadService.UploadConversionAdjustments( new UploadConversionAdjustmentsRequest() { CustomerId = customerId.ToString(), ConversionAdjustments = { conversionAdjustment }, // Enables partial failure (must be true). PartialFailure = true, ValidateOnly = false }); // Prints any partial errors returned. // To review the overall health of your recent uploads, see: // https://developers.google.com/google-ads/api/docs/conversions/upload-summaries if (response.PartialFailureError != null) { // Extracts the partial failure from the response status. GoogleAdsFailure partialFailure = response.PartialFailure; Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " + $"occurred"); } else { ConversionAdjustmentResult result = response.Results[0]; // Print the result. Console.WriteLine($"Uploaded conversion adjustment value of" + $" '{result.ConversionAction}' for Google Click ID " + $"'{result.GclidDateTimePair.Gclid}'"); } } 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 $orderId, string $adjustmentType, string $adjustmentDateTime, ?float $restatementValue ) { $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType); // Applies the conversion adjustment to the existing conversion. $conversionAdjustment = new ConversionAdjustment([ 'conversion_action' => ResourceNames::forConversionAction($customerId, $conversionActionId), 'adjustment_type' => $conversionAdjustmentType, // Sets the orderId to identify the conversion to adjust. 'order_id' => $orderId, // As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', but // setting 'order_id' instead is strongly recommended. // 'conversion_date_time' must be in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format. /* 'gclid_date_time_pair' => new GclidDateTimePair([ 'gclid' => 'INSERT_YOUR_GCLID_HERE', 'conversion_date_time' => 'INSERT_YOUR_CONVERSION_DATE_TIME_HERE' ]), */ 'adjustment_date_time' => $adjustmentDateTime ]); // Sets adjusted value for adjustment type RESTATEMENT. if ( $restatementValue !== null && $conversionAdjustmentType === ConversionAdjustmentType::RESTATEMENT ) { $conversionAdjustment->setRestatementValue(new RestatementValue([ 'adjusted_value' => $restatementValue ])); } // Issues a request to upload the conversion adjustment. $conversionAdjustmentUploadServiceClient = $googleAdsClient->getConversionAdjustmentUploadServiceClient(); $response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments( // Enables partial failure (must be true). UploadConversionAdjustmentsRequest::build($customerId, [$conversionAdjustment], 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 ConversionAdjustmentResult $uploadedConversionAdjustment */ $uploadedConversionAdjustment = $response->getResults()[0]; printf( "Uploaded conversion adjustment of '%s' for order ID '%s'.%s", $uploadedConversionAdjustment->getConversionAction(), $uploadedConversionAdjustment->getOrderId(), PHP_EOL ); } }
Python
def main( client, customer_id, conversion_action_id, adjustment_type, order_id, adjustment_date_time, restatement_value=None, ): """The main method that creates all necessary entities for the example. Args: client: an initialized GoogleAdsClient instance. customer_id: a client customer ID. conversion_action_id: the ID of the conversion action to upload the adjustment to. adjustment_type: the adjustment type, e.g. " "RETRACTION, RESTATEMENT. order_id: the transaction ID of the conversion to adjust. Strongly recommended instead of using gclid and conversion_date_time. adjustment_date_time: the date and time of the adjustment. restatement_value: the adjusted value for adjustment type RESTATEMENT. """ conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum # Determine the adjustment type. conversion_adjustment_type = conversion_adjustment_type_enum[ adjustment_type ].value # Applies the conversion adjustment to the existing conversion. conversion_adjustment = client.get_type("ConversionAdjustment") conversion_action_service = client.get_service("ConversionActionService") conversion_adjustment.conversion_action = ( conversion_action_service.conversion_action_path( customer_id, conversion_action_id ) ) conversion_adjustment.adjustment_type = conversion_adjustment_type conversion_adjustment.adjustment_date_time = adjustment_date_time # Sets the order_id to identify the conversion to adjust. conversion_adjustment.order_id = order_id # As an alternative to setting order_id, you can provide a # gclid_date_time_pair, but setting order_id instead is strongly recommended. # conversion_adjustment.gclid_date_time_pair.gclid = gclid # conversion_adjustment.gclid_date_time_pair.conversion_date_time = ( # conversion_date_time # ) # Sets adjusted value for adjustment type RESTATEMENT. if ( restatement_value and conversion_adjustment_type == conversion_adjustment_type_enum.RESTATEMENT.value ): conversion_adjustment.restatement_value.adjusted_value = float( restatement_value ) # Uploads the click conversion. Partial failure should always be set to # true. service = client.get_service("ConversionAdjustmentUploadService") request = client.get_type("UploadConversionAdjustmentsRequest") request.customer_id = customer_id request.conversion_adjustments.append(conversion_adjustment) # Enables partial failure (must be true) request.partial_failure = True response = service.upload_conversion_adjustments(request=request) # Extracts the partial failure error if present on the response. if response.partial_failure_error: error_details = response.partial_failure_error.details for i, conversion_adjustment_result in enumerate(response.results): # If there's a GoogleAdsFailure in error_details at this position then # the uploaded operation failed and we print the error message. if error_details and error_details[i]: error_detail = error_details[i] failure_message = client.get_type("GoogleAdsFailure") # Parse the string into a GoogleAdsFailure message instance. # To access class-only methods on the message we retrieve its type. GoogleAdsFailure = type(failure_message) failure_object = GoogleAdsFailure.deserialize(error_detail.value) for error in failure_object.errors: # Construct and print a string that details which element in # the operation list failed (by index number) as well as the # error message and error code. print( "A partial failure at index " f"{error.location.field_path_elements[0].index} occurred " f"\nError message: {error.message}\nError code: " f"{error.error_code}" ) else: print( "Uploaded conversion adjustment for conversion action " f"'{conversion_adjustment_result.conversion_action}' and order " f"ID '{conversion_adjustment_result.order_id}'." )
Ruby
def upload_conversion_adjustment( customer_id, conversion_action_id, order_id, adjustment_type, adjustment_date_time, restatement_value ) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new # Applies the conversion adjustment to the existing conversion. conversion_adjustment = client.resource.conversion_adjustment do |ca| ca.conversion_action = client.path.conversion_action(customer_id, conversion_action_id) ca.adjustment_type = adjustment_type ca.order_id = order_id ca.adjustment_date_time = adjustment_date_time # Set adjusted value for adjustment type RESTATEMENT. if adjustment_type == :RESTATEMENT ca.restatement_value = client.resource.restatement_value do |ra| ra.adjusted_value = restatement_value.to_f end end end # Issue a request to upload the conversion adjustment(s). response = client.service.conversion_adjustment_upload.upload_conversion_adjustments( customer_id: customer_id, # This example shows just one adjustment but you may upload multiple ones. conversion_adjustments: [conversion_adjustment], partial_failure: true ) if response.partial_failure_error.nil? # Process and print all results for multiple adjustments response.results.each do |result| puts "Uploaded conversion adjustment for conversion action #{result.conversion_action} "\ "and order ID #{result.order_id}." end else # Print any partial errors returned. failures = client.decode_partial_failure_error(response.partial_failure_error) puts 'Request failed. Failure details:' failures.each do |failure| failure.errors.each do |error| index = error.location.field_path_elements.first.index puts "\toperation[#{index}] #{error.error_code.error_code}: #{error.message}" end end end end
Perl
sub upload_conversion_adjustment { my ($api_client, $customer_id, $conversion_action_id, $order_id, $adjustment_type, $adjustment_date_time, $restatement_value) = @_; # Applies the conversion adjustment to the existing conversion. my $conversion_adjustment = Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::ConversionAdjustment ->new({ conversionAction => Google::Ads::GoogleAds::V18::Utils::ResourceNames::conversion_action( $customer_id, $conversion_action_id ), adjustmentType => $adjustment_type, # Sets the orderId to identify the conversion to adjust. orderId => $order_id, # As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', # but setting 'order_id' instead is strongly recommended. # gclidDateTimePair => # Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::GclidDateTimePair # ->new({ # gclid => $gclid, # conversionDateTime => $conversion_date_time # } # ), adjustmentDateTime => $adjustment_date_time, }); # Set adjusted value for adjustment type RESTATEMENT. $conversion_adjustment->{restatementValue} = Google::Ads::GoogleAds::V18::Services::ConversionAdjustmentUploadService::RestatementValue ->new({ adjustedValue => $restatement_value }) if defined $restatement_value && $adjustment_type eq RESTATEMENT; # Issue a request to upload the conversion adjustment. my $upload_conversion_adjustments_response = $api_client->ConversionAdjustmentUploadService() ->upload_conversion_adjustments({ customerId => $customer_id, conversionAdjustments => [$conversion_adjustment], partialFailure => "true" }); # Print any partial errors returned. if ($upload_conversion_adjustments_response->{partialFailureError}) { printf "Partial error encountered: '%s'.\n", $upload_conversion_adjustments_response->{partialFailureError}{message}; } # Print the result if valid. my $uploaded_conversion_adjustment = $upload_conversion_adjustments_response->{results}[0]; if (%$uploaded_conversion_adjustment) { printf "Uploaded conversion adjustment of the conversion action " . "with resource name '%s' for order ID '%s'.\n", $uploaded_conversion_adjustment->{conversionAction}, $uploaded_conversion_adjustment->{orderId}; } return 1; }
Yêu cầu
Dưới đây là một số yêu cầu và hạn chế cần lưu ý khi điều chỉnh lượt chuyển đổi trong API:
Chỉ tài khoản quản lý hành động chuyển đổi mới có thể tải lên điều chỉnh. Sử dụng hướng dẫn thiết lập tính năng theo dõi lượt chuyển đổi để xác định tài khoản nào đang quản lý lượt chuyển đổi cho tài khoản Google Ads của bạn.
Việc cố gắng tải mức điều chỉnh lên bằng một tài khoản khác sẽ dẫn đến việc
NO_CONVERSION_ACTION_FOUND
. Lỗi này cũng xảy ra nếu bạn chưa bật hành động chuyển đổi của mức điều chỉnh.Google Ads chỉ hỗ trợ điều chỉnh lượt chuyển đổi cho các loại hành động chuyển đổi là
SALESFORCE
,UPLOAD_CLICKS
hoặcWEBPAGE
. Nếu bạn cố gắng tải một mức điều chỉnh lên cho một lượt chuyển đổi mà hành động chuyển đổi không phải là một trong những loại này, thì bạn sẽ gặp lỗiINVALID_CONVERSION_ACTION_TYPE
.Các trường chỉ định ngày và giờ bắt buộc phải có múi giờ không nhất thiết của tài khoản. Định dạng của các trường này là
yyyy-mm-dd HH:mm:ss+|-HH:mm
, ví dụ:2022-01-01 19:32:45-05:00
(bỏ qua giờ tiết kiệm ánh sáng ngày) của Google.Hãy chờ 4 đến 6 giờ sau khi tạo hành động chuyển đổi rồi mới điều chỉnh chuyển đổi để tránh
TOO_RECENT_CONVERSION_ACTION
.Điều chỉnh không thành công với
CONVERSION_NOT_FOUND
nếu bất kỳ điều kiện nào sau đây được đáp ứng:Lượt chuyển đổi này chưa từng được báo cáo.
Lượt chuyển đổi được báo cáo dưới 24 giờ trước khi bạn thử điều chỉnh. Trong một số trường hợp, điều này có thể dẫn đến lỗi
TOO_RECENT_CONVERSION
.
Bạn phải chỉ định
order_id
trongConversionAdjustment
dưới bất kỳ các điều kiện sau:type
của hành động chuyển đổi bằngWEBPAGE
.Lượt chuyển đổi ban đầu mà bạn đang điều chỉnh đã được chỉ định
order_id
.
Nếu bạn chỉ định
gclid_date_time_pair
, thao tác này sẽ thất bại vớiConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE
hoặcConversionAdjustmentUploadError.CONVERSION_NOT_FOUND
lỗi, .Khi tạo
ConversionAdjustment
, thuộc tínhpartial_failure
của thời gianUploadConversionAdjustmentsRequest
phải luôn được đặt thànhtrue
. Làm theo nguyên tắc về lỗi một phần khi xử lý đồng thời thao tác hợp lệ và thao tác không thành công.Bạn không thể thay đổi
ConversionAction
điều chỉnh. Thay vào đó, hãy sử dụngRETRACTION
để xoá lượt chuyển đổi trước đó và tải một lượt chuyển đổi mới lên bằngConversionAction
đã cập nhật. Bạn không cần sửa đổi dấu thời gian. Xem Giới thiệu về lượt chuyển đổi điều chỉnh.