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

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

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

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

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

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

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

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

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

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

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

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

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

SELECT
  customer.id,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enhanced_conversions_for_leads_enabled
FROM customer

إذا كانت قيمة أيّ من accepted_customer_data_terms أو enhanced_conversions_for_leads_enabled هي false، اتّبِع التعليمات الواردة في مركز المساعدة لإكمال هذه المتطلبات الأساسية.

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

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

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

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

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

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

  3. استيراد عناصر ClickConversion إلى Google Ads API باستخدام ConversionUploadService

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

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

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

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

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

  • إزالة المسافات البيضاء البادئة واللاحقة
  • تحويل النص إلى أحرف لاتينية صغيرة
  • تنسيق أرقام الهواتف وفقًا لمعيار E164
  • إزالة جميع النقاط (.) التي تسبق اسم النطاق في عناوين البريد الإلكتروني gmail.com وgooglemail.com

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

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

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

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

Java

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 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);
}
UploadEnhancedConversionsForLeads.java

#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();
}
UploadEnhancedConversionsForLeads.cs

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 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);
}
UploadEnhancedConversionsForLeads.php

Python

def normalize_and_hash_email_address(email_address):
    """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 = email_address.strip().lower()
    email_parts = normalized_email.split("@")

    # Check that there are at least two segments
    if len(email_parts) > 1:
        # 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.
        if re.match(r"^(gmail|googlemail)\.com$", email_parts[1]):
            # 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()
upload_enhanced_conversions_for_leads.py

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
upload_enhanced_conversions_for_leads.rb

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);
}
upload_enhanced_conversions_for_leads.pl

ملء عناصر ClickConversion

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

gclid

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

user_identifiers

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

conversion_date_time

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

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

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

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 وGBRAID) والبيانات المقدّمة من المستخدِم، والتي تشكّل أساس ميزة "الإحالات الناجحة المحسّنة للعملاء المحتملين". هناك طريقتان لاستيراد سمات الجلسة: من خلال تقديم الرمز المميّز المشفّر الذي تم إنشاؤه بواسطة رمز JavaScript في المتصفّح، أو من خلال تقديم أزواج قيم مفاتيح فردية لكل معرّف.

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

Java

// Sets one of the sessionAttributesEncoded or sessionAttributesKeyValuePairs if either is
// provided.
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());
}
UploadEnhancedConversionsForLeads.java

#C

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);
}
UploadEnhancedConversionsForLeads.cs

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.
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 = 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
        )
upload_enhanced_conversions_for_leads.py

Ruby

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

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::V20::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}
upload_enhanced_conversions_for_leads.pl

user_ip_address

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

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

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

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

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

Java

// 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@example.com")
        // Phone number to be converted to E.164 format, with a leading '+' as required.
        .put("phone", "+1 800 5550102")
        // 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(normalizeAndHash(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);
UploadEnhancedConversionsForLeads.java

#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"
    }
});
UploadEnhancedConversionsForLeads.cs

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 (.) 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' => $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::normalizeAndHash(
            $hashAlgorithm,
            $rawRecord['phone'],
            true
        )
    ]);
    // Adds the hashed email identifier to the user identifiers list.
    $userIdentifiers[] = $hashedPhoneNumberIdentifier;
}

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

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 = {
    # 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 = 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 = 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 = 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)
upload_enhanced_conversions_for_leads.py

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.
  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
upload_enhanced_conversions_for_leads.rb

Perl

# Create an empty click conversion.
my $click_conversion =
  Google::Ads::GoogleAds::V20::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::V20::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::V20::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::V20::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;
upload_enhanced_conversions_for_leads.pl

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

Java

// 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.
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();
UploadEnhancedConversionsForLeads.java

#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;
}

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);
}

UploadEnhancedConversionsForLeads.cs

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.
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);
}
UploadEnhancedConversionsForLeads.php

Python

# Add details of the conversion.
# Gets the conversion action resource name.
conversion_action_service = 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.
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 = 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
        )
upload_enhanced_conversions_for_leads.py

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.
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    
upload_enhanced_conversions_for_leads.rb

Perl

# Add details of the conversion.
$click_conversion->{conversionAction} =
  Google::Ads::GoogleAds::V20::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::V20::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::V20::Services::ConversionUploadService::SessionAttributeKeyValuePair
      ->new({sessionAttributeKey => $key, sessionAttributeValue => $value});
    push @{$click_conversion->{sessionAttributesKeyValuePairs}{keyValuePairs}
    }, $pair;
  }
}
upload_enhanced_conversions_for_leads.pl

إنشاء الطلب

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

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

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

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

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

partial_failure

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

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

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

Java

// 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());
UploadEnhancedConversionsForLeads.java

#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
        });

UploadEnhancedConversionsForLeads.cs

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)
);
UploadEnhancedConversionsForLeads.php

Python

# Creates the conversion upload service client.
conversion_upload_service = 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 = conversion_upload_service.upload_click_conversions(
    customer_id=customer_id,
    conversions=[click_conversion],
    # Enables partial failure (must be true).
    partial_failure=True,
)
upload_enhanced_conversions_for_leads.py

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
upload_enhanced_conversions_for_leads.rb

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"
  });
upload_enhanced_conversions_for_leads.pl

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

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

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

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

عند إعداد تقارير عن مقاييس الإحالات الناجحة لحملاتك، يُرجى الرجوع إلى ربط مقاييس واجهة المستخدم لربط مقاييس واجهة المستخدم في "إعلانات 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

إجراء الإحالة الناجحة المحدّد غير مفعَّل أو لا يمكن لحساب العميل المحدّد من خلال الحقل `client_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 هذا الخطأ إلا إذا كانت قيمة debug_enabled هي true في UploadClickConversionsRequest.

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

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

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

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