Conversioni avanzate

L'API per le conversioni offline di CM360 supporta il miglioramento dei tag del sito web basati su tag le conversioni con gli identificatori utente.

Conversione avanzata

  • Accetta i Termini per le conversioni avanzate Servizio per Floodlight configurazione in CM360.
  • Strumenti i tuoi siti web con l'ID corrispondenza.
  • Registrare conversioni Floodlight che si verificano sul tuo sito web. Assicurati di registrare tutti gli elementi seguenti in quanto sono campi obbligatori nelle chiamate API successive:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Una volta trascorsi 90 minuti da quando il tag online ha acquisito la conversione, chiama conversions.batchupdate per migliorare questi le conversioni con gli identificatori utente.
    • Gli identificatori utente devono essere formattati, sottoposti ad hashing e aggiunti a il campo userIdentifiers sugli oggetti di conversione.
    • È necessario specificare quantità e valore. Puoi eventualmente modificare la quantità e il valore della conversione nel stessa chiamata a conversions.batchupdate oppure fornisci la quantità e la quantità originali valore.
    • Ogni batch di inserimenti e aggiornamenti può contenere un mix di successi e errori. È necessario riprovare NOT_FOUND errore nel caso in cui sia trascorso un periodo di tempo più lungo ritardo del solito nell'elaborazione delle conversioni, fino a un massimo di 6 ore.
    • Le conversioni devono essere migliorate con gli identificatori utente entro 24 ore dopo vengono acquisite dai tag online.

Normalizzazione e hashing

Per proteggere la privacy, indirizzi email, numeri di telefono, nomi, cognome nomi e indirizzi devono essere sottoposti ad hashing utilizzando l'algoritmo SHA-256 prima in fase di caricamento. Al fine di standardizzare i risultati di hashing, prima di eseguire l'hashing di questi valori devi:

  • Rimuovi gli spazi vuoti iniziali o finali.
  • Convertire il testo in minuscolo.
  • Formatta i numeri di telefono secondo lo standard E164.
  • Rimuovi tutti i punti (.) che precedono il nome di dominio in gmail.com e googlemail.com indirizzi email.

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

Aggiungere identificatori utente alle conversioni

Innanzitutto, prepara l'oggetto Conversion per il caricamento o modificando come di consueto, quindi allega l'identificatore utente come segue:

{
  "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"
      }
    }
  ]
}

Una risposta corretta dovrebbe essere simile al seguente:

{
  "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"
    }
  ]
}

Errori comuni

Di seguito sono riportati alcuni errori che potresti visualizzare quando migliori una conversione con l'utente identificatori:

Il campo hashed_X non è un hash SHA-256 valido
Tutti i campi con prefisso sottoposto ad hashing accettano solo hash SHA-256 codificati in esadecimali.
La lunghezza del campo country_code non è corretta
country_code deve essere composto esattamente da 2 lettere.
La configurazione Floodlight non ha firmato i Termini di servizio per le conversioni avanzate
I Termini di servizio delle conversioni avanzate non sono stati accettati per il ID configurazione Floodlight della richiesta.
Più di cinque identificatori utente specificati
Una conversione può avere al massimo 5 identificatori utente.

Domande frequenti

Perché la corrispondenza ID è consigliata?
Le modifiche basate sull'ID clic escludono le conversioni non precedute da un clic e da limiti il valore dell'integrazione delle conversioni avanzate.
Perché occorre registrare quantità e valore?
L'API Offline Conversion di CM360 richiede che quantità e valore siano specificato.
Devo ottenere il timestamp esatto in microsecondi registrato da Google per modificare una conversione basata su tag online?
Per le modifiche basate su Match ID, l'API ora accetta una modifica a condizione che l'API il timestamp fornito nella richiesta è entro 1 minuto dalla registrazione da parte di Google timestamp.
Perché devo attendere 90 minuti dopo l'acquisizione di una conversione da un tag online prima di migliorarla?
Possono essere necessari fino a 90 minuti prima che la conversione online venga indicizzata dal API e essere disponibile per le modifiche.
A cosa devo prestare attenzione nella risposta dell'API?
Anche quando l'API Conversion di CM360 restituisce una risposta positiva, alcune il caricamento o l'aggiornamento delle singole conversioni potrebbe non essere riuscito. Ispeziona singoli campi ConversionStatus per gli errori:
  • È possibile e necessario ritentare NOT_FOUND errori, fino a un massimo di 6 ore, nel caso in cui il ritardo nell'elaborazione delle conversioni è più lungo del solito. Vedi anche Domande frequenti sul motivo per cui gli errori NOT_FOUND possono persistere dopo 6 nell'orario lavorativo locale del TAM.
  • Non riprovare INVALID_ARGUMENT e PERMISSION_DENIED.