Czy chcesz podzielić się opinią na temat interfejsu Google Ads API? Zarejestruj się, aby otrzymać zaproszenie do udziału w badaniach opinii użytkowników.

Ta strona została przetłumaczona przez Cloud Translation API.

Zarządzanie konwersjami offline
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Za pomocą interfejsu Google Ads API możesz importować do Google Ads konwersje offline, aby śledzić reklamy, które doprowadziły do sprzedaży offline, np. przez telefon lub przedstawiciela handlowego.

Aby w pełni korzystać z zalet importowania danych o konwersjach, zalecamy stosowanie konwersji rozszerzonych dotyczących potencjalnych klientów, które wykorzystują identyfikatory kliknięć Google i dane przekazywane przez użytkowników w celu maksymalizacji trwałości i skuteczności.

Konwersje rozszerzone

Konwersje rozszerzone pomagają zwiększać dokładność pomiaru konwersji, uzupełniając je o własne dane o konwersjach, takie jak adres e-mail, imię i nazwisko, adres pocztowy i numer telefonu.

Istnieją 2 typy konwersji rozszerzonych. Więcej informacji znajdziesz w artykule Konwersje rozszerzone w Centrum pomocy.

Z następnej sekcji dowiesz się, jak ulepszać konwersje offline, czyli funkcję nazywaną też konwersjami rozszerzonymi dotyczącymi potencjalnych klientów.

Czym są konwersje rozszerzone dotyczące potencjalnych klientów?

Konwersje rozszerzone dotyczące potencjalnych klientów to ulepszona wersja importowania konwersji offline, która wykorzystuje dane przekazywane przez użytkowników, np. adresy e-mail, do uzupełniania importowanych danych o konwersjach offline. Pozwala to zwiększyć dokładność i skuteczność określania stawek. Gdy importujesz konwersje offline, podane zaszyfrowane dane o klientach są używane do przypisywania udziału w konwersjach do kampanii Google Ads przez dopasowywanie do tych samych danych zebranych w Twojej witrynie, np. do formularza kontaktowego, oraz do zalogowanych klientów, którzy wchodzili w interakcję z Twoją reklamą. Więcej informacji o tym, jak działają konwersje rozszerzone dotyczące potencjalnych klientów, znajdziesz w artykule Konwersje rozszerzone dotyczące potencjalnych klientów.

Konwersje rozszerzone dotyczące potencjalnych klientów można wdrożyć na 2 sposoby, w zależności od tego, czy do śledzenia zdarzeń przesłania formularza na stronie internetowej używasz tagu Google. Aby zapewnić najlepszą wydajność i trwałość, zdecydowanie zalecamy korzystanie z tagu Google do konwersji rozszerzonych dotyczących potencjalnych klientów.

Jeśli zaczynasz od zera, zacznij od sekcji Wymagania wstępne.
Jeśli masz już skonfigurowane importowanie konwersji offline i chcesz przejść na konwersje rozszerzone dotyczące potencjalnych klientów, zacznij od sekcji Konfigurowanie tagowania.
Jeśli masz już skonfigurowany tag Google lub nie zamierzasz go używać i zaczynasz pracę nad integracją z interfejsem Google Ads API, przejdź do sekcji Wdrażanie interfejsu API.
Jeśli nie możesz importować danych przekazywanych przez użytkowników lub używasz zewnętrznego źródła atrybucji konwersji, zapoznaj się z starym przewodnikiem po importowaniu konwersji offline.

Wymagania wstępne

Najpierw wykonaj czynności opisane w sekcji „Rozpoczynanie pracy”.

Aby używać konwersji rozszerzonych dotyczących potencjalnych klientów, musisz je włączyć i zaakceptować warunki dotyczące danych klienta. Aby sprawdzić, czy te wymagania wstępne są już spełnione, wyślij do klienta konwersji Google Ads to zapytanie:

SELECT
  customer.id,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enhanced_conversions_for_leads_enabled
FROM customer

Jeśli accepted_customer_data_terms lub enhanced_conversions_for_leads_enabled to false, postępuj zgodnie z instrukcjami w Centrum pomocy, aby spełnić te wymagania wstępne.

Konfigurowanie tagowania

Skonfiguruj tag Google, aby umożliwić konwersje rozszerzone dotyczące potencjalnych klientów. Aby to zrobić, postępuj zgodnie z instrukcjami podanymi w Centrum pomocy. Aby skonfigurować konwersje rozszerzone dotyczące potencjalnych klientów za pomocą Menedżera tagów Google, wykonaj te instrukcje.

Implementacja interfejsu API

Oto ogólny proces importowania konwersji rozszerzonych dotyczących potencjalnych klientów za pomocą interfejsu Google Ads API.

Normalizuj i zahaszuj dane przekazywane przez użytkowników, takie jak adres e-mail, numer telefonu i adres pocztowy.
Wypełnij obiekty ClickConversion znormalizowanymi i zaszyfrowanymi danymi przekazywanymi przez użytkowników.
Zaimportuj obiekty ClickConversion do interfejsu Google Ads API za pomocą interfejsu ConversionUploadService.
Sprawdź zaimportowane dane.

Znormalizowane i zaszyfrowane dane przekazywane przez użytkowników

Ze względu na ochronę prywatności przed importem należy zaszyfrować te dane za pomocą algorytmu SHA-256:

Adres e-mail
Numer telefonu
Imię
Nazwisko
Adres pocztowy

Aby ustandaryzować wyniki szyfrowania, przed zaszyfrowaniem tych wartości wykonaj te czynności:

usuń spacje na początku i na końcu ciągu,
zmień pisownię tekstu na małe litery,
Sformatuj numery telefonów zgodnie ze standardem E.164.
usunąć wszystkie kropki (.) poprzedzające nazwę domeny w adresach e-mail w gmail.com i googlemail.com.

Nie szyfruj tych danych:

Kraj
Region
Miasto
Kod pocztowy

Przykładowy kod

Ten przykład pokazuje, jak znormalizować i zaszyfrować dane przekazywane przez użytkowników.

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);
}UploadEnhancedConversionsForLeads.java

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();
}UploadEnhancedConversionsForLeads.cs

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);
}UploadEnhancedConversionsForLeads.php

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()upload_enhanced_conversions_for_leads.py

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('@'))
endupload_enhanced_conversions_for_leads.rb

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);
}upload_enhanced_conversions_for_leads.pl

Wypełnianie obiektów ClickConversion

Kolekcja obiektów ClickConversion w Twoim UploadClickConversionRequest reprezentuje zestaw konwersji, które chcesz zaimportować. Podczas tworzenia obiektów ClickConversion należy pamiętać o tych kwestiach:

gclid

Identyfikatory GCLID to identyfikatory kliknięć rejestrowane na podstawie parametrów adresu URL, gdy użytkownik klika Twoją reklamę i przechodzi do witryny.

user_identifiers

Jeśli korzystasz z konwersji rozszerzonych dotyczących potencjalnych klientów, musisz wypełnić pole user_identifiers znormalizowanymi i zaszyfrowanymi danymi przekazywanymi przez użytkowników. Jeśli masz dostępnych kilka identyfikatorów użytkowników, utwórz dla każdego z nich osobne UserIdentifier. Możesz użyć maksymalnie 5 identyfikatorów.

conversion_date_time

Data i godzina konwersji.

Wartość musi zawierać określoną strefę czasową i mieć format yyyy-mm-dd HH:mm:ss+|-HH:mm, na przykład: 2022-01-01 19:32:45-05:00 (ignorowanie czasu letniego).

Strefa czasowa może mieć dowolną prawidłową wartość: nie musi pasować do strefy czasowej konta. Jeśli jednak planujesz porównywać zaimportowane dane o konwersjach z danymi w interfejsie Google Ads, zalecamy użycie tego samego czasu strefy, co na koncie Google Ads, aby liczby konwersji były takie same. Więcej informacji i przykładów znajdziesz w Centrum pomocy. Aby poznać listę prawidłowych identyfikatorów stref czasowych, zapoznaj się z artykułem Kodów i formatów.

conversion_action

Nazwa zasobu ConversionAction dla konwersji offline.

Działanie powodujące konwersję musi mieć wartość type UPLOAD_CLICKS i występować w koncie klienta konwersji Google Ads powiązanym z kliknięciem.

conversion_value

Wartość konwersji.

currency_code

Kod waluty conversion_value.

consent

Zdecydowanie zalecamy wypełnienie pola consent obiektu ClickConversion. Jeśli nie ustawisz tej opcji, może się zdarzyć, że konwersje nie będą przypisywane.

order_id

Nazywany też identyfikatorem transakcji konwersji. To pole jest opcjonalne, ale zdecydowanie zalecane, ponieważ ułatwia odwoływanie się do zaimportowanych konwersji podczas wprowadzania korekt. Jeśli ustawisz go podczas importowania, musisz go używać do wprowadzania zmian. Aby dowiedzieć się więcej o używaniu identyfikatora transakcji do ograniczania liczby zduplikowanych konwersji, przeczytaj ten artykuł w Centrum pomocy.

custom_variables

wartości zmiennych niestandardowych konwersji.

Google Ads nie obsługuje niestandardowych zmiennych konwersji w połączeniu z kolumnami wbraid ani gbraid.

conversion_environment

Wskazuje środowisko, w którym została zarejestrowana ta konwersja. Na przykład APP lub WEB.

session_attributes_encoded i session_attributes_key_value_pairs

Atrybuty sesji to zbiorcze identyfikatory używane do atrybucji konwersji. Funkcja ta działa oprócz identyfikatorów kliknięć (np. GCLID i GBRAID) oraz danych przekazywanych przez użytkowników, które są kluczowe dla konwersji rozszerzonych dotyczących potencjalnych klientów. Atrybuty sesji możesz importować na 2 sposoby: podając zakodowany token wygenerowany przez nasz kod JavaScript w przeglądarce lub podając pary klucz-wartość dla każdego z identyfikatorów.

Aby zmaksymalizować skuteczność kampanii, zalecamy importowanie identyfikatorów kliknięć, danych dostarczonych przez użytkowników i atrybutów sesji ze wszystkimi konwersjami (o ile to możliwe).

Java

This example is not yet available in Java; you can take a look at the other languages.

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);
}UploadEnhancedConversionsForLeads.cs

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
        )upload_enhanced_conversions_for_leads.py

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::V19::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}upload_enhanced_conversions_for_leads.pl

Przykładowy kod

Ten przykład pokazuje, jak ustawić znormalizowane i zaszyfrowane dane przekazywane przez użytkowników w obiekcie ClickConversion.

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);UploadEnhancedConversionsForLeads.java

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"
    }
});UploadEnhancedConversionsForLeads.cs

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
];

// 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);UploadEnhancedConversionsForLeads.php

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)upload_enhanced_conversions_for_leads.py

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
endupload_enhanced_conversions_for_leads.rb

Perl

# Create an empty click conversion.
my $click_conversion =
  Google::Ads::GoogleAds::V19::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::V19::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::V19::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::V19::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;upload_enhanced_conversions_for_leads.pl

Ten przykład pokazuje, jak ustawić inne niezbędne pola w obiekcie ClickConversion.

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();UploadEnhancedConversionsForLeads.java

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);
}
UploadEnhancedConversionsForLeads.cs

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']])
    );
}UploadEnhancedConversionsForLeads.php

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
        )upload_enhanced_conversions_for_leads.py

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    upload_enhanced_conversions_for_leads.rb

Perl

# Add details of the conversion.
$click_conversion->{conversionAction} =
  Google::Ads::GoogleAds::V19::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::V19::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::V19::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}upload_enhanced_conversions_for_leads.pl

Tworzenie żądania

Gdy obiekty ClickConversion zostaną skonfigurowane i dodane do pola conversions obiektu UploadClickConversionRequest, ustaw te pola i przekaż żądanie do metody UploadClickConversions obiektu ConversionUploadService.

customer_id

Ustaw to jako klienta konwersji Google Ads na koncie, które jest źródłem kliknięć. Jeśli nie masz pewności, które konto jest właściwe, sprawdź pole customer.conversion_tracking_setting.google_ads_conversion_customer w przykładowym zapytaniu w sekcji Pierwsze kroki .

job_id

Udostępnia mechanizm umożliwiający powiązanie żądań importu z informacjami dotyczącymi poszczególnych zadań w diagnostyce danych offline.

Jeśli nie ustawisz tego pola, interfejs Google Ads API przypisze każdej prośbie unikalną wartość z zakresu [2^31, 2^63). Jeśli wolisz pogrupować wiele żądań w jedną logiczną pracę, ustaw to pole na tę samą wartość w zakresie [0, 2^31) w przypadku każdego żądania w Twojej pracy.

Wartość job_id w odpowiedzi zawiera identyfikator zadania dla żądania, niezależnie od tego, czy została podana przez Ciebie wartość, czy też interfejs Google Ads API przypisał wartość.

partial_failure

Podczas importowania konwersji to pole musi mieć wartość true. Podczas przetwarzania odpowiedzi postępuj zgodnie z wytycznymi dotyczącymi częściowych błędów.

Importowanie żądania

Po wypełnieniu obiektów ClickConversion i utworzeniu żądania możesz przesłać dane.

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());UploadEnhancedConversionsForLeads.java

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
        });
UploadEnhancedConversionsForLeads.cs

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)
);UploadEnhancedConversionsForLeads.php

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,
)upload_enhanced_conversions_for_leads.py

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}."
endupload_enhanced_conversions_for_leads.rb

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"
  });upload_enhanced_conversions_for_leads.pl

Sprawdzanie importowanych danych

Aby sprawdzić ogólny stan ostatnich importów, użyj raportu z diagnostyki konwersji rozszerzonych dotyczących potencjalnych klientów.

Zaimportowane konwersje są uwzględniane w raportach dotyczących daty wyświetlenia pierwotnego kliknięcia, a nie daty conversion_date_time w ClickConversion.

Zanim statystyki zaimportowanych konwersji pojawią się na koncie Google Ads w ramach atrybucji ostatniego kliknięcia, może minąć do 3 godzin. W przypadku innych modeli atrybucji w wyszukiwarce może to zająć więcej niż 3 godziny. Więcej informacji znajdziesz w przewodniku na temat częstotliwości aktualizacji danych.

Aby tworzyć raporty z danymi o konwersjach w kampaniach, zapoznaj się z artykułem Mapowanie danych interfejsu użytkownika, aby powiązać dane interfejsu Google Ads z polami raportowania interfejsu Google Ads API. Możesz też wysłać zapytanie do zasobu conversion_action, aby wyświetlić łączną liczbę konwersji i łączną wartość konwersji dla danego działania powodującego konwersję.

Sprawdzone metody

Podczas wdrażania konwersji rozszerzonych dotyczących potencjalnych klientów pamiętaj o tych sprawdzonych metodach.

Wysyłanie wszystkich danych o konwersjach bez względu na ich kompletność

Aby mieć pełne i dokładne raporty o konwersjach, importuj wszystkie dostępne zdarzenia konwersji offline, w tym niepochodzące z Google Ads. Konwersje, które obejmują tylko dane przekazywane przez użytkowników, są nadal przydatne i mogą pozytywnie wpływać na optymalizację kampanii Google Ads.

Jeśli chcesz przypisać do konwersji tag order_id, zalecamy jego uwzględnienie. Jeśli masz identyfikator GCLID konwersji, zalecamy jego wysłanie oprócz parametru user_identifiers, aby zwiększyć skuteczność. Jeśli masz więcej niż 1 wartość UserIdentifier dla konwersji, uwzględnij je wszystkie w obiekcie ClickConversion, aby zwiększyć prawdopodobieństwo dopasowania.

Przetwarzanie wielu konwersji w ramach jednego żądania

Jeśli chcesz zaimportować kilka konwersji, zgrupuj je w jedną UploadClickConversionsRequest, zamiast wysyłać prośbę o importowanie pojedynczych konwersji.

Informacje o limitach liczby konwersji na żądanie znajdziesz w przewodniku dotyczącym limitów.

Jeśli chcesz, aby diagnostyka danych offline grupowała zestaw żądań w ramach tego samego zadania logicznego, ustaw job_id wszystkich żądań na tę samą wartość. Może to być przydatne, jeśli masz pojedyncze zadanie lub proces, który importuje dużą liczbę konwersji za pomocą wielu żądań. Jeśli dla wszystkich tych żądań ustawisz tę samą wartość parametru job_id, możesz pobrać z job_summaries pojedynczy wpis dotyczący zadania. Jeśli zamiast tego pozwolisz interfejsowi Google Ads API przypisać wygenerowaną przez system wartość do job_id każdego żądania, job_summaries będzie zawierać osobny wpis dla każdego żądania, co może utrudnić analizowanie ogólnego stanu zadania.

Nie używaj zewnętrznych danych atrybucji

Jeśli używasz konwersji rozszerzonych dotyczących potencjalnych klientów, nie ustawiaj parametru external_attribution_data w kampanii ClickConversion ani nie podawaj parametru conversion_action, który używa zewnętrznego modelu atrybucji. Google Ads nie obsługuje konwersji przypisanych zewnętrznie w przypadku importów danych przekazywanych przez użytkowników.

Rozwiązywanie problemów

Diagnostyka danych offline to jedno miejsce, w którym możesz sprawdzać ogólny stan importowanych danych. Podczas implementacji możesz jednak skorzystać z informacji w tej sekcji, aby zbadać błędy zgłoszone w polu partial_failure_error odpowiedzi.

Najczęstsze błędy podczas importowania działań powodujących konwersję to błędy autoryzacji, np. USER_PERMISSION_DENIED. Sprawdź, czy identyfikator klienta w żądaniu jest ustawiony na klienta konwersji Google Ads, który jest właścicielem działania powodującego konwersję. Więcej informacji znajdziesz w przewodniku dotyczącym autoryzacji, a w przewodniku dotyczącym typowych błędów znajdziesz wskazówki dotyczące ich debugowania.

Debugowanie typowych błędów

Błąd
`NO_CONVERSION_ACTION_FOUND`	Wskazane działanie powodujące konwersję jest albo nieaktywne, albo nie jest dostępne na koncie klienta wskazanym w polu „client_id” w żądaniu. Upewnij się, że działanie powodujące konwersję w przesyłanym pliku jest włączone i należy do klienta, który wysyła prośbę o przesyłanie. Ten błąd może też wystąpić, jeśli identyfikator GCLID w prośbie należy do konta klienta, które nie ma dostępu do działania powodującego konwersję określonego w prośbie. Aby sprawdzić, czy identyfikator GCLID należy do konta klienta, użyj zasobu `click_view`. Aby to zrobić, prześlij zapytanie z filtrem `click_view.gclid` i `segments.date`, gdzie data to data kliknięcia.
`INVALID_CONVERSION_ACTION_TYPE`	Wskazane działanie powodujące konwersję ma typ, który nie jest prawidłowy w przypadku konwersji rozszerzonych dotyczących potencjalnych klientów. Upewnij się, że `ConversionAction` określony w żądaniu przesyłania ma typ `UPLOAD_CLICKS`.
`CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS`	Upewnij się, że w ustawieniach konwersji masz włączone konwersje rozszerzone dotyczące potencjalnych klientów. Instrukcje znajdziesz w przewodniku dotyczącym wymagań wstępnych.
`DUPLICATE_ORDER_ID`	Nie udało się przetworzyć zaimportowanych zdarzeń, ponieważ zawierają one wiele konwersji z tym samym identyfikatorem zamówienia. Upewnij się, że identyfikatory zamówień są unikalne, i spróbuj ponownie.
`CLICK_NOT_FOUND`	Nie znaleziono kliknięcia pasującego do podanych identyfikatorów użytkownika. Interfejs Google Ads API zwraca ten błąd tylko wtedy, gdy `debug_enabled` jest `true` w `UploadClickConversionsRequest`. Uwaga: traktuj ten błąd jako ostrzeżenie, chyba że występuje w przypadku większości konwersji. Jeśli konwersja napotyka to ostrzeżenie, interfejs Google Ads API uwzględnia je w `successful_event_count` diagnostyki danych offline. Interfejs Google Ads API zawiera wpis `CLICK_NOT_FOUND` w zbiorze `alerts`, dzięki czemu możesz sprawdzać częstotliwość występowania tego ostrzeżenia. Ten błąd występuje, gdy kliknięcie nie pochodzi z kampanii Google Ads. Może ona na przykład pochodzić z SA360 lub DV360. Inne możliwe przyczyny: Klient przesyłający dane różni się od klienta z konwersjami Google Ads. Tagowanie nie jest prawidłowo skonfigurowane w przypadku formularza kontaktowego. Przesłane dane nie zostały prawidłowo znormalizowane i zahaszowane. W rzadkich przypadkach, gdy klient przesyłający dane różni się od klienta konwersji Google Ads, ten błąd może oznaczać, że klient przesyłający zaakceptował warunki dotyczące danych klienta, ale klient wyświetlający – nie. Aby sprawdzić, czy konto zaakceptowało warunki dotyczące danych klienta, przeprowadź zapytanie o zasób `customer` i sprawdź pole `customer.offline_conversion_tracking_info.accepted_customer_data_terms`.

Wstecz

Pierwsze kroki

Dalej

Zarządzanie konwersjami online

Zarządzanie konwersjami offline Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Konwersje rozszerzone

Czym są konwersje rozszerzone dotyczące potencjalnych klientów?

Wymagania wstępne

Konfigurowanie tagowania

Implementacja interfejsu API

Znormalizowane i zaszyfrowane dane przekazywane przez użytkowników

Przykładowy kod

Java

C#

PHP

Python

Ruby

Perl

Wypełnianie obiektów ClickConversion

Java

C#

PHP

Python

Ruby

Perl

Przykładowy kod

Java

C#

PHP

Python

Ruby

Perl

Java

C#

PHP

Python

Ruby

Perl

Tworzenie żądania

Importowanie żądania

Java

C#

PHP

Python

Ruby

Perl

Sprawdzanie importowanych danych

Sprawdzone metody

Wysyłanie wszystkich danych o konwersjach bez względu na ich kompletność

Przetwarzanie wielu konwersji w ramach jednego żądania

Nie używaj zewnętrznych danych atrybucji

Rozwiązywanie problemów

Debugowanie typowych błędów

Zarządzanie konwersjami offline
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.