Gelişmiş Dönüşümler

CM360 çevrimdışı dönüşüm API'si, web sitesi etiketine dayalı dönüşümlerin kullanıcı kimlikleriyle iyileştirilmesini destekler.

Gelişmiş Dönüşüm

  • CM360'ta 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 donatın.
  • Web sitenizde gerçekleşen Floodlight dönüşümlerini kaydetme Sonraki API çağrılarında zorunlu alanlar olduklarından aşağıdakilerin tümünü kaydettiğinizden emin olun:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Online etiket dönüşümü yakaladıktan 90 dakika sonra, bu dönüşümleri kullanıcı kimlikleriyle iyileştirmek için conversions.batchupdate yöntemini çağırın.
    • Kullanıcı kimlikleri biçimlendirilmeli ve karma oluşturma işleminden geçirilmeli, ardından dönüşüm nesnelerindeki userIdentifiers alanına eklenmelidir.
    • Miktar ve değer belirtilmelidir. İsterseniz 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, başarılı ve başarısız işlemler içerebilir. Dönüşüm işleme sürecinde normalden daha uzun bir gecikme olması durumunda NOT_FOUND ve INTERNAL hataları 6 saate kadar yeniden denenmelidir.
    • Dönüşümler, online etiketler tarafından yakalandıktan sonraki 24 saat içinde kullanıcı kimlikleriyle geliştirilmelidir.

Normalleştirme ve karma oluşturma

Gizliliğin korunmasına yardımcı olmak için e-posta adresleri, telefon numaraları, adlar, soyadlar ve açık adresler yüklenmeden önce SHA-256 algoritması kullanılarak karma oluşturma işlemine tabi tutulmalı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. Artı işaretini (+) ve ülke kodunu ekleyin. Örneğin, ABD telefon numarası (800)555-0200, +18005550200 olarak biçimlendirilmeli ve normalleştirilmelidir.

  • 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ı kimlikleri ekleme

Önce Conversion nesnesini normal şekilde yükleme veya düzenleme için hazırlayın, ardından kullanıcı kimliğini 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 şu şekilde 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"
    }
  ]
}

Sık karşılaşılan hatalar

Kullanıcı tanımlayıcıları ile bir dönüşümü geliştirirken görebileceğiniz bazı hatalar şunlardır:

hashed_X alanı geçerli bir SHA-256 karması değil
"Hashed" ön ekine sahip tüm alanlar, yalnızca onaltılık olarak kodlanmış SHA-256 karmalarını kabul eder.
country_code alanının uzunluğu yanlış
country_code tam olarak 2 harften oluşmalıdır.
Floodlight yapılandırması, gelişmiş dönüşümler hizmet şartlarını imzalamadı
İsteğin Floodlight yapılandırma kimliği için Gelişmiş Dönüşümler Hizmet Şartları kabul edilmedi.
Beşten fazla user_identifiers belirtildi
Bir dönüşümde en fazla 5 kullanıcı kimliği olabilir.

Sık sorulan sorular

Eşleşme kimliği neden önerilir?
Tıklama kimliğine dayalı düzenlemeler, öncesinde 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 Çevrimdışı Dönüşümler API'si, miktar ve değerin belirtilmesini gerektirir.
Online etiket tabanlı bir dönüşümü düzenlemek için Google tarafından kaydedilen tam mikrosaniye zaman damgasını almam gerekir mi?
Eşleşme kimliğine dayalı düzenlemelerde API, istekte sağlanan zaman damgası Google tarafından kaydedilen zaman damgasından en fazla 1 dakika farklı olduğu sürece düzenlemeyi kabul eder.
Bir dönüşüm online etiket tarafından yakalandıktan sonra neden 90 dakika beklemem gerekiyor?
Online dönüşümün API tarafından dizine eklenmesi ve düzenlemeye hazır hale gelmesi 90 dakikayı bulabilir.
API yanıtında nelere dikkat etmeliyim?
CM360 Conversion API başarılı bir yanıt döndürse bile bazı dönüşümler yüklenememiş veya güncellenememiş olabilir. Hatalar için ayrı ayrı ConversionStatus alanlarını inceleyin:
  • Dönüşüm işleme sürecinde normalden daha uzun bir gecikme olması durumunda NOT_FOUND ve INTERNAL hataları 6 saate kadar yeniden denenebilir ve denenmelidir.
  • INVALID_ARGUMENT ve PERMISSION_DENIED hataları yeniden denenmemelidir.
  • Daha fazla bilgi için SSS bölümüne bakın.