Vous souhaitez nous faire part de vos commentaires sur l'API Google Ads ? Inscrivez-vous pour être invité à participer à des recherches sur l'expérience utilisateur.

Cette page a été traduite par l'API Cloud Translation.

Gérer les conversions hors connexion
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Vous pouvez utiliser l'API Google Ads pour importer des conversions hors connexion dans Google Ads afin de suivre les annonces qui ont généré des ventes hors connexion, par exemple par téléphone ou via un représentant commercial.

Pour profiter pleinement des avantages de l'importation de données de conversion, nous vous recommandons d'implémenter le suivi avancé des conversions pour les prospects, qui utilise les GCLID et les données fournies par l'utilisateur pour maximiser la durabilité et les performances.

Suivi avancé des conversions

Le suivi avancé des conversions vous aide à mesurer plus précisément vos conversions en complétant vos conversions avec des données de conversion first party, comme l'adresse e-mail, le nom, l'adresse de domicile et le numéro de téléphone.

Il existe deux types de suivi avancé des conversions. Pour en savoir plus, consultez l'article du Centre d'aide À propos du suivi avancé des conversions.

La section suivante explique comment améliorer les conversions hors connexion, une fonctionnalité également appelée suivi avancé des conversions pour les prospects.

Qu'est-ce que le suivi avancé des conversions pour les prospects ?

Le suivi avancé des conversions pour les prospects est une version améliorée de l'importation des conversions hors connexion. Il utilise des données fournies par l'utilisateur (les adresses e-mail, par exemple) pour compléter les données de conversion hors connexion. Vous pouvez ainsi améliorer la précision de vos mesures et optimiser les performances de vos enchères. Lorsque vous importez vos conversions hors connexion, les données client hachées fournies servent à réattribuer les conversions aux campagnes Google Ads en les faisant correspondre aux mêmes données collectées sur votre site Web (les formulaires pour prospects, par exemple) et aux clients connectés ayant interagi avec votre annonce. Pour en savoir plus sur le fonctionnement du suivi avancé des conversions pour les prospects, consultez notre article À propos du suivi avancé des conversions pour les prospects.

Il existe deux façons d'implémenter le suivi avancé des conversions pour les prospects, selon que vous utilisez la balise Google pour suivre les événements d'envoi de formulaires sur votre page Web. Pour de meilleures performances et une meilleure durabilité, nous vous recommandons vivement d'utiliser la balise Google pour le suivi avancé des conversions pour les prospects.

Si vous partez de zéro, commencez par la section Conditions préalables.
Si vous avez déjà configuré l'importation des conversions hors connexion et que vous souhaitez passer au suivi avancé des conversions pour les prospects, nous vous recommandons de commencer par la section Configurer le taggage.
Si vous avez déjà configuré la balise Google ou que vous ne prévoyez pas de l'utiliser, et que vous commencez à travailler sur l'intégration de l'API Google Ads, passez directement à la section Implémentation de l'API.
Si vous ne parvenez pas à importer les données fournies par l'utilisateur ou si vous vous appuyez sur une attribution externe pour vos conversions, consultez le guide des anciennes importations de conversions hors connexion.

Prérequis

Tout d'abord, assurez-vous d'avoir suivi les étapes de la section "Premiers pas".

Vous devez activer le suivi avancé des conversions pour les prospects et accepter les conditions d'utilisation des données client avant de pouvoir l'utiliser. Pour vérifier si ces conditions préalables sont déjà remplies, envoyez la requête suivante au client de conversion Google Ads:

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

Si l'un des éléments accepted_customer_data_terms ou enhanced_conversions_for_leads_enabled est false, suivez les instructions du Centre d'aide pour remplir ces conditions préalables.

Configurer le taggage

Configurez la balise Google pour activer le suivi avancé des conversions pour les prospects en suivant les instructions du Centre d'aide. Pour configurer le suivi avancé des conversions pour les prospects avec Google Tag Manager, suivez ces instructions.

Implémentation de l'API

Voici la procédure globale d'importation du suivi avancé des conversions pour les prospects à l'aide de l'API Google Ads.

Normalisez et hachez les données fournies par l'utilisateur, telles que l'adresse e-mail, le numéro de téléphone et l'adresse postale.
Réalisez le remplissage des objets ClickConversion avec les données fournies par l'utilisateur, normalisées et hachées.
Importez des objets ClickConversion dans l'API Google Ads à l'aide de ConversionUploadService.
Vérifiez vos importations.

Normaliser et hacher les données fournies par l'utilisateur

Pour des raisons de confidentialité, les données suivantes doivent être hachées à l'aide de SHA-256 avant d'être importées:

Adresse e-mail
Numéro de téléphone
Prénom
Nom
Adresse postale

Afin de standardiser les résultats du hachage, procédez comme suit avant de hacher ces valeurs:

Supprimez les espaces blancs de début et de fin.
Convertissez le texte en minuscules.
Mettez en forme les numéros de téléphone conformément à la norme E164.
supprimer tous les points (.) qui précèdent le nom de domaine des adresses e-mail gmail.com et googlemail.com.

Ne hachez pas les données suivantes:

Pays
État
Ville
Code postal

Exemple de code

Cet exemple montre comment normaliser et hacher les données fournies par l'utilisateur.

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

Renseigner les objets ClickConversion

La collection d'objets ClickConversion de votre UploadClickConversionRequest représente l'ensemble de conversions que vous souhaitez importer. Tenez compte des points suivants lorsque vous créez des objets ClickConversion:

gclid

Les GCLID sont des identifiants de clic capturés à partir des paramètres d'URL lorsqu'un utilisateur clique sur votre annonce et accède à votre site Web.

user_identifiers

Lorsque vous utilisez le suivi avancé des conversions pour les prospects, vous devez renseigner le champ user_identifiers avec des données fournies par l'utilisateur normalisées et hachées. Si vous disposez de plusieurs identifiants utilisateur, créez un UserIdentifier distinct pour chacun d'eux, jusqu'à cinq identifiants.

conversion_date_time

Date et heure de la conversion.

Un fuseau horaire doit être spécifié pour la valeur, et le format doit être yyyy-mm-dd HH:mm:ss+|-HH:mm, par exemple: 2022-01-01 19:32:45-05:00 (ignore l'heure d'été).

Le fuseau horaire peut être une valeur valide quelconque. Il ne doit pas correspondre au fuseau horaire du compte. Toutefois, si vous prévoyez de comparer vos données de conversion importées à celles de l'interface utilisateur Google Ads, nous vous recommandons d'utiliser le même fuseau horaire que celui de votre compte Google Ads afin que le nombre de conversions corresponde. Pour en savoir plus et obtenir des exemples, consultez le Centre d'aide. Vous trouverez la liste des ID de fuseau horaire valides dans la section Codes et formats.

conversion_action

Nom de ressource de l'ConversionAction pour la conversion hors connexion.

L'action de conversion doit avoir une valeur type de UPLOAD_CLICKS et doit figurer dans le client de conversion Google Ads du compte Google Ads associé au clic.

conversion_value

Valeur de la conversion.

currency_code

Code de devise de l'conversion_value.

consent

Il est fortement recommandé de renseigner le champ consent de l'objet ClickConversion. Si ce n'est pas le cas, il est possible que vos conversions ne soient pas attribuables.

order_id

Aussi appelé ID de transaction de la conversion. Ce champ est facultatif, mais vivement recommandé, car il permet de faire référence plus facilement aux conversions importées lorsque vous effectuez des ajustements. Si vous le définissez lors de l'importation, vous devez l'utiliser pour tous les ajustements. Pour en savoir plus sur l'utilisation d'un ID de transaction afin d'éviter de comptabiliser des conversions en double, consultez cet article du Centre d'aide.

custom_variables

Valeurs des variables de conversion personnalisées.

Google Ads n'est pas compatible avec les variables de conversion personnalisées associées à wbraid ou gbraid.

conversion_environment

Indique l'environnement dans lequel cette conversion a été enregistrée. Par exemple, APP ou WEB.

session_attributes_encoded et session_attributes_key_value_pairs

Les attributs de session représentent des identifiants agrégés utilisés pour l'attribution des conversions. Ils fonctionnent en plus des identifiants de clic (tels que les GCLID et les GBRAID) et des données fournies par l'utilisateur, qui sont essentielles au suivi avancé des conversions pour les prospects. Il existe deux façons d'importer des attributs de session: en fournissant le jeton encodé généré par notre code JavaScript dans le navigateur ou en fournissant des paires clé-valeur individuelles pour chacun des identifiants.

Pour optimiser les performances de votre campagne, nous vous recommandons d'importer les identifiants de clic, les données fournies par l'utilisateur et les attributs de session avec toutes vos conversions, si possible.

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

Exemple de code

Cet exemple montre comment définir vos données fournies par l'utilisateur normalisées et hachées sur un objet 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

Cet exemple montre comment définir d'autres champs nécessaires sur un objet 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

Créer la requête

Une fois vos objets ClickConversion configurés et ajoutés au champ conversions de l'objet UploadClickConversionRequest, définissez les champs suivants et transmettez la requête à la méthode UploadClickConversions sur ConversionUploadService.

customer_id

Définir la valeur sur le client de conversion Google Ads du compte à l'origine des clics. En cas de doute, reportez-vous au champ customer.conversion_tracking_setting.google_ads_conversion_customer dans l'exemple de requête de la section Premiers pas .

job_id

Fournit un mécanisme permettant d'associer vos requêtes d'importation aux informations par tâche dans les diagnostics des données hors connexion.

Si vous ne définissez pas ce champ, l'API Google Ads attribue à chaque requête une valeur unique comprise dans la plage [2^31, 2^63). Si vous préférez regrouper plusieurs requêtes dans une seule tâche logique, définissez ce champ sur la même valeur de la plage [0, 2^31) pour chaque requête de votre tâche.

job_id dans la réponse contient l'ID de tâche de la requête, que vous ayez spécifié une valeur ou laissé l'API Google Ads en attribuer une.

partial_failure

Ce champ doit être défini sur true lors de l'importation de conversions. Suivez les consignes concernant les échecs partiels lorsque vous traitez la réponse.

Importer la requête

Une fois que vous avez renseigné vos objets ClickConversion et créé votre requête, vous pouvez envoyer votre importation.

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

Examiner vos importations

Utilisez le rapport sur les diagnostics du suivi avancé des conversions pour les prospects pour examiner l'état global de vos importations récentes.

Les conversions importées sont reflétées dans les rapports pour la date de l'impression du clic d'origine, et non pour la date de la demande d'importation ni pour la date de l'conversion_date_time de l'ClickConversion.

Il peut s'écouler jusqu'à trois heures avant que les statistiques sur les conversions importées ne s'affichent dans votre compte Google Ads pour l'attribution au dernier clic. Pour les autres modèles d'attribution des recherches, cela peut prendre plus de trois heures. Pour en savoir plus, consultez le guide sur la fraîcheur des données.

Lorsque vous créez des rapports sur les métriques de conversion de vos campagnes, consultez Mapper les métriques de l'interface utilisateur pour mettre en corrélation les métriques de l'UI Google Ads avec les champs de création de rapports de l'API Google Ads. Vous pouvez également interroger la ressource conversion_action pour afficher le nombre total de conversions et la valeur de conversion totale pour une action de conversion donnée.

Bonnes pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous implémentez les conversions améliorées pour les prospects.

Envoyer toutes les données de conversion, que les données soient complètes ou non

Pour que les rapports sur les conversions soient complets et précis, importez tous les événements de conversion hors connexion disponibles, y compris ceux qui ne proviennent pas de Google Ads. Les conversions qui n'incluent que des données fournies par l'utilisateur restent utiles et peuvent contribuer positivement à l'optimisation des campagnes Google Ads.

Si vous attribuez un order_id à une conversion, nous vous recommandons de l'inclure. Si vous disposez du GCLID d'une conversion, nous vous recommandons de l'envoyer en plus du user_identifiers pour améliorer les performances. De plus, si vous avez plusieurs UserIdentifier pour la conversion, incluez-les tous sur l'objet ClickConversion pour augmenter la probabilité d'une correspondance.

Regrouper plusieurs conversions en une seule requête

Si vous devez importer plusieurs conversions, regroupez-les dans un seul UploadClickConversionsRequest au lieu d'envoyer une requête d'importation par conversion.

Consultez le guide sur les quotas pour connaître les limites du nombre de conversions par requête.

Si vous souhaitez que les diagnostics des données hors connexion regroupent un ensemble de requêtes dans la même tâche logique, définissez la valeur job_id de toutes les requêtes sur la même valeur. Cela peut être utile si vous avez une seule tâche ou un seul processus qui importe un grand nombre de conversions à l'aide de plusieurs requêtes. Si vous définissez la valeur job_id sur chacune de ces requêtes, vous pouvez récupérer une seule entrée pour la tâche à partir de job_summaries. Si vous laissez plutôt l'API Google Ads attribuer une valeur générée par le système à l'job_id de chaque requête, l'job_summaries contient une entrée distincte pour chaque requête, ce qui peut rendre l'analyse de l'état général de votre tâche plus difficile.

Ne pas utiliser de données d'attribution externes

Lorsque vous utilisez le suivi avancé des conversions pour les prospects, ne définissez pas external_attribution_data sur ClickConversion ni ne spécifiez un conversion_action qui utilise un modèle d'attribution externe. Google Ads n'est pas compatible avec les conversions attribuées via un système externe pour les importations à l'aide de données fournies par l'utilisateur.

Dépannage

Les diagnostics des données hors connexion constituent une ressource unique pour examiner l'état général de vos importations en continu. Toutefois, lors de l'implémentation, vous pouvez utiliser les informations de cette section pour examiner les erreurs signalées dans le champ partial_failure_error de la réponse.

Certaines des erreurs les plus courantes lors de l'importation d'actions de conversion sont des erreurs d'autorisation, telles que USER_PERMISSION_DENIED. Vérifiez que l'ID client de votre requête est défini sur le client de conversion Google Ads propriétaire de l'action de conversion. Pour en savoir plus, consultez notre guide d'autorisation et notre guide des erreurs courantes pour obtenir des conseils sur le débogage de ces différentes erreurs.

Déboguer les erreurs courantes

Erreur
`NO_CONVERSION_ACTION_FOUND`	L'action de conversion spécifiée n'est pas activée ou n'est pas accessible par le compte client spécifié par le champ "client_id" dans la requête. Assurez-vous que l'action de conversion de votre importation est activée et appartient au client qui envoie la demande d'importation. Cette erreur peut également se produire si le GCLID de la requête appartient à un compte client qui n'a pas accès à l'action de conversion spécifiée dans la requête. Vous pouvez vérifier si un GCLID appartient à un compte client à l'aide de la ressource `click_view` en envoyant une requête filtrée par `click_view.gclid` et `segments.date`, où la date correspond à celle du clic.
`INVALID_CONVERSION_ACTION_TYPE`	Le type de l'action de conversion spécifiée n'est pas valide pour le suivi avancé des conversions pour les prospects. Assurez-vous que le `ConversionAction` spécifié dans votre demande d'importation est de type `UPLOAD_CLICKS`.
`CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS`	Assurez-vous d'avoir activé le suivi avancé des conversions pour les prospects dans vos paramètres de conversion. Pour ce faire, consultez le guide des prérequis.
`DUPLICATE_ORDER_ID`	Les événements importés incluent plusieurs conversions avec le même ID de commande et n'ont donc pas été traités. Supprimez les doublons dans les ID de commande, puis réessayez.
`CLICK_NOT_FOUND`	Aucun clic ne correspond aux identifiants utilisateur fournis. L'API Google Ads ne renvoie cette erreur que si `debug_enabled` est `true` sur le `UploadClickConversionsRequest`. Remarque:Traitez cette erreur comme un avertissement, sauf si elle se produit avec la majorité de vos conversions. Si une conversion rencontre cet avertissement, l'API Google Ads l'inclut dans la section `successful_event_count` de vos diagnostics des données hors connexion. L'API Google Ads inclut une entrée pour `CLICK_NOT_FOUND` dans la collection `alerts` afin que vous puissiez surveiller la fréquence de cet avertissement. Cette erreur est attendue si le clic ne provient pas d'une campagne Google Ads. Par exemple, il peut provenir de SA360 ou de DV360. Voici d'autres causes possibles: Le client qui importe les données est différent du client de la conversion Google Ads. Le taggage n'est pas correctement configuré pour votre formulaire pour prospects. Les données importées n'ont pas été correctement normalisées et hachées. Dans de rares cas où le client qui importe les données est différent du client de la conversion Google Ads, cette erreur peut signifier que le client qui importe les données a accepté les conditions relatives aux données client, mais que le client qui diffuse les annonces ne l'a pas fait. Pour déterminer si un compte a accepté les conditions d'utilisation des données client, interrogez la ressource `customer` et vérifiez le champ `customer.offline_conversion_tracking_info.accepted_customer_data_terms`.

Premiers pas

Gérer les conversions en ligne

Gérer les conversions hors connexion Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Suivi avancé des conversions

Qu'est-ce que le suivi avancé des conversions pour les prospects ?

Prérequis

Configurer le taggage

Implémentation de l'API

Normaliser et hacher les données fournies par l'utilisateur

Exemple de code

Java

C#

PHP

Python

Ruby

Perl

Renseigner les objets ClickConversion

Java

C#

PHP

Python

Ruby

Perl

Exemple de code

Java

C#

PHP

Python

Ruby

Perl

Java

C#

PHP

Python

Ruby

Perl

Créer la requête

Importer la requête

Java

C#

PHP

Python

Ruby

Perl

Examiner vos importations

Bonnes pratiques

Envoyer toutes les données de conversion, que les données soient complètes ou non

Regrouper plusieurs conversions en une seule requête

Ne pas utiliser de données d'attribution externes

Dépannage

Déboguer les erreurs courantes

Gérer les conversions hors connexion
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.