Mit der Google Ads API können Sie Offline-Conversions in Google Ads importieren, um Anzeigen zu erfassen, die zu Offline-Verkäufen geführt haben, z. B. am Telefon oder über einen Vertriebsmitarbeiter.
Damit Sie die Vorteile des Imports von Conversion-Daten voll ausschöpfen können, empfehlen wir Ihnen, erweiterte Conversions für Leads zu implementieren. Dabei werden GCLIDs und von Nutzern bereitgestellte Daten verwendet, um Nachhaltigkeit und Leistung zu maximieren.
Erweiterte Conversions
Mit erweiterten Conversions lässt sich die Genauigkeit der Conversion-Analyse verbessern, indem Sie Ihre Conversions mit selbst erhobenen Conversion-Daten wie E-Mail-Adresse, Name, Privatadresse und Telefonnummer ergänzen.
Es gibt zwei Arten von erweiterten Conversions. Weitere Informationen finden Sie im Hilfeartikel Erweiterte Conversions.
Im folgenden Abschnitt wird erläutert, wie Sie Offline-Conversions optimieren können. Diese Funktion wird auch als erweiterte Conversions für Leads bezeichnet.
Was sind erweiterte Conversions für Leads?
Erweiterte Conversions für Leads sind eine optimierte Version des Imports von Offline-Conversions. Dabei werden von Nutzern bereitgestellte Daten wie E‑Mail-Adressen verwendet, um importierte Offline-Conversion-Daten zu ergänzen und so die Genauigkeit und Gebotsleistung zu verbessern. Wenn Sie Ihre Offline-Conversions importieren, werden die bereitgestellten gehashten Kundendaten verwendet, um die Conversion der Google Ads-Kampagne zuzuordnen. Dazu werden sie mit denselben Daten abgeglichen, die auf Ihrer Website erfasst wurden, z. B. über ein Lead-Formular, und mit angemeldeten Kunden, die mit Ihrer Anzeige interagiert haben. Weitere Informationen zu erweiterten Conversions für Leads
Es gibt zwei Möglichkeiten, erweiterte Conversions für Leads zu implementieren. Das hängt davon ab, ob Sie das Google-Tag verwenden, um Ereignisse für das Senden von Formularen auf Ihrer Webseite zu erfassen. Für optimale Leistung und Langlebigkeit empfehlen wir dringend, das Google-Tag für erweiterte Conversions für Leads zu verwenden.
- Wenn Sie ganz von vorn beginnen, lesen Sie zuerst den Abschnitt Voraussetzungen.
- Wenn Sie bereits den Import von Offline-Conversions eingerichtet haben und auf erweiterte Conversions für Leads umstellen möchten, empfehlen wir, mit dem Abschnitt Tagging konfigurieren zu beginnen.
- Wenn Sie das Google-Tag bereits eingerichtet haben oder nicht verwenden möchten und mit der Google Ads API-Integration beginnen, können Sie direkt zum Abschnitt API-Implementierung springen.
- Wenn Sie keine von Nutzern bereitgestellten Daten importieren können oder sich bei der Zuordnung Ihrer Conversions auf externe Quellen verlassen, lesen Sie den Leitfaden zum Import von Legacy-Offline-Conversions.
Vorbereitung
Prüfen Sie zuerst, ob Sie die Schritte im Abschnitt „Erste Schritte“ ausgeführt haben.
Sie müssen erweiterte Conversions für Leads aktivieren und die Nutzungsbedingungen für Kundendaten akzeptieren, bevor Sie erweiterte Conversions für Leads verwenden können. Sie können prüfen, ob diese Voraussetzungen bereits erfüllt sind, indem Sie die folgende Abfrage an den Google Ads-Kunden mit Conversion-Tracking senden:
SELECT
customer.id,
customer.conversion_tracking_setting.accepted_customer_data_terms,
customer.conversion_tracking_setting.enhanced_conversions_for_leads_enabled
FROM customer
Wenn accepted_customer_data_terms
oder enhanced_conversions_for_leads_enabled
false
ist, folgen Sie der Anleitung in der Hilfe, um diese Voraussetzungen zu erfüllen.
Tagging konfigurieren
Konfigurieren Sie das Google-Tag, um erweiterte Conversions für Leads zu aktivieren. Folgen Sie dazu der Anleitung in der Hilfe. Folgen Sie dieser Anleitung, um erweiterte Conversions für Leads mit Google Tag Manager einzurichten.
API-Implementierung
Hier sehen Sie den allgemeinen Ablauf für den Import erweiterter Conversions für Leads über die Google Ads API.
Von Nutzern bereitgestellte Daten normalisieren und hashen, z. B. E-Mail-Adresse, Telefonnummer und Postanschrift.
ClickConversion
-Objekte mit derConversionUploadService
in die Google Ads API importieren
Von Nutzern bereitgestellte Daten normalisieren und hashen
Aus Datenschutzgründen müssen die folgenden Daten vor dem Import mit SHA-256 gehasht werden:
- E-Mail-Adresse
- Telefonnummer
- Vorname
- Nachname
- Adresse
Um die Hash-Ergebnisse zu standardisieren, müssen Sie vor dem Hashen dieser Werte Folgendes tun:
- Entfernen Sie Leerzeichen am Anfang und Ende.
- Verwenden Sie nur Kleinbuchstaben im Text.
- Formatieren Sie Telefonnummern gemäß E164-Standard.
- Entfernen Sie alle Punkte (
.
) vor dem Domainnamen ingmail.com
- undgooglemail.com
-E-Mail-Adressen.
Die folgenden Daten sollten nicht gehasht werden:
- Land
- Bundesstaat
- Stadt
- Postleitzahl
Codebeispiel
In diesem Beispiel wird gezeigt, wie Sie von Nutzern bereitgestellte Daten normalisieren und hashen.
Java
private String normalizeAndHash(MessageDigest digest, String s) throws UnsupportedEncodingException { // Normalizes by first converting all characters to lowercase, then trimming spaces. String normalized = s.toLowerCase(); // Removes leading, trailing, and intermediate spaces. normalized = normalized.replaceAll("\\s+", ""); // Hashes the normalized string using the hashing algorithm. byte[] hash = digest.digest(normalized.getBytes("UTF-8")); StringBuilder result = new StringBuilder(); for (byte b : hash) { result.append(String.format("%02x", b)); } return result.toString(); } /** * Returns the result of normalizing and hashing an email address. For this use case, Google Ads * requires removal of any '.' characters preceding {@code gmail.com} or {@code googlemail.com}. * * @param digest the digest to use to hash the normalized string. * @param emailAddress the email address to normalize and hash. */ private String normalizeAndHashEmailAddress(MessageDigest digest, String emailAddress) throws UnsupportedEncodingException { String normalizedEmail = emailAddress.toLowerCase(); String[] emailParts = normalizedEmail.split("@"); if (emailParts.length > 1 && emailParts[1].matches("^(gmail|googlemail)\\.com\\s*")) { // Removes any '.' characters from the portion of the email address before the domain if the // domain is gmail.com or googlemail.com. emailParts[0] = emailParts[0].replaceAll("\\.", ""); normalizedEmail = String.format("%s@%s", emailParts[0], emailParts[1]); } return normalizeAndHash(digest, normalizedEmail); }
C#
/// <summary> /// Normalizes the email address and hashes it. For this use case, Google Ads requires /// removal of any '.' characters preceding <code>gmail.com</code> or /// <code>googlemail.com</code>. /// </summary> /// <param name="emailAddress">The email address.</param> /// <returns>The hash code.</returns> private string NormalizeAndHashEmailAddress(string emailAddress) { string normalizedEmail = emailAddress.ToLower(); string[] emailParts = normalizedEmail.Split('@'); if (emailParts.Length > 1 && (emailParts[1] == "gmail.com" || emailParts[1] == "googlemail.com")) { // Removes any '.' characters from the portion of the email address before // the domain if the domain is gmail.com or googlemail.com. emailParts[0] = emailParts[0].Replace(".", ""); normalizedEmail = $"{emailParts[0]}@{emailParts[1]}"; } return NormalizeAndHash(normalizedEmail); } /// <summary> /// Normalizes and hashes a string value. /// </summary> /// <param name="value">The value to normalize and hash.</param> /// <returns>The normalized and hashed value.</returns> private static string NormalizeAndHash(string value) { return ToSha256String(digest, ToNormalizedValue(value)); } /// <summary> /// Hash a string value using SHA-256 hashing algorithm. /// </summary> /// <param name="digest">Provides the algorithm for SHA-256.</param> /// <param name="value">The string value (e.g. an email address) to hash.</param> /// <returns>The hashed value.</returns> private static string ToSha256String(SHA256 digest, string value) { byte[] digestBytes = digest.ComputeHash(Encoding.UTF8.GetBytes(value)); // Convert the byte array into an unhyphenated hexadecimal string. return BitConverter.ToString(digestBytes).Replace("-", string.Empty); } /// <summary> /// Removes leading and trailing whitespace and converts all characters to /// lower case. /// </summary> /// <param name="value">The value to normalize.</param> /// <returns>The normalized value.</returns> private static string ToNormalizedValue(string value) { return value.Trim().ToLower(); }
PHP
private static function normalizeAndHash(string $hashAlgorithm, string $value): string { // Normalizes by first converting all characters to lowercase, then trimming spaces. $normalized = strtolower($value); // Removes leading, trailing, and intermediate spaces. $normalized = str_replace(' ', '', $normalized); return hash($hashAlgorithm, strtolower(trim($normalized))); } /** * Returns the result of normalizing and hashing an email address. For this use case, Google * Ads requires removal of any '.' characters preceding "gmail.com" or "googlemail.com". * * @param string $hashAlgorithm the hash algorithm to use * @param string $emailAddress the email address to normalize and hash * @return string the normalized and hashed email address */ private static function normalizeAndHashEmailAddress( string $hashAlgorithm, string $emailAddress ): string { $normalizedEmail = strtolower($emailAddress); $emailParts = explode("@", $normalizedEmail); if ( count($emailParts) > 1 && preg_match('/^(gmail|googlemail)\.com\s*/', $emailParts[1]) ) { // Removes any '.' characters from the portion of the email address before the domain // if the domain is gmail.com or googlemail.com. $emailParts[0] = str_replace(".", "", $emailParts[0]); $normalizedEmail = sprintf('%s@%s', $emailParts[0], $emailParts[1]); } return self::normalizeAndHash($hashAlgorithm, $normalizedEmail); }
Python
def normalize_and_hash_email_address(email_address): """Returns the result of normalizing and hashing an email address. For this use case, Google Ads requires removal of any '.' characters preceding "gmail.com" or "googlemail.com" Args: email_address: An email address to normalize. Returns: A normalized (lowercase, removed whitespace) and SHA-265 hashed string. """ normalized_email = email_address.strip().lower() email_parts = normalized_email.split("@") # Check that there are at least two segments if len(email_parts) > 1: # Checks whether the domain of the email address is either "gmail.com" # or "googlemail.com". If this regex does not match then this statement # will evaluate to None. if re.match(r"^(gmail|googlemail)\.com$", email_parts[1]): # Removes any '.' characters from the portion of the email address # before the domain if the domain is gmail.com or googlemail.com. email_parts[0] = email_parts[0].replace(".", "") normalized_email = "@".join(email_parts) return normalize_and_hash(normalized_email) def normalize_and_hash(s): """Normalizes and hashes a string with SHA-256. Private customer data must be hashed during upload, as described at: https://support.google.com/google-ads/answer/7474263 Args: s: The string to perform this operation on. Returns: A normalized (lowercase, removed whitespace) and SHA-256 hashed string. """ return hashlib.sha256(s.strip().lower().encode()).hexdigest()
Ruby
# Returns the result of normalizing and then hashing the string using the # provided digest. Private customer data must be hashed during upload, as # described at https://support.google.com/google-ads/answer/7474263. def normalize_and_hash(str) # Remove leading and trailing whitespace and ensure all letters are lowercase # before hashing. Digest::SHA256.hexdigest(str.strip.downcase) end # Returns the result of normalizing and hashing an email address. For this use # case, Google Ads requires removal of any '.' characters preceding 'gmail.com' # or 'googlemail.com'. def normalize_and_hash_email(email) email_parts = email.downcase.split("@") # Removes any '.' characters from the portion of the email address before the # domain if the domain is gmail.com or googlemail.com. if email_parts.last =~ /^(gmail|googlemail)\.com\s*/ email_parts[0] = email_parts[0].gsub('.', '') end normalize_and_hash(email_parts.join('@')) end
Perl
sub normalize_and_hash { my $value = shift; # Removes leading, trailing, and intermediate spaces. $value =~ s/\s+//g; return sha256_hex(lc $value); } # Returns the result of normalizing and hashing an email address. For this use # case, Google Ads requires removal of any '.' characters preceding 'gmail.com' # or 'googlemail.com'. sub normalize_and_hash_email_address { my $email_address = shift; my $normalized_email = lc $email_address; my @email_parts = split('@', $normalized_email); if (scalar @email_parts > 1 && $email_parts[1] =~ /^(gmail|googlemail)\.com\s*/) { # Remove any '.' characters from the portion of the email address before the # domain if the domain is 'gmail.com' or 'googlemail.com'. $email_parts[0] =~ s/\.//g; $normalized_email = sprintf '%s@%s', $email_parts[0], $email_parts[1]; } return normalize_and_hash($normalized_email); }
ClickConversion-Objekte erstellen
Die Sammlung von ClickConversion
-Objekten in Ihrem UploadClickConversionRequest
stellt die Menge der Conversions dar, die Sie importieren möchten. Beachten Sie beim Erstellen von ClickConversion
-Objekten Folgendes:
gclid
GCLIDs sind Klick-IDs, die aus URL-Parametern erfasst werden, wenn ein Nutzer auf Ihre Anzeige klickt und Ihre Website aufruft.
user_identifiers
Wenn Sie erweiterte Conversions für Leads verwenden, müssen Sie das Feld
user_identifiers
mit normalisierten und gehashten, von Nutzern bereitgestellten Daten füllen. Wenn Sie mehrere Nutzer-IDs haben, erstellen Sie für jede eine separateUserIdentifier
(bis zu fünf IDs).conversion_date_time
Das Datum und die Uhrzeit der Conversion.
Für den Wert muss eine Zeitzone angegeben werden. Das Format muss
yyyy-mm-dd HH:mm:ss+|-HH:mm
sein, z. B.2022-01-01 19:32:45-05:00
(ohne Berücksichtigung der Sommerzeit).Die Zeitzone kann einen beliebigen gültigen Wert haben. Sie muss nicht mit der Zeitzone des Kontos übereinstimmen. Wenn Sie Ihre importierten Conversion-Daten jedoch 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-Anzahl übereinstimmt. Weitere Informationen und Beispiele finden Sie in der Hilfe. Eine Liste der gültigen Zeitzonen-IDs finden Sie unter Codes und Formate.
conversion_action
Der Ressourcenname von
ConversionAction
für die Offline-Conversion.Die Conversion-Aktion muss den
type
-WertUPLOAD_CLICKS
haben und im Google Ads-Conversion-Kunden des Google Ads-Kontos vorhanden sein, das mit dem Klick verknüpft ist.conversion_value
Der Wert der Conversion.
currency_code
Der Währungscode der
conversion_value
.consent
Es wird dringend empfohlen, das Feld
consent
desClickConversion
-Objekts auszufüllen. Wenn Sie das nicht festlegen, können Ihre Conversions möglicherweise nicht zugeordnet werden.order_id
Auch als Transaktions-ID für die Conversion bezeichnet. Dieses Feld ist optional, wird aber dringend empfohlen, da es einfacher ist, auf importierte Conversions zu verweisen, wenn Sie Anpassungen vornehmen. Wenn Sie sie beim Import festgelegt haben, müssen Sie sie für alle Anpassungen verwenden. Weitere Informationen zum Minimieren doppelter Conversions durch Transaktions-IDs
custom_variables
Die Werte für benutzerdefinierte Conversion-Variablen.
In Google Ads werden benutzerdefinierte Conversion-Variablen in Kombination mit
wbraid
odergbraid
nicht unterstützt.conversion_environment
Gibt die Umgebung an, in der diese Conversion erfasst wurde. Beispiel:
APP
oderWEB
.session_attributes_encoded
undsession_attributes_key_value_pairs
Sitzungsattribute sind aggregierte Kennungen, die für die Conversion-Zuordnung verwendet werden. Sie funktionieren zusätzlich zu Klick-IDs (z. B. GCLIDs und GBRAIDs) und von Nutzern bereitgestellten Daten, die für erweiterte Conversions für Leads von zentraler Bedeutung sind. Es gibt zwei Möglichkeiten, Sitzungsattribute zu importieren: Sie können das codierte Token angeben, das von unserem JavaScript-Code im Browser generiert wird, oder einzelne Schlüssel/Wert-Paare für jede der Kennungen.
Wenn Sie die Leistung Ihrer Kampagne maximieren möchten, empfehlen wir, nach Möglichkeit Klick-IDs, von Nutzern bereitgestellte Daten und Sitzungsattribute mit allen Ihren Conversions zu importieren.
Java
// Sets one of the sessionAttributesEncoded or sessionAttributesKeyValuePairs if either is // provided. if (rawRecord.containsKey("sessionAttributesEncoded")) { clickConversionBuilder.setSessionAttributesEncoded( ByteString.copyFromUtf8(rawRecord.get("sessionAttributesEncoded"))); } else if (rawRecord.containsKey("sessionAttributesMap")) { List<String> pairings = Arrays.stream(rawRecord.get("sessionAttributesMap").split(" ")) .map(String::trim) .collect(Collectors.toList()); SessionAttributesKeyValuePairs.Builder sessionAttributePairs = SessionAttributesKeyValuePairs.newBuilder(); for (String pair : pairings) { String[] parts = pair.split("=", 2); if (parts.length != 2) { throw new IllegalArgumentException( "Failed to read the sessionAttributesMap. SessionAttributesMap must use a " + "space-delimited list of session attribute key value pairs. Each pair should be" + " separated by an equal sign, for example: 'gad_campaignid=12345 gad_source=1'"); } sessionAttributePairs.addKeyValuePairs( SessionAttributeKeyValuePair.newBuilder() .setSessionAttributeKey(parts[0]) .setSessionAttributeValue(parts[1]) .build()); } clickConversionBuilder.setSessionAttributesKeyValuePairs(sessionAttributePairs.build()); }
C#
if (!string.IsNullOrEmpty(sessionAttributesEncoded)) { clickConversion.SessionAttributesEncoded = ByteString.CopyFrom(sessionAttributesEncoded, Encoding.Unicode); } else if (!string.IsNullOrEmpty(sessionAttributes)) { IEnumerable<SessionAttributeKeyValuePair> parsedSessionAttributes = sessionAttributes.Split(';').Select(pair => { string[] split = pair.Split('='); return new SessionAttributeKeyValuePair() { SessionAttributeKey = split[0], SessionAttributeValue = split[1] }; }); clickConversion.SessionAttributesKeyValuePairs = new SessionAttributesKeyValuePairs(); clickConversion.SessionAttributesKeyValuePairs.KeyValuePairs .AddRange(parsedSessionAttributes); }
PHP
This example is not yet available in PHP; you can take a look at the other languages.
Python
# Set one of the session_attributes_encoded or # session_attributes_key_value_pairs fields if either are provided. if session_attributes_encoded: click_conversion.session_attributes_encoded = session_attributes_encoded elif session_attributes_dict: for key, value in session_attributes_dict.items(): pair = client.get_type("SessionAttributeKeyValuePair") pair.session_attribute_key = key pair.session_attribute_value = value click_conversion.session_attributes_key_value_pairs.key_value_pairs.append( pair )
Ruby
This example is not yet available in Ruby; you can take a look at the other languages.
Perl
# Set one of the session_attributes_encoded or session_attributes_key_value_pairs # fields if either are provided. if (defined $session_attributes_encoded) { $click_conversion->{sessionAttributesEncoded} = $session_attributes_encoded; } elsif (defined $session_attributes_hash) { while (my ($key, $value) = each %$session_attributes_hash) { my $pair = Google::Ads::GoogleAds::V20::Services::ConversionUploadService::SessionAttributeKeyValuePair ->new({sessionAttributeKey => $key, sessionAttributeValue => $value}); push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs} }, $pair; } }
user_ip_address
Die IP-Adresse des Kunden, als er nach einem Anzeigenklick und vor einem Conversion-Ereignis auf der Landingpage ankam. Das ist die IP-Adresse des Geräts des Kunden, nicht die des Servers des Werbetreibenden.
Dieses Feld ist ein String, der eine IP-Adresse im IPv4- oder IPv6-Format darstellt. Beispiel:
- IPv4:
"192.0.2.0"
- IPv6:
"2001:0DB8:1234:5678:9999:1111:0000:0001"
- IPv4:
Codebeispiel
In diesem Beispiel wird gezeigt, wie Sie Ihre normalisierten und gehashten von Nutzern bereitgestellten Daten in ein ClickConversion
-Objekt einfügen.
Java
// Creates an empty builder for constructing the click conversion. ClickConversion.Builder clickConversionBuilder = ClickConversion.newBuilder(); // Extracts user email and phone from the raw data, normalizes and hashes it, then wraps it in // UserIdentifier objects. // Creates a separate UserIdentifier object for each. The data in this example is hardcoded, but // in your application you might read the raw data from an input file. // IMPORTANT: Since the identifier attribute of UserIdentifier // (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a // oneof // (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE of // hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting more // than one of these attributes on the same UserIdentifier will clear all the other members // of the oneof. For example, the following code is INCORRECT and will result in a // UserIdentifier with ONLY a hashedPhoneNumber. // // UserIdentifier incorrectlyPopulatedUserIdentifier = // UserIdentifier.newBuilder() // .setHashedEmail("...") // .setHashedPhoneNumber("...") // .build(); ImmutableMap.Builder<String, String> rawRecordBuilder = ImmutableMap.<String, String>builder() .put("email", "alex.2@example.com") // Phone number to be converted to E.164 format, with a leading '+' as required. .put("phone", "+1 800 5550102") // This example lets you put conversion details as arguments, but in reality you might // store this data alongside other user data, so we include it in this sample user // record. .put("conversionActionId", Long.toString(conversionActionId)) .put("conversionDateTime", conversionDateTime) .put("conversionValue", Double.toString(conversionValue)) .put("currencyCode", "USD"); // Adds entries for the optional fields. if (orderId != null) { rawRecordBuilder.put("orderId", orderId); } if (gclid != null) { rawRecordBuilder.put("gclid", gclid); } if (adUserDataConsent != null) { rawRecordBuilder.put("adUserDataConsent", adUserDataConsent.name()); } if (sessionAttributesEncoded != null) { rawRecordBuilder.put("sessionAttributesEncoded", sessionAttributesEncoded); } if (sessionAttributesMap != null) { rawRecordBuilder.put("sessionAttributesMap", sessionAttributesMap); } // Builds the map representing the record. Map<String, String> rawRecord = rawRecordBuilder.build(); // Creates a SHA256 message digest for hashing user identifiers in a privacy-safe way, as // described at https://support.google.com/google-ads/answer/9888656. MessageDigest sha256Digest = MessageDigest.getInstance("SHA-256"); // Creates a list for the user identifiers. List<UserIdentifier> userIdentifiers = new ArrayList<>(); // Creates a user identifier using the hashed email address, using the normalize and hash method // specifically for email addresses. UserIdentifier emailIdentifier = UserIdentifier.newBuilder() // Optional: specify the user identifier source. .setUserIdentifierSource(UserIdentifierSource.FIRST_PARTY) // Uses the normalize and hash method specifically for email addresses. .setHashedEmail(normalizeAndHashEmailAddress(sha256Digest, rawRecord.get("email"))) .build(); userIdentifiers.add(emailIdentifier); // Creates a user identifier using normalized and hashed phone info. UserIdentifier hashedPhoneNumberIdentifier = UserIdentifier.newBuilder() .setHashedPhoneNumber(normalizeAndHash(sha256Digest, rawRecord.get("phone"))) .build(); // Adds the hashed phone number identifier to the UserData object's list. userIdentifiers.add(hashedPhoneNumberIdentifier); // Adds the user identifiers to the conversion. clickConversionBuilder.addAllUserIdentifiers(userIdentifiers);
C#
// Adds a user identifier using the hashed email address, using the normalize // and hash method specifically for email addresses. clickConversion.UserIdentifiers.Add(new UserIdentifier() { HashedEmail = NormalizeAndHashEmailAddress("alex.2@example.com"), // Optional: Specifies the user identifier source. UserIdentifierSource = UserIdentifierSource.FirstParty }); // Adds a user identifier using normalized and hashed phone info. clickConversion.UserIdentifiers.Add(new UserIdentifier() { HashedPhoneNumber = NormalizeAndHash("+1 800 5550102"), // Optional: Specifies the user identifier source. UserIdentifierSource = UserIdentifierSource.FirstParty }); // Adds a user identifier with all the required mailing address elements. clickConversion.UserIdentifiers.Add(new UserIdentifier() { AddressInfo = new OfflineUserAddressInfo() { // FirstName and LastName must be normalized and hashed. HashedFirstName = NormalizeAndHash("Alex"), HashedLastName = NormalizeAndHash("Quinn"), // CountryCode and PostalCode are sent in plain text. CountryCode = "US", PostalCode = "94045" } });
PHP
// Creates a click conversion with the specified attributes. $clickConversion = new ClickConversion(); // Extract user email and phone from the raw data, normalize and hash it, then wrap it in // UserIdentifier objects. Creates a separate UserIdentifier object for each. // The data in this example is hardcoded, but in your application you might read the raw // data from an input file. // IMPORTANT: Since the identifier attribute of UserIdentifier // (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a // oneof // (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE // of hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting // more than one of these attributes on the same UserIdentifier will clear all the other // members of the oneof. For example, the following code is INCORRECT and will result in a // UserIdentifier with ONLY a hashedPhoneNumber. // // $incorrectlyPopulatedUserIdentifier = new UserIdentifier([ // 'hashed_email' => '...', // 'hashed_phone_number' => '...' // ]); $rawRecord = [ // Email address that includes a period (.) before the Gmail domain. 'email' => 'alex.2@example.com', // Phone number to be converted to E.164 format, with a leading '+' as required. 'phone' => '+1 800 5550102', // This example lets you input conversion details as arguments, but in reality you might // store this data alongside other user data, so we include it in this sample user // record. 'orderId' => $orderId, 'gclid' => $gclid, 'conversionActionId' => $conversionActionId, 'conversionDateTime' => $conversionDateTime, 'conversionValue' => $conversionValue, 'currencyCode' => 'USD', 'adUserDataConsent' => $adUserDataConsent, 'sessionAttributesEncoded' => $sessionAttributesEncoded, 'sessionAttributesDict' => $sessionAttributesDict ]; // Creates a list for the user identifiers. $userIdentifiers = []; // Uses the SHA-256 hash algorithm for hashing user identifiers in a privacy-safe way, as // described at https://support.google.com/google-ads/answer/9888656. $hashAlgorithm = "sha256"; // Creates a user identifier using the hashed email address, using the normalize and hash // method specifically for email addresses. $emailIdentifier = new UserIdentifier([ // Uses the normalize and hash method specifically for email addresses. 'hashed_email' => self::normalizeAndHashEmailAddress( $hashAlgorithm, $rawRecord['email'] ), // Optional: Specifies the user identifier source. 'user_identifier_source' => UserIdentifierSource::FIRST_PARTY ]); $userIdentifiers[] = $emailIdentifier; // Checks if the record has a phone number, and if so, adds a UserIdentifier for it. if (array_key_exists('phone', $rawRecord)) { $hashedPhoneNumberIdentifier = new UserIdentifier([ 'hashed_phone_number' => self::normalizeAndHash( $hashAlgorithm, $rawRecord['phone'], true ) ]); // Adds the hashed email identifier to the user identifiers list. $userIdentifiers[] = $hashedPhoneNumberIdentifier; } // Adds the user identifiers to the conversion. $clickConversion->setUserIdentifiers($userIdentifiers);
Python
# Extract user email and phone from the raw data, normalize and hash it, # then wrap it in UserIdentifier objects. Create a separate UserIdentifier # object for each. The data in this example is hardcoded, but in your # application you might read the raw data from an input file. # IMPORTANT: Since the identifier attribute of UserIdentifier # (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) # is a oneof # (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must # set only ONE of hashed_email, hashed_phone_number, mobile_id, # third_party_user_id, or address_info. Setting more than one of these # attributes on the same UserIdentifier will clear all the other members of # the oneof. For example, the following code is INCORRECT and will result in # a UserIdentifier with ONLY a hashed_phone_number: # # incorrectly_populated_user_identifier = client.get_type("UserIdentifier") # incorrectly_populated_user_identifier.hashed_email = "..."" # incorrectly_populated_user_identifier.hashed_phone_number = "..."" raw_record = { # Email address that includes a period (.) before the Gmail domain. "email": "alex.2@example.com", # Phone number to be converted to E.164 format, with a leading '+' as # required. "phone": "+1 800 5550102", # This example lets you input conversion details as arguments, # but in reality you might store this data alongside other user data, # so we include it in this sample user record. "order_id": order_id, "gclid": gclid, "conversion_action_id": conversion_action_id, "conversion_date_time": conversion_date_time, "conversion_value": conversion_value, "currency_code": "USD", "ad_user_data_consent": ad_user_data_consent, } # Constructs the click conversion. click_conversion = client.get_type("ClickConversion") # Creates a user identifier using the hashed email address, using the # normalize and hash method specifically for email addresses. email_identifier = client.get_type("UserIdentifier") # Optional: Specifies the user identifier source. email_identifier.user_identifier_source = ( client.enums.UserIdentifierSourceEnum.FIRST_PARTY ) # Uses the normalize and hash method specifically for email addresses. email_identifier.hashed_email = normalize_and_hash_email_address( raw_record["email"] ) # Adds the user identifier to the conversion. click_conversion.user_identifiers.append(email_identifier) # Checks if the record has a phone number, and if so, adds a UserIdentifier # for it. if raw_record.get("phone") is not None: phone_identifier = client.get_type("UserIdentifier") phone_identifier.hashed_phone_number = normalize_and_hash( raw_record["phone"] ) # Adds the phone identifier to the conversion adjustment. click_conversion.user_identifiers.append(phone_identifier)
Ruby
# Extract user email and phone from the raw data, normalize and hash it, # then wrap it in UserIdentifier objects. Create a separate UserIdentifier # object for each. The data in this example is hardcoded, but in your # application you might read the raw data from an input file. # IMPORTANT: Since the identifier attribute of UserIdentifier # (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) # is a oneof # (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must # set only ONE of hashed_email, hashed_phone_number, mobile_id, # third_party_user_id, or address_info. Setting more than one of these # attributes on the same UserIdentifier will clear all the other members of # the oneof. For example, the following code is INCORRECT and will result in # a UserIdentifier with ONLY a hashed_phone_number: # # incorrectly_populated_user_identifier.hashed_email = "..."" # incorrectly_populated_user_identifier.hashed_phone_number = "..."" raw_record = { # Email address that includes a period (.) before the Gmail domain. "email" => "alex.2@example.com", # Phone number to be converted to E.164 format, with a leading '+' as # required. "phone" => "+1 800 5550102", # This example lets you input conversion details as arguments, # but in reality you might store this data alongside other user data, # so we include it in this sample user record. "order_id" => order_id, "gclid" => gclid, "conversion_action_id" => conversion_action_id, "conversion_date_time" => conversion_date_time, "conversion_value" => conversion_value, "currency_code" => "USD", "ad_user_data_consent" => ad_user_data_consent, "session_attributes_encoded" => session_attributes_encoded, "session_attributes_hash" => session_attributes_hash } click_conversion = client.resource.click_conversion do |cc| cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id) cc.conversion_date_time = conversion_date_time cc.conversion_value = conversion_value.to_f cc.currency_code = 'USD' unless order_id.nil? cc.order_id = order_id end unless raw_record["gclid"].nil? cc.gclid = gclid end # 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 unless raw_record["ad_user_data_consent"].nil? cc.consent = client.resource.consent do |c| c.ad_user_data = ad_user_data_consent end end # Set one of the session_attributes_encoded or # session_attributes_key_value_pairs fields if either are provided. if session_attributes_encoded != nil cc.class.module_eval { attr_accessor :session_attributes_encoded} cc.session_attributes_encoded = session_attributes_encoded elsif session_attributes_hash != nil # Add new attribute to click conversion object cc.class.module_eval { attr_accessor :session_attributes_key_value_pairs} cc.session_attributes_key_value_pairs = ::Google::Ads::GoogleAds::V19::Services::SessionAttributesKeyValuePairs.new # Loop thru inputted session_attributes_hash to populate session_attributes_key_value_pairs session_attributes_hash.each do |key, value| pair = ::Google::Ads::GoogleAds::V19::Services::SessionAttributeKeyValuePair.new pair.session_attribute_key = key pair.session_attribute_value = value cc.session_attributes_key_value_pairs.key_value_pairs << pair end end # Creates a user identifier using the hashed email address, using the # normalize and hash method specifically for email addresses. # If using a phone number, use the normalize_and_hash method instead. cc.user_identifiers << client.resource.user_identifier do |ui| ui.hashed_email = normalize_and_hash_email(raw_record["email"]) # Optional: Specifies the user identifier source. ui.user_identifier_source = :FIRST_PARTY end # Checks if the record has a phone number, and if so, adds a UserIdentifier # for it. unless raw_record["phone"].nil? cc.user_identifiers << client.resource.user_identifier do |ui| ui.hashed_phone_number = normalize_and_hash(raw_record["phone"]) end end end
Perl
# Create an empty click conversion. my $click_conversion = Google::Ads::GoogleAds::V20::Services::ConversionUploadService::ClickConversion ->new({}); # Extract user email and phone from the raw data, normalize and hash it, # then wrap it in UserIdentifier objects. Create a separate UserIdentifier # object for each. # The data in this example is hardcoded, but in your application # you might read the raw data from an input file. # # IMPORTANT: Since the identifier attribute of UserIdentifier # (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) # is a oneof # (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set # only ONE of hashed_email, hashed_phone_number, mobile_id, third_party_user_id, # or address-info. Setting more than one of these attributes on the same UserIdentifier # will clear all the other members of the oneof. For example, the following code is # INCORRECT and will result in a UserIdentifier with ONLY a hashed_phone_number: # # my $incorrect_user_identifier = Google::Ads::GoogleAds::V20::Common::UserIdentifier->new({ # hashedEmail => '...', # hashedPhoneNumber => '...', # }); my $raw_record = { # Email address that includes a period (.) before the Gmail domain. email => 'alex.2@example.com', # Phone number to be converted to E.164 format, with a leading '+' as # required. phone => '+1 800 5550102', # This example lets you input conversion details as arguments, # but in reality you might store this data alongside other user data, # so we include it in this sample user record. orderId => $order_id, gclid => $gclid, conversionActionId => $conversion_action_id, conversionDateTime => $conversion_date_time, conversionValue => $conversion_value, currencyCode => "USD", adUserDataConsent => $ad_user_data_consent }; my $user_identifiers = []; # Create a user identifier using the hashed email address, using the normalize # and hash method specifically for email addresses. my $hashed_email = normalize_and_hash_email_address($raw_record->{email}); push( @$user_identifiers, Google::Ads::GoogleAds::V20::Common::UserIdentifier->new({ hashedEmail => $hashed_email, # Optional: Specify the user identifier source. userIdentifierSource => FIRST_PARTY })); # Create a user identifier using normalized and hashed phone info. my $hashed_phone = normalize_and_hash($raw_record->{phone}); push( @$user_identifiers, Google::Ads::GoogleAds::V20::Common::UserIdentifier->new({ hashedPhone => $hashed_phone, # Optional: Specify the user identifier source. userIdentifierSource => FIRST_PARTY })); # Add the user identifiers to the conversion. $click_conversion->{userIdentifiers} = $user_identifiers;
In diesem Beispiel wird gezeigt, wie andere erforderliche Felder für ein ClickConversion
-Objekt festgelegt werden.
Java
// Adds details of the conversion. clickConversionBuilder.setConversionAction( ResourceNames.conversionAction( customerId, Long.parseLong(rawRecord.get("conversionActionId")))); clickConversionBuilder.setConversionDateTime(rawRecord.get("conversionDateTime")); clickConversionBuilder.setConversionValue(Double.parseDouble(rawRecord.get("conversionValue"))); clickConversionBuilder.setCurrencyCode(rawRecord.get("currencyCode")); // Sets the order ID if provided. if (rawRecord.containsKey("orderId")) { clickConversionBuilder.setOrderId(rawRecord.get("orderId")); } // Sets the Google click ID (gclid) if provided. if (rawRecord.containsKey("gclid")) { clickConversionBuilder.setGclid(rawRecord.get("gclid")); } // Sets the consent information, if provided. if (rawRecord.containsKey("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. clickConversionBuilder.setConsent( Consent.newBuilder() .setAdUserData(ConsentStatus.valueOf(rawRecord.get("adUserDataConsent")))); } // Sets one of the sessionAttributesEncoded or sessionAttributesKeyValuePairs if either is // provided. if (rawRecord.containsKey("sessionAttributesEncoded")) { clickConversionBuilder.setSessionAttributesEncoded( ByteString.copyFromUtf8(rawRecord.get("sessionAttributesEncoded"))); } else if (rawRecord.containsKey("sessionAttributesMap")) { List<String> pairings = Arrays.stream(rawRecord.get("sessionAttributesMap").split(" ")) .map(String::trim) .collect(Collectors.toList()); SessionAttributesKeyValuePairs.Builder sessionAttributePairs = SessionAttributesKeyValuePairs.newBuilder(); for (String pair : pairings) { String[] parts = pair.split("=", 2); if (parts.length != 2) { throw new IllegalArgumentException( "Failed to read the sessionAttributesMap. SessionAttributesMap must use a " + "space-delimited list of session attribute key value pairs. Each pair should be" + " separated by an equal sign, for example: 'gad_campaignid=12345 gad_source=1'"); } sessionAttributePairs.addKeyValuePairs( SessionAttributeKeyValuePair.newBuilder() .setSessionAttributeKey(parts[0]) .setSessionAttributeValue(parts[1]) .build()); } clickConversionBuilder.setSessionAttributesKeyValuePairs(sessionAttributePairs.build()); } // Calls build to build the conversion. ClickConversion clickConversion = clickConversionBuilder.build();
C#
// Adds details of the conversion. clickConversion.ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId); clickConversion.ConversionDateTime = conversionDateTime; clickConversion.ConversionValue = conversionValue; clickConversion.CurrencyCode = "USD"; // Sets the order ID if provided. if (!string.IsNullOrEmpty(orderId)) { clickConversion.OrderId = orderId; } // Sets the Google click ID (gclid) if provided. if (!string.IsNullOrEmpty(gclid)) { clickConversion.Gclid = gclid; } if (!string.IsNullOrEmpty(sessionAttributesEncoded)) { clickConversion.SessionAttributesEncoded = ByteString.CopyFrom(sessionAttributesEncoded, Encoding.Unicode); } else if (!string.IsNullOrEmpty(sessionAttributes)) { IEnumerable<SessionAttributeKeyValuePair> parsedSessionAttributes = sessionAttributes.Split(';').Select(pair => { string[] split = pair.Split('='); return new SessionAttributeKeyValuePair() { SessionAttributeKey = split[0], SessionAttributeValue = split[1] }; }); clickConversion.SessionAttributesKeyValuePairs = new SessionAttributesKeyValuePairs(); clickConversion.SessionAttributesKeyValuePairs.KeyValuePairs .AddRange(parsedSessionAttributes); }
PHP
// Adds details of the conversion. $clickConversion->setConversionAction( ResourceNames::forConversionAction($customerId, $rawRecord['conversionActionId']) ); $clickConversion->setConversionDateTime($rawRecord['conversionDateTime']); $clickConversion->setConversionValue($rawRecord['conversionValue']); $clickConversion->setCurrencyCode($rawRecord['currencyCode']); // Sets the order ID if provided. if (!empty($rawRecord['orderId'])) { $clickConversion->setOrderId($rawRecord['orderId']); } // Sets the Google click ID (gclid) if provided. if (!empty($rawRecord['gclid'])) { $clickConversion->setGclid($rawRecord['gclid']); } // Sets the ad user data consent if provided. if (!empty($rawRecord['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' => $rawRecord['adUserDataConsent']]) ); } // Set one of the sessionAttributesEncoded or // SessionAttributeKeyValuePair fields if either are provided. if (!empty($sessionAttributesEncoded)) { $clickConversion->setSessionAttributesEncoded($sessionAttributesEncoded); } elseif (!empty($sessionAttributesDict)) { // Create a new container object to hold key-value pairs. $sessionAttributesKeyValuePairs = new SessionAttributesKeyValuePairs(); // Initialize an array to hold individual key-value pair messages. $keyValuePairs = []; // Append each key-value pair provided to the $keyValuePairs array foreach ($sessionAttributesDict as $key => $value) { $pair = new SessionAttributeKeyValuePair(); $pair->setSessionAttributeKey($key); $pair->setSessionAttributeValue($value); $keyValuePairs[] = $pair; } // Set the the full list of key-value pairs on the container object. $sessionAttributesKeyValuePairs->setKeyValuePairs($keyValuePairs); // Attach the container of key-value pairs to the ClickConversion object. $clickConversion->setSessionAttributesKeyValuePairs($sessionAttributesKeyValuePairs); }
Python
# Add details of the conversion. # Gets the conversion action resource name. conversion_action_service = client.get_service("ConversionActionService") click_conversion.conversion_action = ( conversion_action_service.conversion_action_path( customer_id, raw_record["conversion_action_id"] ) ) click_conversion.conversion_date_time = raw_record["conversion_date_time"] click_conversion.conversion_value = raw_record["conversion_value"] click_conversion.currency_code = raw_record["currency_code"] # Sets the order ID if provided. if raw_record.get("order_id"): click_conversion.order_id = raw_record["order_id"] # Sets the gclid if provided. if raw_record.get("gclid"): click_conversion.gclid = raw_record["gclid"] # 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 raw_record["ad_user_data_consent"]: click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[ raw_record["ad_user_data_consent"] ] # Set one of the session_attributes_encoded or # session_attributes_key_value_pairs fields if either are provided. if session_attributes_encoded: click_conversion.session_attributes_encoded = session_attributes_encoded elif session_attributes_dict: for key, value in session_attributes_dict.items(): pair = client.get_type("SessionAttributeKeyValuePair") pair.session_attribute_key = key pair.session_attribute_value = value click_conversion.session_attributes_key_value_pairs.key_value_pairs.append( pair )
Ruby
cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id) cc.conversion_date_time = conversion_date_time cc.conversion_value = conversion_value.to_f cc.currency_code = 'USD' unless order_id.nil? cc.order_id = order_id end unless raw_record["gclid"].nil? cc.gclid = gclid end # 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 unless raw_record["ad_user_data_consent"].nil? cc.consent = client.resource.consent do |c| c.ad_user_data = ad_user_data_consent end end # Set one of the session_attributes_encoded or # session_attributes_key_value_pairs fields if either are provided. if session_attributes_encoded != nil cc.class.module_eval { attr_accessor :session_attributes_encoded} cc.session_attributes_encoded = session_attributes_encoded elsif session_attributes_hash != nil # Add new attribute to click conversion object cc.class.module_eval { attr_accessor :session_attributes_key_value_pairs} cc.session_attributes_key_value_pairs = ::Google::Ads::GoogleAds::V19::Services::SessionAttributesKeyValuePairs.new # Loop thru inputted session_attributes_hash to populate session_attributes_key_value_pairs session_attributes_hash.each do |key, value| pair = ::Google::Ads::GoogleAds::V19::Services::SessionAttributeKeyValuePair.new pair.session_attribute_key = key pair.session_attribute_value = value cc.session_attributes_key_value_pairs.key_value_pairs << pair end end
Perl
# Add details of the conversion. $click_conversion->{conversionAction} = Google::Ads::GoogleAds::V20::Utils::ResourceNames::conversion_action( $customer_id, $raw_record->{conversionActionId}); $click_conversion->{conversionDateTime} = $raw_record->{conversionDateTime}; $click_conversion->{conversionValue} = $raw_record->{conversionValue}; $click_conversion->{currencyCode} = $raw_record->{currencyCode}; # Set the order ID if provided. if (defined $raw_record->{orderId}) { $click_conversion->{orderId} = $raw_record->{orderId}; } # Set the Google click ID (gclid) if provided. if (defined $raw_record->{gclid}) { $click_conversion->{gclid} = $raw_record->{gclid}; } # Set the consent information, if provided. if (defined $raw_record->{adUserDataConsent}) { $click_conversion->{consent} = Google::Ads::GoogleAds::V20::Common::Consent->new({ adUserData => $raw_record->{adUserDataConsent}}); } # Set one of the session_attributes_encoded or session_attributes_key_value_pairs # fields if either are provided. if (defined $session_attributes_encoded) { $click_conversion->{sessionAttributesEncoded} = $session_attributes_encoded; } elsif (defined $session_attributes_hash) { while (my ($key, $value) = each %$session_attributes_hash) { my $pair = Google::Ads::GoogleAds::V20::Services::ConversionUploadService::SessionAttributeKeyValuePair ->new({sessionAttributeKey => $key, sessionAttributeValue => $value}); push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs} }, $pair; } }
Erstellen Sie die Anfrage
Sobald Ihre ClickConversion
-Objekte konfiguriert und dem Feld conversions
des UploadClickConversionRequest
-Objekts hinzugefügt wurden, legen Sie die folgenden Felder fest und übergeben Sie die Anfrage an die UploadClickConversions
-Methode für ConversionUploadService
.
customer_id
- Legen Sie diesen Wert auf den Google Ads-Conversion-Kunden des Kontos fest, aus dem die Klicks stammen. Wenn Sie sich nicht sicher sind, welches Konto das richtige ist, sehen Sie sich das Feld
customer.conversion_tracking_setting.google_ads_conversion_customer
in der Beispielanfrage im Abschnitt Erste Schritte an. job_id
Bietet einen Mechanismus zum Zuordnen Ihrer Importanfragen zu den Informationen pro Job in der Diagnose von Offlinedaten.
Wenn Sie dieses Feld nicht festlegen, weist die Google Ads API jeder Anfrage einen eindeutigen Wert im Bereich von
[2^31, 2^63)
zu. Wenn Sie mehrere Anfragen in einem einzigen logischen Job gruppieren möchten, legen Sie dieses Feld in jeder Anfrage in Ihrem Job auf denselben Wert im Bereich[0, 2^31)
fest.Die
job_id
in 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
Dieses Feld muss beim Importieren von Conversions auf
true
gesetzt werden. Befolgen Sie beim Verarbeiten der Antwort die Richtlinien für Teilausfälle.
Anfrage importieren
Nachdem Sie Ihre ClickConversion
-Objekte mit Daten gefüllt und Ihre Anfrage erstellt haben, können Sie den Import senden.
Java
// 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());
C#
// 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 UploadClickConversionsResponse response = conversionUploadService.UploadClickConversions( new UploadClickConversionsRequest() { CustomerId = customerId.ToString(), Conversions = { clickConversion }, // Enables partial failure (must be true). PartialFailure = true });
PHP
// Issues a request to upload the click 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->uploadClickConversions( // Enables partial failure (must be true). UploadClickConversionsRequest::build($customerId, [$clickConversion], true) );
Python
# Creates the conversion upload service client. conversion_upload_service = client.get_service("ConversionUploadService") # Uploads the click conversion. Partial failure should always be set to # 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 response = conversion_upload_service.upload_click_conversions( customer_id=customer_id, conversions=[click_conversion], # Enables partial failure (must be true). partial_failure=True, )
Ruby
response = client.service.conversion_upload.upload_click_conversions( customer_id: customer_id, conversions: [click_conversion], # Partial failure must be true. partial_failure: true, ) if response.partial_failure_error puts "Partial failure encountered: #{response.partial_failure_error.message}" else result = response.results.first puts "Uploaded click conversion that happened at #{result.conversion_date_time} " \ "to #{result.conversion_action}." end
Perl
# 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 $response = $api_client->ConversionUploadService()->upload_click_conversions({ customerId => $customer_id, conversions => [$click_conversion], # Enable partial failure (must be true). partialFailure => "true" });
Importe überprüfen
Im Diagnosebericht zu erweiterten Conversions für Leads können Sie den allgemeinen Status Ihrer letzten Importe einsehen.
Importierte Conversions werden in Berichten für das Impressionsdatum desursprünglichen Klicksconversion_date_time
und nicht für das Datum der Importanfrage oder das Datum des ClickConversion
erfasst.
Es kann bis zu drei Stunden dauern, bis Statistiken zu importierten Conversions in Ihrem Google Ads-Konto für die Attribution des letzten Klicks angezeigt werden. Bei anderen Attributionsmodellen für die Suche kann es länger als drei Stunden dauern. Weitere Informationen finden Sie im Leitfaden zur Datenaktualität.
Wenn Sie Berichte zu Conversion-Messwerten für Ihre Kampagnen erstellen, können Sie die Messwerte der Google Ads-Benutzeroberfläche mit den Berichtsfeldern der Google Ads API korrelieren. Weitere Informationen finden Sie unter Messwerte der Benutzeroberfläche zuordnen. Sie können auch die conversion_action
-Ressource abfragen, um die Gesamtzahl der Conversions und den Conversion-Gesamtwert für eine bestimmte Conversion-Aktion aufzurufen.
Best Practices
Beachten Sie die folgenden Best Practices, wenn Sie erweiterte Conversions für Leads implementieren.
Alle Conversion-Daten senden, unabhängig von der Vollständigkeit
Damit Sie vollständige und korrekte Conversion-Berichte erhalten, sollten Sie alle verfügbaren Offline-Conversion-Ereignisse importieren – auch solche, die nicht aus Google Ads stammen. Conversions, die nur von Nutzern bereitgestellte Daten enthalten, sind weiterhin nützlich und können positiv zur Optimierung von Google Ads-Kampagnen beitragen.
Wenn Sie einer Conversion eine order_id
zuweisen, empfehlen wir, sie anzugeben.
Wenn Sie die GCLID für eine Conversion haben, empfehlen wir, sie zusätzlich zur user_identifiers
zu senden, um die Leistung zu verbessern. Wenn Sie mehr als ein UserIdentifier
für die Conversion haben, geben Sie alle im ClickConversion
-Objekt an, um die Wahrscheinlichkeit eines Abgleichs zu erhöhen.
Mehrere Conversions in einer einzelnen Anfrage zusammenfassen
Wenn Sie mehrere Conversions importieren möchten, fassen Sie sie in einer UploadClickConversionsRequest
zusammen, anstatt für jede Conversion eine Importanfrage zu senden.
In der Kontingentübersicht finden Sie Informationen zu den Limits für die Anzahl der Conversions pro Anfrage.
Wenn Sie möchten, dass bei der Offlinedaten-Diagnose eine Reihe von Anfragen unter demselben logischen Job gruppiert werden, legen Sie den job_id
aller Anfragen auf denselben Wert fest. Das kann nützlich sein, wenn Sie einen einzelnen Job oder Prozess haben, mit dem eine große Anzahl von Conversions über mehrere Anfragen importiert wird. Wenn Sie job_id
für jede dieser Anfragen auf denselben Wert setzen, können Sie einen einzelnen Eintrag für den Job aus job_summaries
abrufen.
Wenn Sie stattdessen die Google Ads API einen systemgenerierten Wert für die job_id
jeder Anfrage zuweisen lassen, enthält die job_summaries
einen separaten Eintrag für jede Anfrage. Das kann die Analyse des Gesamtzustands Ihres Jobs erschweren.
Keine externen Attributionsdaten verwenden
Wenn Sie erweiterte Conversions für Leads verwenden, legen Sie external_attribution_data
nicht für ClickConversion
fest und geben Sie keine conversion_action
an, für die ein externes Attributionsmodell verwendet wird. Extern zugeordnete Conversions werden in Google Ads nicht für Importe mit von Nutzern bereitgestellten Daten unterstützt.
Keine benutzerdefinierten Variablen einbeziehen
Wenn Sie erweiterte Conversions für Leads verwenden, dürfen Sie keine custom_variables
einfügen.
In Google Ads wird die Verwendung benutzerdefinierter Variablen mit von Nutzern bereitgestellten Daten beim Importieren von Conversions nicht unterstützt. Wenn benutzerdefinierte Variablen in Conversions mit von Nutzern bereitgestellten Daten enthalten sind, gelten diese Conversions als ungültig und werden verworfen.
Fehlerbehebung
Die Diagnose von Offlinedaten bietet eine zentrale Ressource, mit der Sie den allgemeinen Status Ihrer Importe 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 Feld partial_failure_error
der Antwort gemeldet werden.
Zu den häufigsten Fehlern beim Importieren 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, dem die Conversion-Aktion gehört. Weitere Informationen finden Sie in unserem Leitfaden zur Autorisierung. Tipps zur Fehlerbehebung bei diesen verschiedenen Fehlern finden Sie in unserem Leitfaden zu häufigen Fehlern.
Häufige Fehler beheben
Fehler | |
---|---|
NO_CONVERSION_ACTION_FOUND
|
Die angegebene Conversion-Aktion ist entweder nicht aktiviert oder kann nicht über das Kundenkonto aufgerufen werden, das im Feld „client_id“ der Anfrage angegeben ist. Die Conversion-Aktion in Ihrem Upload muss aktiviert sein und dem Kunden gehören, der die Uploadanfrage sendet. Dieser Fehler kann auch auftreten, wenn der GCLID-Wert in der Anfrage zu einem Kundenkonto gehört, das keinen Zugriff auf die in der Anfrage angegebene Conversion-Aktion hat. Sie können prüfen, ob eine GCLID zu einem Kundenkonto gehört, indem Sie die Ressource |
INVALID_CONVERSION_ACTION_TYPE
|
Die angegebene Conversion-Aktion hat einen Typ, der für erweiterte Conversions für Leads nicht gültig ist. Achten Sie darauf, dass die in Ihrer Uploadanfrage angegebene ConversionAction den Typ UPLOAD_CLICKS hat.
|
CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS
|
Achten Sie darauf, dass Sie in den Conversion-Einstellungen erweiterte Conversions für Leads aktiviert haben. Eine Anleitung dazu finden Sie im Leitfaden zu Voraussetzungen. |
DUPLICATE_ORDER_ID
|
Die importierten Ereignisse umfassen mehrere Conversions mit derselben Bestell-ID und wurden nicht verarbeitet. Vergewissern Sie sich, dass die Bestell-IDs eindeutig sind, und versuchen Sie es noch einmal. |
CLICK_NOT_FOUND
|
Es wurde kein Klick gefunden, der mit den angegebenen Nutzer-IDs übereinstimmt. Die Google Ads API gibt diesen Fehler nur zurück, wenn debug_enabled für UploadClickConversionsRequest auf true festgelegt ist.
Wenn bei einer Conversion diese Warnung angezeigt wird, wird sie in der Google Ads API in die Dieser Fehler wird erwartet, wenn der Klick nicht aus einer Google Ads-Kampagne stammt. Sie kann beispielsweise aus SA360 oder DV360 stammen. Weitere mögliche Ursachen:
In seltenen Fällen, in denen sich der Kunde, der die Daten hochlädt, vom Google Ads-Conversion-Kunden unterscheidet, kann dieser Fehler bedeuten, dass der Kunde, der die Daten hochlädt, die Nutzungsbedingungen für Kundendaten akzeptiert hat, der Kunde, der die Daten verwendet, jedoch nicht. Ob ein Konto die Nutzungsbedingungen für Kundendaten akzeptiert hat, können Sie ermitteln, indem Sie die Ressourcecustomer abfragen und das Feld customer.offline_conversion_tracking_info.accepted_customer_data_terms prüfen.
|