الإحالات الناجحة المحسّنة

تتيح واجهة برمجة التطبيقات للإحالات الناجحة غير الإلكترونية في CM360 تحسين الإحالات الناجحة المستندة إلى علامات الموقع الإلكتروني باستخدام معرّفات المستخدمين.

الإحالات الناجحة المحسّنة

  • اقبل بنود خدمة "الإحالات الناجحة المحسّنة" لإعدادات Floodlight في "مدير الحملة 360".
  • جهِّز مواقعك الإلكترونية باستخدام رقم تعريف مطابق.
  • تسجيل الإحالات الناجحة في Floodlight التي تحدث على موقعك الإلكتروني تأكَّد من تسجيل كل ما يلي لأنّها حقول مطلوبة في طلبات البيانات اللاحقة من واجهة برمجة التطبيقات:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • بعد مرور 90 دقيقة على تسجيل العلامة على الإنترنت للإحالة الناجحة، يمكنك استدعاء conversions.batchupdate لتحسين هذه الإحالات الناجحة باستخدام معرّفات المستخدمين.
    • يجب تنسيق معرّفات المستخدمين وتجزئتها وإضافتها إلى الحقل userIdentifiers في عناصر الإحالات الناجحة.
    • يجب تحديد الكمية والقيمة. يمكنك اختياريًا تعديل كمية الإحالة الناجحة وقيمتها في طلب conversions.batchupdate نفسه، أو تقديم الكمية والقيمة الأصليتَين.
    • يمكن أن تحتوي كل دفعة من عمليات الإدراج والتعديل على مزيج من النجاحات والإخفاقات. يجب إعادة محاولة معالجة حالات الفشل NOT_FOUND وINTERNAL في حال حدوث تأخير أطول من المعتاد في معالجة الإحالات الناجحة، وذلك لمدة تصل إلى 6 ساعات.
    • يجب تحسين الإحالات الناجحة باستخدام معرّفات المستخدمين خلال 24 ساعة من تسجيلها بواسطة العلامات على الإنترنت.

التسوية والتجزئة

للمساعدة في حماية الخصوصية، يجب تجزئة عناوين البريد الإلكتروني وأرقام الهواتف والأسماء الأولى وأسماء العائلة وعناوين الشوارع باستخدام خوارزمية SHA-256 قبل تحميلها. لتوحيد نتائج التجزئة، عليك إجراء ما يلي قبل تجزئة إحدى هذه القيم:

  • إزالة أي مسافات بيضاء سابقة أو لاحقة
  • تحويل النص إلى أحرف لاتينية صغيرة
  • تنسيق أرقام الهواتف وفقًا لمعيار E164 يجب تضمين علامة الجمع (+) ورمز البلد. على سبيل المثال، يجب تنسيق رقم الهاتف الأمريكي (800)555-0200 وتوحيده ليصبح +18005550200

  • إزالة جميع النقاط (.) التي تسبق اسم النطاق في عناوين البريد الإلكتروني gmail.com و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();
}

جافا

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

إضافة معرّفات المستخدمين إلى الإحالات الناجحة

أولاً، عليك إعداد عنصر Conversion من أجل تحميله أو تعديله كالمعتاد، ثم إرفاق معرّف المستخدم على النحو التالي:

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

يُفترض أن تظهر الاستجابة الناجحة على النحو التالي:

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

الأخطاء الشائعة

في ما يلي بعض الأخطاء التي قد تظهر لك عند تحسين إحالة ناجحة باستخدام معرّفات المستخدمين:

الحقل hashed_X ليس قيمة تجزئة صالحة متوافقة مع SHA-256
جميع الحقول التي تبدأ بكلمة "مجزّأ" تقبل فقط تجزئات SHA-256 المرمّزة بنظام العد الستة عشري.
طول الحقل country_code غير صحيح
يجب أن يتألف "country_code" من حرفَين بالضبط.
لم يتم توقيع بنود خدمة "الإحالات الناجحة المحسّنة" في إعدادات Floodlight
لم يتم قبول بنود خدمة "الإحالات الناجحة المحسّنة" لرقم تعريف إعدادات Floodlight في الطلب.
تم تحديد أكثر من خمسة معرّفات مستخدمين (user_identifiers)
يمكن أن تتضمّن الإحالة الناجحة ما يصل إلى 5 معرّفات مستخدمين فقط.

الأسئلة الشائعة

لماذا يُنصح باستخدام رقم تعريف مطابق؟
تستبعد التعديلات المستندة إلى معرّف النقرة الإحالات الناجحة التي لم تسبقها نقرة، وتحدّ من قيمة دمج ميزة "الإحالات الناجحة المحسّنة".
لماذا يجب تسجيل الكمية والقيمة؟
تتطلّب واجهة CM360 Offline Conversions API تحديد الكمية والقيمة.
هل أحتاج إلى الحصول على الطابع الزمني الدقيق بالمايكرو ثانية الذي سجّلته Google لتعديل إحالة ناجحة مستندة إلى علامة على الإنترنت؟
بالنسبة إلى التعديلات المستندة إلى رقم تعريف المباراة، تقبل واجهة برمجة التطبيقات الآن التعديل طالما أنّ الطابع الزمني المقدَّم في الطلب يقع ضمن دقيقة واحدة من الطابع الزمني الذي سجّلته Google.
لماذا عليّ الانتظار لمدة 90 دقيقة بعد تسجيل إحالة ناجحة بواسطة علامة على الإنترنت قبل تحسينها؟
قد تستغرق فهرسة الإحالة الناجحة الإلكترونية من خلال واجهة برمجة التطبيقات وإتاحتها للتعديلات مدة تصل إلى 90 دقيقة.
ما الذي يجب الانتباه إليه في الردّ من واجهة برمجة التطبيقات؟
حتى عندما تعرض واجهة CM360 Conversion API ردًا ناجحًا، قد يتعذّر تحميل أو تعديل بعض الإحالات الناجحة الفردية. افحص حقول ConversionStatus الفردية بحثًا عن حالات تعذُّر:
  • يمكن ويجب إعادة محاولة إرسال طلبات NOT_FOUND وINTERNAL التي تعذّر إرسالها، وذلك لمدة تصل إلى 6 ساعات، في حال حدوث تأخير أطول من المعتاد في معالجة الإحالات الناجحة.
  • يجب عدم إعادة محاولة معالجة الخطأين INVALID_ARGUMENT وPERMISSION_DENIED.
  • يُرجى الاطّلاع على الأسئلة الشائعة لمزيد من التفاصيل.