إدارة الإحالات الناجحة بلا إنترنت

يمكنك استخدام Google Ads API لاستيراد الإحالات الناجحة غير الإلكترونية إلى "إعلانات Google" من أجل تتبُّع الإعلانات التي أدّت إلى مبيعات غير إلكترونية، مثل المبيعات عبر الهاتف أو من خلال مندوب مبيعات.

للاستفادة بشكل كامل من مزايا استيراد بيانات الإحالات الناجحة، ننصحك بتفعيل ميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين" التي تستفيد من معرّفات النقرة من Google والبيانات المقدَّمة من المستخدم لزيادة الاستدامة والأداء إلى أقصى حدّ.

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

تساعدك ميزة "الإحالات الناجحة المحسّنة" في تحسين دقة قياس إحالاتك الناجحة من خلال تكميلها ببيانات الإحالات الناجحة الخاصة بالطرف الأول، مثل عنوان البريد الإلكتروني ورقم الهاتف والعنوان البريدي.

هناك نوعان من الإحالات الناجحة المحسّنة. لمزيد من التفاصيل، اطّلِع على المقالة لمحة عن الإحالات الناجحة المحسّنة.

يوضّح القسم التالي كيفية تحسين الإحالات الناجحة غير الإلكترونية، وهي ميزة يُشار إليها أيضًا باسم الإحالات الناجحة المحسّنة للعملاء المحتملين.

ما هي ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين"؟

ميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين" هي نسخة متطورة من ميزة "استيراد الإحالات الناجحة غير الإلكترونية" التي تستخدم البيانات المقدَّمة من المستخدِم، مثل عناوين البريد الإلكتروني، لتكملة بيانات الإحالات الناجحة غير الإلكترونية المستورَدة من أجل تحسين الدقّة وأداء عروض الأسعار. عند استيراد إحالاتك الناجحة غير الإلكترونية، يتم استخدام بيانات العملاء المجزّأة المقدَّمة لتحديد مصدرها على أنّه الحملة على "إعلانات Google" عن طريق مطابقتها مع البيانات نفسها التي تم جمعها على موقعك الإلكتروني، مثل نموذج العملاء المحتملين، والعملاء الذين سجَّلوا الدخول وتفاعلوا مع إعلانك. لمزيد من المعلومات، اطّلِع على المقالة لمحة عن "الإحالات الناجحة المحسّنة للعملاء المهتمين".

تتوفّر طريقتان لتنفيذ ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين"، وذلك حسب ما إذا كنت تستخدم علامة التتبُّع من Google لتتبُّع أحداث إرسال النماذج على صفحة الويب. للحصول على أفضل أداء ومتانة، ننصح باستخدام علامة تتبُّع من Google لـ "الإحالات الناجحة المحسّنة للعملاء المحتملين".

المتطلبات الأساسية

أولاً، تأكَّد من إكمال الخطوات الواردة في قسم البدء.

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

SELECT
  customer.id,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enablement_setting,
  customer.conversion_tracking_setting.effective_enablement_setting
FROM customer

إذا كانت قيمة accepted_customer_data_terms هي false، أو إذا كانت قيمة enablement_setting (أو effective_enablement_setting عند استخدام ميزة تتبُّع الإحالات الناجحة على جميع الحسابات) ليست ON، اتّبِع التعليمات الواردة في إنشاء إجراء إحالة ناجحة جديد لإكمال هذه المتطلبات الأساسية.

ضبط إعدادات وضع العلامات

اضبط "علامة التتبُّع من Google" لتفعيل ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين" باتّباع التعليمات الواردة في ضبط إعدادات "علامة التتبُّع من Google". لإعداد ميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين" باستخدام Google Tag Manager، اتّبِع تعليمات Google Tag Manager هذه.

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

في ما يلي المسار العام لاستيراد الإحالات الناجحة المحسّنة للعملاء المحتملين باستخدام Google Ads API.

  1. تسوية البيانات المقدَّمة من المستخدِم وتجزئتها، مثل عنوان البريد الإلكتروني ورقم الهاتف والعنوان البريدي

  2. املأ عناصر ClickConversion بالبيانات المقدَّمة من المستخدم بعد توحيدها وتجزئتها.

  3. استيراد عناصر ClickConversion إلى Google Ads API باستخدام ConversionUploadService يُرجى الاطّلاع على UploadClickConversions لمزيد من التفاصيل.

  4. راجِع عمليات الاستيراد.

استرداد اسم مورد إجراء الإحالة الناجحة

لتحميل الإحالات الناجحة، عليك تحديد اسم المورد الخاص بـ ConversionAction الذي أعددته في "إعلانات Google" لاستيراد الإحالات الناجحة الناتجة عن النقرات. يمكنك العثور على اسم المورد من خلال طلب البحث عن مورد conversion_action باستخدام طلب البحث التالي في لغة طلب البحث في "إعلانات Google"‏ (GAQL):

SELECT
  customer.id,
  conversion_action.id,
  conversion_action.name,
  conversion_action.type,
  conversion_action.resource_name
FROM conversion_action
WHERE conversion_action.type = 'UPLOAD_CLICKS'
  AND conversion_action.status = 'ENABLED'

تسوية البيانات المقدَّمة من المستخدم وتجزئتها

لمراعاة اعتبارات الخصوصية، يجب تجزئة البيانات التالية باستخدام SHA-256 قبل استيرادها:

  • عنوان البريد الإلكتروني
  • رقم الهاتف
  • الاسم الأول
  • اسم العائلة
  • عنوان الشارع

يجب عدم تجزئة البيانات التالية:

  • البلد
  • الولاية
  • المدينة
  • الرمز البريدي

لتوحيد نتائج التجزئة، عليك إجراء ما يلي قبل تجزئة كلّ من هذه القيم:

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

تنسيق عنوان البريد الإلكتروني لميزة "الإحالات الناجحة المحسّنة"

لضمان أعلى نسب مطابقة للإحالات الناجحة المحسّنة، عليك تنسيق عناوين البريد الإلكتروني وتجزئتها بشكل صحيح باتّباع الخطوات التالية:

  1. تطبيق التسوية العادية (جميع عناوين البريد الإلكتروني):

    • إزالة أي مسافة بيضاء بادئة ولاحقة في ASCII
    • حوِّل جميع الأحرف في عنوان البريد الإلكتروني إلى أحرف صغيرة.

  2. تطبيق التسوية الخاصة بالنطاق (gmail.com وgooglemail.com فقط):

    • بعد تحويل عنوان البريد الإلكتروني إلى أحرف صغيرة، تحقَّق مما إذا كان النطاق (بعد الرمز @) هو gmail.com أو googlemail.com.
    • إزالة النقاط (.): من جزء اسم المستخدم (قبل الرمز @)، أزِل جميع أحرف النقطة.
    • إزالة اللاحقات التي تتضمّن علامة الجمع (+): من جزء اسم المستخدم، أزِل علامة الجمع الأولى (+) وجميع الأحرف اللاحقة حتى الرمز @.
      • مثال: يصبح Jane.Doe+Shopping@googlemail.com أولاً jane.doe+shopping@googlemail.com (أحرف صغيرة)، ثم janedoe@googlemail.com (قواعد Gmail وGooglemail).
    • النطاقات الأخرى: بالنسبة إلى أي نطاق غير gmail.com أو googlemail.com، لا تُزِل النقاط أو اللاحقات التي تتضمّن علامة الجمع من اسم المستخدم. يتم تطبيق التسوية العادية فقط (إزالة المسافات البيضاء وتحويل الأحرف إلى أحرف صغيرة).
      • مثال: تتم تسوية user.name+NYC@Example.com إلى user.name+nyc@example.com.

  3. تجزئة عنوان البريد الإلكتروني العادي:

    • ترميز سلسلة البريد الإلكتروني العادية كبايتات UTF-8
    • جزِّئ وحدات بايت UTF-8 باستخدام خوارزمية SHA-256.
    • يجب تنسيق الملخّص الناتج كسلسلة سداسية عشرية بأحرف صغيرة (64 حرفًا).
import hashlib
import re


def normalize_and_hash_email(email: str) -> str:
    """Normalizes and SHA-256 hashes an email address for enhanced conversions."""
    normalized = email.strip().lower()
    parts = normalized.split("@")
    if len(parts) != 2:
        raise ValueError("Invalid email address format.")
    username, domain = parts
    if domain in ("gmail.com", "googlemail.com"):
        username = username.replace(".", "")
        username = re.sub(r"\+.*$", "", username)
    normalized = f"{username}@{domain}"
    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()

مثال على الرمز البرمجي

يوضّح هذا المثال كيفية تسوية البيانات المقدَّمة من المستخدِم وتجزئتها.

جافا

private String normalizeAndHash(MessageDigest digest, String s)
    throws UnsupportedEncodingException {
  // Normalizes by first converting all characters to lowercase, then trimming spaces.
  String normalized = s.toLowerCase();
  // Removes leading, trailing, and intermediate spaces.
  normalized = normalized.replaceAll("\\s+", "");
  // 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, Google Ads
 * requires removal of any '.' characters or trailing '+' and characters that follow it from the
 * username portion of the email address if the domain is {@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 {
  // Removes all whitespace (leading, trailing, and intermediate) from the email address.
  String normalizedEmail = emailAddress.toLowerCase().replaceAll("\\s+", "");
  String[] emailParts = normalizedEmail.split("@", 2);
  if (emailParts.length == 2 && emailParts[1].matches("^(gmail|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].replaceAll("\\.", "");
    // Removes any '+' and all characters that follow it 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);
}

/**
 * Returns the result of normalizing and hashing a phone number. For this use case, Google Ads
 * requires phone numbers to be in E.164 format.
 *
 * @param digest the digest to use to hash the normalized string.
 * @param phoneNumber the phone number to normalize and hash.
 */
private String normalizeAndHashPhoneNumber(MessageDigest digest, String phoneNumber)
    throws UnsupportedEncodingException {
  // Removes non-digit characters and prepends a leading '+' sign.
  String digitsOnly = phoneNumber.replaceAll("[^0-9]", "");
  String formattedPhone = "+" + digitsOnly;
  if (!formattedPhone.matches("^\\+[1-9]\\d{6,14}$")) {
    throw new IllegalArgumentException("Phone number must be in E.164 format: " + phoneNumber);
  }
  return normalizeAndHash(digest, formattedPhone);
}

#C

/// <summary>
/// Normalizes the email address and hashes it. For this use case, Google Ads 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();
}

PHP

private static function normalizeAndHash(string $hashAlgorithm, string $value): string
{
    // Normalizes by first converting all characters to lowercase, then trimming spaces.
    $normalized = strtolower($value);
    // Removes leading, trailing, and intermediate spaces.
    $normalized = str_replace(' ', '', $normalized);
    return hash($hashAlgorithm, strtolower(trim($normalized)));
}

/**
 * Returns the result of normalizing and hashing an email address. For this use case, Google
 * Ads requires removal of any '.' characters or trailing '+' and characters that follow it
 * from the username portion of the email address if the domain is "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 {
    // Removes all whitespace (leading, trailing, and intermediate) from the email address.
    $normalizedEmail = preg_replace('/\s+/', '', strtolower($emailAddress));
    $emailParts = explode('@', $normalizedEmail, 2);
    if (
        count($emailParts) === 2
        && preg_match('/^(gmail|googlemail)\.com$/', $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]);
        // Removes any '+' and all characters that follow it from the portion of the email
        // address before the domain if the domain is gmail.com or googlemail.com.
        $emailParts[0] = preg_replace('/\+.*/', '', $emailParts[0]);
        $normalizedEmail = sprintf('%s@%s', $emailParts[0], $emailParts[1]);
    }
    return self::normalizeAndHash($hashAlgorithm, $normalizedEmail);
}

/**
 * Returns the result of normalizing and hashing a phone number. For this use case, Google Ads
 * requires phone numbers to be in E.164 format.
 *
 * @param  string $hashAlgorithm the hash algorithm to use
 * @param  string $phoneNumber   the phone number to normalize and hash
 * @return string the normalized and hashed phone number
 * @throws \InvalidArgumentException if the phone number is not in E.164 format
 */
private static function normalizeAndHashPhoneNumber(
    string $hashAlgorithm,
    string $phoneNumber
): string {
    // Removes non-digit characters and prepends a leading '+' sign.
    $digitsOnly = preg_replace('/[^0-9]/', '', $phoneNumber);
    $formattedPhone = '+' . $digitsOnly;
    if (!preg_match('/^\+[1-9]\d{6,14}$/', $formattedPhone)) {
        throw new \InvalidArgumentException(
            "Phone number must be in E.164 format: $phoneNumber"
        );
    }
    return self::normalizeAndHash($hashAlgorithm, $formattedPhone);
}

Python

def normalize_and_hash_email_address(email_address: str) -> str:
    """Returns the result of normalizing and hashing an email address.

    For this use case, Google Ads 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: str = email_address.strip().lower()
    email_parts: list[str] = normalized_email.split("@")

    # Check that there are at least two segments
    if len(email_parts) > 1:
        # Removes any '.' and '+' characters from the portion of the email address
        # before the domain
        chars_to_remove = ".+"
        translation_table = str.maketrans("", "", chars_to_remove)
        email_parts[0] = email_parts[0].translate(translation_table)
        normalized_email = "@".join(email_parts)

    return normalize_and_hash(normalized_email)


def normalize_and_hash(s: str) -> str:
    """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 hashing.
  Digest::SHA256.hexdigest(str.strip.downcase)
end

# Returns the result of normalizing and hashing an email address. For this use
# case, Google Ads 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

Perl

sub normalize_and_hash {
  my $value = shift;

  # Removes leading, trailing, and intermediate spaces.
  $value =~ s/\s+//g;
  return sha256_hex(lc $value);
}

# Returns the result of normalizing and hashing an email address. For this use
# case, Google Ads requires removal of any '.' characters preceding 'gmail.com'
# or 'googlemail.com'.
sub normalize_and_hash_email_address {
  my $email_address = shift;

  my $normalized_email = lc $email_address;
  my @email_parts      = split('@', $normalized_email);
  if (scalar @email_parts > 1
    && $email_parts[1] =~ /^(gmail|googlemail)\.com\s*/)
  {
    # Remove any '.' characters from the portion of the email address before the
    # domain if the domain is 'gmail.com' or 'googlemail.com'.
    $email_parts[0] =~ s/\.//g;
    $normalized_email = sprintf '%s@%s', $email_parts[0], $email_parts[1];
  }
  return normalize_and_hash($normalized_email);
}

curl

ملء عناصر ClickConversion

تمثّل مجموعة عناصر ClickConversion في UploadClickConversionsRequest مجموعة الإحالات الناجحة التي تريد استيرادها. يُرجى وضع التفاصيل التالية في الاعتبار عند إنشاء عناصر ClickConversion:

gclid

معرّفات GCLID هي معرّفات يتم الحصول عليها من مَعلمات عناوين URL عندما ينقر مستخدم على إعلانك وينتقل إلى موقعك الإلكتروني.

gbraid

‫gbraid هي مَعلمة عنوان URL تظهر عندما ينقر مستخدم على إعلان على الويب ويتم توجيهه إلى تطبيق iOS.

wbraid

‫wbraid هي مَعلمة عنوان URL تظهر عندما ينقر مستخدم على إعلان في تطبيق iOS ويتم توجيهه إلى صفحة الويب الخاصة بك.

cart_data

تحتوي على تفاصيل على مستوى السلعة بشأن الإحالة الناجحة. يجب ملء حقل cart_data لإعداد تقارير عن بيانات سلة التسوّق، مثل السلع التي تم شراؤها والسعر والكمية، في واجهة مستخدم &quot;إعلانات Google&quot;. اطّلِع على تعريف العنصر CartData لمعرفة البنية المطلوبة، ومزيد من المعلومات في لمحة عن الإحالات الناجحة استنادًا إلى بيانات سلة التسوّق.

user_identifiers

عند استخدام ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين"، يجب ملء الحقل user_identifiers بالبيانات المقدَّمة من المستخدمين بعد تسويتها وتجزئتها. إذا كانت لديك معرّفات مستخدمين متعددة، أنشِئ UserIdentifier منفصلاً لكل معرّف، بحد أقصى خمسة معرّفات.

conversion_date_time

تاريخ الإحالة الناجحة ووقتها

يجب تحديد منطقة زمنية للقيمة، ويجب أن يكون التنسيق yyyy-mm-dd HH:mm:ss+|-HH:mm، على سبيل المثال: 2022-01-01 19:32:45-05:00 (مع تجاهل نظام التوقيت الصيفي) .

يمكن أن يكون النطاق الزمني أي قيمة صالحة، ولا يشترط أن يتطابق مع النطاق الزمني للحساب. ومع ذلك، إذا كنت تخطّط لمقارنة بيانات الإحالات الناجحة المستورَدة مع البيانات في واجهة مستخدم "إعلانات Google"، ننصحك باستخدام المنطقة الزمنية نفسها لحسابك على "إعلانات Google" لكي تتطابق أعداد الإحالات الناجحة. يمكنك العثور على مزيد من التفاصيل والأمثلة في مقالة إعداد البيانات للاستيراد والاطّلاع على الرموز والتنسيقات للحصول على قائمة بمعرّفات المناطق الزمنية الصالحة.

conversion_action

تمثّل هذه السمة اسم المورد الخاص ConversionAction للإحالة الناجحة غير الإلكترونية.

يجب أن يكون لإجراء الإحالة الناجحة type بقيمة UPLOAD_CLICKS، ويجب أن يكون متوفّرًا في حساب عميل الإحالة الناجحة على "إعلانات Google" المرتبط بحساب "إعلانات Google" المرتبط بالنقرة.

conversion_value

قيمة الإحالة الناجحة.

currency_code

رمز العملة الخاص بـ conversion_value

consent

ننصحك بشدة بملء حقل consent في عنصر ClickConversion. في حال عدم ضبطها، قد لا يمكن تحديد مصدر إحالاتك الناجحة.

order_id

يُعرف أيضًا باسم معرّف المعاملة للإحالة الناجحة. هذا الحقل اختياري، ولكنّنا ننصح بشدة باستخدامه لأنّه يسهّل الرجوع إلى الإحالات الناجحة المستورَدة عند إجراء تعديلات. إذا ضبطت هذا الإعداد أثناء عملية الاستيراد، عليك استخدامه لإجراء أي تعديلات. لمزيد من المعلومات عن كيفية استخدام معرِّف المعاملة لتقليل الإحالات الناجحة المكرّرة، اطّلِع على مقالة استخدام معرِّف المعاملة لتقليل الإحالات الناجحة المكرّرة.

custom_variables

قيم متغيّرات الإحالات الناجحة المخصّصة: لا تتيح "إعلانات Google" استخدام متغيّرات الإحالات الناجحة المخصّصة مع wbraid أو gbraid.

conversion_environment

تشير إلى البيئة التي تم تسجيل هذه الإحالة الناجحة فيها. على سبيل المثال، APP أو WEB.

session_attributes_encoded وsession_attributes_key_value_pairs

تمثّل سمات الجلسة المعرّفات المجمّعة المستخدَمة لتحديد مصدر الإحالات الناجحة. وتعمل هذه الميزة بالإضافة إلى معرّفات النقرة من Google ومَعلمات عناوين URL (مثل معرّفات GBRAID) والبيانات المقدَّمة من المستخدم، وهي ميزة أساسية في "الإحالات الناجحة المحسّنة للعملاء المهتمين". هناك طريقتان لاستيراد سمات الجلسة: من خلال تقديم الرمز المميّز المشفّر الذي تم إنشاؤه بواسطة رمز JavaScript في المتصفّح، أو من خلال تقديم أزواج مفتاح/قيمة فردية لكل معرّف.

لتحسين أداء حملتك إلى أقصى حدّ، ننصحك باستيراد معرّفات النقرات والبيانات المقدَّمة من المستخدِم وسمات الجلسة مع جميع إحالاتك الناجحة، إن أمكن.

جافا

// Sets one of the sessionAttributesEncoded or sessionAttributesKeyValuePairs if either is
// provided. The session attribute fields are only available to allowlisted users.
// To include these fields in conversion imports, upgrade to the Data Manager API.
if (rawRecord.containsKey("sessionAttributesEncoded")) {
  clickConversionBuilder.setSessionAttributesEncoded(
      ByteString.copyFromUtf8(rawRecord.get("sessionAttributesEncoded")));
} else if (rawRecord.containsKey("sessionAttributesMap")) {
  List<String> pairings =
      Arrays.stream(rawRecord.get("sessionAttributesMap").split(" "))
          .map(String::trim)
          .collect(Collectors.toList());
  SessionAttributesKeyValuePairs.Builder sessionAttributePairs =
      SessionAttributesKeyValuePairs.newBuilder();
  for (String pair : pairings) {
    String[] parts = pair.split("=", 2);
    if (parts.length != 2) {
      throw new IllegalArgumentException(
          "Failed to read the sessionAttributesMap. SessionAttributesMap must use a"
              + " space-delimited list of session attribute key value pairs. Each pair should"
              + " be separated by an equal sign, for example: 'gad_campaignid=12345"
              + " gad_source=1'");
    }
    sessionAttributePairs.addKeyValuePairs(
        SessionAttributeKeyValuePair.newBuilder()
            .setSessionAttributeKey(parts[0])
            .setSessionAttributeValue(parts[1])
            .build());
  }
  clickConversionBuilder.setSessionAttributesKeyValuePairs(sessionAttributePairs.build());
}

#C

// The session attribute fields are only available to allowlisted users. To
// include these fields in conversion imports, upgrade to the Data Manager API.
if (!string.IsNullOrEmpty(sessionAttributesEncoded))
{
    clickConversion.SessionAttributesEncoded =
        ByteString.CopyFrom(sessionAttributesEncoded, Encoding.Unicode);
}
else if (!string.IsNullOrEmpty(sessionAttributes))
{
    IEnumerable<SessionAttributeKeyValuePair> parsedSessionAttributes =
        sessionAttributes.Split(';').Select(pair => {
            string[] split = pair.Split('=');
            return new SessionAttributeKeyValuePair()
            {
                SessionAttributeKey = split[0],
                SessionAttributeValue = split[1]
            };
        });

    clickConversion.SessionAttributesKeyValuePairs =
        new SessionAttributesKeyValuePairs();
    clickConversion.SessionAttributesKeyValuePairs.KeyValuePairs
        .AddRange(parsedSessionAttributes);
}

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

# Set one of the session_attributes_encoded or
# session_attributes_key_value_pairs fields if either are provided.
# The session attribute fields are only available to allowlisted users.
# To include these fields in conversion imports, upgrade to the Data Manager API.
if session_attributes_encoded:
    click_conversion.session_attributes_encoded = session_attributes_encoded
elif session_attributes_dict:
    for key, value in session_attributes_dict.items():
        pair: SessionAttributeKeyValuePair = client.get_type(
            "SessionAttributeKeyValuePair"
        )
        pair.session_attribute_key = key
        pair.session_attribute_value = value
        click_conversion.session_attributes_key_value_pairs.key_value_pairs.append(
            pair
        )

Ruby

# Set one of the session_attributes_encoded or
# session_attributes_key_value_pairs fields if either are provided.
# The session attribute fields are only available to allowlisted users.
# To include these fields in conversion imports, upgrade to the Data Manager API.
if session_attributes_encoded != nil
  cc.class.module_eval { attr_accessor :session_attributes_encoded}
  cc.session_attributes_encoded = session_attributes_encoded
elsif session_attributes_hash != nil
  # Add new attribute to click conversion object
  cc.class.module_eval { attr_accessor :session_attributes_key_value_pairs}
  cc.session_attributes_key_value_pairs = ::Google::Ads::GoogleAds::V19::Services::SessionAttributesKeyValuePairs.new

  # Loop thru inputted session_attributes_hash to populate session_attributes_key_value_pairs
  session_attributes_hash.each do |key, value|
    pair = ::Google::Ads::GoogleAds::V19::Services::SessionAttributeKeyValuePair.new
    pair.session_attribute_key = key
    pair.session_attribute_value = value
    cc.session_attributes_key_value_pairs.key_value_pairs << pair
  end
end

Perl

# Set one of the session_attributes_encoded or session_attributes_key_value_pairs
# fields if either are provided.
if (defined $session_attributes_encoded) {
  $click_conversion->{sessionAttributesEncoded} = $session_attributes_encoded;
} elsif (defined $session_attributes_hash) {
  while (my ($key, $value) = each %$session_attributes_hash) {
    my $pair =
      Google::Ads::GoogleAds::V25::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}

curl

user_ip_address

عنوان IP الخاص بالعميل عند وصوله إلى الصفحة المقصودة بعد النقر على إعلان وقبل حدث إحالة ناجحة هذا هو عنوان IP لجهاز العميل، وليس لخادم المعلِن.

هذا الحقل عبارة عن سلسلة تمثّل عنوان IP بتنسيق IPv4 أو IPv6. على سبيل المثال:

  • الإصدار 4 من بروتوكول الإنترنت (IPv4): "192.0.2.0"
  • الإصدار 6 من بروتوكول الإنترنت (IPv6): "2001:0DB8:1234:5678:9999:1111:0000:0001"

مثال على الرمز

يوضّح هذا المثال كيفية ضبط البيانات المقدَّمة من المستخدِم التي تمّت تسويتها وتجزئتها على عنصر ClickConversion.

جافا

// Creates an empty builder for constructing the click conversion.
ClickConversion.Builder clickConversionBuilder = ClickConversion.newBuilder();

// Extracts user email and phone from the raw data, normalizes and hashes it, then wraps it in
// UserIdentifier objects.
// Creates a separate UserIdentifier object for each. The data in this example is hardcoded, but
// in your application you might read the raw data from an input file.

// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a
// oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE of
// hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting more
// than one of these attributes on the same UserIdentifier will clear all the other members
// of the oneof. For example, the following code is INCORRECT and will result in a
// UserIdentifier with ONLY a hashedPhoneNumber.
//
// UserIdentifier incorrectlyPopulatedUserIdentifier =
//     UserIdentifier.newBuilder()
//         .setHashedEmail("...")
//         .setHashedPhoneNumber("...")
//         .build();

ImmutableMap.Builder<String, String> rawRecordBuilder =
    ImmutableMap.<String, String>builder()
        .put("email", "alex.2+myalias@gmail.com")
        // Phone number to be converted to E.164 format, with a leading '+' as required.
        .put("phone", "+1 (800) 555-0102")
        // This example lets you put conversion details as arguments, but in reality you might
        // store this data alongside other user data, so we include it in this sample user
        // record.
        .put("conversionActionId", Long.toString(conversionActionId))
        .put("conversionDateTime", conversionDateTime)
        .put("conversionValue", Double.toString(conversionValue))
        .put("currencyCode", "USD");

// Adds entries for the optional fields.
if (orderId != null) {
  rawRecordBuilder.put("orderId", orderId);
}
if (gclid != null) {
  rawRecordBuilder.put("gclid", gclid);
}
if (adUserDataConsent != null) {
  rawRecordBuilder.put("adUserDataConsent", adUserDataConsent.name());
}
if (sessionAttributesEncoded != null) {
  rawRecordBuilder.put("sessionAttributesEncoded", sessionAttributesEncoded);
}
if (sessionAttributesMap != null) {
  rawRecordBuilder.put("sessionAttributesMap", sessionAttributesMap);
}

// Builds the map representing the record.
Map<String, String> rawRecord = rawRecordBuilder.build();

// Creates a SHA256 message digest for hashing user identifiers in a privacy-safe way, as
// described at https://support.google.com/google-ads/answer/9888656.
MessageDigest sha256Digest = MessageDigest.getInstance("SHA-256");

// Creates a list for the user identifiers.
List<UserIdentifier> userIdentifiers = new ArrayList<>();

// Creates a user identifier using the hashed email address, using the normalize and hash method
// specifically for email addresses.
UserIdentifier emailIdentifier =
    UserIdentifier.newBuilder()
        // Optional: specify the user identifier source.
        .setUserIdentifierSource(UserIdentifierSource.FIRST_PARTY)
        // Uses the normalize and hash method specifically for email addresses.
        .setHashedEmail(normalizeAndHashEmailAddress(sha256Digest, rawRecord.get("email")))
        .build();
userIdentifiers.add(emailIdentifier);

// Creates a user identifier using normalized and hashed phone info.
UserIdentifier hashedPhoneNumberIdentifier =
    UserIdentifier.newBuilder()
        .setHashedPhoneNumber(normalizeAndHashPhoneNumber(sha256Digest, rawRecord.get("phone")))
        .build();
// Adds the hashed phone number identifier to the UserData object's list.
userIdentifiers.add(hashedPhoneNumberIdentifier);

// Adds the user identifiers to the conversion.
clickConversionBuilder.addAllUserIdentifiers(userIdentifiers);

#C

// Adds a user identifier using the hashed email address, using the normalize
// and hash method specifically for email addresses.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
    HashedEmail = NormalizeAndHashEmailAddress("alex.2@example.com"),
    // Optional: Specifies the user identifier source.
    UserIdentifierSource = UserIdentifierSource.FirstParty
});

// Adds a user identifier using normalized and hashed phone info.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
    HashedPhoneNumber = NormalizeAndHash("+1 800 5550102"),
    // Optional: Specifies the user identifier source.
    UserIdentifierSource = UserIdentifierSource.FirstParty
});

// Adds a user identifier with all the required mailing address elements.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
    AddressInfo = new OfflineUserAddressInfo()
    {
        // FirstName and LastName must be normalized and hashed.
        HashedFirstName = NormalizeAndHash("Alex"),
        HashedLastName = NormalizeAndHash("Quinn"),
        // CountryCode and PostalCode are sent in plain text.
        CountryCode = "US",
        PostalCode = "94045"
    }
});

PHP

// Creates a click conversion with the specified attributes.
$clickConversion = new ClickConversion();

// Extract user email and phone from the raw data, normalize and hash it, then wrap it in
// UserIdentifier objects. Creates a separate UserIdentifier object for each.
// The data in this example is hardcoded, but in your application you might read the raw
// data from an input file.

// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a
// oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE
// of hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting
// more than one of these attributes on the same UserIdentifier will clear all the other
// members of the oneof. For example, the following code is INCORRECT and will result in a
// UserIdentifier with ONLY a hashedPhoneNumber.
//
// $incorrectlyPopulatedUserIdentifier = new UserIdentifier([
//    'hashed_email' => '...',
//    'hashed_phone_number' => '...'
// ]);

$rawRecord = [
    // Email address that includes a period (.) and plus (+) suffix before the Gmail domain.
    'email' => 'alex.2+myalias@gmail.com',
    // Phone number to be converted to E.164 format, with a leading '+' as required.
    'phone' => '+1 (800) 555-0102',
    // This example lets you input conversion details as arguments, but in reality you might
    // store this data alongside other user data, so we include it in this sample user
    // record.
    'orderId' => $orderId,
    'gclid' => $gclid,
    'conversionActionId' => $conversionActionId,
    'conversionDateTime' => $conversionDateTime,
    'conversionValue' => $conversionValue,
    'currencyCode' => 'USD',
    'adUserDataConsent' => $adUserDataConsent,
    'sessionAttributesEncoded' => $sessionAttributesEncoded,
    'sessionAttributesDict' => $sessionAttributesDict
];

// Creates a list for the user identifiers.
$userIdentifiers = [];

// Uses the SHA-256 hash algorithm for hashing user identifiers in a privacy-safe way, as
// described at https://support.google.com/google-ads/answer/9888656.
$hashAlgorithm = "sha256";

// Creates a user identifier using the hashed email address, using the normalize and hash
// method specifically for email addresses.
$emailIdentifier = new UserIdentifier(
    [
    // Uses the normalize and hash method specifically for email addresses.
    'hashed_email' => self::normalizeAndHashEmailAddress(
        $hashAlgorithm,
        $rawRecord['email']
    ),
    // Optional: Specifies the user identifier source.
    'user_identifier_source' => UserIdentifierSource::FIRST_PARTY
    ]
);
$userIdentifiers[] = $emailIdentifier;

// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (array_key_exists('phone', $rawRecord)) {
    $hashedPhoneNumberIdentifier = new UserIdentifier(
        [
        'hashed_phone_number' => self::normalizeAndHashPhoneNumber(
            $hashAlgorithm,
            $rawRecord['phone']
        )
        ]
    );
    // Adds the hashed phone number identifier to the user identifiers list.
    $userIdentifiers[] = $hashedPhoneNumberIdentifier;
}

// Adds the user identifiers to the conversion.
$clickConversion->setUserIdentifiers($userIdentifiers);

Python

# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each. The data in this example is hardcoded, but in your
# application you might read the raw data from an input file.

# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must
# set only ONE of hashed_email, hashed_phone_number, mobile_id,
# third_party_user_id, or address_info. Setting more than one of these
# attributes on the same UserIdentifier will clear all the other members of
# the oneof. For example, the following code is INCORRECT and will result in
# a UserIdentifier with ONLY a hashed_phone_number:
#
# incorrectly_populated_user_identifier = client.get_type("UserIdentifier")
# incorrectly_populated_user_identifier.hashed_email = "...""
# incorrectly_populated_user_identifier.hashed_phone_number = "...""

raw_record: Dict[str, Union[str, float]] = {
    # Email address that includes a period (.) before the Gmail domain.
    "email": "alex.2@example.com",
    # Phone number to be converted to E.164 format, with a leading '+' as
    # required.
    "phone": "+1 800 5550102",
    # This example lets you input conversion details as arguments,
    # but in reality you might store this data alongside other user data,
    # so we include it in this sample user record.
    "order_id": order_id,
    "gclid": gclid,
    "conversion_action_id": conversion_action_id,
    "conversion_date_time": conversion_date_time,
    "conversion_value": conversion_value,
    "currency_code": "USD",
    "ad_user_data_consent": ad_user_data_consent,
}

# Constructs the click conversion.
click_conversion: ClickConversion = client.get_type("ClickConversion")
# Creates a user identifier using the hashed email address, using the
# normalize and hash method specifically for email addresses.
email_identifier: UserIdentifier = client.get_type("UserIdentifier")
# Optional: Specifies the user identifier source.
email_identifier.user_identifier_source = (
    client.enums.UserIdentifierSourceEnum.FIRST_PARTY
)
# Uses the normalize and hash method specifically for email addresses.
email_identifier.hashed_email = normalize_and_hash_email_address(
    raw_record["email"]
)
# Adds the user identifier to the conversion.
click_conversion.user_identifiers.append(email_identifier)

# Checks if the record has a phone number, and if so, adds a UserIdentifier
# for it.
if raw_record.get("phone") is not None:
    phone_identifier: UserIdentifier = client.get_type("UserIdentifier")
    phone_identifier.hashed_phone_number = normalize_and_hash(
        raw_record["phone"]
    )
    # Adds the phone identifier to the conversion adjustment.
    click_conversion.user_identifiers.append(phone_identifier)

Ruby

# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each. The data in this example is hardcoded, but in your
# application you might read the raw data from an input file.

# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must
# set only ONE of hashed_email, hashed_phone_number, mobile_id,
# third_party_user_id, or address_info. Setting more than one of these
# attributes on the same UserIdentifier will clear all the other members of
# the oneof. For example, the following code is INCORRECT and will result in
# a UserIdentifier with ONLY a hashed_phone_number:
#
# incorrectly_populated_user_identifier.hashed_email = "...""
# incorrectly_populated_user_identifier.hashed_phone_number = "...""

raw_record = {
  # Email address that includes a period (.) before the Gmail domain.
  "email" => "alex.2@example.com",
  # Phone number to be converted to E.164 format, with a leading '+' as
  # required.
  "phone" => "+1 800 5550102",
  # This example lets you input conversion details as arguments,
  # but in reality you might store this data alongside other user data,
  # so we include it in this sample user record.
  "order_id" => order_id,
  "gclid" => gclid,
  "conversion_action_id" => conversion_action_id,
  "conversion_date_time" => conversion_date_time,
  "conversion_value" => conversion_value,
  "currency_code" => "USD",
  "ad_user_data_consent" => ad_user_data_consent,
  "session_attributes_encoded" => session_attributes_encoded,
  "session_attributes_hash" => session_attributes_hash
}

click_conversion = client.resource.click_conversion do |cc|
  cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
  cc.conversion_date_time = conversion_date_time
  cc.conversion_value = conversion_value.to_f
  cc.currency_code = 'USD'

  unless order_id.nil?
    cc.order_id = order_id
  end

  unless raw_record["gclid"].nil?
    cc.gclid = gclid
  end

  # Specifies whether user consent was obtained for the data you are
  # uploading. For more details, see:
  # https://www.google.com/about/company/user-consent-policy
  unless raw_record["ad_user_data_consent"].nil?
    cc.consent = client.resource.consent do |c|
      c.ad_user_data = ad_user_data_consent
    end
  end

  # Set one of the session_attributes_encoded or
  # session_attributes_key_value_pairs fields if either are provided.
  # The session attribute fields are only available to allowlisted users.
  # To include these fields in conversion imports, upgrade to the Data Manager API.
  if session_attributes_encoded != nil
    cc.class.module_eval { attr_accessor :session_attributes_encoded}
    cc.session_attributes_encoded = session_attributes_encoded
  elsif session_attributes_hash != nil
    # Add new attribute to click conversion object
    cc.class.module_eval { attr_accessor :session_attributes_key_value_pairs}
    cc.session_attributes_key_value_pairs = ::Google::Ads::GoogleAds::V19::Services::SessionAttributesKeyValuePairs.new

    # Loop thru inputted session_attributes_hash to populate session_attributes_key_value_pairs
    session_attributes_hash.each do |key, value|
      pair = ::Google::Ads::GoogleAds::V19::Services::SessionAttributeKeyValuePair.new
      pair.session_attribute_key = key
      pair.session_attribute_value = value
      cc.session_attributes_key_value_pairs.key_value_pairs << pair
    end
  end    

  # Creates a user identifier using the hashed email address, using the
  # normalize and hash method specifically for email addresses.
  # If using a phone number, use the normalize_and_hash method instead.
  cc.user_identifiers << client.resource.user_identifier do |ui|
    ui.hashed_email = normalize_and_hash_email(raw_record["email"])
    # Optional: Specifies the user identifier source.
    ui.user_identifier_source = :FIRST_PARTY
  end

  # Checks if the record has a phone number, and if so, adds a UserIdentifier
  # for it.
  unless raw_record["phone"].nil?
    cc.user_identifiers << client.resource.user_identifier do |ui|
      ui.hashed_phone_number = normalize_and_hash(raw_record["phone"])
    end
  end
end

Perl

# Create an empty click conversion.
my $click_conversion =
  Google::Ads::GoogleAds::V25::Services::ConversionUploadService::ClickConversion
  ->new({});

# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each.
# The data in this example is hardcoded, but in your application
# you might read the raw data from an input file.
#
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set
# only ONE of hashed_email, hashed_phone_number, mobile_id, third_party_user_id,
# or address-info. Setting more than one of these attributes on the same UserIdentifier
# will clear all the other members of the oneof. For example, the following code is
# INCORRECT and will result in a UserIdentifier with ONLY a hashed_phone_number:
#
# my $incorrect_user_identifier = Google::Ads::GoogleAds::V25::Common::UserIdentifier->new({
#   hashedEmail => '...',
#   hashedPhoneNumber => '...',
# });
my $raw_record = {
  # Email address that includes a period (.) before the Gmail domain.
  email => 'alex.2@example.com',
  # Phone number to be converted to E.164 format, with a leading '+' as
  # required.
  phone => '+1 800 5550102',
  # This example lets you input conversion details as arguments,
  # but in reality you might store this data alongside other user data,
  # so we include it in this sample user record.
  orderId            => $order_id,
  gclid              => $gclid,
  conversionActionId => $conversion_action_id,
  conversionDateTime => $conversion_date_time,
  conversionValue    => $conversion_value,
  currencyCode       => "USD",
  adUserDataConsent  => $ad_user_data_consent
};
my $user_identifiers = [];

# Create a user identifier using the hashed email address, using the normalize
# and hash method specifically for email addresses.
my $hashed_email = normalize_and_hash_email_address($raw_record->{email});
push(
  @$user_identifiers,
  Google::Ads::GoogleAds::V25::Common::UserIdentifier->new({
      hashedEmail => $hashed_email,
      # Optional: Specify the user identifier source.
      userIdentifierSource => FIRST_PARTY
    }));

# Create a user identifier using normalized and hashed phone info.
my $hashed_phone = normalize_and_hash($raw_record->{phone});
push(
  @$user_identifiers,
  Google::Ads::GoogleAds::V25::Common::UserIdentifier->new({
      hashedPhone => $hashed_phone,
      # Optional: Specify the user identifier source.
      userIdentifierSource => FIRST_PARTY
    }));

# Add the user identifiers to the conversion.
$click_conversion->{userIdentifiers} = $user_identifiers;

curl

يوضّح هذا المثال كيفية ضبط الحقول الضرورية الأخرى في عنصر ClickConversion.

جافا

// Adds details of the conversion.
clickConversionBuilder.setConversionAction(
    ResourceNames.conversionAction(
        customerId, Long.parseLong(rawRecord.get("conversionActionId"))));
clickConversionBuilder.setConversionDateTime(rawRecord.get("conversionDateTime"));
clickConversionBuilder.setConversionValue(Double.parseDouble(rawRecord.get("conversionValue")));
clickConversionBuilder.setCurrencyCode(rawRecord.get("currencyCode"));

// Sets the order ID if provided.
if (rawRecord.containsKey("orderId")) {
  clickConversionBuilder.setOrderId(rawRecord.get("orderId"));
}

// Sets the Google click ID (gclid) if provided.
if (rawRecord.containsKey("gclid")) {
  clickConversionBuilder.setGclid(rawRecord.get("gclid"));
}

// Sets the consent information, if provided.
if (rawRecord.containsKey("adUserDataConsent")) {
  // Specifies whether user consent was obtained for the data you are uploading. See
  // https://www.google.com/about/company/user-consent-policy for details.
  clickConversionBuilder.setConsent(
      Consent.newBuilder()
          .setAdUserData(ConsentStatus.valueOf(rawRecord.get("adUserDataConsent"))));
}

// Sets one of the sessionAttributesEncoded or sessionAttributesKeyValuePairs if either is
// provided. The session attribute fields are only available to allowlisted users.
// To include these fields in conversion imports, upgrade to the Data Manager API.
if (rawRecord.containsKey("sessionAttributesEncoded")) {
  clickConversionBuilder.setSessionAttributesEncoded(
      ByteString.copyFromUtf8(rawRecord.get("sessionAttributesEncoded")));
} else if (rawRecord.containsKey("sessionAttributesMap")) {
  List<String> pairings =
      Arrays.stream(rawRecord.get("sessionAttributesMap").split(" "))
          .map(String::trim)
          .collect(Collectors.toList());
  SessionAttributesKeyValuePairs.Builder sessionAttributePairs =
      SessionAttributesKeyValuePairs.newBuilder();
  for (String pair : pairings) {
    String[] parts = pair.split("=", 2);
    if (parts.length != 2) {
      throw new IllegalArgumentException(
          "Failed to read the sessionAttributesMap. SessionAttributesMap must use a"
              + " space-delimited list of session attribute key value pairs. Each pair should"
              + " be separated by an equal sign, for example: 'gad_campaignid=12345"
              + " gad_source=1'");
    }
    sessionAttributePairs.addKeyValuePairs(
        SessionAttributeKeyValuePair.newBuilder()
            .setSessionAttributeKey(parts[0])
            .setSessionAttributeValue(parts[1])
            .build());
  }
  clickConversionBuilder.setSessionAttributesKeyValuePairs(sessionAttributePairs.build());
}

// Calls build to build the conversion.
ClickConversion clickConversion = clickConversionBuilder.build();

#C

// Adds details of the conversion.
clickConversion.ConversionAction =
    ResourceNames.ConversionAction(customerId, conversionActionId);
clickConversion.ConversionDateTime = conversionDateTime;
clickConversion.ConversionValue = conversionValue;
clickConversion.CurrencyCode = "USD";

// Sets the order ID if provided.
if (!string.IsNullOrEmpty(orderId))
{
    clickConversion.OrderId = orderId;
}

// Sets the Google click ID (gclid) if provided.
if (!string.IsNullOrEmpty(gclid))
{
    clickConversion.Gclid = gclid;
}

// The session attribute fields are only available to allowlisted users. To
// include these fields in conversion imports, upgrade to the Data Manager API.
if (!string.IsNullOrEmpty(sessionAttributesEncoded))
{
    clickConversion.SessionAttributesEncoded =
        ByteString.CopyFrom(sessionAttributesEncoded, Encoding.Unicode);
}
else if (!string.IsNullOrEmpty(sessionAttributes))
{
    IEnumerable<SessionAttributeKeyValuePair> parsedSessionAttributes =
        sessionAttributes.Split(';').Select(pair => {
            string[] split = pair.Split('=');
            return new SessionAttributeKeyValuePair()
            {
                SessionAttributeKey = split[0],
                SessionAttributeValue = split[1]
            };
        });

    clickConversion.SessionAttributesKeyValuePairs =
        new SessionAttributesKeyValuePairs();
    clickConversion.SessionAttributesKeyValuePairs.KeyValuePairs
        .AddRange(parsedSessionAttributes);
}

PHP

// Adds details of the conversion.
$clickConversion->setConversionAction(
    ResourceNames::forConversionAction($customerId, $rawRecord['conversionActionId'])
);
$clickConversion->setConversionDateTime($rawRecord['conversionDateTime']);
$clickConversion->setConversionValue($rawRecord['conversionValue']);
$clickConversion->setCurrencyCode($rawRecord['currencyCode']);

// Sets the order ID if provided.
if (!empty($rawRecord['orderId'])) {
    $clickConversion->setOrderId($rawRecord['orderId']);
}

// Sets the Google click ID (gclid) if provided.
if (!empty($rawRecord['gclid'])) {
    $clickConversion->setGclid($rawRecord['gclid']);
}

// Sets the ad user data consent if provided.
if (!empty($rawRecord['adUserDataConsent'])) {
    // Specifies whether user consent was obtained for the data you are uploading. See
    // https://www.google.com/about/company/user-consent-policy for details.
    $clickConversion->setConsent(
        new Consent(['ad_user_data' => $rawRecord['adUserDataConsent']])
    );
}

// Set one of the sessionAttributesEncoded or
// SessionAttributeKeyValuePair fields if either are provided. The session attribute
// fields are only available to allowlisted users. To include these fields in conversion
// imports, upgrade to the Data Manager API.
if (!empty($sessionAttributesEncoded)) {
    $clickConversion->setSessionAttributesEncoded($sessionAttributesEncoded);
} elseif (!empty($sessionAttributesDict)) {
    // Create a new container object to hold key-value pairs.
    $sessionAttributesKeyValuePairs = new SessionAttributesKeyValuePairs();
    // Initialize an array to hold individual key-value pair messages.
    $keyValuePairs = [];
    // Append each key-value pair provided to the $keyValuePairs array
    foreach ($sessionAttributesDict as $key => $value) {
        $pair = new SessionAttributeKeyValuePair();
        $pair->setSessionAttributeKey($key);
        $pair->setSessionAttributeValue($value);
        $keyValuePairs[] = $pair;
    }
    // Set the the full list of key-value pairs on the container object.
    $sessionAttributesKeyValuePairs->setKeyValuePairs($keyValuePairs);
    // Attach the container of key-value pairs to the ClickConversion object.
    $clickConversion->setSessionAttributesKeyValuePairs($sessionAttributesKeyValuePairs);
}

Python

# Add details of the conversion.
# Gets the conversion action resource name.
conversion_action_service: ConversionActionServiceClient = (
    client.get_service("ConversionActionService")
)
click_conversion.conversion_action = (
    conversion_action_service.conversion_action_path(
        customer_id, raw_record["conversion_action_id"]
    )
)
click_conversion.conversion_date_time = raw_record["conversion_date_time"]
click_conversion.conversion_value = raw_record["conversion_value"]
click_conversion.currency_code = raw_record["currency_code"]

# Sets the order ID if provided.
if raw_record.get("order_id"):
    click_conversion.order_id = raw_record["order_id"]

# Sets the gclid if provided.
if raw_record.get("gclid"):
    click_conversion.gclid = raw_record["gclid"]

# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
if raw_record["ad_user_data_consent"]:
    click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
        raw_record["ad_user_data_consent"]
    ]

# Set one of the session_attributes_encoded or
# session_attributes_key_value_pairs fields if either are provided.
# The session attribute fields are only available to allowlisted users.
# To include these fields in conversion imports, upgrade to the Data Manager API.
if session_attributes_encoded:
    click_conversion.session_attributes_encoded = session_attributes_encoded
elif session_attributes_dict:
    for key, value in session_attributes_dict.items():
        pair: SessionAttributeKeyValuePair = client.get_type(
            "SessionAttributeKeyValuePair"
        )
        pair.session_attribute_key = key
        pair.session_attribute_value = value
        click_conversion.session_attributes_key_value_pairs.key_value_pairs.append(
            pair
        )

Ruby

cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
cc.conversion_date_time = conversion_date_time
cc.conversion_value = conversion_value.to_f
cc.currency_code = 'USD'

unless order_id.nil?
  cc.order_id = order_id
end

unless raw_record["gclid"].nil?
  cc.gclid = gclid
end

# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
unless raw_record["ad_user_data_consent"].nil?
  cc.consent = client.resource.consent do |c|
    c.ad_user_data = ad_user_data_consent
  end
end

# Set one of the session_attributes_encoded or
# session_attributes_key_value_pairs fields if either are provided.
# The session attribute fields are only available to allowlisted users.
# To include these fields in conversion imports, upgrade to the Data Manager API.
if session_attributes_encoded != nil
  cc.class.module_eval { attr_accessor :session_attributes_encoded}
  cc.session_attributes_encoded = session_attributes_encoded
elsif session_attributes_hash != nil
  # Add new attribute to click conversion object
  cc.class.module_eval { attr_accessor :session_attributes_key_value_pairs}
  cc.session_attributes_key_value_pairs = ::Google::Ads::GoogleAds::V19::Services::SessionAttributesKeyValuePairs.new

  # Loop thru inputted session_attributes_hash to populate session_attributes_key_value_pairs
  session_attributes_hash.each do |key, value|
    pair = ::Google::Ads::GoogleAds::V19::Services::SessionAttributeKeyValuePair.new
    pair.session_attribute_key = key
    pair.session_attribute_value = value
    cc.session_attributes_key_value_pairs.key_value_pairs << pair
  end
end

Perl

# Add details of the conversion.
$click_conversion->{conversionAction} =
  Google::Ads::GoogleAds::V25::Utils::ResourceNames::conversion_action(
  $customer_id, $raw_record->{conversionActionId});
$click_conversion->{conversionDateTime} = $raw_record->{conversionDateTime};
$click_conversion->{conversionValue}    = $raw_record->{conversionValue};
$click_conversion->{currencyCode}       = $raw_record->{currencyCode};

# Set the order ID if provided.
if (defined $raw_record->{orderId}) {
  $click_conversion->{orderId} = $raw_record->{orderId};
}

# Set the Google click ID (gclid) if provided.
if (defined $raw_record->{gclid}) {
  $click_conversion->{gclid} = $raw_record->{gclid};
}

# Set the consent information, if provided.
if (defined $raw_record->{adUserDataConsent}) {
  $click_conversion->{consent} =
    Google::Ads::GoogleAds::V25::Common::Consent->new({
      adUserData => $raw_record->{adUserDataConsent}});
}

# Set one of the session_attributes_encoded or session_attributes_key_value_pairs
# fields if either are provided.
if (defined $session_attributes_encoded) {
  $click_conversion->{sessionAttributesEncoded} = $session_attributes_encoded;
} elsif (defined $session_attributes_hash) {
  while (my ($key, $value) = each %$session_attributes_hash) {
    my $pair =
      Google::Ads::GoogleAds::V25::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}

curl

إنشاء الطلب

بعد ضبط عناصر ClickConversion وإضافتها إلى حقل conversions في عنصر UploadClickConversionsRequest، اضبط الحقول التالية وأرسِل الطلب إلى طريقة UploadClickConversions في ConversionUploadService.

customer_id
اضبط هذا الحقل على عميل الإحالة الناجحة في "إعلانات Google" الخاص بالحساب الذي يمثّل مصدر النقرات. إذا لم تكن متأكدًا من الحساب الصحيح، يُرجى الرجوع إلى حقل customer.conversion_tracking_setting.google_ads_conversion_customer في نموذج طلب البحث في قسم البدء.
job_id

توفير آلية لربط طلبات الاستيراد بمعلومات كل مهمة في أداة تشخيص البيانات غير الإلكترونية

في حال عدم ضبط هذا الحقل، ستعيّن Google Ads API لكل طلب قيمة فريدة في نطاق [2^31, 2^63). إذا كنت تفضّل تجميع طلبات متعددة في مهمة منطقية واحدة، اضبط هذا الحقل على القيمة نفسها في النطاق [0, 2^31) لكل طلب في مهمتك.

يحتوي الحقل job_id في الاستجابة على رقم تعريف الوظيفة للطلب، بغض النظر عمّا إذا كنت قد حدّدت قيمة أو سمحت لواجهة Google Ads API بتعيين قيمة.

partial_failure

يجب ضبط هذا الحقل على true عند استيراد الإحالات الناجحة. اتّبِع إرشادات حالات الإخفاق الجزئي عند معالجة الاستجابة.

استيراد الطلب

بعد ملء عناصر ClickConversion وإنشاء طلبك، يمكنك إرسال عملية الاستيراد.

جافا

// Creates the conversion upload service client.
try (ConversionUploadServiceClient conversionUploadServiceClient =
    googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
  // Uploads the click conversion. Partial failure should always be set to true.

  // NOTE: This request contains a single conversion as a demonstration.  However, if you have
  // multiple conversions to upload, it's best to upload multiple conversions per request
  // instead of sending a separate request per conversion. See the following for per-request
  // limits:
  // https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
  UploadClickConversionsResponse response =
      conversionUploadServiceClient.uploadClickConversions(
          UploadClickConversionsRequest.newBuilder()
              .setCustomerId(Long.toString(customerId))
              .addConversions(clickConversion)
              // Enables partial failure (must be true).
              .setPartialFailure(true)
              .build());

#C

// Uploads the click conversion. Partial failure should always be set to true.
// NOTE: This request contains a single conversion as a demonstration.
// However, if you have multiple conversions to upload, it's best to upload multiple
// conversions per request instead of sending a separate request per conversion.
// See the following for per-request limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload
UploadClickConversionsResponse response =
    conversionUploadService.UploadClickConversions(
        new UploadClickConversionsRequest()
        {
            CustomerId = customerId.ToString(),
            Conversions = { clickConversion },
            // Enables partial failure (must be true).
            PartialFailure = true
        });

PHP

// Issues a request to upload the click conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
// NOTE: This request contains a single conversion as a demonstration.  However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
$response = $conversionUploadServiceClient->uploadClickConversions(
    // Enables partial failure (must be true).
    UploadClickConversionsRequest::build($customerId, [$clickConversion], true)
);

Python

# Creates the conversion upload service client.
conversion_upload_service: ConversionUploadServiceClient = (
    client.get_service("ConversionUploadService")
)
# Uploads the click conversion. Partial failure should always be set to
# True.
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's most efficient to upload them in a
# single request. See the following for per-request limits for reference:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
response: UploadClickConversionsResponse = (
    conversion_upload_service.upload_click_conversions(
        customer_id=customer_id,
        conversions=[click_conversion],
        # Enables partial failure (must be true).
        partial_failure=True,
    )
)

Ruby

response = client.service.conversion_upload.upload_click_conversions(
  customer_id: customer_id,
  conversions: [click_conversion],
  # Partial failure must be true.
  partial_failure: true,
)

if response.partial_failure_error
  puts "Partial failure encountered: #{response.partial_failure_error.message}"
else
  result = response.results.first
  puts "Uploaded click conversion that happened at #{result.conversion_date_time} " \
    "to #{result.conversion_action}."
end

Perl

# Upload the click conversion. Partial failure should always be set to true.
#
# NOTE: This request contains a single conversion as a demonstration.
# However, if you have multiple conversions to upload, it's best to
# upload multiple conversions per request instead of sending a separate
# request per conversion. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
my $response =
  $api_client->ConversionUploadService()->upload_click_conversions({
    customerId  => $customer_id,
    conversions => [$click_conversion],
    # Enable partial failure (must be true).
    partialFailure => "true"
  });

curl

مراجعة عمليات الاستيراد

استخدِم تقرير تشخيص الإحالات الناجحة المحسّنة للعملاء المحتملين لمراجعة الحالة العامة لعمليات الاستيراد الأخيرة.

تظهر الإحالات الناجحة المستورَدة في التقارير الخاصة بتاريخ ظهور النقرة الأصلية، وليس تاريخ طلب الاستيراد أو تاريخ conversion_date_time ClickConversion.

يستغرق ظهور إحصاءات الإحالات الناجحة المستورَدة في حسابك على "إعلانات Google" مدة تصل إلى ثلاث ساعات لتحديد المصدر بالاستناد إلى النقرة الأخيرة. بالنسبة إلى نماذج تحديد المصدر الأخرى على شبكة البحث، يمكن أن يستغرق ذلك أكثر من ثلاث ساعات. يمكنك الاطّلاع على دليل سرعة توفُّر البيانات لمزيد من المعلومات.

عند إعداد تقارير عن مقاييس الإحالات الناجحة لحملاتك، ارجع إلى ربط مقاييس واجهة المستخدِم لربط مقاييس واجهة مستخدِم "إعلانات Google" بحقول إعداد تقارير Google Ads API. يمكنك أيضًا الاستعلام عن مورد conversion_action لعرض إجمالي عدد الإحالات الناجحة وإجمالي قيمة الإحالة الناجحة لإجراء إحالة ناجحة معيّن.

أفضل الممارسات

يُرجى مراعاة أفضل الممارسات التالية عند تنفيذ ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين".

إرسال جميع بيانات الإحالات الناجحة بغض النظر عن اكتمالها

لضمان إعداد تقارير إحالات ناجحة كاملة ودقيقة، استورِد جميع أحداث الإحالات الناجحة غير الإلكترونية المتاحة، بما في ذلك تلك التي قد لا تكون واردة من "إعلانات Google". تظلّ الإحالات الناجحة التي تتضمّن البيانات المقدَّمة من المستخدم فقط مفيدة ويمكن أن تساهم بشكل إيجابي في تحسين الحملات على "إعلانات Google".

إذا حدّدت order_id لإحالة ناجحة، ننصحك بتضمينها. إذا كان لديك معرّف النقرة من Google لإحالة ناجحة، ننصحك بإرساله بالإضافة إلى user_identifiers لتحسين الأداء. بالإضافة إلى ذلك، إذا كان لديك أكثر من UserIdentifier واحد للإحالة الناجحة، يجب تضمينها جميعًا في عنصر ClickConversion لزيادة احتمالية العثور على مطابقة.

تجميع إحالات ناجحة متعددة في طلب واحد

إذا كان لديك عدّة إحالات ناجحة تريد استيرادها، يمكنك تجميعها في UploadClickConversionsRequest واحد بدلاً من إرسال طلب استيراد لكل إحالة ناجحة.

يُرجى مراجعة دليل الحصص لمعرفة الحدود القصوى لعدد الإحالات الناجحة لكل طلب.

إذا أردت أن تجمع بيانات تشخيص البيانات غير الإلكترونية مجموعة من الطلبات ضمن المهمة المنطقية نفسها، اضبط job_id لجميع الطلبات على القيمة نفسها. يمكن أن يكون ذلك مفيدًا إذا كان لديك مهمة أو عملية واحدة تستورد عددًا كبيرًا من الإحالات الناجحة باستخدام طلبات متعددة. إذا ضبطت قيمة job_id على القيمة نفسها في كل طلب من هذه الطلبات، يمكنك استرداد إدخال واحد للوظيفة من job_summaries. في المقابل، إذا سمحت لـ Google Ads API بتعيين قيمة من إنشاء النظام لكل job_id في كل طلب، سيتضمّن job_summaries إدخالاً منفصلاً لكل طلب، ما قد يجعل تحليل الحالة العامة لمهمتك أكثر صعوبة.

عدم استخدام بيانات تحديد المصدر الخارجي

عند استخدام ميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين"، لا تضبط external_attribution_data على ClickConversion أو تحدّد conversion_action يستخدم نموذج تحديد مصدر خارجي. لا تتيح "إعلانات Google" الإحالات الناجحة المحدّدة المصدر خارجيًا لعمليات الاستيراد التي تستخدم البيانات المقدَّمة من المستخدم.

عدم تضمين المتغيّرات المخصّصة

عند استخدام ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين"، لا تُدرِج أيًّا من custom_variables. لا تتيح "إعلانات Google" استخدام المتغيّرات المخصّصة مع البيانات المقدَّمة من المستخدِم في عمليات استيراد الإحالات الناجحة. إذا تم تضمين المتغيّرات المخصّصة مع الإحالات الناجحة التي تحتوي على بيانات مقدَّمة من المستخدم، سيتم اعتبار هذه الإحالات الناجحة غير صالحة وسيتم تجاهلها.

تحديد المشاكل وحلّها

توفّر أدوات تشخيص البيانات غير الإلكترونية مرجعًا واحدًا لمراجعة الحالة العامة لعمليات الاستيراد بشكل مستمر. ومع ذلك، يمكنك أثناء التنفيذ استخدام المعلومات الواردة في هذا القسم للتحقيق في أي أخطاء تم الإبلاغ عنها في حقل partial_failure_error الخاص بالاستجابة.

بعض الأخطاء الأكثر شيوعًا عند استيراد إجراءات الإحالات الناجحة هي أخطاء التفويض، مثل USER_PERMISSION_DENIED. يُرجى التأكّد من أنّ رقم تعريف العميل في طلبك مضبوط على عميل الإحالة الناجحة في "إعلانات Google" الذي يملك إجراء الإحالة الناجحة. يُرجى الانتقال إلى دليل التفويض لمزيد من التفاصيل، والاطّلاع على دليل الأخطاء الشائعة للحصول على نصائح حول كيفية تصحيح هذه الأخطاء المختلفة.

تصحيح الأخطاء الشائعة

تساعدك الإرشادات التالية في تشخيص الأخطاء الشائعة وإصلاحها في ما يتعلّق بميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين".

خطأ
NO_CONVERSION_ACTION_FOUND

إجراء الإحالة الناجحة المحدّد إما غير مفعَّل أو لا يمكن الوصول إليه من خلال حساب العميل المحدّد في الحقل customer_id في الطلب. تأكَّد من أنّ إجراء الإحالة الناجحة في عملية التحميل مفعَّل ومملوك للعميل الذي يرسل طلب التحميل.

قد يحدث هذا الخطأ أيضًا إذا كانت معلمة GCLID في الطلب تنتمي إلى حساب عميل لا يمكنه الوصول إلى إجراء الإحالة الناجحة المحدّد في الطلب. يمكنك التحقّق مما إذا كان معرّف النقرة من Google ‏(GCLID) ينتمي إلى حساب عميل باستخدام المورد click_view، وذلك عن طريق إرسال طلب بحث تتم فلترته حسب click_view.gclid وsegments.date، حيث يكون التاريخ هو تاريخ حدوث النقرة.

INVALID_CONVERSION_ACTION_TYPE نوع إجراء الإحالة الناجحة المحدّد غير صالح لميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين". تأكَّد من أنّ السمة ConversionAction المحدّدة في طلب التحميل من النوع UPLOAD_CLICKS.
CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS تأكَّد من تفعيل ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين" في إعدادات الإحالات الناجحة. يمكنك العثور على تعليمات حول ذلك في دليل المتطلبات الأساسية.
DUPLICATE_ORDER_ID تتضمّن الأحداث المستورَدة إحالات ناجحة متعددة بمعرّف الطلب نفسه ولم تتم معالجتها. يُرجى التأكّد من أنّ معرّفات الطلبات فريدة، ثم إعادة المحاولة.
CLICK_NOT_FOUND لم يتم العثور على أي نقرة تطابق معرّفات المستخدمين المقدَّمة.

إذا واجهت إحالة ناجحة هذا التحذير، ستضمّنها Google Ads API في successful_event_count من بيانات تشخيص الإحالات الناجحة غير الإلكترونية. تتضمّن Google Ads API إدخالاً لـ CLICK_NOT_FOUND في مجموعة alerts لتتمكّن من تتبُّع معدّل تكرار هذا التحذير.

من المتوقّع حدوث هذا الخطأ إذا لم تكن النقرة واردة من حملة على "إعلانات Google". على سبيل المثال، قد تأتي من SA360 أو DV360. في ما يلي الأسباب المحتملة الأخرى:

في الحالات النادرة التي يختلف فيها العميل الذي يحمّل البيانات عن عميل الإحالة الناجحة في "إعلانات Google"، قد يعني هذا الخطأ أنّ العميل الذي يحمّل البيانات قد وافق على أحكام بيانات العملاء، ولكنّ العميل الذي يعرض الإعلانات لم يوافق عليها.

يمكنك تحديد ما إذا كان الحساب قد قبل بنود بيانات العملاء من خلال طلب البحث عن مورد customer والتحقّق من الحقل customer.conversion_tracking_setting.accepted_customer_data_terms.
السابق
بدء استخدام الإحالات الناجحة
التالي
إدارة الإحالات الناجحة على الإنترنت