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

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

מידע כללי על חיפוש והמלצות למדיה זמין במאמר [מבוא לחיפוש והמלצות למדיה][about-media].

לקבלת עזרה ברישום אירועים של משתמשים, אפשר לעיין במאמר בנושא [רישום אירועים בזמן אמת][record-events]. כדי לייבא אירועים קודמים של משתמשים בכמות גדולה, אפשר לעיין במאמר בנושא [ייבוא אירועים היסטוריים של משתמשים][import-user-events].

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

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

שם האירוע של המשתמש פעולת המשתמש
view-item צפייה בפרטים של מסמך.
view-home-page צפייה בדף הבית.
search חיפוש באפליקציה.
media-play המשתמש לוחץ על לחצן ההפעלה של פריט מדיה.
media-complete הפסקת ההפעלה של פריט מדיה, שמסמלת את סיום הצפייה.

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

דרישות לגבי אירועים לצורך חיפוש והמלצות למדיה

סוגי אירועי המשתמש שאתם צריכים תלויים בשאלה אם האפליקציה שלכם היא אפליקציית חיפוש או אפליקציית המלצות, ביעד (שיעור קליקים, שיעור המרות או משך צפייה) ובסוג המודל שבחרתם (רק לאפליקציות המלצות). מידע נוסף על סוגי מודלים של המלצות ויעדי אופטימיזציה זמין במאמר [מידע על סוגי המלצות לאפליקציות מדיה][rec-type-reqs].

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

אירוע search view-home-page view-item media-play media-complete
תרחיש שימוש בחיפוש
חובה לא
נדרש		 חובה חובה חובה
סוג המודל 'מומלץ בשבילך', לפי יעד
שיעור קליקים לא
נדרש		 נדרש להקשר של דף הבית

לא נדרש להקשר כללי		 צריך לציין view-item או media-play מומלץ מאוד


חובה אם ההיסטוריה של הורדת הדירוג מופעלת
שיעור המרות (CVR) לא
נדרש		 נדרש להקשר של דף הבית

לא נדרש להקשר כללי		 צריך לציין view-item או media-play חובה
משך הצפייה לא
נדרש		 נדרש להקשר של דף הבית

לא נדרש להקשר כללי		 צריך לציין view-item או media-play חובה
סוג המודל 'עוד תוצאות שאולי יעניינו אותך', לפי יעד
שיעור קליקים לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play מומלץ מאוד


חובה אם ההורדה של היסטוריית ההמרות מופעלת
שיעור המרות (CVR) לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play חובה
משך הצפייה לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play חובה
סוג המודל 'יצירת נכסים דומים', לפי יעד
שיעור קליקים לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play חובה אם הפעלתם הורדה של מוצרים מההיסטוריה
שיעור המרות (CVR) לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play חובה
משך הצפייה לא
נדרש		 לא
נדרש		 צריך לציין view-item או media-play חובה
סוג המודל הפופולרי ביותר, לפי יעד
שיעור קליקים לא
נדרש		 לא
נדרש		 חובה לציין את view-item או את media-play לא
נדרש
שיעור המרות (CVR) לא
נדרש		 לא
נדרש		 לא
נדרש		 לא
נדרש		 חובה

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

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

סוג אירוע דרישה השפעה
כל האירועים

אל תכללו נתונים סינתטיים או אירועים כפולים.

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

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

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

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

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

חובה למלא את השדה DocumentInfo.name או את השדה DocumentInfo.id בכל המסמכים.

אי אפשר להשתמש באירוע שכולל מסמך ללא שדה DocumentInfo.name או שדה DocumentInfo.id באפליקציות להמלצות על מדיה.

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

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

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

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

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

view-item

לכל אירוע צריך לצרף מסמך אחד בלבד.

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

search

כוללים את attributionToken. הערך attributionToken מוחזר על ידי השיטה search יחד עם תוצאות החיפוש או הגלישה.

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

media-play

לכל אירוע צריך לצרף מסמך אחד בלבד.

אם נכללים כמה מסמכים, האירוע פגום ואי אפשר להשתמש בו.

תגי אירועים של משתמשים לבדיקות A/B

אם אתם מבצעים בדיקות A/B, הקפידו להוסיף מזהי תגים לכל אירועי המשתמשים שאתם אוספים, ולהוסיף תג אחד לכל קבוצת בדיקה.

לדוגמה, מוסיפים את התג "tagIds": ["original"] לאירועים של המשתמשים מהמודל הנוכחי ואת התג "tagIds": ["google"] לאירועים של המשתמשים מחיפוש מבוסס סוכנים למדיה.

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

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

view-home-page

בדוגמה הבאה מוצג הפורמט של אירוע משתמש view-home-page.

האובייקט המינימלי הנדרש view-home-page

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

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

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

JavaScript Pixel

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "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": "quantity",
        "type": "INT64",
        "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"
          }
        ]
      }
    ]
  }
]

מידע על אובייקט panels זמין במאמר מידע על חלוניות.

בדוגמה הבאה מוצג הפורמט של אירוע משתמש 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"
      }
    ]
  }
]

media-play

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

אובייקט מינימלי של הפעלת מדיה

בדוגמאות הבאות מוצגים רק השדות הנדרשים של הפורמט media-play user event.

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

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

JavaScript Pixel

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

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"
          }
        ]
      }
    ]
  }
]

media-complete

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

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

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

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

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

JavaScript Pixel

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 0.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"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

מאפיינים מותאמים אישית

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

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

אפשר לספק ערכי טקסט מותאמים אישית באמצעות השדה text או ערכים מספריים מותאמים אישית באמצעות השדה numbers.

לדוגמה, הקטע attributes הבא מתוך בקשה לתיעוד אירוע של משתמש:

  attributes: {
    user_age: {text: ["teen", "young adult"]},
    user_location: {text: ["CA"]},
    user_zip: {numbers: [90210]}
  }

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

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

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

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

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

מידע על לוחות

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

פרטי החלונית של אירועים שקשורים למשתמשים

כדי להשתמש באירועי המשתמש המומלצים מסוג view-home-page ו-view-item, צריך להוסיף מידע על החלונית. חובה להציג מידע בחלונית בדפי בית ובדפי פרטים שבהם מוצג תוכן שמומלץ על ידי Google.

אם אתם עורכים A/B Testing בפאנל, אתם צריכים לתעד אירועים של משתמשים עם פרטי הפאנל לגבי כל התוכן בבדיקה, ללא קשר למקור. בדפי בית ובדפים עם פרטים שלא כוללים תוכן של חלונית שנוצר על ידי Google, מומלץ לספק את פרטי החלונית באירועים view-home-page ו-view-item, אבל זה לא חובה. הדרישות האלה מסוכמות בטבלה הבאה:

מקור אירוע המשתמש (view-home-page ו-view-item) PanelInfo חובה
כולל תוכן שמומלץ על ידי Google כן
כולל תוכן שלא מומלץ על ידי Google ומשמש לבדיקות A/B כן
כולל תוכן שלא מומלץ על ידי Google ושלא נעשה בו שימוש בבדיקות A/B לא

פרטי הלוח (PanelInfo) הם קבוצה של שדות שמתארים רכיבים שונים של הלוח:

  • מספר הזיהוי של הלוח

  • השם המוצג

  • המיקום של החלונית בדף (למשל, החלונית הראשונה (1) בדף או החלונית השלישית (3) בדף)

  • המספר הכולל של חלוניות בדף

  • רשימת המסמכים (DocumentInfo) שמוצגת בכל חלונית

מידע מפורט על אובייקטים של PanelInfo זמין במאמר PanelInfo.

טעינה מראש של לוחות לעומת טעינה עצלה של לוחות

יש שתי שיטות נפוצות להצגת המלצות בדפי אינטרנט או בדפים לנייד. השיטה שבה אתם משתמשים קובעת את המספר והתוכן של view-home-page אירועי המשתמשים שאתם מתעדים.

  • טעינה מראש: בטעינה מראש, כל פריטי ההמלצות נוצרים כשהמשתמש מגיע לדף. במקרה הזה, כשמשתמש טוען את דף הבית, מתועד אירוע משתמש אחד view-home-page (או view-item) עם כל החלוניות והמסמכים.

  • טעינה מדורגת: בטעינה מדורגת, התוכן של החלונית לא נוצר כשהמשתמש מגיע לדף, אלא נטען באופן דינמי כשהמשתמש גולל למטה לחלוניות או ימינה כדי לראות עוד המלצות. במקרה הזה, כשמשתמש טוען את דף הבית, המערכת מתעדת אירוע משתמש ראשוני view-home-page (או view-item) ואז ממשיכה לתעד עוד אירועים כשהמשתמש גולל כדי ליצור עוד תוכן מומלץ. באירועים הבאים, צריך לכלול במערך panels רק את הגידול במספר המסמכים שמוצגים.

מקרה לדוגמה

בדף הבית של חברת מדיה מוצגות שתי חלוניות של המלצות:

  • חלונית 'פופולריים עכשיו' שמבוססת על המודל הכי פופולריים.

  • לוח המלצות מותאם אישית שנבדק באמצעות בדיקת A/B. חלק מהמשתמשים רואים חלונית עם הצעות שמבוססות על המודל מומלץ בשבילך (קבוצה א'), וחלק מהמשתמשים רואים המלצות שמבוססות על המודל הקנייני של החברה (קבוצה ב').

כשמשתמש שמשויך לקבוצה ב' צופה בדף הבית הזה, אירוע המשתמש בפורמט JavaScript Pixel נראה כך:

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "4003345673.123451357",
  "eventTime": "2025-07-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "jane.doe@example.com",
  },
  "tagIds": ["group-B"],
  "panels": [
    {
      "panelId": "panel-1",
      "displayId": "Trending Now",
      "documents": [
        {
          "id": "254722"
        },
        {
          "id": "2951"
        },
        ...
        {
          "id": "1201"
        }
      ],
      "panelPosition": 1,
      "totalPanels": 2
    },
    {
      "panelId": "panel-2",
      "displayId": "Recommended for You",
      "documents": [
        {
          "id": "79132"
        },
        {
          "id": "109487"
        },
        ...
        {
          "id": "164179"
        }
      ],
      "panelPosition": 2,
      "totalPanels": 2
    }
  ]
};

המאמרים הבאים

  • איך מתעדים אירועי משתמשים

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

[about-media]: /generative-ai-app-builder/docs/about-media [about-user-events]: /generative-ai-app-builder/docs/user-events [import-user-events]: /generative-ai-app-builder/docs/import-user-events [record-events]: /generative-ai-app-builder/docs/record-user-events