Suivi avancé des conversions

L'API de conversion hors connexion CM360 permet d'améliorer les balises de site Web avec des identifiants utilisateur.

Suivi avancé des conversions

  • Acceptez les Conditions d'utilisation du suivi avancé des conversions de de service de votre projet Floodlight dans CM360.
  • Instrumentez vos sites Web avec un ID de correspondance.
  • Enregistrez les conversions Floodlight qui se produisent sur votre site Web. Veillez à enregistrer Tous les champs suivants, car ils sont obligatoires dans les appels d'API suivants: <ph type="x-smartling-placeholder">
      </ph>
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Au bout de 90 minutes, appelez conversions.batchupdate pour les améliorer avec des identifiants utilisateur.
    • Les identifiants utilisateur doivent être mis en forme et hachés, puis ajoutés aux le champ userIdentifiers sur les objets de conversion.
    • Vous devez indiquer la quantité et la valeur. Si vous le souhaitez, vous pouvez ajuster la quantité et la valeur de la conversion dans le même appel conversions.batchupdate, ou indiquer la quantité d'origine et .
    • Chaque lot d'insertions et de mises à jour peut contenir une combinaison de réussites et d'échecs. NOT_FOUND échec doit faire l'objet d'une nouvelle tentative au cas où que d'habitude, jusqu'à six heures.
    • Le suivi avancé des conversions doit être effectué avec des identifiants utilisateur dans les 24 heures elles sont capturées par des tags en ligne.

Normalisation et hachage

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

  • Supprimez les espaces blancs de début ou de fin.
  • convertir le texte en minuscules ;
  • Mettez en forme les numéros de téléphone conformément à la norme E164.

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

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

Préparez d'abord l'objet Conversion pour l'importation ou modification comme d'habitude, puis associez l'identifiant de l'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 erreurs que vous pouvez rencontrer lorsque vous améliorez une conversion en ciblant les utilisateurs identifiants:

Le champ hashed_X n'est pas un hachage SHA-256 valide
Tous les champs précédés de hachage n'acceptent que les hachages SHA-256 encodés en les nombres hexadécimaux.
La longueur du champ country_code est incorrecte.
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 le ID de configuration Floodlight de la requête.
Plus de cinq identifiants user_identifier spécifiés
Une conversion ne peut pas comporter plus de cinq identifiants utilisateur.

Questions fréquentes

Pourquoi l'ID de correspondance est-il recommandé ?
Les modifications basées sur l'ID de clic excluent les conversions non précédées d'un clic et sont soumises à des limites la valeur de l'intégration du suivi avancé des conversions.
Pourquoi enregistrer la quantité et la valeur ?
L'API de conversions hors connexion CM360 requiert que la quantité et la valeur soient spécifiques.
Dois-je obtenir le code temporel exact de la microseconde enregistré par Google pour modifier une conversion en ligne basée sur une balise ?
Pour les modifications basées sur un ID de correspondance, l'API accepte désormais les modifications tant que l'élément le code temporel fourni dans la demande correspond à moins d'une minute après l'enregistrement par Google code temporel.
Pourquoi dois-je attendre 90 minutes après qu'une conversion a été enregistrée par une balise en ligne avant de l'améliorer ?
Il peut s'écouler jusqu'à 90 minutes avant que la conversion en ligne soit indexée par API et être disponible pour des modifications.
À quoi dois-je prêter attention dans la réponse de l'API ?
Même lorsque l'API de conversion CM360 renvoie une réponse positive, certaines des conversions spécifiques n'ont peut-être pas pu être importées ou mises à jour. Inspectez des champs ConversionStatus individuels en cas d'échec: <ph type="x-smartling-placeholder">
    </ph>
  • NOT_FOUND échecs peuvent et doivent faire l'objet de nouvelles tentatives, jusqu'à six heures, au cas où Le délai de traitement des conversions est plus long que d'habitude. Consultez également les Questions fréquentes sur les raisons pour lesquelles les erreurs NOT_FOUND peuvent persister au-delà de 6 heures.
  • N'essayez pas de relancer les erreurs INVALID_ARGUMENT et PERMISSION_DENIED.