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

تتيح واجهة برمجة التطبيقات للإحالات الناجحة بلا إنترنت في "مدير الحملة 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();
}

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

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

عليك أولاً إعداد عنصر 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"
    }
  ]
}

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

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

قيمة التجزئة المجزأة للحقل SHA-256 ليست صالحة.

لا تقبل جميع الحقول التي تبدأ بعلامات تجزئة إلّا تجزئات SHA-256 التي تم ترميزها بالأرقام السداسية العشرية.

طول الحقل country_code غير صحيح

يجب أن يتألف country_code من حرفَين بالضبط.

لم توقّع إعدادات Floodlight على بنود خدمة الإحالات الناجحة المحسّنة

لم يتم قبول بنود خدمة الإحالات الناجحة المحسّنة لرقم تعريف إعداد Floodlight الخاص بالطلب.

تم تحديد أكثر من خمسة معرّفات user_identifier.

يمكن أن تحتوي الإحالة الناجحة على ما يصل إلى 5 معرّفات مستخدمين فقط.

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

لماذا يُنصح باستخدام رقم تعريف مطابق؟

تستثني التعديلات المستندة إلى معرّف النقرة الإحالات الناجحة التي لا تسبقها نقرة وتحدّ من قيمة دمج الإحالات الناجحة المحسّنة.

لماذا يجب تسجيل الكمية والقيمة؟

تتطلب واجهة برمجة التطبيقات للإحالات الناجحة بلا إنترنت في "مدير الحملة 360" تحديد الكمية والقيمة.

هل أحتاج إلى الحصول على الطابع الزمني الدقيق بالميكرو ثانية الذي تسجّله Google من أجل تعديل إحالة ناجحة مستندة إلى العلامة على الإنترنت؟

بالنسبة إلى التعديلات المستندة إلى معرّف المطابقة، تقبل واجهة برمجة التطبيقات الآن التعديل طالما أنّ الطابع الزمني المقدّم في الطلب يقع خلال دقيقة واحدة من الطابع الزمني الذي سجّلته Google.

لماذا عليّ الانتظار لمدة 90 دقيقة بعد تسجيل إحالة ناجحة بواسطة علامة على الإنترنت قبل تحسينها؟

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

ما الذي يجب الانتباه إليه في استجابة واجهة برمجة التطبيقات؟

حتى عندما تعرض واجهة برمجة التطبيقات للإحالات الناجحة في "مدير الحملة 360" استجابة ناجحة، من الممكن أن يتعذّر تحميل بعض الإحالات الناجحة الفردية أو تعديلها. افحص حقول ConversionStatus الفردية بحثًا عن أي أخطاء:

• يمكن أن تتم إعادة محاولة تنفيذ NOT_FOUND بنجاح لمدة تصل إلى 6 ساعات في حال حدوث تأخير في معالجة الإحالة الناجحة أطول من المعتاد. ويمكنك أيضًا الاطّلاع على الأسئلة الشائعة حول سبب استمرار أخطاء NOT_FOUND لأكثر من 6 ساعات.
• يجب عدم إعادة المحاولة في خطأَي INVALID_ARGUMENT وPERMISSION_DENIED.