Puoi utilizzare l'API Google Ads per caricare le chiamate offline conversioni in Google Ads per monitorare quando gli annunci generano telefonate e quando alle azioni più redditizie dei clienti.
Un clic click-to-call da dispositivo mobile non può essere caricato come conversione se non sono presenti Numero di inoltro di Google associato alla chiamata. Senza un inoltro di Google numero, Google non è in grado di essere certo che il clic abbia generato una chiamata e poi in una conversione. Se un clic viene caricato in questo modo, verrà ignorato dalla azione di conversione.
La mappatura sull'interfaccia utente di Google Ads equivale all'utilizzo della conversione Caricamenti. sorgente, seguita da Conversioni da chiamate.
Crea una conversione di chiamata
Ecco alcuni aspetti da tenere a mente durante la creazione di un CallConversion:
A partire dalla versione v15 dell'API Google Ads, devi compilare la
consentdelCallConversionoggetto.L'attributo
partial_failuredelUploadCallConversionsRequestdeve essere sempre impostato sutrue. Segui gli errori parziali linee guida per la gestione contemporaneamente operazioni non riuscite.Se riscontri un
TOO_RECENT_CONVERSION_ACTIONoTOO_RECENT_CALLmessaggio di risposta a una richiesta di caricamento di conversione, attendere 6 ore o 12 ore prima di riprovare per le righe con errori.Sono necessarie fino a tre ore prima che le statistiche delle conversioni importate siano visibili nel tuo account Google Ads.
Se carichi conversioni duplicate (ovvero, un
CallConversioncon uncaller_id,conversion_date_timeeconversion_action, ovvero caricato in precedenza), viene restituito un erroreCALL_CONVERSION_ALREADY_EXISTS.- Se una singola richiesta contiene più operazioni per la stessa conversione,
viene restituito un errore
DUPLICATE_CALL_CONVERSION_IN_REQUEST.
- Se una singola richiesta contiene più operazioni per la stessa conversione,
viene restituito un errore
Carica una conversione di chiamata
Per associare le conversioni di chiamata offline a un'azione di conversione,
sono necessarie le seguenti informazioni: ID chiamante (numero di telefono),
data e ora della conversione, nome della risorsa dell'azione di conversione e, facoltativamente, il nome
il valore di conversione e la valuta
ConversionUploadService
Per ulteriori dettagli sui diversi input, consulta la nostra Guida
assistenza. Il codice
example descrive anche i formati dei diversi input.
Requisiti
Esistono diversi requisiti che devono essere soddisfatti quando carichi un
CallConversion
Per evitare un errore ConversionUploadError.INVALID_CONVERSION_ACTION, il
Attributo conversion_action
deve fare riferimento a una ConversionAction in cui:
Il valore
ConversionActionTypeèUPLOAD_CALLSLa
statusdiConversionActionèENABLED. In caso contrario, l'operazione non va a buon fineNO_CONVERSION_ACTION_FOUND.ConversionActionesiste nel cliente Google Ads che ha effettuato la conversione dell'account l'account Google Ads di un clic.
Ti consigliamo inoltre di impostare
ConversionAction.category al
categoria che meglio descrive le tue conversioni.
Inoltre, devono essere soddisfatte le seguenti condizioni:
Al momento della chiamata, il monitoraggio delle conversioni era attivato nel Cliente Google Ads che ha effettuato una conversione dell'account Google Ads della chiamata.
Il
customer_iddelUploadCallConversionsRequestdeve essere l'ID cliente della conversione di Google Ads cliente di all'account Google Ads della chiamata. In caso contrario, il caricamento della conversione genereràConversionUploadError.INVALID_CUSTOMER_FOR_CALLerrore.Il valore
conversion_valuedeve essere maggiore o uguale a zero.conversion_date_timedeve avere un fuso orario specificato e il formato è comeyyyy-mm-dd HH:mm:ss+|-HH:mm, ad esempio:2022-01-01 19:32:45-05:00(ignorando l'ora legale) di Google. Il fuso orario può essere qualsiasi valore valido: non devono corrispondere al fuso orario dell'account.
Esempio di codice
Java
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
String conversionActionId,
String callerId,
String callStartDateTime,
double conversionValue,
Long conversionCustomVariableId,
String conversionCustomVariableValue,
ConsentStatus adUserDataConsent) {
// Create a call conversion by specifying currency as USD.
CallConversion.Builder conversionBuilder =
CallConversion.newBuilder()
.setConversionAction(conversionActionId)
.setCallerId(callerId)
.setCallStartDateTime(callStartDateTime)
.setConversionValue(conversionValue)
.setCurrencyCode("USD");
if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
conversionBuilder.addCustomVariables(
CustomVariable.newBuilder()
.setConversionCustomVariable(
ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
.setValue(conversionCustomVariableValue));
}
// 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.
conversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent));
}
CallConversion conversion = conversionBuilder.build();
// Uploads the call conversion to the API.
try (ConversionUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
// Partial failure MUST be enabled for this request.
// 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
UploadCallConversionsResponse response =
conversionUploadServiceClient.uploadCallConversions(
UploadCallConversionsRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.setCustomerId(Long.toString(customerId))
.addConversions(conversion)
.setPartialFailure(true)
.build());
// Prints any partial failure errors returned.
if (response.hasPartialFailureError()) {
GoogleAdsFailure googleAdsFailure =
ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
googleAdsFailure
.getErrorsList()
.forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage()));
throw new RuntimeException(
"Partial failure occurred " + response.getPartialFailureError().getMessage());
}
// Prints the result if valid.
CallConversionResult result = response.getResults(0);
System.out.printf(
"Uploaded call conversion that occurred at '%' for caller ID '%' to the conversion"
+ " action with resource name '%'.%n",
result.getCallStartDateTime(), result.getCallerId(), result.getConversionAction());
}
}
C#
public void Run(GoogleAdsClient client, long customerId,
long conversionActionId, string callerId, string callStartTime,
string conversionTime, double conversionValue,
long? conversionCustomVariableId, string conversionCustomVariableValue,
ConsentStatus? adUserDataConsent)
{
// Get the ConversionUploadService.
ConversionUploadServiceClient conversionUploadService =
client.GetService(Services.V17.ConversionUploadService);
// Create a call conversion by specifying currency as USD.
CallConversion callConversion = new CallConversion()
{
ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
CallerId = callerId,
CallStartDateTime = callStartTime,
ConversionDateTime = conversionTime,
ConversionValue = conversionValue,
CurrencyCode = "USD",
};
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.
callConversion.Consent = new Consent()
{
AdUserData = (ConsentStatus)adUserDataConsent
};
}
if (conversionCustomVariableId != null &&
!string.IsNullOrEmpty(conversionCustomVariableValue))
{
callConversion.CustomVariables.Add(new CustomVariable()
{
ConversionCustomVariable = ResourceNames.ConversionCustomVariable(
customerId, conversionCustomVariableId.Value),
Value = conversionCustomVariableValue
});
}
UploadCallConversionsRequest request = new UploadCallConversionsRequest()
{
CustomerId = customerId.ToString(),
Conversions = { callConversion },
PartialFailure = true
};
try
{
// Issues a request to upload the call conversion. The partialFailure parameter
// is set to true, and validateOnly parameter to false as required by this method
// call.
// 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
UploadCallConversionsResponse response =
conversionUploadService.UploadCallConversions(request);
// Since we set partialFailure = true, we can retrieve error messages (if any) from
// the operation response.
if (response.PartialFailureError != null)
{
Console.WriteLine("Call conversion upload failed.");
// Retrieves the errors from the partial failure and prints them.
List<GoogleAdsError> errors =
response.PartialFailure.GetErrorsByOperationIndex(0);
foreach (GoogleAdsError error in errors)
{
Console.WriteLine($"Operation failed with error: {error}.");
}
}
else
{
// Prints the result.
CallConversionResult uploadedCallConversion = response.Results[0];
Console.WriteLine($"Uploaded call conversion that occurred at " +
$"'{uploadedCallConversion.CallStartDateTime}' for caller ID " +
$"'{uploadedCallConversion.CallerId}' to the conversion action with " +
$"resource name '{uploadedCallConversion.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 $callerId,
string $callStartDateTime,
string $conversionDateTime,
float $conversionValue,
?string $conversionCustomVariableId,
?string $conversionCustomVariableValue,
?int $adUserDataConsent
) {
// Creates a call conversion by specifying currency as USD.
$callConversion = new CallConversion([
'conversion_action' =>
ResourceNames::forConversionAction($customerId, $conversionActionId),
'caller_id' => $callerId,
'call_start_date_time' => $callStartDateTime,
'conversion_date_time' => $conversionDateTime,
'conversion_value' => $conversionValue,
'currency_code' => 'USD'
]);
if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
$callConversion->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.
$callConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent]));
}
// Issues a request to upload the call conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
// 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->uploadCallConversions(
// Partial failure MUST be enabled for this request.
UploadCallConversionsRequest::build($customerId, [$callConversion], 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 CallConversionResult $uploadedCallConversion */
$uploadedCallConversion = $response->getResults()[0];
printf(
"Uploaded call conversion that occurred at '%s' for caller ID '%s' to the "
. "conversion action with resource name '%s'.%s",
$uploadedCallConversion->getCallStartDateTime(),
$uploadedCallConversion->getCallerId(),
$uploadedCallConversion->getConversionAction(),
PHP_EOL
);
}
}
Python
def main(
client,
customer_id,
conversion_action_id,
caller_id,
call_start_date_time,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
ad_user_data_consent,
):
"""Imports offline call conversion values for calls related to your ads.
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.
caller_id: The caller ID from which this call was placed. Caller ID is
expected to be in E.164 format with preceding '+' sign,
e.g. '+18005550100'.
call_start_date_time: The date and time at which the call occurred. The
format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
e.g. '2021-01-01 12:32:45-08:00'.
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.
ad_user_data_consent: The consent status for ad user data for all
members in the job.
"""
# Get the ConversionUploadService client.
conversion_upload_service = client.get_service("ConversionUploadService")
# Create a call conversion in USD currency.
call_conversion = client.get_type("CallConversion")
call_conversion.conversion_action = client.get_service(
"ConversionActionService"
).conversion_action_path(customer_id, conversion_action_id)
call_conversion.caller_id = caller_id
call_conversion.call_start_date_time = call_start_date_time
call_conversion.conversion_date_time = conversion_date_time
call_conversion.conversion_value = conversion_value
call_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_custom_variable_id
)
conversion_custom_variable.value = conversion_custom_variable_value
call_conversion.custom_variables.append(conversion_custom_variable)
# 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
if ad_user_data_consent:
call_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
ad_user_data_consent
]
# Issue a request to upload the call conversion.
# Partial failure MUST be enabled for this request.
request = client.get_type("UploadCallConversionsRequest")
request.customer_id = customer_id
request.conversions = [call_conversion]
request.partial_failure = True
# 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
upload_call_conversions_response = (
conversion_upload_service.upload_call_conversions(request=request)
)
# Print any partial errors returned.
if upload_call_conversions_response.partial_failure_error:
print(
"Partial error occurred: "
f"'{upload_call_conversions_response.partial_failure_error.message}'"
)
# Print the result if valid.
uploaded_call_conversion = upload_call_conversions_response.results[0]
if uploaded_call_conversion.call_start_date_time:
print(
"Uploaded call conversion that occurred at "
f"'{uploaded_call_conversion.call_start_date_time}' "
f"for caller ID '{uploaded_call_conversion.caller_id}' "
"to the conversion action with resource name "
f"'{uploaded_call_conversion.conversion_action}'."
)
Ruby
def upload_call_conversion(
customer_id,
conversion_action_id,
caller_id,
call_start_date_time,
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
# Create a call conversion by specifying currency as USD.
call_conversion = client.resource.call_conversion do |c|
c.conversion_action = client.path.conversion_action(
customer_id, conversion_action_id)
c.caller_id = caller_id
c.call_start_date_time = call_start_date_time
c.conversion_date_time = conversion_date_time
c.conversion_value = conversion_value
c.currency_code = "USD"
if conversion_custom_variable_id && conversion_custom_variable_value
c.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
unless ad_user_data_consent.nil?
c.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
# Issues a request to upload the call conversion.
response = client.service.conversion_upload.upload_call_conversions(
customer_id: customer_id,
# 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
conversions: [call_conversion],
partial_failure: true
)
# Prints errors if any partial failure error is returned.
if response.partial_failure_error
failures = client.decode_partial_failure_error(response.partial_failure_error)
failures.each do |failure|
failure.errors.each do |error|
human_readable_error_path = error
.location
.field_path_elements
.map { |location_info|
if location_info.index
"#{location_info.field_name}[#{location_info.index}]"
else
"#{location_info.field_name}"
end
}.join(" > ")
errmsg = "error occured while adding operations " \
"#{human_readable_error_path}" \
" with value: #{error.trigger.string_value}" \
" because #{error.message.downcase}"
puts errmsg
end
end
else
# Print the result if valid.
uploaded_call_conversion = response.results.first
puts "Uploaded call conversion that occurred at " \
"#{uploaded_call_conversion.call_start_date_time} " \
"for caller ID " \
"#{uploaded_call_conversion.caller_id} " \
"to the conversion action with resource name " \
"#{uploaded_call_conversion.conversion_action}"
end
end
Perl
sub upload_call_conversion {
my (
$api_client, $customer_id,
$conversion_action_id, $caller_id,
$call_start_date_time, $conversion_date_time,
$conversion_value, $conversion_custom_variable_id,
$conversion_custom_variable_value, $ad_user_data_consent
) = @_;
# Create a call conversion by specifying currency as USD.
my $call_conversion =
Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CallConversion
->new({
conversionAction =>
Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
),
callerId => $caller_id,
callStartDateTime => $call_start_date_time,
conversionDateTime => $conversion_date_time,
conversionValue => $conversion_value,
currencyCode => "USD"
});
if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
$call_conversion->{customVariables} = [
Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CustomVariable
->new({
conversionCustomVariable =>
Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_custom_variable(
$customer_id, $conversion_custom_variable_id
),
value => $conversion_custom_variable_value
})];
}
# 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.
$call_conversion->{consent} =
Google::Ads::GoogleAds::V17::Common::Consent->new({
adUserData => $ad_user_data_consent
});
}
# Issue a request to upload the call conversion.
# 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_call_conversions_response =
$api_client->ConversionUploadService()->upload_call_conversions({
customerId => $customer_id,
conversions => [$call_conversion],
partialFailure => "true"
});
# Print any partial errors returned.
if ($upload_call_conversions_response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$upload_call_conversions_response->{partialFailureError}{message};
}
# Print the result if valid.
my $uploaded_call_conversion =
$upload_call_conversions_response->{results}[0];
if (%$uploaded_call_conversion) {
printf "Uploaded call conversion that occurred at '%s' " .
"for caller ID '%s' to the conversion action with resource name '%s'.\n",
$uploaded_call_conversion->{callStartDateTime},
$uploaded_call_conversion->{callerId},
$uploaded_call_conversion->{conversionAction};
}
return 1;
}