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

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

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

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

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

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

  • إزالة أي مسافات بيضاء سابقة أو لاحقة
  • تحويل النص إلى أحرف لاتينية صغيرة
  • تنسيق أرقام الهواتف وفقًا لمعيار E164

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

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

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