Konversi yang Disempurnakan

API konversi offline CM360 mendukung peningkatan kualitas situs berbasis tag konversi dengan ID pengguna.

Konversi yang Disempurnakan

  • Setujui Persyaratan Konversi yang Disempurnakan Layanan untuk Floodlight Anda di CM360.
  • Lengkapi situs Anda dengan ID kecocokan.
  • Catat konversi Floodlight yang terjadi di situs Anda. Pastikan untuk merekam semua hal berikut karena merupakan kolom yang wajib diisi dalam panggilan API berikutnya:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Setelah 90 menit berlalu sejak tag {i>online<i} menangkap konversi, panggil conversions.batchupdate untuk meningkatkan kualitas konversi dengan ID pengguna.
    • ID pengguna harus diformat dan di-hash, serta ditambahkan ke kolom userIdentifiers di objek Conversion.
    • Jumlah dan nilai harus ditentukan. Secara opsional, Anda dapat menyesuaikan kuantitas dan nilai konversi di panggilan conversions.batchupdate yang sama, atau berikan jumlah asli dan dengan sejumlah nilai.
    • Setiap batch penyisipan dan pembaruan dapat berisi campuran keberhasilan dan gagal. NOT_FOUND kegagalan harus dicoba lagi jika terjadi jangka waktu yang lebih lama jeda waktu dalam pemrosesan konversi dari biasanya, hingga 6 jam.
    • Konversi harus ditingkatkan dengan ID pengguna dalam waktu 24 jam setelahnya posisi tersebut ditangkap oleh tag online.

Normalisasi dan {i>hashing<i}

Untuk membantu melindungi privasi, alamat email, nomor telepon, nama depan, belakang nama, dan alamat harus di-{i>hash<i} menggunakan algoritma SHA-256 sebelum sedang diupload. Untuk menstandarkan hasil {i>hash<i}, sebelum melakukan {i>hashing <i}satu dari nilai tersebut, Anda harus:

  • Hapus spasi kosong di awal atau di akhir.
  • Mengonversi teks menjadi huruf kecil.
  • Format nomor telepon sesuai dengan standar E164.

  • Menghapus semua titik (.) yang mendahului nama domain di alamat email gmail.com dan 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

Menambahkan ID pengguna ke konversi

Pertama, siapkan objek Conversion untuk upload atau mengedit seperti biasa, lalu tambahkan ID pengguna seperti berikut:

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

Respons yang berhasil akan terlihat seperti ini:

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

Error yang biasa terjadi

Berikut adalah beberapa error yang mungkin Anda lihat saat meningkatkan konversi dengan pengguna pengenal:

Kolom yang di-hash_X bukan hash SHA-256 yang valid
Semua kolom yang diawali dengan di-hash hanya menerima hash SHA-256 yang dienkode dalam heksadesimal.
Kolom country_code memiliki panjang yang salah
country_code harus tepat 2 huruf.
Konfigurasi Floodlight belum menandatangani persyaratan layanan konversi yang disempurnakan
Persyaratan Layanan Konversi yang Disempurnakan belum disetujui untuk ID konfigurasi Floodlight permintaan.
Lebih dari lima user_IDs ditentukan
Sebuah konversi hanya dapat memiliki maksimal 5 ID pengguna.

Pertanyaan umum (FAQ)

Mengapa ID kecocokan direkomendasikan?
Pengeditan yang berbasis ID klik mengecualikan konversi yang tidak didahului dengan klik dan batas nilai integrasi konversi yang disempurnakan.
Mengapa kuantitas dan nilai harus dicatat?
CM360 Offline Conversions API mengharuskan kuantitas dan nilai ditentukan.
Apakah saya harus mendapatkan stempel waktu mikrodetik yang tepat yang dicatat oleh Google untuk mengedit konversi berbasis tag online?
Untuk pengeditan berbasis ID kecocokan, API sekarang menerima pengeditan selama stempel waktu yang diberikan dalam permintaan berada dalam waktu 1 menit sejak Google direkam tanda waktu.
Mengapa saya harus menunggu 90 menit setelah konversi ditangkap oleh tag online sebelum meningkatkannya?
Perlu waktu hingga 90 menit agar konversi online diindeks oleh API dan tersedia untuk pengeditan.
Apa yang harus saya perhatikan dalam respons API?
Bahkan saat API konversi CM360 menampilkan respons yang berhasil, beberapa konversi individual mungkin saja gagal diupload atau diperbarui. Periksa kolom ConversionStatus individual untuk kegagalan:
  • NOT_FOUND kegagalan dapat dan harus dicoba lagi, hingga 6 jam, jika terjadi terjadi keterlambatan yang lebih lama dari biasanya dalam pemrosesan konversi. Lihat juga FAQ tentang alasan error NOT_FOUND dapat terus berlanjut melebihi 6 dalam jam kerja lokal mereka.
  • Error INVALID_ARGUMENT dan PERMISSION_DENIED tidak boleh dicoba lagi.