將轉換回報給 Google Ads 後,您日後可以在 Google Ads API 中調整轉換。
您必須先設定轉換動作,並記錄要調整的轉換,才能調整轉換。
程式碼範例
Google Ads API 支援使用 order_id
(又稱為「交易 ID」) 來識別要透過 ConversionAdjustmentUploadService
調整的轉換。
如要取得調整轉換調整項所需的 conversion_action_id
,請執行下列任一操作:
在 Google Ads UI 中點選轉換詳細資料時,從網址可用的
ctId
參數中取得值。在
conversion_action
報表中查詢conversion_action.id
的 Google Ads API。
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 gclid, string conversionDateTime, string adjustmentDateTime, ConversionAdjustmentType adjustmentType, double? restatementValue) { // Get the ConversionAdjustmentUploadService. ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService = client.GetService(Services.V16.ConversionAdjustmentUploadService); // Associate conversion adjustments with the existing conversion action. // The GCLID should have been uploaded before with a conversion. ConversionAdjustment conversionAdjustment = new ConversionAdjustment() { ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId), AdjustmentType = adjustmentType, 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 }, PartialFailure = true, ValidateOnly = false }); 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 $gclid, string $adjustmentType, string $conversionDateTime, string $adjustmentDateTime, float $restatementValue ) { $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType); // Associates conversion adjustments with the existing conversion action. // The GCLID should have been uploaded before with a conversion. $conversionAdjustment = new ConversionAdjustment([ 'conversion_action' => ResourceNames::forConversionAction($customerId, $conversionActionId), 'adjustment_type' => $conversionAdjustmentType, 'gclid_date_time_pair' => new GclidDateTimePair([ 'gclid' => $gclid, 'conversion_date_time' => $conversionDateTime ]), '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( 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 Google Click ID '%s'.%s", $uploadedConversionAdjustment->getConversionAction(), $uploadedConversionAdjustment->getGclidDateTimePair()->getGclid(), PHP_EOL ); } }
Python
def main( client, customer_id, conversion_action_id, gclid, adjustment_type, conversion_date_time, adjustment_date_time, restatement_value, ): conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum # Determine the adjustment type. conversion_adjustment_type = conversion_adjustment_type_enum[ adjustment_type ].value # Associates conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a 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 # Set the Gclid Date 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 ) conversion_adjustment_upload_service = client.get_service( "ConversionAdjustmentUploadService" ) request = client.get_type("UploadConversionAdjustmentsRequest") request.customer_id = customer_id request.conversion_adjustments = [conversion_adjustment] request.partial_failure = True response = ( conversion_adjustment_upload_service.upload_conversion_adjustments( request=request, ) ) conversion_adjustment_result = response.results[0] print( f"Uploaded conversion that occurred at " f'"{conversion_adjustment_result.adjustment_date_time}" ' f"from Gclid " f'"{conversion_adjustment_result.gclid_date_time_pair.gclid}"' f' to "{conversion_adjustment_result.conversion_action}"' )
Ruby
def upload_conversion_adjustment( customer_id, conversion_action_id, gclid, adjustment_type, conversion_date_time, 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 # Associate conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a 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.gclid_date_time_pair = client.resource.gclid_date_time_pair do |gdtp| gdtp.gclid = gclid gdtp.conversion_date_time = conversion_date_time end 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 at #{result.adjustment_date_time} " \ "for adjustment #{result.adjustment_type} to #{result.conversion_action}." 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| puts "\t#{error.error_code.error_code}: #{error.message}" end end end end
Perl
sub upload_conversion_adjustment { my ($api_client, $customer_id, $conversion_action_id, $gclid, $adjustment_type, $conversion_date_time, $adjustment_date_time, $restatement_value) = @_; # Associate conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a conversion. my $conversion_adjustment = Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::ConversionAdjustment ->new({ conversionAction => Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_action( $customer_id, $conversion_action_id ), adjustmentType => $adjustment_type, gclidDateTimePair => Google::Ads::GoogleAds::V16::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::V16::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 Google Click ID '%s'.\n", $uploaded_conversion_adjustment->{conversionAction}, $uploaded_conversion_adjustment->{gclidDateTimePair}{gclid}; } return 1; }
需求條件
在 API 中調整轉換時,請注意下列規定和限制:
只有管理轉換動作的帳戶才能上傳調整項。使用轉換追蹤設定操作說明,判斷哪個帳戶管理 Google Ads 帳戶的轉換。
嘗試使用其他帳戶上傳調整項會導致
NO_CONVERSION_ACTION_FOUND
錯誤。如果未啟用調整項的轉換動作,也會發生這個錯誤。Google Ads 僅支援調整
SALESFORCE
、UPLOAD_CLICKS
或WEBPAGE
轉換動作類型的轉換資料。如果嘗試為轉換上傳調整項,但轉換動作並非上述其中一種類型,就會導致INVALID_CONVERSION_ACTION_TYPE
錯誤。指定日期和時間的欄位可能需要設定帳戶時區。這些欄位的格式為
yyyy-mm-dd HH:mm:ss+|-HH:mm
,例如:2022-01-01 19:32:45-05:00
(忽略日光節約時間)。建立轉換動作後,請等待 4 到 6 小時再調整轉換,以免發生
TOO_RECENT_CONVERSION_ACTION
錯誤。如果符合以下任一條件,調整項就會失敗並顯示
CONVERSION_NOT_FOUND
錯誤:系統從未記錄該次轉換。
系統在嘗試調整前少於 24 小時才記錄轉換。在某些情況下,這可能會改為發生
TOO_RECENT_CONVERSION
錯誤。
您必須在符合以下任一條件的
ConversionAdjustment
中指定order_id
:轉換動作的
type
等於WEBPAGE
。您要調整的原始轉換已指派
order_id
。
如果您改為指定
gclid_date_time_pair
,作業將會失敗並顯示ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE
或ConversionAdjustmentUploadError.CONVERSION_NOT_FOUND
錯誤。建立
ConversionAdjustment
時,UploadConversionAdjustmentsRequest
的partial_failure
屬性應一律設為true
。同時處理有效和失敗的作業時,請遵循部分失敗指南。您無法利用調整項變更
ConversionAction
。請改用RETRACTION
移除先前的轉換,並使用更新後的ConversionAction
上傳新的轉換。時間戳記不需要修改。請參閱「關於轉換調整項」一文。