Suivi avancé des conversions

L'API CM360 Offline Conversion permet d'améliorer les conversions basées sur des balises de site Web avec des identifiants utilisateur.

Suivi avancé des conversions

  • Acceptez les conditions d'utilisation du suivi avancé des conversions pour votre configuration Floodlight dans CM360.
  • Instrumentez vos sites Web avec un ID de correspondance.
  • Enregistrez les conversions Floodlight qui ont lieu sur votre site Web. Veillez à enregistrer tous les éléments suivants, car ils sont obligatoires dans les appels d'API ultérieurs :
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • 90 minutes après que la balise en ligne a capturé la conversion, appelez conversions.batchupdate pour améliorer ces conversions avec des identifiants utilisateur.
    • Les identifiants utilisateur doivent être mis en forme et hachés, puis ajoutés au champ userIdentifiers des objets Conversion.
    • La quantité et la valeur doivent être spécifiées. Vous pouvez éventuellement ajuster la quantité et la valeur de la conversion dans le même appel conversions.batchupdate, ou fournir la quantité et la valeur d'origine.
    • Chaque lot d'insertions et de mises à jour peut contenir un mélange de réussites et d'échecs. Les échecs NOT_FOUND doivent faire l'objet d'une nouvelle tentative en cas de délai de traitement des conversions plus long que d'habitude, jusqu'à six heures.
    • Les conversions doivent être améliorées avec des identifiants utilisateur dans les 24 heures suivant leur capture par des balises en ligne.

Normalisation et hachage

Pour protéger la confidentialité, les adresses e-mail, les numéros de téléphone, les prénoms, les noms et les adresses postales doivent être hachés à l'aide de l'algorithme SHA-256 avant d'être importés. Afin de standardiser les résultats du hachage, avant de hacher l'une de ces valeurs, vous devez :

  • Supprimer les espaces blancs de début ou de fin.
  • convertir le texte en minuscules ;
  • Mettre en forme les numéros de téléphone conformément à la norme E164. Saisissez le signe plus (+) et le code pays. Par exemple, le numéro de téléphone américain (800)555-0200 doit être mis en forme et normalisé en +18005550200.

  • Supprimez tous les points (.) qui précèdent le nom de domaine dans les adresses e-mail gmail.com et googlemail.com.

C#

/// <summary>
/// Normalizes the email address and hashes it. For this use case, Campaign Manager 360
/// 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();
}

Java

private String normalizeAndHash(MessageDigest digest, String s)
    throws UnsupportedEncodingException {
  // Normalizes by removing leading and trailing whitespace and converting all characters to
  // lower case.
  String normalized = s.trim().toLowerCase();
  // 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, Campaign Manager 360
 * 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);
}

PHP

private static function normalizeAndHash(string $hashAlgorithm, string $value): string
{
    return hash($hashAlgorithm, strtolower(trim($value)));
}

/**
  * Returns the result of normalizing and hashing an email address. For this use case, Campaign
  * Manager 360 requires removal of any '.' characters preceding "gmail.com" or "googlemail.com".
  *
  * @param string $hashAlgorithm the hash algorithm to use
  * @param string $emailAddress the email address to normalize and hash
  * @return string the normalized and hashed email address
  */
private static function normalizeAndHashEmailAddress(
    string $hashAlgorithm,
    string $emailAddress
): string {
    $normalizedEmail = strtolower($emailAddress);
    $emailParts = explode("@", $normalizedEmail);
    if (
        count($emailParts) > 1
        && preg_match('/^(gmail|googlemail)\.com\s*/', $emailParts[1])
    ) {
        // Removes any '.' characters from the portion of the email address before the domain
        // if the domain is gmail.com or googlemail.com.
        $emailParts[0] = str_replace(".", "", $emailParts[0]);
        $normalizedEmail = sprintf('%s@%s', $emailParts[0], $emailParts[1]);
    }
    return self::normalizeAndHash($hashAlgorithm, $normalizedEmail);
}

Python

def normalize_and_hash_email_address(email_address):
    """Returns the result of normalizing and hashing an email address.

    For this use case, Campaign Manager 360 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.lower()
    email_parts = normalized_email.split("@")
    # 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.
    is_gmail = re.match(r"^(gmail|googlemail)\.com$", email_parts[1])

    # Check that there are at least two segments and the second segment
    # matches the above regex expression validating the email domain name.
    if len(email_parts) > 1 and is_gmail:
        # Removes any '.' characters from the portion of the email address
        # before the domain if the domain is gmail.com or googlemail.com.
        email_parts[0] = email_parts[0].replace(".", "")
        normalized_email = "@".join(email_parts)

    return normalize_and_hash(normalized_email)

def normalize_and_hash(s):
    """Normalizes and hashes a string with SHA-256.

    Private customer data must be hashed during upload, as described at:
    https://support.google.com/google-ads/answer/7474263

    Args:
        s: The string to perform this operation on.

    Returns:
        A normalized (lowercase, removed whitespace) and SHA-256 hashed string.
    """
    return hashlib.sha256(s.strip().lower().encode()).hexdigest()

Ruby

# Returns the result of normalizing and then hashing the string using the
# provided digest.  Private customer data must be hashed during upload, as
# described at https://support.google.com/google-ads/answer/7474263.
def normalize_and_hash(str)
  # Remove leading and trailing whitespace and ensure all letters are lowercase
  # before hasing.
  Digest::SHA256.hexdigest(str.strip.downcase)
end

# Returns the result of normalizing and hashing an email address. For this use
# case, Campaign Manager 360 requires removal of any '.' characters preceding
# 'gmail.com' or 'googlemail.com'.
def normalize_and_hash_email(email)
  email_parts = email.downcase.split("@")
  # Removes any '.' characters from the portion of the email address before the
  # domain if the domain is gmail.com or googlemail.com.
  if email_parts.last =~ /^(gmail|googlemail)\.com\s*/
    email_parts[0] = email_parts[0].gsub('.', '')
  end
  normalize_and_hash(email_parts.join('@'))
end

Ajouter des identifiants utilisateur aux conversions

Commencez par préparer l'objet Conversion pour l'importer ou le modifier comme d'habitude, puis associez l'identifiant utilisateur comme suit :

{
  "matchId": "my-match-id-846513278",
  "ordinal": "my-ordinal-12345678512",
  "quantity": 1,
  "value": 104.23,
  "timestampMicros": 1656950400000000,
  "floodlightConfigurationId": 99999,
  "floodlightActivityId": 8888,
  "userIdentifiers": [
    { "hashedEmail": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b" },
    { "hashedPhoneNumber": "1fb1f420856780a29719b994c8764b81770d79f97e2e1861ba938a7a5a15dfb9" },
    {
      "addressInfo": {
        "hashedFirstName": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
        "hashedLastName": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
        "hashedStreetAddress": "22b7e2d69b91e0ef4a88e81a73d897b92fd9c93ccfbe0a860f77db16c26f662e",
        "city": "seattle",
        "state": "washington",
        "countryCode": "US",
        "postalCode": "98101"
      }
    }
  ]
}

Une réponse positive doit se présenter comme suit :

{
  "hasFailures": false,
  "status": [
    {
      "conversion": {
        "floodlightConfigurationId": 99999,
        "floodlightActivityId": 8888,
        "timestampMicros": 1656950400000000,
        "value": 104.23,
        "quantity": 1,
        "ordinal": "my-ordinal-12345678512",
        "matchId": "my-match-id-846513278",
        "userIdentifiers": [
          { "hashedEmail": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b" },
          { "hashedPhoneNumber": "1fb1f420856780a29719b994c8764b81770d79f97e2e1861ba938a7a5a15dfb9" },
          {
            "addressInfo": {
              "hashedFirstName": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
              "hashedLastName": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
              "hashedStreetAddress": "22b7e2d69b91e0ef4a88e81a73d897b92fd9c93ccfbe0a860f77db16c26f662e",
              "city": "seattle",
              "state": "washington",
              "countryCode": "US",
              "postalCode": "98101"
            }
          }
        ],
        "kind": "dfareporting#conversion"
      },
      "kind": "dfareporting#conversionStatus"
    }
  ]
}

Erreurs fréquentes

Voici quelques-unes des erreurs que vous pouvez rencontrer lorsque vous améliorez une conversion avec des identifiants utilisateur :

Le champ hashed_X n'est pas un hachage SHA-256 valide
Tous les champs préfixés par hashed n'acceptent que les hachages SHA-256 encodés en hexadécimal.
Le champ country_code n'a pas la bonne longueur
country_code doit comporter exactement deux lettres.
La configuration Floodlight n'a pas signé les conditions d'utilisation du suivi avancé des conversions
Les conditions d'utilisation du suivi avancé des conversions n'ont pas été acceptées pour l'ID de configuration Floodlight de la requête.
Plus de cinq user_identifiers spécifiés
Une conversion ne peut comporter que cinq identifiants utilisateur au maximum.

Questions fréquentes

Pourquoi l'ID de correspondance est-il recommandé ?
Les modifications basées sur l'ID de clic excluent les conversions qui ne sont pas précédées d'un clic et limitent la valeur de l'intégration du suivi avancé des conversions.
Pourquoi enregistrer la quantité et la valeur ?
L'API CM360 Offline Conversions nécessite de spécifier la quantité et la valeur.
Dois-je obtenir l'horodatage exact en microsecondes enregistré par Google pour modifier une conversion basée sur une balise en ligne ?
Pour les modifications basées sur l'ID de correspondance, l'API accepte désormais une modification tant que l'horodatage fourni dans la requête se situe à moins d'une minute de l'horodatage enregistré par Google.
Pourquoi dois-je attendre 90 minutes après qu'une conversion a été capturée par une balise en ligne avant de l'améliorer ?
L'indexation de la conversion en ligne par l'API et sa disponibilité pour les modifications peuvent prendre jusqu'à 90 minutes.
À quoi dois-je faire attention dans la réponse de l'API ?
Même lorsque l'API CM360 Conversion renvoie une réponse positive, il est possible que certaines conversions individuelles n'aient pas pu être importées ni mises à jour. Inspectez les champs ConversionStatus individuels pour détecter les échecs :
  • Les échecs NOT_FOUND peuvent et doivent faire l'objet d'une nouvelle tentative, jusqu'à six heures, en cas de délai de traitement des conversions plus long que d'habitude. Consultez également la section Questions fréquentes pour savoir pourquoi les erreurs NOT_FOUND peuvent persister au-delà de six heures.
  • Les erreurs INVALID_ARGUMENT et PERMISSION_DENIED ne doivent pas faire l'objet d'une nouvelle tentative.