REST Resource: projects.locations.dataStores.userEvents

משאב: UserEvent

האירוע UserEvent מתעד את כל נתוני המטא-נתונים ש-Discovery Engine API צריך לדעת על האינטראקציות של משתמשי הקצה עם האתר שלכם.

ייצוג ב-JSON 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
שדות
eventType

string

חובה. סוג אירוע המשתמש. הערכים המותרים הם:

ערכים כלליים:

  • ‫search: חיפוש מסמכים.
  • view-item: תצוגת דף מפורטת של מסמך.
  • ‫view-item-list: תצוגה של חלונית או רשימה מסודרת של מסמכים.
  • ‫view-home-page: תצוגה של דף הבית.
  • ‫view-category-page: צפייה בדף קטגוריה, למשל דף הבית > גברים > ג'ינסים

ערכים שקשורים לקמעונאות:

  • ‫add-to-cart: הוספת פריטים לעגלת קניות, למשל בקניות קמעונאיות באינטרנט
  • purchase: רכישת פריטים

ערכים שקשורים למדיה:

  • ‫media-play: הפעלה או המשך של צפייה בסרטון, הפעלה של שיר וכו'.
  • ‫media-complete: סיימו לצפות בסרטון, להאזין לשיר וכו' או הפסיקו באמצע.

ערך המרה מותאם אישית:

  • ‫conversion: אירוע המרה שהוגדר על ידי הלקוח.
conversionType

string

זה שינוי אופציונלי. סוג ההמרה.

חובה אם הערך של UserEvent.event_type הוא conversion. זהו שם המרה שהוגדר על ידי הלקוח באותיות קטנות או במספרים שמופרדים באמצעות '-', כמו watch,‏ good-visit וכו'.

אם הערך של UserEvent.event_type הוא לא conversion, אל תגדירו את השדה. האירוע הזה משלב את אירוע ההמרה המותאם אישית עם אירועים מוגדרים מראש כמו search, ‏ view-item וכו'.
userPseudoId

string

חובה. מזהה ייחודי למעקב אחרי מבקרים.

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

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

השדה חייב להיות מחרוזת בקידוד UTF-8, עם מגבלת אורך של 128 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

השדה לא יכול להכיל פרטים אישיים מזהים (PII) או נתוני משתמשים. מומלץ להשתמש במזהה לקוח של Google Analytics בשדה הזה.
engine

string

שם המשאב Engine, בפורמט projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

זה שינוי אופציונלי. נדרש רק לאירועים של משתמשים שנוצרו על ידי Engine. לדוגמה, אירועי משתמשים מחיפוש משולב.
dataStore

string

השם המלא של משאב DataStore, בתבנית projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

זה שינוי אופציונלי. הפרמטר הזה נדרש רק לאירועים שקשורים למשתמשים, שלא ניתן לקבוע את מאגר הנתונים שלהם באמצעות UserEvent.engine או UserEvent.documents. אם מאגר הנתונים מוגדר ברכיב ההורה של בקשות כתיבה, ייבוא או איסוף של אירועי משתמשים, אפשר להשמיט את השדה הזה.
eventTime

string (Timestamp format)

נדרש רק לשיטה UserEventService.ImportUserEvents. חותמת הזמן של האירוע שקשור למשתמש.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

מידע על משתמש הקצה.
directUserRequest

boolean

צריך להגדיר את הערך כ-true אם הבקשה מגיעה ישירות ממשתמש הקצה. במקרה כזה, אפשר לאכלס את UserEvent.user_info.user_agent מתוך בקשת ה-HTTP.

צריך להגדיר את הדגל הזה רק אם בקשת ה-API מגיעה ישירות ממשתמש הקצה, למשל מאפליקציה לנייד (ולא אם שער או שרת מעבדים את אירועי המשתמש ושולחים אותם).

אין להגדיר את הערך הזה כשמשתמשים בתג JavaScript ב-UserEventService.CollectUserEvent.
sessionId

string

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

הנחיה כללית לאכלוס הערך sessionId:

  1. אם משתמש לא מבצע פעילות במשך 30 דקות, צריך להקצות לו sessionId חדש.
  2. מזהה הסשן צריך להיות ייחודי לכל המשתמשים. מומלץ להשתמש ב-UUID או להוסיף את הקידומת UserEvent.user_pseudo_id.
pageInfo

object (PageInfo)

מטא-נתונים של הדף, כמו קטגוריות ומידע קריטי אחר לסוגים מסוימים של אירועים, כמו view-category-page.
attributionToken

string

טוקן לשיוך תגובת API לפעולות של משתמשים להפעלת האירוע.

מומלץ מאוד לאירועי משתמש שהם תוצאה של RecommendationService.Recommend. השדה הזה מאפשר שיוך מדויק של הביצועים למודל ההמלצות.

הערך צריך להיות אחד מהערכים הבאים:

הטוקן הזה מאפשר לנו לשייך באופן מדויק את הצפייה בדף או את השלמת ההמרה בחזרה לאירוע ולתגובה הספציפית של התחזית שמכילה את המוצר הזה שהמשתמש לחץ עליו או רכש אותו. אם המשתמש לוחץ על מוצר K בתוצאות ההמלצות, צריך להעביר את הערך RecommendResponse.attribution_token כפרמטר של כתובת URL לדף של מוצר K. כשמתעדים אירועים בדף של מוצר K, צריך לרשום את RecommendResponse.attribution_token בשדה הזה.
filter

string

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

לדוגמה, באירועים מסוג search, יכול להיות שהמאפיין המשויך SearchRequest יכיל ביטוי מסנן ב-SearchRequest.filter בהתאם ל-https://google.aip.dev/160#filtering.

באופן דומה, לגבי view-item-list אירועים שנוצרים מתוך RecommendRequest, יכול להיות שהשדה הזה יאוכלס ישירות מתוך RecommendRequest.filter בהתאם ל-https://google.aip.dev/160#filtering.

הערך חייב להיות מחרוזת בקידוד UTF-8, באורך של עד 1,000 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
documents[]

object (DocumentInfo)

רשימה של Documents שמשויכים לאירוע המשתמש הזה.

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

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

באירוע search, השדה הזה מייצג את המסמכים שמוחזרים למשתמש הקצה בדף הנוכחי (יכול להיות שמשתמש הקצה עדיין לא סיים לעיין בכל הדף). כשדף חדש מוחזר למשתמש הקצה, אחרי חלוקה לעמודים, סינון או מיון, גם אם מדובר באותה שאילתה, רצוי שיוחזר אירוע search חדש עם ערכים שונים של UserEvent.documents.
panel

object (PanelInfo)

מטא-נתונים של הפאנל שמשויכים לאירוע המשתמש הזה.
searchInfo

object (SearchInfo)

פרטים של SearchService.Search שקשורים לאירוע.

צריך להגדיר את השדה הזה לאירוע search.
completionInfo

object (CompletionInfo)

פרטים של CompletionService.CompleteQuery שקשורים לאירוע.

צריך להגדיר את השדה הזה לאירוע search כשהפונקציה של ההשלמה האוטומטית מופעלת והמשתמש לוחץ על הצעה לחיפוש.
transactionInfo

object (TransactionInfo)

מטא-נתונים של העסקה (אם יש) שמשויכים לאירוע המשתמש הזה.
tagIds[]

string

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

string

מזהי המבצעים אם מדובר באירוע שמשויך למבצעים. בשלב הזה, השדה הזה מוגבל למזהה אחד לכל היותר.
attributes

map (key: string, value: object)

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

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

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

  • המפתח חייב להיות מחרוזת בקידוד UTF-8, באורך של עד 5,000 תווים.
  • במאפייני טקסט, אפשר להזין עד 400 ערכים. אסור להשאיר ערכים ריקים. כל ערך צריך להיות מחרוזת בקידוד UTF-8, באורך של עד 256 תווים.
  • במאפייני מספרים, אפשר להזין עד 400 ערכים.

לגבי המלצות למוצרים, דוגמה למידע נוסף על המשתמש היא traffic_channel, שמתאר את האופן שבו המשתמש הגיע לאתר. המשתמשים יכולים להגיע לאתר ישירות, דרך חיפוש Google או בדרכים אחרות.
attributes.text[]

string

הערכים הטקסטואליים של המאפיין המותאם אישית הזה. לדוגמה, ["yellow", "green"] כשמילת המפתח היא color.

אסור להשתמש במחרוזת ריקה. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

צריך להגדיר בדיוק אחד מהמאפיינים CustomAttribute.text או CustomAttribute.numbers. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
attributes.numbers[]

number

הערכים המספריים של המאפיין המותאם אישית הזה. לדוגמה, [2.3, 15.4] כשהמפתח הוא lengths_cm.

צריך להגדיר בדיוק אחד מהמאפיינים CustomAttribute.text או CustomAttribute.numbers. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

מידע ספציפי למדיה.
panels[]

object (PanelInfo)

זה שינוי אופציונלי. רשימה של חלוניות שמשויכות לאירוע הזה. הם משמשים לנתוני חשיפות ברמת הדף.

PageInfo

מידע מפורט על הדף.

ייצוג ב-JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
שדות
pageviewId

string

מזהה ייחודי של צפייה בדף אינטרנט.

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

כשמשתמשים בדיווח על אירועים בצד הלקוח עם JavaScript pixel ו-Google Tag Manager, הערך הזה מתעדכן באופן אוטומטי.
pageCategory

string

הקטגוריה הכי ספציפית שמשויכת לדף קטגוריה.

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

דפי קטגוריות כוללים דפים מיוחדים כמו דפי מבצעים או קידומי מכירות. לדוגמה, דף מבצע מיוחד יכול להיות חלק מהיררכיית הקטגוריות הבאה: "pageCategory" : "Sales > 2017 Black Friday Deals".

חובה לאירועים מסוג view-category-page. אין להגדיר את השדה הזה לסוגים אחרים של אירועים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
uri

string

כתובת ה-URL המלאה (window.location.href) של הדף הנוכחי של המשתמש.

כשמשתמשים בדיווח על אירועים בצד הלקוח עם JavaScript pixel ו-Google Tag Manager, הערך הזה מתעדכן באופן אוטומטי. האורך המרבי הוא 5,000 תווים.
referrerUri

string

כתובת ה-URL של הגורם המפנה של הדף הנוכחי.

כשמשתמשים בדיווח על אירועים בצד הלקוח עם JavaScript pixel ו-Google Tag Manager, הערך הזה מתעדכן באופן אוטומטי. עם זאת, יכול להיות שהשדה הזה יהיה ריק בגלל מגבלות פרטיות מסוימות בדפדפן.

DocumentInfo

מידע מפורט על המסמך שמשויך לאירוע של משתמש.

ייצוג ב-JSON 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
שדות
promotionIds[]

string

מזהי המבצעים שמשויכים למסמך הזה. בשלב הזה, השדה הזה מוגבל למזהה אחד לכל היותר.
joined

boolean

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

שדה איחוד document_descriptor. תיאור חובה של Document המשויך.

  • אם מציינים את id, המערכת משתמשת בערכי ברירת המחדל של {location},‏ {collection_id},‏ {data_store_id} ו-{branch_id} כשמוסיפים הערות באמצעות המסמך המאוחסן.

  • אם מציינים את name, נעשה שימוש בערכים שסופקו (מותרים ערכי ברירת מחדל) עבור {location}, {collection_id}, {data_store_id} ו-{branch_id} כשמוסיפים הערות באמצעות המסמך המאוחסן. הערך document_descriptor יכול להיות רק אחד מהבאים:
id

string

מזהה המשאב Document.
name

string

השם המלא של משאב Document, בפורמט: projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

ה-URI‏ Document – מותר רק במאגרי נתונים של אתרים.
quantity

integer

כמות המסמך שמשויכת לאירוע המשתמש. ברירת המחדל היא 1.

לדוגמה, הערך בשדה הזה הוא 2 אם שני עותקים של אותו מסמך מעורבים באירוע add-to-cart.

חובה לאירועים מהסוגים הבאים:

  • add-to-cart
  • purchase
conversionValue

number

זה שינוי אופציונלי. ערך ההמרה שמשויך למסמך הזה. חובה להגדיר את הערך הזה אם הערך של UserEvent.event_type הוא conversion.

לדוגמה, ערך של 1,000 מציין שמשך הצפייה במסמך היה 1,000 שניות עבור watch סוג ההמרה.

PanelInfo

מידע מפורט על הפאנל שמשויך לאירוע של משתמש.

ייצוג ב-JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
שדות
panelId

string

חובה. מזהה הלוח.
displayName

string

השם המוצג של הלוח.
documents[]

object (DocumentInfo)

זה שינוי אופציונלי. מזהי המסמכים שמשויכים לחלונית הזו.
panelPosition

integer

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

integer

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

SearchInfo

מידע מפורט על החיפוש.

ייצוג ב-JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
שדות
searchQuery

string

שאילתת החיפוש של המשתמש.

הגדרה מופיעה בכתובת SearchRequest.query.

הערך חייב להיות מחרוזת בקידוד UTF-8, באורך של עד 5,000 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

כדי להגדיר אירועי search, צריך להגדיר לפחות אחד מהפרמטרים searchQuery או PageInfo.page_category. אין להגדיר את השדה הזה לסוגים אחרים של אירועים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
orderBy

string

סדר החזרת המוצרים, אם רלוונטי.

הגדרה ותחביר מופיעים כאן: SearchRequest.order_by.

הערך חייב להיות מחרוזת בקידוד UTF-8, באורך של עד 1,000 תווים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

אפשר להגדיר את זה רק לאירועים מסוג search. אין להגדיר את השדה הזה לסוגים אחרים של אירועים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.
offset

integer

מספר שלם שמציין את ההיסט הנוכחי של העמודים (המיקום ההתחלתי באינדקס 0, מבין המוצרים שה-API קבע כרלוונטיים).

הגדרה מופיעה בכתובת SearchRequest.offset.

אם השדה הזה שלילי, הפונקציה מחזירה INVALID_ARGUMENT.

אפשר להגדיר את זה רק לאירועים מסוג search. אין להגדיר את השדה הזה לסוגים אחרים של אירועים. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

CompletionInfo

פרטי השלמה מפורטים, כולל טוקן ייחוס השלמה ופרטי השלמה של קליקים.

ייצוג ב-JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
שדות
selectedSuggestion

string

נבחר משתמש קצה CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

המיקום שנבחר על ידי משתמש הקצה, החל מ-0.CompleteQueryResponse.QuerySuggestion.suggestion

TransactionInfo

עסקה מייצגת את כל עסקת הרכישה.

ייצוג ב-JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
שדות
currency

string

חובה. קוד מטבע. צריך להשתמש בקוד בן שלוש אותיות לפי תקן ISO-4217.
transactionId

string

מזהה הטרנזקציה, עם מגבלת אורך של 128 תווים.
value

number

חובה. הערך הכולל שמשויך לעסקה, לא כולל אפסים. הערך הזה יכול לכלול משלוח, מס או התאמות אחרות לערך הכולל שרוצים לכלול.
tax

number

כל המיסים שמשויכים לעסקה.
cost

number

כל העלויות שמשויכות למוצרים. אלה יכולות להיות עלויות ייצור, הוצאות משלוח שלא חלות על משתמש הקצה או כל עלויות אחרות, כך ש:
discountValue

number

הערך הכולל של ההנחות שחלות על העסקה הזו. הנתון הזה לא צריך להיכלל ב-TransactionInfo.value

לדוגמה, אם משתמש שילם סכום של TransactionInfo.value, הערך הנומינלי (לפני הנחה) של העסקה הוא הסכום של TransactionInfo.value ושל TransactionInfo.discount_value

כלומר, הרווח מחושב באותו אופן, ללא קשר לערך ההנחה, והערך TransactionInfo.discount_value יכול להיות גדול מהערך TransactionInfo.value:

MediaInfo

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

ייצוג ב-JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
שדות
mediaProgressDuration

string (Duration format)

זמן ההתקדמות במדיה בשניות, אם רלוונטי. לדוגמה, אם משתמש הקצה סיים צפייה בסרטון באורך 90 שניות, צריך להגדיר את MediaInfo.media_progress_duration.seconds ל-90.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-'s'. דוגמה: "3.5s".
mediaProgressPercentage

number

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

הערך צריך להיות בין [0, 1.0] כולל.

אם מדובר בשידור חי שעדיין מתקיים או שאי אפשר לחשב את ההתקדמות (למשל, שידור חי שעדיין מתקיים), צריך להשאיר את השדה הזה ללא ערך.

Methods

collect

 כותב אירוע משתמש יחיד מהדפדפן.

import

 ייבוא בכמות גדולה של אירועים שקשורים למשתמשים.

purge

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

write

 כתיבה של אירוע משתמש יחיד.