Mit der Google Ads API können Sie Offline-Click- Conversions in Google Ads hochladen, um Anzeigen zu erfassen, die zu Verkäufen im Offline-Bereich geführt haben, z. B. per Telefon oder über einen Vertriebsmitarbeiter.
Einrichtung
Für eine funktionierende Einrichtung von Offline-Conversions müssen einige Voraussetzungen erfüllt sein. Prüfen Sie, ob alle Voraussetzungen erfüllt sind, bevor Sie mit der Implementierung fortfahren:
Aktivieren Sie das Conversion-Tracking im Google Ads-Conversion-Kundenkonto.
Konfigurieren Sie das Tagging und speichern Sie die Click-IDs.
1. Conversion-Tracking im Google Ads-Conversion-Kundenkonto aktivieren
Wenn Sie die Anleitung für den Einstieg in das Conversion-Tracking durchgearbeitet und das Conversion-Tracking aktiviert haben können Sie mit Schritt 2 fortfahren: Tagging konfigurieren.
Informationen zur Einrichtung des Conversion-Trackings abrufen
Sie können die Einrichtung des Conversion-Trackings für Ihr Konto prüfen und bestätigen, dass das Conversion
Tracking aktiviert ist, indem Sie die Customer Ressource
nach der ConversionTrackingSetting abfragen.
Führen Sie die folgende Abfrage mit
GoogleAdsService.SearchStream aus:
SELECT
customer.conversion_tracking_setting.google_ads_conversion_customer,
customer.conversion_tracking_setting.conversion_tracking_status,
customer.conversion_tracking_setting.conversion_tracking_id,
customer.conversion_tracking_setting.cross_account_conversion_tracking_id
FROM customer
Das Feld google_ads_conversion_customer gibt das Google Ads-Konto an, in dem Conversions für diesen Kunden erstellt und verwaltet werden. Bei Kunden, die
kontoübergreifendes Conversion-Tracking,
verwenden, ist dies die ID eines Verwaltungskontos. Die Google Ads-Conversion-Kunden-ID sollte in Google Ads API-Anfragen zum Erstellen und Verwalten von Conversions als customer_id angegeben werden.
Dieses Feld wird auch dann ausgefüllt, wenn das Conversion-Tracking nicht aktiviert ist.
Das
conversion_tracking_status
Feld gibt an, ob das Conversion-Tracking aktiviert ist und ob das Konto
kontoübergreifendes Conversion-Tracking verwendet.
Conversion-Aktion im Google Ads-Conversion-Kundenkonto erstellen
Wenn der Wert von conversion_tracking_status NOT_CONVERSION_TRACKED ist, ist das Conversion-Tracking für das Konto nicht aktiviert. Aktivieren Sie das Conversion-Tracking
indem Sie im Google Ads-Conversion-Konto mindestens eine ConversionAction erstellen, wie im folgenden Beispiel. Alternativ können Sie
eine Conversion-Aktion in der Benutzeroberfläche erstellen. Folgen Sie dazu der Anleitung in der
Hilfe für den
Conversion-Typ, den Sie aktivieren möchten.
Erweiterte Conversions werden automatisch aktiviert, wenn sie über die Google Ads API gesendet werden. Sie können jedoch über die Google Ads-Benutzeroberfläche deaktiviert werden.
Codebeispiel
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { // Creates a ConversionAction. ConversionAction conversionAction = ConversionAction.newBuilder() // Note that conversion action names must be unique. If a conversion action already // exists with the specified conversion_action_name the create operation will fail with // a ConversionActionError.DUPLICATE_NAME error. .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime()) .setCategory(ConversionActionCategory.DEFAULT) .setType(ConversionActionType.WEBPAGE) .setStatus(ConversionActionStatus.ENABLED) .setViewThroughLookbackWindowDays(15L) .setValueSettings( ValueSettings.newBuilder() .setDefaultValue(23.41) .setAlwaysUseDefaultValue(true) .build()) .build(); // Creates the operation. ConversionActionOperation operation = ConversionActionOperation.newBuilder().setCreate(conversionAction).build(); try (ConversionActionServiceClient conversionActionServiceClient = googleAdsClient.getLatestVersion().createConversionActionServiceClient()) { MutateConversionActionsResponse response = conversionActionServiceClient.mutateConversionActions( Long.toString(customerId), Collections.singletonList(operation)); System.out.printf("Added %d conversion actions:%n", response.getResultsCount()); for (MutateConversionActionResult result : response.getResultsList()) { System.out.printf( "New conversion action added with resource name: '%s'%n", result.getResourceName()); } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the ConversionActionService. ConversionActionServiceClient conversionActionService = client.GetService(Services.V25.ConversionActionService); // Note that conversion action names must be unique. // If a conversion action already exists with the specified name the create operation // will fail with a ConversionAction.DUPLICATE_NAME error. string ConversionActionName = "Earth to Mars Cruises Conversion #" + ExampleUtilities.GetRandomString(); // Add a conversion action. ConversionAction conversionAction = new ConversionAction() { Name = ConversionActionName, Category = ConversionActionCategory.Default, Type = ConversionActionType.Webpage, Status = ConversionActionStatus.Enabled, ViewThroughLookbackWindowDays = 15, ValueSettings = new ConversionAction.Types.ValueSettings() { DefaultValue = 23.41, AlwaysUseDefaultValue = true } }; // Create the operation. ConversionActionOperation operation = new ConversionActionOperation() { Create = conversionAction }; try { // Create the conversion action. MutateConversionActionsResponse response = conversionActionService.MutateConversionActions(customerId.ToString(), new ConversionActionOperation[] { operation }); // Display the results. foreach (MutateConversionActionResult newConversionAction in response.Results) { Console.WriteLine($"New conversion action with resource name = " + $"'{newConversionAction.ResourceName}' was added."); } } 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) { // Creates a conversion action. $conversionAction = new ConversionAction([ // Note that conversion action names must be unique. // If a conversion action already exists with the specified conversion_action_name // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error. 'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(), 'category' => ConversionActionCategory::PBDEFAULT, 'type' => ConversionActionType::WEBPAGE, 'status' => ConversionActionStatus::ENABLED, 'view_through_lookback_window_days' => 15, 'value_settings' => new ValueSettings([ 'default_value' => 23.41, 'always_use_default_value' => true ]) ]); // Creates a conversion action operation. $conversionActionOperation = new ConversionActionOperation(); $conversionActionOperation->setCreate($conversionAction); // Issues a mutate request to add the conversion action. $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient(); $response = $conversionActionServiceClient->mutateConversionActions( MutateConversionActionsRequest::build($customerId, [$conversionActionOperation]) ); printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL); foreach ($response->getResults() as $addedConversionAction) { /** @var ConversionAction $addedConversionAction */ printf( "New conversion action added with resource name: '%s'%s", $addedConversionAction->getResourceName(), PHP_EOL ); } }
Python
def main(client: GoogleAdsClient, customer_id: str) -> None: conversion_action_service: ConversionActionServiceClient = ( client.get_service("ConversionActionService") ) # Create the operation. conversion_action_operation: ConversionActionOperation = client.get_type( "ConversionActionOperation" ) # Create conversion action. conversion_action: ConversionAction = conversion_action_operation.create # Note that conversion action names must be unique. If a conversion action # already exists with the specified conversion_action_name, the create # operation will fail with a ConversionActionError.DUPLICATE_NAME error. conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}" conversion_action.type_ = ( client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS ) conversion_action.category = ( client.enums.ConversionActionCategoryEnum.DEFAULT ) conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED conversion_action.view_through_lookback_window_days = 15 # Create a value settings object. value_settings: ConversionAction.ValueSettings = ( conversion_action.value_settings ) value_settings.default_value = 15.0 value_settings.always_use_default_value = True # Add the conversion action. conversion_action_response: MutateConversionActionsResponse = ( conversion_action_service.mutate_conversion_actions( customer_id=customer_id, operations=[conversion_action_operation], ) ) print( "Created conversion action " f'"{conversion_action_response.results[0].resource_name}".' )
Ruby
def add_conversion_action(customer_id) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new # Add a conversion action. conversion_action = client.resource.conversion_action do |ca| ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}" ca.type = :UPLOAD_CLICKS ca.category = :DEFAULT ca.status = :ENABLED ca.view_through_lookback_window_days = 15 # Create a value settings object. ca.value_settings = client.resource.value_settings do |vs| vs.default_value = 15 vs.always_use_default_value = true end end # Create the operation. conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action) # Add the ad group ad. response = client.service.conversion_action.mutate_conversion_actions( customer_id: customer_id, operations: [conversion_action_operation], ) puts "New conversion action with resource name = #{response.results.first.resource_name}." end
Perl
sub add_conversion_action { my ($api_client, $customer_id) = @_; # Note that conversion action names must be unique. # If a conversion action already exists with the specified conversion_action_name, # the create operation fails with error ConversionActionError.DUPLICATE_NAME. my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid(); # Create a conversion action. my $conversion_action = Google::Ads::GoogleAds::V25::Resources::ConversionAction->new({ name => $conversion_action_name, category => DEFAULT, type => WEBPAGE, status => ENABLED, viewThroughLookbackWindowDays => 15, valueSettings => Google::Ads::GoogleAds::V25::Resources::ValueSettings->new({ defaultValue => 23.41, alwaysUseDefaultValue => "true" })}); # Create a conversion action operation. my $conversion_action_operation = Google::Ads::GoogleAds::V25::Services::ConversionActionService::ConversionActionOperation ->new({create => $conversion_action}); # Add the conversion action. my $conversion_actions_response = $api_client->ConversionActionService()->mutate({ customerId => $customer_id, operations => [$conversion_action_operation]}); printf "New conversion action added with resource name: '%s'.\n", $conversion_actions_response->{results}[0]{resourceName}; return 1; }
curl
Prüfen Sie, ob conversion_action_type auf den richtigen
ConversionActionType-Wert festgelegt ist.
Weitere Informationen zum Erstellen von Conversion-Aktionen in der Google Ads API finden Sie unter Conversion-Aktionen erstellen.
Vorhandene Conversion-Aktion abrufen
Sie können Details zu einer vorhandenen Conversion-Aktion abrufen, indem Sie die folgende Abfrage ausführen. Prüfen Sie, ob die Kunden-ID in der Anfrage auf den oben angegebenen Google Ads
Conversion-Kunden festgelegt ist und der Conversion-Aktionstyp auf den richtigen
ConversionActionType
Wert gesetzt ist.
SELECT
conversion_action.resource_name,
conversion_action.name,
conversion_action.status
FROM conversion_action
WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'
2. Tagging konfigurieren und Click-IDs speichern
Folgen Sie der Anleitung um zu bestätigen, dass das automatische Tagging aktiviert ist. Richten Sie Ihr Google Ads-Konto, Ihre Website und Ihr Lead-Tracking-System so ein, dass die GCLID für jede Impression sowie die URL-Parameter GBRAID oder WBRAID für Ihre Anzeigen erfasst und gespeichert werden. Für neue Konten ist das automatische Tagging standardmäßig aktiviert.
Anfrage erstellen
Folgen Sie dieser Anleitung, um Ihre
UploadClickConversionsRequest
zu erstellen und die Felder auf die entsprechenden Werte festzulegen.
customer_idGibt das Google Ads-Konto Ihres Uploads an. Legen Sie dies auf den Google Ads Conversion-Kunden des Kontos fest, aus dem die Klicks stammen.
job_idBietet einen Mechanismus, um Ihre Upload-Anfragen mit den jobbezogenen Informationen in der Diagnose von Offline-Daten zu verknüpfen.
Wenn Sie dieses Feld nicht festlegen, weist die Google Ads API jeder Anfrage einen eindeutigen Wert im Bereich
[2^31, 2^63)zu. Wenn Sie mehrere Anfragen zu einem einzelnen logischen Job zusammenfassen möchten, legen Sie dieses Feld für jede Anfrage in Ihrem Job auf denselben Wert im Bereich[0, 2^31)fest.Das
job_idin der Antwort enthält die Job-ID für die Anfrage, unabhängig davon, ob Sie einen Wert angegeben oder die Google Ads API einen Wert zugewiesen haben.partial_failure_enabledBestimmt, wie die Google Ads API Fehler aus Vorgängen verarbeitet.
Dieses Feld muss auf
truefestgelegt sein. Folgen Sie bei der Verarbeitung der Antwort der Anleitung zu teilweisen Fehlern.debug_enabledBestimmt das Verhalten bei der Fehlerberichterstellung für Uploads von erweiterten Conversions für Leads. Die Google Ads API ignoriert dieses Feld bei der Verarbeitung von Uploads für Click-Conversions mit den URL-Parametern
gclid,gbraidoderwbraid.
Click-Conversion-Vorgänge erstellen
Die Sammlung von ClickConversion-Objekten in
Ihrer UploadClickConversionRequest definiert die Conversions, die Sie hochladen möchten. Folgen Sie dieser Anleitung, um jede ClickConversion zu erstellen und die Felder auf die entsprechenden Werte festzulegen.
Pflichtfelder für jeden Conversion-Vorgang festlegen
Folgen Sie dieser Anleitung, um die Pflichtfelder von ClickConversion auf die entsprechenden Werte festzulegen.
gclid,gbraid,wbraidDie GCLID oder URL-Parameter, die erfasst werden, wenn ein Nutzer nach einem Anzeigenklick auf Ihrer Website oder in Ihrer App landet. Einer der folgenden Werte ist erforderlich:
gclidgbraidwbraid
conversion_date_timeDatum und Uhrzeit der Conversion.
Für den Wert muss eine Zeitzone angegeben sein und das Format muss
yyyy-mm-dd HH:mm:ss+|-HH:mmsein, z. B.2022-01-01 19:32:45-05:00(ohne Berücksichtigung der Sommerzeit) .Die Zeitzone kann ein beliebiger gültiger Wert sein. Sie muss nicht mit der Zeitzone des Kontos übereinstimmen. Wenn Sie jedoch Ihre hochgeladenen Conversion-Daten mit denen in der Google Ads-Benutzeroberfläche vergleichen möchten, empfehlen wir, dieselbe Zeitzone wie für Ihr Google Ads-Konto zu verwenden, damit die Conversion-Anzahlen übereinstimmen. Weitere Informationen und Beispiele finden Sie in der Hilfe . Eine Liste der gültigen Zeitzonen-IDs finden Sie unter Codes und Formate.
user_identifiersLegen Sie dieses Feld nicht fest, wenn Sie Conversions nur mit Click-IDs hochladen. Wenn dieses Feld festgelegt ist, behandelt Google Ads den Upload-Vorgang als Upload für erweiterte Conversions für Leads.
conversion_actionDer Ressourcenname der
ConversionActionfür die Click-Conversion.Die Conversion-Aktion muss den
typeUPLOAD_CLICKShaben und im Google Ads-Conversion-Kundenkonto des Google Ads-Kontos vorhanden sein, das mit dem Klick verknüpft ist.conversion_valueDer Wert der Conversion.
currency_codeDer Währungscode des
conversion_value.
Optionale Felder für jeden Conversion-Vorgang festlegen
Sehen Sie sich die folgende Liste optionaler Felder an und legen Sie sie nach Bedarf für Ihre ClickConversion fest.
order_id- Die Transaktions-ID für die Conversion. Dieses Feld ist optional, wird aber dringend empfohlen. Wenn Sie es beim Upload festlegen, müssen Sie es für alle Anpassungen verwenden, die an der Conversion vorgenommen werden. Weitere Informationen zur Verwendung einer Transaktions-ID, um Duplikate von Conversions zu vermeiden, finden Sie in diesem Hilfeartikel.
external_attribution_dataWenn Sie Tools von Drittanbietern oder eigene Lösungen verwenden, um Conversions zu erfassen, können Sie Google Ads nur einen Teil des Werts für die Conversion zuweisen oder den Wert für eine Conversion auf mehrere Klicks verteilen. Bei extern zugeordneten Conversion-Importen können Sie Conversions mit anteiliger Zuordnung hochladen, die jedem Klick zugewiesen ist.
Wenn Sie anteilige Werte hochladen möchten, legen Sie dieses Feld auf ein
ExternalAttributionData-Objekt mit Werten fürexternal_attribution_modelundexternal_attribution_creditfest.custom_variablesDie Werte für benutzerdefinierte Conversion-Variablen.
Google Ads unterstützt keine benutzerdefinierten Conversion-Variablen in Kombination mit
wbraidodergbraid.
cart_data
Sie können Warenkorbdaten
für eine ClickConversion im Feld cart_data
angeben. Dieses Feld besteht aus den folgenden Attributen:
merchant_id: Die ID des verknüpften Merchant Center-Kontos.feed_country_code: Der ISO 3166-Ländercode mit zwei Zeichen des Merchant Center-Feeds.feed_language_code: Der ISO 639-1 Sprachcode des Merchant Center-Feeds.local_transaction_cost: Die Summe aller Rabatte auf Transaktionsebene in dercurrency_codederClickConversion.items: Die Artikel im Einkaufswagen.Jeder Artikel in
itemsbesteht aus den folgenden Attributen:product_id: Die ID des Produkts, manchmal auch Angebots-ID oder Artikel-ID genannt.quantity: Die Menge des Artikels.unit_price: Der Einzelpreis des Artikels.
conversion_environment
Gibt die Umgebung an, in der diese Conversion erfasst wurde. Beispiel: App oder Web.
Codebeispiel
Java
private void runExample( GoogleAdsClient googleAdsClient, long customerId, long conversionActionId, String gclid, String gbraid, String wbraid, String conversionDateTime, Double conversionValue, Long conversionCustomVariableId, String conversionCustomVariableValue, String orderId, ConsentStatus adUserDataConsent) throws InvalidProtocolBufferException { // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required. // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details. long numberOfIdsSpecified = Arrays.asList(gclid, gbraid, wbraid).stream().filter(idField -> idField != null).count(); if (numberOfIdsSpecified != 1) { throw new IllegalArgumentException( "Exactly 1 of gclid, gbraid, or wbraid is required, but " + numberOfIdsSpecified + " ID values were provided"); } // Constructs the conversion action resource name from the customer and conversion action IDs. String conversionActionResourceName = ResourceNames.conversionAction(customerId, conversionActionId); // Creates the click conversion. ClickConversion.Builder clickConversionBuilder = ClickConversion.newBuilder() .setConversionAction(conversionActionResourceName) .setConversionDateTime(conversionDateTime) .setConversionValue(conversionValue) .setCurrencyCode("USD"); // Sets the single specified ID field. if (gclid != null) { clickConversionBuilder.setGclid(gclid); } else if (gbraid != null) { clickConversionBuilder.setGbraid(gbraid); } else { clickConversionBuilder.setWbraid(wbraid); } if (conversionCustomVariableId != null && conversionCustomVariableValue != null) { // Sets the custom variable and value, if provided. clickConversionBuilder.addCustomVariables( CustomVariable.newBuilder() .setConversionCustomVariable( ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId)) .setValue(conversionCustomVariableValue)); } if (orderId != null) { // Sets the order ID (unique transaction ID), if provided. clickConversionBuilder.setOrderId(orderId); } // 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. clickConversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent)); } ClickConversion clickConversion = clickConversionBuilder.build(); // Creates the conversion upload service client. try (ConversionUploadServiceClient conversionUploadServiceClient = googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) { // Uploads the click conversion. Partial failure should always be set to true. // 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 UploadClickConversionsResponse response = conversionUploadServiceClient.uploadClickConversions( UploadClickConversionsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .addConversions(clickConversion) // Enables partial failure (must be true). .setPartialFailure(true) .build()); // Prints any partial errors returned. if (response.hasPartialFailureError()) { GoogleAdsFailure googleAdsFailure = ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError()); // Constructs a protocol buffer printer that will print error details in a concise format. Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace(); for (int operationIndex = 0; operationIndex < response.getResultsCount(); operationIndex++) { ClickConversionResult conversionResult = response.getResults(operationIndex); if (ErrorUtils.getInstance().isPartialFailureResult(conversionResult)) { // Prints the errors for the failed operation. System.out.printf("Operation %d failed with the following errors:%n", operationIndex); for (GoogleAdsError resultError : ErrorUtils.getInstance().getGoogleAdsErrors(operationIndex, googleAdsFailure)) { // Prints the error with newlines and extra spaces removed. System.out.printf(" %s%n", errorPrinter.print(resultError)); } } else { // Prints the information about the successful operation. StringBuilder clickInfoBuilder = new StringBuilder("conversion that occurred at ") .append(String.format("'%s' ", conversionResult.getConversionDateTime())) .append("with "); if (conversionResult.hasGclid()) { clickInfoBuilder.append(String.format("gclid '%s'", conversionResult.getGclid())); } else if (!conversionResult.getGbraid().isEmpty()) { clickInfoBuilder.append(String.format("gbraid '%s'", conversionResult.getGbraid())); } else if (!conversionResult.getWbraid().isEmpty()) { clickInfoBuilder.append(String.format("wbraid '%s'", conversionResult.getWbraid())); } else { clickInfoBuilder.append("no click ID"); } System.out.printf("Operation %d for %s succeeded.%n", operationIndex, clickInfoBuilder); } } } } }
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId, string gclid, string gbraid, string wbraid, string conversionTime, double conversionValue, ConsentStatus? adUserDataConsent) { // Get the ConversionActionService. ConversionUploadServiceClient conversionUploadService = client.GetService(Services.V25.ConversionUploadService); // Creates a click conversion by specifying currency as USD. ClickConversion clickConversion = new ClickConversion() { ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId), ConversionValue = conversionValue, ConversionDateTime = conversionTime, CurrencyCode = "USD", }; // 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. clickConversion.Consent = new Consent() { AdUserData = (ConsentStatus)adUserDataConsent }; } // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required. // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks // for details. string[] ids = { gclid, gbraid, wbraid }; int idCount = ids.Where(id => !string.IsNullOrEmpty(id)).Count(); if (idCount != 1) { throw new ArgumentException($"Exactly 1 of gclid, gbraid, or wbraid is " + $"required, but {idCount} ID values were provided"); } // Sets the single specified ID field. if (!string.IsNullOrEmpty(gclid)) { clickConversion.Gclid = gclid; } else if (!string.IsNullOrEmpty(wbraid)) { clickConversion.Wbraid = wbraid; } else if (!string.IsNullOrEmpty(gbraid)) { clickConversion.Gbraid = gbraid; } try { // Issues a request to upload the click conversion. UploadClickConversionsResponse response = conversionUploadService.UploadClickConversions( new UploadClickConversionsRequest() { CustomerId = customerId.ToString(), Conversions = { clickConversion }, PartialFailure = true, ValidateOnly = false }); // Prints the result. ClickConversionResult uploadedClickConversion = response.Results[0]; Console.WriteLine($"Uploaded conversion that occurred at " + $"'{uploadedClickConversion.ConversionDateTime}' from Google " + $"Click ID '{uploadedClickConversion.Gclid}' to " + $"'{uploadedClickConversion.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 $gclid, ?string $gbraid, ?string $wbraid, ?string $orderId, string $conversionDateTime, float $conversionValue, ?string $conversionCustomVariableId, ?string $conversionCustomVariableValue, ?int $adUserDataConsent ) { // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required. // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details. $nonNullFields = array_filter( [$gclid, $gbraid, $wbraid], function ($field) { return !is_null($field); } ); if (count($nonNullFields) !== 1) { throw new \UnexpectedValueException( sprintf( "Exactly 1 of gclid, gbraid or wbraid is required, but %d ID values were " . "provided", count($nonNullFields) ) ); } // Creates a click conversion by specifying currency as USD. $clickConversion = new ClickConversion([ 'conversion_action' => ResourceNames::forConversionAction($customerId, $conversionActionId), 'conversion_value' => $conversionValue, 'conversion_date_time' => $conversionDateTime, 'currency_code' => 'USD' ]); // Sets the single specified ID field. if (!is_null($gclid)) { $clickConversion->setGclid($gclid); } elseif (!is_null($gbraid)) { $clickConversion->setGbraid($gbraid); } else { $clickConversion->setWbraid($wbraid); } if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) { $clickConversion->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. $clickConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent])); } if (!empty($orderId)) { // Sets the order ID (unique transaction ID), if provided. $clickConversion->setOrderId($orderId); } // Issues a request to upload the click conversion. $conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient(); /** @var UploadClickConversionsResponse $response */ // 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->uploadClickConversions( // Uploads the click conversion. Partial failure should always be set to true. UploadClickConversionsRequest::build($customerId, [$clickConversion], 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 ClickConversionResult $uploadedClickConversion */ $uploadedClickConversion = $response->getResults()[0]; printf( "Uploaded click conversion that occurred at '%s' from Google Click ID '%s' " . "to '%s'.%s", $uploadedClickConversion->getConversionDateTime(), $uploadedClickConversion->getGclid(), $uploadedClickConversion->getConversionAction(), PHP_EOL ); } }
Python
def main( client: GoogleAdsClient, customer_id: str, conversion_action_id: str, gclid: Optional[str], conversion_date_time: str, conversion_value: str, conversion_custom_variable_id: Optional[str], conversion_custom_variable_value: Optional[str], gbraid: Optional[str], wbraid: Optional[str], order_id: Optional[str], ad_user_data_consent: Optional[str], ) -> None: """Creates a click conversion with a default currency of USD. 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. gclid: The Google Click Identifier ID. If set, the wbraid and gbraid parameters must be None. 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. gbraid: The GBRAID for the iOS app conversion. If set, the gclid and wbraid parameters must be None. wbraid: The WBRAID for the iOS app conversion. If set, the gclid and gbraid parameters must be None. order_id: The order ID for the click conversion. ad_user_data_consent: The ad user data consent for the click. """ click_conversion: ClickConversion = client.get_type("ClickConversion") conversion_upload_service: ConversionUploadServiceClient = ( client.get_service("ConversionUploadService") ) conversion_action_service: ConversionActionServiceClient = ( client.get_service("ConversionActionService") ) click_conversion.conversion_action = ( conversion_action_service.conversion_action_path( customer_id, conversion_action_id ) ) # Sets the single specified ID field. if gclid: click_conversion.gclid = gclid elif gbraid: click_conversion.gbraid = gbraid else: click_conversion.wbraid = wbraid click_conversion.conversion_value = float(conversion_value) click_conversion.conversion_date_time = conversion_date_time click_conversion.currency_code = "USD" if conversion_custom_variable_id and conversion_custom_variable_value: conversion_custom_variable: CustomVariable = client.get_type( "CustomVariable" ) conversion_custom_variable.conversion_custom_variable = ( conversion_upload_service.conversion_custom_variable_path( customer_id, conversion_custom_variable_id ) ) conversion_custom_variable.value = conversion_custom_variable_value click_conversion.custom_variables.append(conversion_custom_variable) if order_id: click_conversion.order_id = order_id # Sets the consent information, if provided. if ad_user_data_consent: # 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 click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[ ad_user_data_consent ] # Uploads the click conversion. Partial failure must be set to True here. # # 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 request: UploadClickConversionsRequest = client.get_type( "UploadClickConversionsRequest" ) request.customer_id = customer_id request.conversions.append(click_conversion) request.partial_failure = True conversion_upload_response: UploadClickConversionsResponse = ( conversion_upload_service.upload_click_conversions( request=request, ) ) uploaded_click_conversion: ClickConversionResult = ( conversion_upload_response.results[0] ) print( f"Uploaded conversion that occurred at " f'"{uploaded_click_conversion.conversion_date_time}" from ' f'Google Click ID "{uploaded_click_conversion.gclid}" ' f'to "{uploaded_click_conversion.conversion_action}"' )
Ruby
def upload_offline_conversion( customer_id, conversion_action_id, gclid, gbraid, wbraid, 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 # Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required. # See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details. identifiers_specified = [gclid, gbraid, wbraid].reject {|v| v.nil?}.count if identifiers_specified != 1 raise "Must specify exactly one of GCLID, GBRAID, and WBRAID. " \ "#{identifiers_specified} values were provided." end click_conversion = client.resource.click_conversion do |cc| cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id) # Sets the single specified ID field. if !gclid.nil? cc.gclid = gclid elsif !gbraid.nil? cc.gbraid = gbraid else cc.wbraid = wbraid end cc.conversion_value = conversion_value.to_f cc.conversion_date_time = conversion_date_time cc.currency_code = 'USD' if conversion_custom_variable_id && conversion_custom_variable_value cc.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 # Sets the consent information, if provided. unless ad_user_data_consent.nil? cc.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 response = client.service.conversion_upload.upload_click_conversions( customer_id: customer_id, # 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 conversions: [click_conversion], partial_failure: true, ) if response.partial_failure_error.nil? result = response.results.first puts "Uploaded conversion that occurred at #{result.conversion_date_time} " \ "from Google Click ID #{result.gclid} to #{result.conversion_action}." else 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_offline_conversion { my ( $api_client, $customer_id, $conversion_action_id, $gclid, $gbraid, $wbraid, $conversion_date_time, $conversion_value, $conversion_custom_variable_id, $conversion_custom_variable_value, $order_id, $ad_user_data_consent ) = @_; # Verify that exactly one of gclid, gbraid, and wbraid is specified, as required. # See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details. my $number_of_ids_specified = grep { defined $_ } ($gclid, $gbraid, $wbraid); if ($number_of_ids_specified != 1) { die sprintf "Exactly 1 of gclid, gbraid, or wbraid is required, " . "but %d ID values were provided.\n", $number_of_ids_specified; } # Create a click conversion by specifying currency as USD. my $click_conversion = Google::Ads::GoogleAds::V25::Services::ConversionUploadService::ClickConversion ->new({ conversionAction => Google::Ads::GoogleAds::V25::Utils::ResourceNames::conversion_action( $customer_id, $conversion_action_id ), conversionDateTime => $conversion_date_time, conversionValue => $conversion_value, currencyCode => "USD" }); # Set the single specified ID field. if (defined $gclid) { $click_conversion->{gclid} = $gclid; } elsif (defined $gbraid) { $click_conversion->{gbraid} = $gbraid; } else { $click_conversion->{wbraid} = $wbraid; } if ($conversion_custom_variable_id && $conversion_custom_variable_value) { $click_conversion->{customVariables} = [ Google::Ads::GoogleAds::V25::Services::ConversionUploadService::CustomVariable ->new({ conversionCustomVariable => Google::Ads::GoogleAds::V25::Utils::ResourceNames::conversion_custom_variable( $customer_id, $conversion_custom_variable_id ), value => $conversion_custom_variable_value })]; } if (defined $order_id) { # Set the order ID (unique transaction ID), if provided. $click_conversion->{orderId} = $order_id; } # 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. $click_conversion->{consent} = Google::Ads::GoogleAds::V25::Common::Consent->new({ adUserData => $ad_user_data_consent }); } # Issue a request to upload the click conversion. Partial failure should # always be set to true. # # 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_click_conversions_response = $api_client->ConversionUploadService()->upload_click_conversions({ customerId => $customer_id, conversions => [$click_conversion], partialFailure => "true" }); # Print any partial errors returned. if ($upload_click_conversions_response->{partialFailureError}) { printf "Partial error encountered: '%s'.\n", $upload_click_conversions_response->{partialFailureError}{message}; } # Print the result if valid. my $uploaded_click_conversion = $upload_click_conversions_response->{results}[0]; if (%$uploaded_click_conversion) { printf "Uploaded conversion that occurred at '%s' from Google Click ID '%s' " . "to the conversion action with resource name '%s'.\n", $uploaded_click_conversion->{conversionDateTime}, $uploaded_click_conversion->{gclid}, $uploaded_click_conversion->{conversionAction}; } return 1; }
curl
# This code example uploads a click conversion. # # Variables: # API_VERSION, # CUSTOMER_ID, # DEVELOPER_TOKEN, # MANAGER_CUSTOMER_ID, # OAUTH2_ACCESS_TOKEN: # See https://developers.google.com/google-ads/api/rest/auth#request_headers # for details. # # CONVERSION_ACTION_RESOURCE_NAME: Resource name of the conversion action # associated with this conversion. # GCLID: The Google click ID (gclid) associated with this conversion. # CONVERSION_VALUE: The value of the conversion for the advertiser. # CONVERSION_DATE_TIME: The date time at which the conversion occurred. The # format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", for example, # "2019-01-01 12:32:45-08:00". # CURRENCY_CODE: The currency code of the conversion value. This is the # ISO 4217 3-character currency code. For example: USD, EUR. # CONVERSION_CUSTOM_VARIABLE: The name of the conversion custom variable. # CONVERSION_CUSTOM_VARIABLE_VALUE: The value of the conversion custom # variable. # ORDER_ID: The order ID of the conversion. curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}:uploadClickConversions" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "conversions": [ { "conversionAction": "${CONVERSION_ACTION_RESOURCE_NAME}", "gclid": "${GCLID}", "conversionValue": ${CONVERSION_VALUE}, "conversionDateTime": "${CONVERSION_DATE_TIME}", "currencyCode": "${CURRENCY_CODE}", "customVariables": [ { "conversionCustomVariable": "${CONVERSION_CUSTOM_VARIABLE}", "value": "${CONVERSION_CUSTOM_VARIABLE_VALUE}" } ], "orderId": "${ORDER_ID}", "consent": { "adUserData": "GRANTED" } } ], "partialFailure": true } EOF
Fehlerbehebung
Die Diagnose von Offline-Daten bietet eine
zentrale Ressource, mit der Sie den allgemeinen Status Ihrer Uploads fortlaufend überprüfen können. Während der Implementierung können Sie jedoch die Informationen in diesem
Abschnitt verwenden, um Fehler zu untersuchen, die im
partial_failure_error
Feld der Antwort gemeldet werden.
Zu den häufigsten Fehlern beim Hochladen von Conversion-Aktionen gehören Autorisierungsfehler wie USER_PERMISSION_DENIED. Prüfen Sie noch einmal, ob die Kunden-ID in Ihrer Anfrage auf den Google Ads-Conversion-Kunden festgelegt ist, der Inhaber der Conversion-Aktion ist. Weitere Informationen finden Sie in unserer
Anleitung zur Autorisierung und Tipps zur Behebung dieser verschiedenen Fehler in unserer
Anleitung zu häufigen Fehlern.
Häufige Fehler beheben
| Fehler | |
|---|---|
INVALID_CONVERSION_ACTION_TYPE
|
Die angegebene Conversion-Aktion hat einen
Typ
der für das Hochladen von Click-Conversions nicht gültig ist. Prüfen Sie, ob die ConversionAction
in Ihrer Upload-Anfrage angegebene den Typ UPLOAD_CLICKS hat.
|
NO_CONVERSION_ACTION_FOUND
|
Die angegebene Conversion-Aktion ist entweder nicht aktiviert oder kann
in der hochladenden customer_id nicht gefunden werden. Rufen Sie Informationen zu Ihrer Conversion-Einrichtung ab
um sicherzustellen, dass die Conversion-Aktion in Ihrem Upload aktiviert ist und der
customer_id der Upload-Anfrage gehört.
|
TOO_RECENT_CONVERSION_ACTION
|
Die Conversion-Aktion wurde neu erstellt. Warten Sie mindestens 6 Stunden nach dem Erstellen der Aktion, bevor Sie die fehlgeschlagenen Conversions noch einmal versuchen. |
INVALID_CUSTOMER_FOR_CLICK
|
Die customer_id der Anfrage ist nicht dieselbe Kunden-ID
die zum Zeitpunkt des Klicks das Google Ads API-Conversion-Konto
war. Aktualisieren Sie die customer_id von
der Anfrage auf den richtigen Kunden.
|
EVENT_NOT_FOUND
|
Google Ads kann die Kombination aus Click-ID und
customer_id nicht finden. Prüfen Sie die Anforderungen für customer_id und
bestätigen Sie, dass Sie den Upload mit dem richtigen Google Ads-Konto ausführen.
|
DUPLICATE_CLICK_CONVERSION_IN_REQUEST
|
Mehrere Conversions in der Anfrage haben dieselbe Kombination aus Click-ID, conversion_date_time
und conversion_action. Entfernen Sie doppelte Conversions aus Ihrer
Anfrage.
|
CLICK_CONVERSION_ALREADY_EXISTS
|
Eine Conversion mit derselben Kombination aus Click-ID,
conversion_date_time, und conversion_action wurde
bereits hochgeladen. Ignorieren Sie diesen Fehler, wenn Sie den Upload noch einmal versucht haben und diese
Conversion zuvor erfolgreich war. Wenn Sie zusätzlich zur zuvor hochgeladenen Conversion eine weitere Conversion hinzufügen möchten, passen Sie die conversion_date_time der ClickConversion an, um zu vermeiden, dass die zuvor hochgeladene Conversion dupliziert wird.
|
EVENT_NOT_FOUND
|
Google Ads kann die Kombination aus Click-ID und
customer_id nicht finden. Prüfen Sie die Anforderungen für customer_id und
bestätigen Sie, dass Sie den Upload mit dem richtigen Google Ads-Konto ausführen.
|
EXPIRED_EVENT
|
Der importierte Klick erfolgte vor dem im Feld
click_through_lookback_window_days angegebenen Zeitraum. Eine
Änderung an click_through_lookback_window_days wirkt sich nur auf Klicks
aus, die nach der Änderung erfasst wurden. Wenn Sie das Lookback-Window ändern, wird dieser Fehler für den jeweiligen Klick also nicht behoben. Ändern Sie gegebenenfalls die
conversion_action in eine andere Aktion mit einem längeren Lookback
window. |
CONVERSION_PRECEDES_EVENT
|
Die conversion_date_time liegt vor dem Datum und der Uhrzeit des
Klicks. Aktualisieren Sie conversion_date_time auf einen späteren Wert.
|
GBRAID_WBRAID_BOTH_SET
|
Für die ClickConversion ist ein Wert für sowohl
gbraid als auch wbraid festgelegt. Aktualisieren Sie die Conversion so, dass nur
eine Click-ID oder ein URL-Parameter verwendet wird, und prüfen Sie, ob Sie nicht mehrere Klicks in derselben Conversion kombinieren. Jeder Klick hat nur eine Click-ID
oder einen URL-Parameter.
|
VALUE_MUST_BE_UNSET
|
Prüfen Sie die location des
GoogleAdsError um zu ermitteln, welches der folgenden Probleme zu
dem Fehler geführt hat.
|
Conversions in Berichten
Hochgeladene Conversions werden in Berichten für das Datum der Impression des ursprünglichen Klicks angezeigt,
nicht für das Datum der Upload-Anfrage oder das Datum von conversion_date_time der ClickConversion.
Es kann bis zu 3 Stunden dauern, bis importierte Conversion-Statistiken in Ihrem Google Ads-Konto für die Attribution des letzten Klicks angezeigt werden. Bei anderen Suchattributionsmodellen kann es länger als 3 Stunden dauern. Weitere Informationen finden Sie in der Anleitung zur Datenaktualität.