Method: customers.uploadClickConversions

מעבד את ההמרות הנתונות מקליקים.

רשימה של שגיאות שקרו: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

בקשת HTTP

POST https://googleads.googleapis.com/v16/customers/{customerId}:uploadClickConversions

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
customerId

string

חובה. מזהה הלקוח שמבצע את ההעלאה.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "conversions": [
    {
      object (ClickConversion)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "debugEnabled": boolean,
  "jobId": integer
}
שדות
conversions[]

object (ClickConversion)

חובה. ההמרות שמעלים.
partialFailure

boolean

חובה. אם הערך הוא true, פעולות שבוצעו בהצלחה ופעולות לא חוקיות יחזירו שגיאות. אם הערך הוא False, כל הפעולות יבוצעו בעסקה אחת אם ורק אם כולן תקינות. תמיד צריך להגדיר את הערך כ-True. מידע נוסף על כשל חלקי זמין בכתובת https://developers.google.com/google-ads/api/docs/best-practices/partial-failures.
validateOnly

boolean

אם הערך הוא True, הבקשה מאומתת אבל לא מבוצעת. רק שגיאות מוחזרות, לא תוצאות.
debugEnabled

boolean

אם הערך הוא True, ה-API יבצע את כל בדיקות ההעלאה ויחזיר שגיאות אם יימצאו. אם הערך הוא False, הוא יבצע רק אימות קלט בסיסי, ידלג על בדיקות ההעלאה הבאות ויחזור בהצלחה גם אם לא נמצא קליק ב-userIdentifiers שצוין.

ההגדרה הזו משפיעה רק על ההמרות המשופרות בהעלאות לידים שנעשה בהן שימוש ב-userIdentifiers במקום ב-GCLID, ב-GBRAID או ב-WBRAID. כשמעלים המרות משופרות לצורך שיוך ללידים, צריך להעלות את כל אירועי ההמרות ל-API, כולל אירועי המרה שאולי לא הגיעו מקמפיינים ב-Google Ads. העלאה של אירוע שאינו מקמפיין ב-Google Ads תוביל לשגיאה CLICK_NOT_FOUND אם השדה הזה מוגדר לערך true. מכיוון שהשגיאות האלה צפויות עבור אירועים כאלה, צריך להגדיר את השדה הזה לערך false כדי לוודא שההעלאות בפורמט הנכון, אבל להתעלם מ-CLICK_NOT_FOUND שגיאות מכל ההמרות שאינן מקמפיין של Google Ads. כך תוכלו להתמקד רק בשגיאות שאתם יכולים לטפל בהן.

ברירת המחדל היא False.
jobId

integer

אפשרות. שדה אופציונלי להגדרת מזהה המשימה. חייב להיות מספר לא שלילי שקטן מ-2^31, אם צוין. אם לא תספקו את השדה הזה, ה-API ייצור מזהה משימה בטווח [ 2^31, (2^63)-1]. ה-API יחזיר את הערך של הבקשה הזו בשדה jobId של UploadClickConversionsResponse.

גוף התשובה

הודעת תשובה לגבי ConversionUploadService.UploadClickConversions.

אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ClickConversionResult)
    }
  ],
  "jobId": string
}
שדות
partialFailureError

object (Status)

שגיאות שמתייחסות לכשלים בהמרות במצב 'כשל חלקי'. מוחזרות כאשר כל השגיאות מתרחשות בתוך ההמרות. אם מתרחשות שגיאות מחוץ להמרות (למשל, שגיאות אימות), נחזיר שגיאה ברמת ה-RPC. מידע נוסף על כשל חלקי זמין בכתובת https://developers.google.com/google-ads/api/docs/best-practices/partial-failures.
results[]

object (ClickConversionResult)

מוחזר עבור המרות שעובדו בהצלחה. השדה Proto יהיה ריק בשורות שהתקבלה בהן שגיאה. התוצאות לא מוחזרות אם הערך של validateOnly הוא TRUE.
jobId

string (int64 format)

מזהה המשימה להעלאה של קבוצת הקבצים.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/adwords

למידע נוסף, עיינו בסקירה הכללית על OAuth 2.0.

ClickConversion

המרה מסוג קליק.

ייצוג JSON 
{
  "gbraid": string,
  "wbraid": string,
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "conversionEnvironment": enum (ConversionEnvironment),
  "consent": {
    object (Consent)
  },
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}
שדות
gbraid

string

מזהה הקליק של קליקים שמשויכים להמרות באפליקציה שמקורם במכשירי iOS שמתחילים ב-iOS 14.
wbraid

string

מזהה הקליק של קליקים שמשויכים להמרות באתר ושמקורם במכשירי iOS החל מ-iOS 14.
externalAttributionData

object (ExternalAttributionData)

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

object (CustomVariable)

המשתנים המותאמים אישית שמשויכים להמרה הזו.
cartData

object (CartData)

נתוני עגלות הקניות שמשויכים להמרה הזו.
userIdentifiers[]

object (UserIdentifier)

מזהי המשתמש המשויכים להמרה הזו. אפשר להעלות המרות רק באמצעות hashedEmail ו-hashedPhoneNumber. המספר המקסימלי של מזהי משתמש לכל המרה הוא 5.
conversionEnvironment

enum (ConversionEnvironment)

הסביבה שבה ההמרה הזו תועדה. למשל, אפליקציה או אתר.
consent

object (Consent)

הגדרת ההסכמה לאירוע.
gclid

string

מספר הקליק ב-Google (GCLID) שמשויך להמרה הזו.
conversionAction

string

שם המשאב של פעולת ההמרה שמשויכת להמרה הזו. הערה: שם המשאב הזה מורכב ממספר לקוח וממזהה של פעולת המרה, אבל המערכת תתעלם ממספר הלקוח ותשתמש במזהה פעולת ההמרה בתור המזהה היחיד של פעולת ההמרה.
conversionDateTime

string

התאריך שבו התרחשה ההמרה. חייב להיות אחרי מועד הקליק. חובה לציין את אזור הזמן. הפורמט הוא 'yyyy-mm-dd hh:mm:ss+|-hh:mm', לדוגמה, '2019-01-01 12:32:45-08:00'.
conversionValue

number

ערך ההמרה של המפרסם.
currencyCode

string

המטבע שמשויך לערך ההמרה. זהו קוד המטבע בן 3 התווים לפי תקן ISO 4217. לדוגמה: USD, EUR.
orderId

string

מזהה ההזמנה המשויך להמרה. אפשר להשתמש במזהה הזמנה רק להמרה אחת לכל פעולת המרה.

ExternalAttributionData

כאן מופיע מידע נוסף על המרות שהשיוך שלהן נקבע במערכת חיצונית.

ייצוג JSON 
{
  "externalAttributionCredit": number,
  "externalAttributionModel": string
}
שדות
externalAttributionCredit

number

מייצג את החלק מההמרה שמיוחסת לקליק ב-Google Ads.
externalAttributionModel

string

מציין את שם מודל השיוך.

CartData

מכילה מידע נוסף על נתוני עגלות הקניות.

ייצוג JSON 
{
  "merchantId": string,
  "feedCountryCode": string,
  "feedLanguageCode": string,
  "localTransactionCost": number,
  "items": [
    {
      object (Item)
    }
  ]
}
שדות
merchantId

string (int64 format)

מספר חשבון Merchant Center שאליו הועלו הפריטים.
feedCountryCode

string

קוד המדינה שמשויך אל הפיד שאליו מועלים הפריטים.
feedLanguageCode

string

קוד השפה שמשויך אל הפיד שאליו מועלים הפריטים.
localTransactionCost

number

הסכום של כל ההנחות ברמת העסקה, כמו משלוח חינם והנחות בשוברים בכל עגלת הקניות. קוד המטבע זהה לקוד המטבע שמוצג בהודעה של ClickConversion.
items[]

object (Item)

נתונים של הפריטים שנרכשו.

פריט

מכילה נתונים של הפריטים שנרכשו.

ייצוג JSON 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
שדות
productId

string

מזהה הקנייה של הפריט. חייב להיות שווה למזהה המוצר ב-Merchant Center.
quantity

integer

מספר הפריטים שנמכרו.
unitPrice

number

המחיר ליחידה, לא כולל מס, משלוח והנחות ברמת העסקה. קוד המטבע זהה לקוד המטבע שמוצג בהודעה של ClickConversion.

ConversionEnvironment

סביבת ההמרה של ההמרה שהועלתה.

טיפוסים בני מנייה (enums)
UNSPECIFIED לא צוין.
UNKNOWN משמש לציון הערך המוחזר בלבד. מייצג ערך לא ידוע בגרסה הזו.
APP ההמרה תועדה באפליקציה.
WEB ההמרה תועדה באתר.

ClickConversionResult

זיהוי מידע עבור ClickConversion שעובדה בהצלחה.

ייצוג JSON 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
שדות
gbraid

string

מזהה הקליק של קליקים שמשויכים להמרות באפליקציה שמקורם במכשירי iOS שמתחילים ב-iOS 14.
wbraid

string

מזהה הקליק של קליקים שמשויכים להמרות באתר ושמקורם במכשירי iOS החל מ-iOS 14.
userIdentifiers[]

object (UserIdentifier)

מזהי המשתמש המשויכים להמרה הזו. אפשר להעלות המרות רק באמצעות hashedEmail ו-hashedPhoneNumber. המספר המקסימלי של מזהי משתמש לכל המרה הוא 5.
gclid

string

מספר הקליק ב-Google (GCLID) שמשויך להמרה הזו.
conversionAction

string

שם המשאב של פעולת ההמרה שמשויכת להמרה הזו.
conversionDateTime

string

התאריך שבו התרחשה ההמרה. הפורמט הוא 'yyyy-mm-dd hh:mm:ss+|-hh:mm', לדוגמה, '2019-01-01 12:32:45-08:00'.