Mit der Google Ads API können Sie Offline-Anruf-Conversions in Google Ads hochladen und so erfassen, wann Ihre Anzeigen zu Anrufen und diese Anrufe zu wertvollen Kundenaktionen führen.
Wenn es für einen Anruf keine Google-Weiterleitungsnummer gibt, lässt sich ein Click-to-Call nicht als Conversion hochladen. Ohne Google-Weiterleitungsnummer kann Google nicht feststellen, ob der Klick zu einem Anruf und anschließend zu einer Conversion geführt hat. Wenn ein Klick auf diese Weise hochgeladen wird, wird er von der Conversion-Aktion ignoriert.
Die Zuordnung zur Google Ads-Benutzeroberfläche entspricht der Verwendung der Conversion-Quelle Uploads, gefolgt von Anruf-Conversions.
Anruf-Conversion erstellen
Beachten Sie beim Erstellen von CallConversion
Folgendes:
Ab Version 15 der Google Ads API muss das Feld
consent
desCallConversion
-Objekts ausgefüllt werden.Das Attribut
partial_failure
vonUploadCallConversionsRequest
sollte immer auftrue
festgelegt sein. Halten Sie sich an die Richtlinien für partielle Fehler, wenn Sie gültige und fehlgeschlagene Vorgänge gleichzeitig ausführen.Wenn Sie auf eine Anfrage zum Hochladen einer Conversion eine
TOO_RECENT_CONVERSION_ACTION
- oderTOO_RECENT_CALL
-Antwortnachricht erhalten, warten Sie 6 Stunden bzw. 12 Stunden, bevor Sie die fehlerhaften Zeilen wiederholen.Es dauert bis zu drei Stunden, bis importierte Conversion-Statistiken in Ihrem Google Ads-Konto angezeigt werden.
Wenn Sie Conversions doppelt hochladen (d. h. ein
CallConversion
mitcaller_id
,conversion_date_time
undconversion_action
, das bereits hochgeladen wurde), wird der FehlerCALL_CONVERSION_ALREADY_EXISTS
zurückgegeben.- Wenn eine einzelne Anfrage mehrere Vorgänge für dieselbe Conversion enthält, wird der Fehler
DUPLICATE_CALL_CONVERSION_IN_REQUEST
zurückgegeben.
- Wenn eine einzelne Anfrage mehrere Vorgänge für dieselbe Conversion enthält, wird der Fehler
Anruf-Conversion hochladen
Wenn Sie Ihre Offline-Anruf-Conversions einer Conversion-Aktion zuordnen möchten, benötigen Sie die folgenden Informationen: Anrufer-ID (Telefonnummer), Datum und Uhrzeit der Conversion, Ressourcenname der Conversion-Aktion und optional den Conversion-Wert und die Währung für die ConversionUploadService
.
Weitere Informationen zu den verschiedenen Eingaben finden Sie in diesem Hilfeartikel. Im Codebeispiel werden auch die Formate für die verschiedenen Eingaben beschrieben.
Voraussetzungen
Beim Hochladen einer CallConversion
müssen mehrere Anforderungen erfüllt sein.
Um den Fehler ConversionUploadError.INVALID_CONVERSION_ACTION
zu vermeiden, muss sich das Attribut conversion_action
auf ConversionAction
beziehen, wobei Folgendes gilt:
ConversionActionType
istUPLOAD_CALLS
.Der
status
vonConversionAction
istENABLED
. Andernfalls schlägt der Vorgang mit dem FehlerNO_CONVERSION_ACTION_FOUND
fehl.Die
ConversionAction
ist im Google Ads-Conversion-Kunden des Google Ads-Kontos des Klicks vorhanden.
Wir empfehlen außerdem, ConversionAction.category
auf die Kategorie festzulegen, die Ihre Conversions am besten beschreibt.
Außerdem müssen folgende Bedingungen erfüllt sein:
Zum Zeitpunkt des Anrufs war Conversion-Tracking für den Google Ads-Conversion-Kunden im Google Ads-Konto des Anrufs aktiviert.
Die
customer_id
derUploadCallConversionsRequest
muss die Kundennummer des Google Ads-Conversion-Kunden des Google Ads-Kontos des Anrufs sein. Andernfalls tritt beim Conversion-Upload der FehlerConversionUploadError.INVALID_CUSTOMER_FOR_CALL
auf.conversion_value
muss größer oder gleich null sein.Für
conversion_date_time
muss eine Zeitzone angegeben werden. Das Format istyyyy-mm-dd HH:mm:ss+|-HH:mm
, z. B.2022-01-01 19:32:45-05:00
(ohne Sommerzeit). Die Zeitzone kann für jeden gültigen Wert verwendet werden: Sie muss nicht mit der Zeitzone des Kontos übereinstimmen.
Codebeispiel
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.V16.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::V16::Services::ConversionUploadService::CallConversion ->new({ conversionAction => Google::Ads::GoogleAds::V16::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::V16::Services::ConversionUploadService::CustomVariable ->new({ conversionCustomVariable => Google::Ads::GoogleAds::V16::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::V16::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; }