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

בדף הזה מתוארים אירועים שקשורים למשתמשים באפליקציות Gemini Enterprise, כולל סוגי אירועים שקשורים למשתמשים, דרישות ודוגמאות לסוגי אירועים שקשורים למשתמשים.

אם אתם משתמשים בממשקי Gemini Enterprise API באפליקציות שלכם, אתם צריכים להגדיר חיפוש באפליקציה כדי לקבל את אירועי המשתמשים, ואז להוסיף את נתוני אירועי המשתמשים לאפליקציית Gemini Enterprise.

אם יצרתם את האפליקציה דרךGoogle Cloud מסוף, אתם לא צריכים לייבא אירועים של משתמשים באופן ידני (ואתם לא צריכים לקרוא את הדף הזה).

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

סוגי אירועים שקשורים למשתמשים

אתם יכולים לתעד את סוגי האירועים הבאים של משתמשים בזמן שהם גולשים באתר או מחפשים בו:

שם האירוע של המשתמש	פעולת המשתמש
view-item	צפייה בפרטים של מסמך.
search	חיפוש נתונים באפליקציית Gemini Enterprise.

פרטים על אובייקט אירוע המשתמש מופיעים בUserEventמאמרי העזרה של ה-API.

דוגמאות וסכימות של סוגי אירועים של משתמשים

בקטע הזה מפורטים פורמטי הנתונים של כל סוג אירוע שנתמך באפליקציות של Gemini Enterprise. הוספנו דוגמאות ל-JavaScript Pixel. ב-BigQuery, מפורטת סכימת הטבלה המלאה לכל סוג.

הפרמטר userId הוא אופציונלי לכל סוגי האירועים שקשורים למשתמשים.

פרטים נוספים על אובייקט אירוע המשתמש מופיעים ב[UserEventמאמרי העזרה בנושא API][user-event].

view-item

בהמשך מוצג פורמט נתוני האירועים של המשתמש view-item.

דרישות האופטימיזציה של החיפוש לאירועים מסוג view_item

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

מומלץ להעלות אירועים לפחות פעם ביום, עם עיכוב של עד 24 שעות.

מדד האירועים	נפח או תדירות האירועים	תיאור
נפח האירועים מסוג view-item	250,000 צפיות בפריטים	נדרשים לפחות 250,000 אירועים מסוג view_item כדי לבצע אופטימיזציה של חוויית החיפוש על סמך אירועים שהמערכת קולטת.

אובייקט view-item מינימלי נדרש

בדוגמאות הבאות מוצגים רק שדות החובה של פורמט אירוע המשתמש view-item.

האובייקט documents מכיל את מזהה המסמך (id) ואת שם המשאב שלו (name).

• כשמבצעים המרה או תיעוד של אירועים ברמת מאגר הנתונים, אפשר לספק את מזהה המסמך (id) או את שם המשאב (name).
• כשמבצעים המרה או הקלטה של אירועים ברמת המיקום, צריך לספק את שם המשאב של המסמך (name) כי הוא מציין את הנתיב המלא של המסמך ומתייחס למאגר הנתונים שבו המסמך נמצא. אפשר לספק את המזהה של המסמך כמידע נוסף אופציונלי.

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

BigQuery

זוהי סכימת ה-JSON המלאה של סוג אירוע המשתמש הזה. מציינים את הסכימה הזו כשיוצרים טבלאות לסוג האירוע הזה של המשתמש ב-BigQuery.

הערכים של מצבי שדות החובה הם REQUIRED או REPEATED. האמצעים להגעה לשדות אופציונליים מוגדרים כNULLABLE.

שימו לב: כדי לייבא אירועים באמצעות BigQuery, צריך להגדיר את eventTime. ‫eventTime היא מחרוזת בפורמט של חותמת זמן.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

דוגמה מלאה לאובייקט view-item

הדוגמאות הבאות כוללות שדות חובה ושדות אופציונליים עבור אירוע המשתמש view-item.

JavaScript Pixel

var user_event = {
  eventType: "view-item",
  userPseudoId: "visitor0",
  "engine": "APP_ID",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "[e-mail]",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels: [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

BigQuery

זוהי סכימת ה-JSON המלאה של סוג אירוע המשתמש הזה. מציינים את הסכימה הזו כשיוצרים טבלאות לסוג האירוע הזה של המשתמש ב-BigQuery.

הערכים של מצבי שדות החובה הם REQUIRED או REPEATED. האמצעים להגעה לשדות אופציונליים מוגדרים כNULLABLE.

שימו לב: כדי לייבא אירועים באמצעות BigQuery, צריך להגדיר את eventTime. ‫eventTime היא מחרוזת בפורמט של חותמת זמן.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

search

בדוגמה הבאה מוצג הפורמט של אירוע משתמש search.

דרישות לאופטימיזציה של חיפושים לאירועים שקשורים לחיפוש

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

מומלץ להעלות אירועים לפחות פעם ביום, עם עיכוב של עד 24 שעות.

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

אובייקט החיפוש המינימלי הנדרש

בדוגמאות הבאות מוצגים רק שדות החובה של הפורמט search של אירוע משתמש.

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

הערך attributionToken מוחזר עם תוצאות שאילתת החיפוש.

האובייקט documents מכיל את מזהה המסמך (id) ואת שם המשאב שלו (name).

• כשמבצעים המרה או תיעוד של אירועים ברמת מאגר הנתונים, אפשר לספק את מזהה המסמך (id) או את שם המשאב (name).
• כשמבצעים המרה או הקלטה של אירועים ברמת המיקום, צריך לספק את שם המשאב של המסמך (name) כי הוא מציין את הנתיב המלא של המסמך ומתייחס למאגר הנתונים שבו המסמך נמצא. אפשר לספק את המזהה של המסמך כמידע נוסף אופציונלי.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

BigQuery

זוהי סכימת ה-JSON המלאה של סוג אירוע המשתמש הזה. מציינים את הסכימה הזו כשיוצרים טבלאות לסוג האירוע הזה של המשתמש ב-BigQuery.

הערכים של מצבי שדות החובה הם REQUIRED או REPEATED. האמצעים להגעה לשדות אופציונליים מוגדרים כNULLABLE.

שימו לב: כדי לייבא אירועים באמצעות BigQuery, צריך להגדיר את eventTime. ‫eventTime היא מחרוזת בפורמט של חותמת זמן.

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

מידע על פרטי משתמשים

‫userPseudoId מייצג את מזהה המשתמש הייחודי והוא נדרש כשרושמים אירוע של משתמש.

פרטי המשתמש ([UserInfo][user-info]) שנכללים כשמתעדים אירוע משתמש מכילים את הערך userPseudoId, ואם הוא זמין, גם את הערך userId. ‫userId הוא אופציונלי ויכול לשמש כמזהה ייחודי וקבוע של משתמש במכשירים שונים, בכל פעם שמשתמש מתחבר לאתר שלכם. כשמפעילים את userId עבור משתמש, אפליקציות Gemini Enterprise יכולות ליצור תוצאות מותאמות אישית יותר עבור משתמש אחד במכשירים שונים, למשל במכשיר נייד ובדפדפן אינטרנט.

הערה: כדי לשמור על האנונימיות של המשתמשים ב-Gemini Enterprise ולהגן על הפרטיות שלהם, מומלץ להשתמש במזהה ייחודי מאובטח. באחריותכם לצנזר פרטים אישיים מזהים (PII), כמו כתובות אימייל או כתובות מגורים, מהנתונים שלכם.

מידע על חותמת הזמן

כשאתם מתעדים אירוע משתמש, חשוב לכלול חותמת זמן מדויקת של מועד התרחשות האירוע. חותמות זמן מדויקות מבטיחות שהאירועים יישמרו בסדר הנכון. חותמות הזמן מתועדות באופן אוטומטי עבור אירועים שנאספים באמצעות JavaScript Pixel. כשמייבאים אירועים, צריך לציין את חותמת הזמן בשדה [eventTime][event-time] בפורמט שמוגדר ב-RFC 3339.

‫[rec-type-reqs]: /gemini/enterprise/docs/about-media-recommendations-types ‫[record-events]: /gemini/enterprise/docs/record-user-events ‫[event-time]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#UserEvent.FIELDS.event_time ‫[user-event]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents ‫[user-info]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#userinfo