Gelişmiş Dönüşümler

CM360 çevrimdışı dönüşüm API'si, kullanıcı tanımlayıcılarıyla web sitesi etiketine dayalı dönüşümleri geliştirmeyi destekler.

Gelişmiş Dönüşüm

  • CM360'taki Floodlight yapılandırmanız için Gelişmiş Dönüşümler Hizmet Şartları'nı kabul edin.
  • Web sitelerinizi eşleşme kimliği ile ayarlayın.
  • Web sitenizde gerçekleşen Floodlight dönüşümlerini kaydedin. Sonraki API çağrılarında zorunlu alanlar olduğundan aşağıdakilerin tümünü kaydettiğinizden emin olun:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Online etiketin dönüşümü yakalamasının üzerinden 90 dakika geçtikten sonra bu dönüşümleri kullanıcı tanımlayıcılarıyla geliştirmek için conversions.batchupdate çağrısı yapın.
    • Kullanıcı tanımlayıcıları biçimlendirilmeli, karma oluşturulmalı ve Dönüşüm nesnelerindeki userIdentifiers alanına eklenmelidir.
    • Miktar ve değer belirtilmelidir. İsteğe bağlı olarak, aynı conversions.batchupdate çağrısında dönüşümün miktarını ve değerini ayarlayabilir veya orijinal miktar ve değeri sağlayabilirsiniz.
    • Her ekleme ve güncelleme grubu, hem başarılı hem de başarısız noktaları içerebilir. Dönüşüm işlemede normalden daha uzun bir gecikme olduğunda (en fazla 6 saat) NOT_FOUND hataları yeniden denenmelidir.
    • Dönüşümler, online etiketler tarafından yakalandıktan sonraki 24 saat içinde kullanıcı tanımlayıcıları ile geliştirilmelidir.

Normalleştirme ve karma oluşturma

Gizliliğin korunmasına yardımcı olmak amacıyla, e-posta adreslerine, telefon numaralarına, adlara, soyadlarına ve açık adreslere yüklenmeden önce SHA-256 algoritması kullanılarak karma oluşturma işlemi uygulanmalıdır. Karma oluşturma sonuçlarını standart hale getirmek için bu değerlerden birine karma oluşturma işlemi uygulamadan önce şunları yapmanız gerekir:

  • Baştaki veya sondaki boşlukları kaldırın.
  • Metni küçük harfe dönüştürün.
  • Telefon numaralarını E164 standardına göre biçimlendirin.

  • gmail.com ve googlemail.com e-posta adreslerinde alan adından önce gelen tüm noktaları (.) kaldırın.

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

Dönüşümlere kullanıcı tanımlayıcıları ekleme

Öncelikle Conversion nesnesini normal şekilde yükleme veya düzenleme için hazırlayın, ardından kullanıcı tanımlayıcısını aşağıdaki gibi ekleyin:

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

Başarılı bir yanıt aşağıdaki gibi görünmelidir:

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

Yaygın görülen hatalar

Bir dönüşümü kullanıcı tanımlayıcılarıyla geliştirirken karşılaşabileceğiniz bazı hatalar aşağıda verilmiştir:

hashed_X alanı geçerli bir SHA-256 karması değil
Ön ekinde karma oluşturma işlemi uygulanmış tüm alanlar, yalnızca onaltılık olarak kodlanmış SHA-256 karmalarını kabul eder.
Alanın ülke_kodunun uzunluğu yanlış
country_code tam olarak 2 harf olmalıdır.
Floodlight yapılandırması, gelişmiş dönüşüm hizmet şartlarını imzalamadı
İsteğin Floodlight yapılandırma kimliği için Gelişmiş Dönüşüm Hizmet Şartları kabul edilmedi.
Beşten fazla user_identifier belirtildi
Bir dönüşümde en fazla 5 kullanıcı tanımlayıcısı olabilir.

Sık sorulan sorular

Eşleşme kimliği neden önerilir?
Tıklama kimliğine dayalı düzenlemeler, başında tıklama olmayan dönüşümleri hariç tutar ve gelişmiş dönüşüm entegrasyonunun değerini sınırlar.
Miktar ve değer neden kaydedilmelidir?
CM360 Offline Conversions API için miktarın ve değerin belirtilmesi gerekir.
Etikete dayalı online bir dönüşümü düzenlemek için Google tarafından kaydedilen mikrosaniye zaman damgasını tam olarak almam gerekir mi?
İstekte belirtilen zaman damgası, Google'ın kaydettiği zaman damgasına 1 dakika uzaklıkta olduğu sürece eşleşme kimliğine dayalı düzenlemelerde artık API tarafından düzenleme kabul edilmektedir.
Bir dönüşümü iyileştirmek için, çevrimiçi etiket tarafından yakalandıktan sonra neden 90 dakika beklemem gerekiyor?
Online dönüşümün API tarafından dizine eklenmesi ve düzenlenmeye uygun olması 90 dakikayı bulabilir.
API yanıtında nelere dikkat etmeliyim?
CM360 dönüşüm API'si başarılı bir yanıt döndürse bile bazı dönüşümlerin yüklenmesi veya güncellenmesi başarısız olmuş olabilir. Bağımsız ConversionStatus alanlarındaki hata olup olmadığını inceleyin:
  • NOT_FOUND hataları, dönüşüm işlemede normalden daha uzun bir gecikme yaşanması ihtimaline karşı 6 saate kadar yeniden denenebilir. NOT_FOUND hatalarının neden 6 saatten uzun süre devam edebildiğini öğrenmek için SSS bölümüne de göz atın.
  • INVALID_ARGUMENT ve PERMISSION_DENIED hatalarının yeniden denenmemesi gerekir.