Una volta che una conversione è già stata registrata in Google Ads, puoi modificarla in un secondo momento nell'API Google Ads.
Per aggiustare una conversione, devi prima aver configurato un'azione di conversione e devi anche aver registrato le conversioni che stai per aggiustare.
Esempio di codice
L'API Google Ads supporta l'uso di order_id, noto anche come ID transazione, per identificare la conversione da adeguare con ConversionAdjustmentUploadService.
Per ottenere il conversion_action_id necessario per apportare un aggiustamento delle conversioni, puoi
eseguire una delle seguenti operazioni:
Ottieni il valore dal parametro
ctIddisponibile nell'URL quando fai clic sui dettagli delle conversioni nell'interfaccia utente di Google Ads.Esegui una query sull'API Google Ads per
conversion_action.idnel reportconversion_action.
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.V17.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::V17::Services::ConversionAdjustmentUploadService::ConversionAdjustment
->new({
conversionAction =>
Google::Ads::GoogleAds::V17::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::V17::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::V17::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;
}
Requisiti
Di seguito sono riportati alcuni requisiti e limitazioni da tenere presenti durante la regolazione delle conversioni nell'API:
Solo l'account che gestisce le azioni di conversione può caricare gli aggiustamenti. Utilizza le istruzioni per la configurazione del monitoraggio delle conversioni per determinare quale account gestisce le conversioni per il tuo account Google Ads.
Il tentativo di caricare un aggiustamento utilizzando un altro account genera un errore
NO_CONVERSION_ACTION_FOUND. Questo errore si verifica anche se l'azione di conversione dell'aggiustamento non è abilitata.Google Ads supporta solo l'aggiustamento delle conversioni per i tipi di azioni di conversione di
SALESFORCE,UPLOAD_CLICKSoWEBPAGE. Il tentativo di caricare un aggiustamento per una conversione in cui l'azione di conversione non è uno di questi tipi genera un erroreINVALID_CONVERSION_ACTION_TYPE.I campi che specificano data e ora richiedono un fuso orario che non deve necessariamente essere quello dell'account. Il formato di questi campi è
yyyy-mm-dd HH:mm:ss+|-HH:mm, ad esempio:2022-01-01 19:32:45-05:00(ignora l'ora legale) .Attendi da 4 a 6 ore dopo aver creato l'azione di conversione prima di modificarne le conversioni per evitare un errore
TOO_RECENT_CONVERSION_ACTION.L'aggiustamento non va a buon fine e viene visualizzato un errore
CONVERSION_NOT_FOUNDse viene soddisfatta una delle seguenti condizioni:La conversione non è mai stata registrata.
La conversione è stata registrata meno di 24 ore prima del tentativo di aggiustamento. In alcune situazioni, questo potrebbe generare un errore
TOO_RECENT_CONVERSION.
Devi specificare
order_idinConversionAdjustmentin una delle seguenti condizioni:Il
typedell'azione di conversione è uguale aWEBPAGE.Alla conversione originale che stai modificando è stato assegnato un valore
order_id.
Se specifichi invece
gclid_date_time_pair, l'operazione non andrà a buon fine con rispettivamente un erroreConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGEoConversionAdjustmentUploadError.CONVERSION_NOT_FOUND.Quando si crea un elemento
ConversionAdjustment, l'attributopartial_failurediUploadConversionAdjustmentsRequestdeve essere sempre impostato sutrue. Segui le linee guida per gli errori parziali quando gestisci contemporaneamente operazioni valide e non riuscite.Non puoi modificare
ConversionActioncon un aggiustamento. Utilizza invece un elementoRETRACTIONper rimuovere la conversione precedente e caricane una nuova con il valoreConversionActionaggiornato. Il timestamp non deve essere modificato. Consulta Informazioni sugli aggiustamenti delle conversioni.