ניהול המרות אופליין

אתם יכולים להשתמש ב-Google Ads API כדי לייבא המרות אופליין ל-Google Ads, וכך לעקוב אחרי מודעות שהובילו למכירות בעולם הפיזי, למשל בטלפון או דרך נציג מכירות.

כדי ליהנות מכל היתרונות של ייבוא נתוני המרות, מומלץ להטמיע המרות משופרות לצורך שיוך ללידים. התכונה הזו משתמשת ב-GCLID ובפרטים שהמשתמשים סיפקו כדי לשפר את העמידות והביצועים.

המרות משופרות

התכונה "המרות משופרות" מוסיפה להמרות שלכם גם נתוני המרות מאינטראקציה ישירה (First-Party), כמו כתובת אימייל, מספר טלפון וכתובת למשלוח דואר, וכך משפרת את הדיוק של מעקב ההמרות.

יש שני סוגים של המרות משופרות. מידע נוסף זמין במאמר בנושא המרות משופרות.

בקטע הבא מוסבר איך לשפר המרות אופליין, תכונה שנקראת גם המרות משופרות לצורך שיוך ללידים.

מה זה המרות משופרות לצורך שיוך ללידים?

התכונה "המרות משופרות לצורך שיוך ללידים" היא גרסה משודרגת של "ייבוא של נתוני המרות אופליין (OCI)" והיא מבוססת על הפרטים שהמשתמשים סיפקו (UPD), כמו כתובות אימייל. היא משמשת כתוספת לנתונים המיובאים של המרות אופליין כדי לשפר את הדיוק ואת ביצועי הבידינג. כשאתם מייבאים המרות אופליין, המערכת משתמשת בפרטים המגובבים (hashed) שהלקוחות סיפקו כדי ליצור שיוך לקמפיין Google Ads. השיוך נעשה על ידי התאמה לנתונים זהים שנאספו באתר שלכם, כמו טופס להשארת פרטים, והתאמה ללקוחות שמחוברים לחשבון ויצרו אינטראקציה עם המודעה שלכם. מידע נוסף זמין במאמר מידע על המרות משופרות לצורך שיוך ללידים.

יש שתי דרכים להטמיע המרות משופרות לצורך שיוך ללידים, בהתאם לשאלה אם אתם משתמשים ב-Google Tag כדי לעקוב אחרי אירועים של שליחת טפסים בדף האינטרנט שלכם. כדי לקבל את הביצועים הטובים ביותר ולשמור על עמידות, מומלץ להשתמש ב-Google Tag להמרות משופרות לצורך שיוך ללידים.

  • אם אתם מתחילים מאפס, התחילו בקטע דרישות מוקדמות.
  • אם כבר הגדרתם ייבוא של נתוני המרות אופליין ואתם רוצים לשדרג להמרות משופרות לצורך שיוך ללידים, מומלץ להתחיל בקטע הגדרת תיוג.
  • אם כבר הגדרתם את Google Tag או שאתם לא מתכננים להשתמש ב-Google Tag, ואתם מתחילים לעבוד על השילוב של Google Ads API, אתם יכולים לדלג אל הקטע הטמעה של API.
  • אם אתם לא יכולים לייבא פרטים שהמשתמשים סיפקו, או אם אתם מסתמכים על שיוך חיצוני להמרות, עיינו במדריך לייבוא של נתוני המרות אופליין (OCI) בגרסה הקודמת.

דרישות מוקדמות

קודם כל, חשוב לוודא שביצעתם את השלבים בקטע תחילת העבודה.

כדי להשתמש בהמרות משופרות לצורך שיוך ללידים, צריך להביע הסכמה לשימוש בהמרות משופרות ולאשר את התנאים לאיסוף נתוני לקוחות ושימוש בהם. כדי לבדוק אם אתם כבר עומדים בדרישות המוקדמות האלה, אתם יכולים לשלוח את השאילתה הבאה ללקוח ההמרות ב-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 Tag לפי ההוראות במאמר קביעת ההגדרות של Google Tag. כדי להגדיר המרות משופרות לצורך שיוך ללידים באמצעות Google Tag Manager, צריך לפעול לפי ההוראות האלה של Google Tag Manager.

הטמעת API

זהו התהליך הכולל לייבוא המרות משופרות לצורך שיוך ללידים באמצעות 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) וקוד מטבע בן 3 תווים בתקן 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'

נרמול וגיבוב (hash) של פרטים שהמשתמשים סיפקו

משיקולי פרטיות, צריך לבצע גיבוב של הנתונים הבאים באמצעות SHA-256 לפני שמייבאים אותם:

  • כתובת אימייל
  • מספר טלפון
  • שם פרטי
  • שם משפחה
  • רחוב

אל תבצעו גיבוב של הנתונים הבאים:

  • מדינה
  • מדינה (State)
  • עיר
  • מיקוד

כדי לבצע סטנדרטיזציה של תוצאות הגיבוב, צריך לבצע את הפעולות הבאות לפני שמגבבים את הערכים האלה:

  • מסירים רווחים לבנים בתחילת הטקסט ובסופו.
  • ממירים את הטקסט לאותיות קטנות.
  • מזינים מספרי טלפון בפורמט שתואם לתקן E.164.

פורמט כתובת האימייל להמרות משופרות

כדי להבטיח את אחוזי הלקוחות לטירגוט הגבוהים ביותר להמרות משופרות, צריך להגדיר את הפורמט של כתובות האימייל ולגבב אותן בצורה נכונה לפי השלבים הבאים:

  1. החלת נורמליזציה סטנדרטית (כל כתובות האימייל):

    • מסירים רווחים לבנים בתחילת הטקסט ובסופו.
    • ממירים את כל התווים בכתובת האימייל לאותיות קטנות.

  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.
    • מבצעים גיבוב (hash) של בייטים בקידוד UTF-8 באמצעות האלגוריתם SHA-256.
    • הפונקציה מעצבת את הגיבוב שמתקבל כמחרוזת הקסדצימלית באותיות קטנות (64 תווים).
import hashlib
import re


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

קוד לדוגמה

הדוגמה הזו מראה איך לנרמל ולגבב פרטים שהמשתמשים סיפקו.

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

Perl

sub normalize_and_hash {
  my $value = shift;

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

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

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

curl

איכלוס של אובייקטים מסוג ClickConversion

אוסף האובייקטים מסוג ClickConversion ב-UploadClickConversionsRequest מייצג את קבוצת ההמרות שרוצים לייבא. כשיוצרים אובייקטים ב-ClickConversion, חשוב לזכור את הפרטים הבאים:

gclid

מספרי GCLID הם מזהים שמתועדים מפרמטרים של כתובות URL כשמשתמש לוחץ על המודעה שלכם ועובר לאתר שלכם.

gbraid

gbraid הוא פרמטר של כתובת URL שמופיע כשמשתמש לוחץ על מודעה באינטרנט ומופנה לאפליקציה ל-iOS שלכם.

wbraid

wbraid הוא פרמטר של כתובת URL שמופיע כשמשתמש לוחץ על מודעה באפליקציה ל-iOS ומופנה לדף האינטרנט שלכם.

cart_data

כולל פרטים ברמת הפריט לגבי המרה. חובה למלא את השדה cart_data כדי לדווח על נתוני סל הקניות – כמו פריטים שנרכשו, מחיר וכמות – בממשק המשתמש של Google Ads. הגדרת האובייקט CartData מופיעה בהמשך המאמר. מידע נוסף זמין במאמר מידע על המרות עם נתונים מעגלות קניות.

user_identifiers

כשמשתמשים בהמרות משופרות לצורך שיוך ללידים, חובה לאכלס את השדה user_identifiers בפרטים שהמשתמשים סיפקו (UPD) אחרי שעברו נרמול וגיבוב. אם יש לכם כמה מזהי משתמשים, אתם יכולים ליצור עד חמישה 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 שמשויך לקליק.

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, לפרמטרים של כתובות URL (כמו GBRAID) ולפרטים שהמשתמשים מספקים (UPD), שהם מרכיב מרכזי בהמרות משופרות לצורך שיוך ללידים. יש שתי דרכים לייבא מאפייני סשן: לספק את האסימון המקודד שנוצר על ידי קוד ה-JavaScript שלנו בדפדפן, או לספק זוגות נפרדים של מפתח/ערך לכל אחד מהמזהים.

כדי לשפר את הביצועים ברמת הקמפיין, מומלץ לייבא מזהי קליקים, פרטים שהמשתמשים סיפקו ומאפייני סשן עם כל ההמרות, אם אפשר.

Java

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

C#‎

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

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

PHP

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

Python

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

Ruby

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

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

Perl

# Set one of the session_attributes_encoded or session_attributes_key_value_pairs
# fields if either are provided.
if (defined $session_attributes_encoded) {
  $click_conversion->{sessionAttributesEncoded} = $session_attributes_encoded;
} elsif (defined $session_attributes_hash) {
  while (my ($key, $value) = each %$session_attributes_hash) {
    my $pair =
      Google::Ads::GoogleAds::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.

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

Perl

# 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.

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

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

C#‎

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

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

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

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

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

PHP

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

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

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

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

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

Python

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

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

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

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

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

Ruby

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

unless order_id.nil?
  cc.order_id = order_id
end

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

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

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

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

Perl

# Add details of the conversion.
$click_conversion->{conversionAction} =
  Google::Ads::GoogleAds::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, מגדירים את השדות הבאים ומעבירים את הבקשה ל-method‏ 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 ויוצרים את הבקשה, אפשר לשלוח את הייבוא.

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

C#‎

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

PHP

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

Python

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

Ruby

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

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

Perl

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

curl

מבנה הבקשה והתגובה של 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 עבור שיוך לקליק אחרון. במודלים אחרים של שיוך (Attribution) לרשת החיפוש, יכול להיות שזה ייקח יותר משלוש שעות. מידע נוסף זמין במדריך בנושא עדכניות הנתונים.

כשמדווחים על מדדי המרות בקמפיינים, כדאי לעיין במאמר מיפוי מדדים של ממשק המשתמש כדי להתאים בין המדדים של ממשק המשתמש של 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 יכיל רשומה נפרדת לכל בקשה, וזה עלול להקשות על ניתוח התקינות הכוללת של המשימה.

לא להשתמש בנתוני שיוך (Attribution) חיצוניים

כשמשתמשים בהמרות משופרות לצורך שיוך ללידים, אל תגדירו את 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 בבקשה שייך לחשבון לקוח שאין לו גישה לפעולת ההמרה שצוינה בבקשה. כדי לבדוק אם GCLID שייך לחשבון לקוח, אפשר להשתמש במשאב click_view ולשלוח שאילתה שמסננת לפי click_view.gclid ו-segments.date, כשהתאריך הוא התאריך שבו התרחש הקליק.

INVALID_CONVERSION_ACTION_TYPE סוג פעולת ההמרה שצוין לא תקין להמרות משופרות לצורך שיוך ללידים. צריך לוודא שהערך של ConversionAction שצוין בבקשת ההעלאה הוא מסוג UPLOAD_CLICKS.
CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS מוודאים שהפעלתם את התכונה "המרות משופרות לצורך שיוך ללידים" בהגדרות ההמרה. הוראות בנושא מופיעות במדריך הדרישות המוקדמות.
DUPLICATE_ORDER_ID האירועים שיובאו כוללים מספר המרות עם אותו מזהה הזמנה, ולא עובדו. צריך לוודא שמזהי ההזמנות ייחודיים ולנסות שוב.
CLICK_NOT_FOUND לא נמצא קליק שתואם למזהי המשתמשים שסופקו.

אם מופיעה אזהרה כזו לגבי המרה, ה-Google Ads API כולל אותה ב-successful_event_count של אבחון הנתונים ממקורות אופליין. ‫Google Ads API כולל רשומה של CLICK_NOT_FOUND באוסף alerts, כך שאפשר לעקוב אחרי התדירות של האזהרה הזו.

השגיאה הזו צפויה אם הקליק לא הגיע מקמפיין Google Ads. לדוגמה, הוא יכול להגיע מ-SA360 או מ-DV360. סיבות אפשריות אחרות:

במקרים נדירים שבהם הלקוח המעלה שונה מהלקוח של ההמרה ב-Google Ads, השגיאה הזו יכולה להצביע על כך שהלקוח המעלה אישר את התנאים בנוגע לנתוני לקוחות, אבל הלקוח שמציג את המודעה לא אישר אותם.

כדי לבדוק אם בחשבון מסוים אושרו התנאים לאיסוף נתוני לקוחות ושימוש בהם, שולחים שאילתה למשאב customer ובודקים את השדה customer.conversion_tracking_setting.accepted_customer_data_terms.
הקודם
איך מתחילים לעבוד עם המרות
הבא
ניהול המרות אונליין