مدیریت تبدیل‌های آفلاین

می‌توانید از Google Ads API برای وارد کردن تبدیل‌های آفلاین به Google Ads استفاده کنید تا آگهی‌هایی را که منجر به فروش در دنیای آفلاین شده‌اند، مانند فروش تلفنی یا ازطریق نماینده فروش، ردیابی کنید.

برای بهره‌مندی کامل از مزایای وارد کردن داده‌های تبدیل، توصیه می‌کنیم تبدیل‌های بهبودیافته را برای مشتریان بالقوه پیاده‌سازی کنید، که از GCLID و داده‌های ارائه‌شده توسط کاربر برای به‌حداکثر رساندن ماندگاری و عملکرد استفاده می‌کند.

تبدیل‌های بهبودیافته

تبدیل‌های بهبودیافته به شما کمک می‌کند تا دقت سنجش تبدیل خود را با تکمیل کردن تبدیل‌هایتان با داده‌های تبدیل طرف اول، مانند نشانی ایمیل، شماره تلفن، و نشانی پستی، بهبود دهید.

دو نوع تبدیل بهبودیافته وجود دارد. برای جزئیات بیشتر، درباره تبدیل‌های بهبودیافته را ببینید.

بخش زیر نحوه بهبود تبدیل‌های آفلاین را توضیح می‌دهد، ویژگی‌ای که تبدیل‌های بهبودیافته برای مشتریان بالقوه نیز نامیده می‌شود.

«تبدیل‌های بهبودیافته برای مشتریان بالقوه» چیست؟

تبدیل‌های بهبودیافته برای مشتریان بالقوه نسخه ارتقایافته وارد کردن تبدیل آفلاین است که از داده‌های ارائه‌شده توسط کاربر، مانند نشانی‌های ایمیل، برای تکمیل داده‌های تبدیل آفلاین واردشده استفاده می‌کند تا دقت و عملکرد پیشنهاد قیمت را بهبود بخشد. وقتی تبدیل‌های آفلاینتان را وارد می‌کنید، از داده‌های درهم‌سازی‌شده مشتری که ارائه شده است برای نسبت دادن به پویش Google Ads استفاده می‌شود. این کار ازطریق مطابقت دادن با همان داده‌های جمع‌آوری‌شده در وب‌سایتتان (مثل فرم مشتری بالقوه) و مشتریانی که به سیستم وارد شده‌اند و با آگهی‌تان تعامل داشته‌اند انجام می‌شود. برای اطلاعات بیشتر، درباره تبدیل‌های بهبودیافته برای مشتریان بالقوه را ببینید.

دو روش برای پیاده‌سازی تبدیل‌های بهبودیافته برای مشتریان بالقوه وجود دارد که به این بستگی دارد که آیا از برچسب Google برای پیگیری رویدادهای ارسال فرم در صفحه وب خود استفاده می‌کنید یا نه. برای بهترین عملکرد و دوام، توصیه می‌کنیم از برچسب Google برای تبدیل‌های به‌سازی‌شده برای مشتریان بالقوه استفاده کنید.

  • اگر از ابتدا شروع می‌کنید، با بخش پیش‌نیازها شروع کنید.
  • اگر قبلاً وارد کردن تبدیل‌های آفلاین را راه‌اندازی کرده‌اید و می‌خواهید به تبدیل‌های بهبودیافته برای مشتریان بالقوه ارتقا دهید، توصیه می‌کنیم با بخش پیکربندی برچسب‌گذاری شروع کنید.
  • اگر قبلاً برچسب Google را راه‌اندازی کرده‌اید یا قصد ندارید از برچسب Google استفاده کنید، و درحال شروع کار روی ادغام Google Ads API هستید، به بخش پیاده‌سازی API بروید.
  • اگر نمی‌توانید داده‌های ارائه‌شده توسط کاربر را وارد کنید یا برای تبدیل‌هایتان به ارجاع خارجی متکی هستید، راهنمای واردات آفلاین تبدیل قدیمی را ببینید.

پیش‌نیازها

ابتدا، مطمئن شوید که مراحل موجود در بخش شروع به کار را تکمیل کرده‌اید.

پیش‌از اینکه بتوانید از تبدیل‌های بهبودیافته برای مشتریان بالقوه استفاده کنید، باید با تبدیل‌های بهبودیافته موافقت کنید و شرایط داده‌های مشتری را بپذیرید. می‌توانید با ارسال پُرسمان زیر به مشتری تبدیل Google Ads، بررسی کنید که آیا این پیش‌نیازها قبلاً برآورده شده‌اند یا نه:

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. موارد واردشده را مرور کنید.

خلاصه طرح‌واره Request و ClickConversion

جدول زیر فیلدهای کلیدی را در UploadClickConversionsRequest و ClickConversion برای تبدیل‌های بهبودیافته برای مشتریان بالقوه خلاصه می‌کند (برای جزئیات کامل فیلد، تکمیل کردن اشیاء ClickConversion و ساختن درخواست را ببینید):

مسیر مزرعه الزام قالب و محدودیت‌ها
customer_id الزامی روی شناسه مشتری تبدیل Google Ads (google_ads_conversion_customer در customer.conversion_tracking_setting) بدون خط تیره تنظیم شده است.
partial_failure الزامی باید روی true تنظیم شود تا تبدیل‌های معتبر وارد شوند و خطاهای سطح ردیف در partial_failure_error برگردانده شوند.
validate_only اختیاری وقتی true، درخواست را بدون وارد کردن تبدیل‌ها اعتبارسنجی می‌کند (هرگونه خطای اعتبارسنجی را در partial_failure_error برمی‌گرداند).
job_id اختیاری int32 غیرمنفی (0 تا 2^31 - 1) برای گروه‌بندی چند درخواست تحت یک کار منطقی در job_summaries.
conversions[].conversion_action الزامی نام منبع (customers/{conversion_customer_id}/conversionActions/{action_id}) کنش تبدیل ENABLED با type = UPLOAD_CLICKS.
conversions[].conversion_date_time الزامی باید بعداز زمان کلیک باشد و شامل اختلاف منطقه زمانی باشد: yyyy-mm-dd hh:mm:ss+|-hh:mm (برای مثال، 2026-06-01 14:30:00-04:00).
‫conversions[].conversion_value و currency_code توصیه‌شده مقدار تبدیل عددی (double) و کد ارز ISO 4217 سه‌نویسه‌ای (برای مثال، USD).
conversions[].order_id توصیه‌شده شناسه تراکنش یکتا برای هر کنش تبدیل برای جلوگیری از وارد کردن تکراری و پشتیبانی از اصلاحات آتی.
conversions[].gclid / gbraid / wbraid درصورت دردسترس بودن توصیه می‌شود شناسه کلیک از نشانی وب صفحه مقصد گرفته شده است. هرزمان دردسترس بود، در کنار user_identifiers گنجانده شود.
conversions[].user_identifiers[] برای تبدیل‌های بهبودیافته برای مشتریان بالقوه الزامی است یک تا پنج شیء UserIdentifier برای هر تبدیل. user_identifier_source اختیاری (مثل FIRST_PARTY) و hashed_email (پیرایش‌شده، با حروف کوچک، نقطه‌ها و پسوندهای + قبل‌از @ برای gmail.com و googlemail.com برداشته شده، شانزده‌شانزدهی SHA-256) یا hashed_phone_number (قالب E.164، شانزده‌شانزدهی SHA-256) را تنظیم کنید؛ به نرمال‌سازی و درهم‌سازی داده‌ها مراجعه کنید. ‫address_info پشتیبانی نمی‌شود.
conversions[].consent.ad_user_data توصیه‌شده روی GRANTED یا DENIED در Consent تنظیم شده است. (ad_personalization فقط در OfflineUserDataJobService و UserDataService پشتیبانی می‌شود.)
‫conversions[].custom_variables و external_attribution_data با user_identifiers تنظیم نشود تبدیل‌های حاوی user_identifiers نباید custom_variables یا external_attribution_data را تنظیم کنند، درغیراین‌صورت رد می‌شوند.

بازیابی نام منبع کنش تبدیل

برای بارگذاری تبدیل‌ها، باید نام منبع ConversionAction را که در Google Ads برای وارد کردن تبدیل‌های کلیک راه‌اندازی کرده‌اید مشخص کنید. می‌توانید نام منبع را با پُرسمان کردن منبع conversion_action بااستفاده از پُرسمان 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 درهم‌سازی کنید.
    • خلاصه حاصل را به‌عنوان رشته شانزده‌شانزدهی با حروف کوچک (۶۴ نویسه) قالب‌بندی کنید.
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 preceding "gmail.com" or "googlemail.com".
 *
 * @param  string $hashAlgorithm the hash algorithm to use
 * @param  string $emailAddress  the email address to normalize and hash
 * @return string the normalized and hashed email address
 */
private static function normalizeAndHashEmailAddress(
    string $hashAlgorithm,
    string $emailAddress
): string {
    $normalizedEmail = strtolower($emailAddress);
    $emailParts = explode("@", $normalizedEmail);
    if (
        count($emailParts) > 1
        && preg_match('/^(gmail|googlemail)\.com\s*/', $emailParts[1])
    ) {
        // Removes any '.' characters from the portion of the email address before the domain
        // if the domain is gmail.com or googlemail.com.
        $emailParts[0] = str_replace(".", "", $emailParts[0]);
        $normalizedEmail = sprintf('%s@%s', $emailParts[0], $emailParts[1]);
    }
    return self::normalizeAndHash($hashAlgorithm, $normalizedEmail);
}

Python

def normalize_and_hash_email_address(email_address: 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

پرل

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

شناسه‌های کلیک Google شناسه‌هایی هستند که وقتی فردی روی آگهی‌تان کلیک می‌کند و به وب‌سایتتان می‌رود، از پارامترهای نشانی وب گرفته می‌شوند.

gbraid

gbraid پارامتر نشانی وبی است که وقتی کاربر روی آگهی‌ای در وب کلیک می‌کند و به برنامه iOS شما هدایت می‌شود، وجود دارد.

wbraid

wbraid پارامتر نشانی وبی است که وقتی کاربر روی آگهی‌ای در برنامه iOS کلیک می‌کند و به صفحه وب شما هدایت می‌شود، وجود دارد.

cart_data

حاوی جزئیات سطح مورد درباره تبدیل است. برای گزارش کردن داده‌های سبد خرید (مثل موارد خریداری‌شده، قیمت، و تعداد) در میانای کاربری Google Ads، باید فیلد cart_data را پر کنید. برای ساختار موردنیاز، تعریف شیء 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 Ads مقایسه کنید، توصیه می‌کنیم از همان منطقه زمانی حساب Google Ads خود استفاده کنید تا تعداد تبدیل‌ها مطابقت داشته باشد. می‌توانید جزئیات و نمونه‌های بیشتر را در آماده‌سازی داده‌ها برای وارد کردن پیدا کنید و کدها و قالب‌ها را برای فهرست شناسه‌های معتبر منطقه زمانی بررسی کنید.

conversion_action

نام منبع ConversionAction برای تبدیل آفلاین.

کنش تبدیل باید type UPLOAD_CLICKS داشته باشد و باید در مشتری تبدیل Google Ads حساب Google Ads مرتبط با کلیک وجود داشته باشد.

conversion_value

مقدار تبدیل.

currency_code

کد ارز conversion_value.

consent

اکیداً توصیه می‌شود فیلد consent شیء ClickConversion را پر کنید. اگر تنظیم نشود، ممکن است تبدیل‌هایتان قابل‌انتساب نباشد.

order_id

به‌عنوان شناسه تراکنش برای تبدیل نیز شناخته می‌شود. این فیلد اختیاری است، اما به‌شدت توصیه می‌شود، زیرا ارجاع به تبدیل‌های واردشده را هنگام انجام تعدیلات ساده‌تر می‌کند. اگر آن را درطول وارد کردن تنظیم کرده‌اید، باید از آن برای هرگونه اصلاح استفاده کنید. برای کسب اطلاعات بیشتر درباره نحوه استفاده از شناسه تراکنش برای به‌حداقل رساندن تبدیل‌های تکراری، به استفاده از شناسه تراکنش برای به‌حداقل رساندن تبدیل‌های تکراری مراجعه کنید.

custom_variables

مقادیر متغیرهای تبدیل سفارشی. Google Ads از متغیرهای تبدیل سفارشی در ترکیب با wbraid یا gbraid پشتیبانی نمی‌کند.

conversion_environment

محیطی را که این تبدیل در آن ثبت شده است نشان می‌دهد. برای مثال، APP یا WEB.

‫session_attributes_encoded و session_attributes_key_value_pairs

مشخصه‌های جلسه نشان‌دهنده شناسه‌های انبوهشی استفاده‌شده برای اسناد تبدیل است. این‌ها علاوه‌بر GCLID و پارامترهای نشانی وب (مثل GBRAID) و داده‌های ارائه‌شده توسط کاربر که برای تبدیل‌های بهبودیافته برای مشتریان بالقوه ضروری است کار می‌کنند. دو روش برای وارد کردن شاخصه‌های جلسه وجود دارد: با ارائه کد رمزبندی‌شده تولیدشده توسط کد جاوا اسکریپت ما در مرورگر، یا با ارائه جفت‌های کلید-مقدار مجزا برای هریک از شناسه‌ها.

برای بیشینه‌سازی عملکرد پویش، توصیه می‌کنیم شناسه‌های کلیک، داده‌های ارائه‌شده توسط کاربر، و شاخصه‌های جلسه را درصورت امکان با همه تبدیل‌هایتان وارد کنید.

جاوا

// 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

// 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

# 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

پرل

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

curl

user_ip_address

نشانی IP مشتری وقتی که پس‌از کلیک کردن روی آگهی و پیش‌از رویداد تبدیل به صفحه فرود می‌رسد. این نشانی IP دستگاه مشتری است، نه سرور تبلیغ‌کننده.

این فیلد رشته‌ای است که نشانی IP را در قالب IPv4 یا IPv6 نشان می‌دهد. برای مثال:

  • IPv4: "192.0.2.0"
  • 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 (.) 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);

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

پرل

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

پرل

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

curl

ساختن درخواست

وقتی اشیای ClickConversion پیکربندی شدند و به فیلد conversions شیء UploadClickConversionsRequest اضافه شدند، فیلدهای زیر را تنظیم کنید و درخواست را به روش UploadClickConversions در ConversionUploadService ارسال کنید.

customer_id
این را روی مشتری تبدیل Google Ads حسابی که منبع کلیک‌ها است تنظیم کنید. اگر مطمئن نیستید کدام حساب درست است، به فیلد 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

پرل

# 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

ساختار درخواست و پاسخ REST

هنگام فراخوانی ConversionUploadService.UploadClickConversions ازطریق REST، درخواست POST را با تنظیم partialFailure روی true ارسال کنید:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:uploadClickConversions
{
  "partialFailure": true,
  "jobId": 1001,
  "conversions": [
    {
      "conversionAction": "customers/{customer_id}/conversionActions/{conversion_action_id}",
      "conversionDateTime": "2026-06-01 14:30:00-04:00",
      "conversionValue": 125.50,
      "currencyCode": "USD",
      "orderId": "ORDER-2026-0001",
      "gclid": "EAIaIQobChMI...",
      "consent": {
        "adUserData": "GRANTED"
      },
      "userIdentifiers": [
        {
          "userIdentifierSource": "FIRST_PARTY",
          "hashedEmail": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a"
        },
        {
          "userIdentifierSource": "FIRST_PARTY",
          "hashedPhoneNumber": "42975f8f9e46c2e13c1a2294957e5cb8d8e6f4f7341a036c6e595bc9f5e24621"
        }
      ]
    },
    {
      "conversionAction": "customers/{customer_id}/conversionActions/{conversion_action_id}",
      "conversionDateTime": "2026-06-01 14:35:00-04:00",
      "conversionValue": 80.00,
      "currencyCode": "USD",
      "orderId": "ORDER-2026-0002",
      "gclid": "EAIaIQobChMI_expired...",
      "consent": {
        "adUserData": "GRANTED"
      }
    }
  ]
}

در این دسته دوتبدیلی که مورد دوم ناموفق است، ردیف‌های موفق ورودی‌های پرشده ClickConversionResult را در results[] برمی‌گردانند، درحالی‌که ردیف‌های ناموفق اشیای خالی {} را در results[] به‌همراه جزئیات خطا در partialFailureError در UploadClickConversionsResponse برمی‌گردانند:

{
  "results": [
    {
      "conversionAction": "customers/{customer_id}/conversionActions/{conversion_action_id}",
      "conversionDateTime": "2026-06-01 14:30:00-04:00",
      "gclid": "EAIaIQobChMI...",
      "userIdentifiers": [
        {
          "userIdentifierSource": "FIRST_PARTY",
          "hashedEmail": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a"
        },
        {
          "userIdentifierSource": "FIRST_PARTY",
          "hashedPhoneNumber": "42975f8f9e46c2e13c1a2294957e5cb8d8e6f4f7341a036c6e595bc9f5e24621"
        }
      ]
    },
    {}
  ],
  "jobId": "1001",
  "partialFailureError": {
    "code": 3,
    "message": "The click associated with the given identifier or iOS URL parameter occurred less recently than the maximum lookback window., at conversions[1].gclid",
    "details": [
      {
        "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
        "errors": [
          {
            "errorCode": {
              "conversionUploadError": "EXPIRED_EVENT"
            },
            "message": "The click associated with the given identifier or iOS URL parameter occurred less recently than the maximum lookback window.",
            "location": {
              "fieldPathElements": [
                {
                  "fieldName": "conversions",
                  "index": 1
                },
                {
                  "fieldName": "gclid"
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

مرور موارد واردشده

از گزارش تشخیص خرابی تبدیل‌های بهبودیافته برای مشتریان بالقوه برای بررسی سلامت کلی واردات اخیرتان استفاده کنید.

تشخیص خرابی بارگذاری پُرسمان با GAQL

همچنین می‌توانید با پرسمان کردن offline_conversion_upload_client_summary دربرابر شناسه مشتری تبدیل، سلامت بارگذاری در سطح حساب، تعداد کارهای اخیر، و هشدارهای خطا را به‌صورت برنامه‌نویسی‌شده بررسی کنید:

SELECT
  customer.id,
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.total_event_count,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.success_rate,
  offline_conversion_upload_client_summary.pending_event_count,
  offline_conversion_upload_client_summary.pending_rate,
  offline_conversion_upload_client_summary.last_upload_date_time,
  offline_conversion_upload_client_summary.alerts,
  offline_conversion_upload_client_summary.daily_summaries,
  offline_conversion_upload_client_summary.job_summaries
FROM offline_conversion_upload_client_summary

تبدیل‌های واردشده در گزارش‌های مربوط به تاریخ ظهور کلیک اصلی منعکس می‌شوند، نه تاریخ درخواست وارد کردن یا تاریخ conversion_date_time مربوط به ClickConversion.

تا سه ساعت طول می‌کشد تا آمار تبدیل واردشده در حساب Google Ads شما برای اسناد آخرین کلیک ظاهر شود. برای سایر مدل‌های اسنادی جستجو، ممکن است بیشتر از سه ساعت طول بکشد. برای اطلاعات بیشتر، به راهنمای تازگی داده‌ها مراجعه کنید.

هنگام گزارش‌دهی درباره سنجه‌های تبدیل برای پویش‌هایتان، به نگاشت سنجه‌های میانای کاربر مراجعه کنید تا سنجه‌های میانای کاربر Google Ads را با فیلدهای گزارش‌دهی Google Ads API مرتبط کنید. همچنین می‌توانید منبع conversion_action را پُرسمان کنید تا تعداد کل تبدیل‌ها و مقدار کل تبدیل را برای کنش تبدیل مشخصی مشاهده کنید.

روال‌های مطلوب

هنگام پیاده‌سازی تبدیل‌های بهبودیافته برای مشتریان بالقوه، روال‌های مطلوب زیر را به‌خاطر داشته باشید.

ارسال همه داده‌های تبدیل بدون درنظر گرفتن کامل بودن

برای اطمینان از گزارش‌دهی کامل و دقیق تبدیل، همه رویدادهای تبدیل آفلاین دردسترس را وارد کنید، ازجمله رویدادهایی که ممکن است از Google Ads نیامده باشند. تبدیل‌هایی که فقط شامل داده‌های ارائه‌شده توسط کاربر هستند همچنان مفیدند و می‌توانند به بهینه‌سازی پویش Google Ads کمک کنند.

اگر order_id را به تبدیلی اختصاص می‌دهید، توصیه می‌کنیم آن را اضافه کنید. اگر GCLID را برای تبدیل دارید، توصیه می‌کنیم آن را علاوه‌بر 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 Ads از تبدیل‌های انتساب‌یافته خارجی برای وارد کردن بااستفاده از داده‌های ارائه‌شده توسط کاربر پشتیبانی نمی‌کند.

متغیرهای سفارشی اضافه نشود

هنگام استفاده از تبدیل‌های بهبودیافته برای مشتریان بالقوه، هیچ‌گونه custom_variables را اضافه نکنید. Google Ads از استفاده از متغیرهای سفارشی با داده‌های ارائه‌شده توسط کاربر در وارد کردن تبدیل پشتیبانی نمی‌کند. اگر متغیرهای سفارشی در تبدیل‌هایی که حاوی داده‌های ارائه‌شده توسط کاربر هستند گنجانده شده باشند، آن تبدیل‌ها نامعتبر درنظر گرفته می‌شوند و حذف می‌شوند.

عیب‌یابی

عیب‌یابی داده‌های آفلاین منبعی واحد برای بررسی سلامت کلی واردات شما به‌طور مداوم ارائه می‌دهد. بااین‌حال، درحین پیاده‌سازی می‌توانید از اطلاعات این بخش برای بررسی خطاهای گزارش‌شده در فیلد partial_failure_error پاسخ استفاده کنید.

برخی‌از رایج‌ترین خطاها هنگام وارد کردن کنش‌های تبدیل عبارت‌اند از خطاهای مجوز، مانند USER_PERMISSION_DENIED. دوباره بررسی کنید که شناسه مشتری را در درخواست خود روی مشتری تبدیل Google Ads که مالک کنش تبدیل است تنظیم کرده باشید. برای جزئیات بیشتر، به راهنمای صدور مجوز ما مراجعه کنید و برای نکاتی درباره نحوه اشکال‌زدایی این خطاهای مختلف، راهنمای خطاهای رایج ما را ببینید.

اشکال‌زدایی خطاهای رایج

راهنمایی‌های زیر به شما کمک می‌کند خطاهای رایج در تبدیل‌های بهبودیافته برای مشتریان بالقوه را تشخیص دهید و برطرف کنید.

خطا
NO_CONVERSION_ACTION_FOUND

کنش تبدیل مشخص‌شده یا فعال نیست یا حساب مشتری مشخص‌شده با فیلد customer_id در درخواست نمی‌تواند به آن دسترسی داشته باشد. مطمئن شوید کنش تبدیل در بارگذاری شما فعال است و متعلق به مشتری‌ای است که درخواست بارگذاری را ارسال می‌کند.

این خطا همچنین ممکن است زمانی رخ دهد که GCLID در درخواست متعلق به حساب مشتری‌ای باشد که به کنش تبدیل مشخص‌شده در درخواست دسترسی ندارد. می‌توانید بااستفاده از منبع click_view و با ارسال پُرسمانی که براساس click_view.gclid و segments.date فیلتر می‌کند، تأیید کنید که آیا «شناسه کلیک Google» به حساب مشتری تعلق دارد یا نه. تاریخ همان تاریخی است که کلیک انجام شده است.

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 Ads نباشد، این خطا مورد انتظار است. برای مثال، ممکن است از SA360 یا DV360 باشد. سایر علل احتمالی به‌شرح زیر است:

در موارد نادری که مشتری بارگذاری‌کننده با مشتری تبدیل Google Ads متفاوت است، این خطا می‌تواند به این معنی باشد که مشتری بارگذاری‌کننده شرایط داده‌های مشتری را پذیرفته است، اما مشتری ارائه‌دهنده نپذیرفته است.

با پُرسمان کردن منبع customer و بررسی فیلد customer.conversion_tracking_setting.accepted_customer_data_terms می‌توانید تعیین کنید که آیا حسابی شرایط داده‌های مشتری را پذیرفته است یا نه.
قبلی
شروع کار با تبدیل‌ها
بعدی
مدیریت تبدیل‌های آنلاین