אובייקטים של אירוע

בדף הזה מוסבר על המבנה של אובייקטים של אירועים בתוספים ל-Google Workspace.

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

תוספים ל-Google Workspace משתמשים באובייקטים של אירועים במקומות הבאים:

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

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

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

  • ‫Gmail מספק טריגר הקשרי כשמשתמש פותח הודעה, ועוד טריגר כשמשתמש כותב הודעה.
  • יומן Google מספק טריגר תלוי-הקשר שמופעל כשמשתמש פותח אירוע.
  • ‫Google Drive מספק טריגר הקשרי שמופעל כשמשתמש בוחר קבצים ב-Drive.

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

• פעולות בווידג'ט. אובייקטים של אירועים משמשים גם כדי לספק אינטראקטיביות של ווידג'טים, באמצעות אותו מודל פעולה שבו משתמשים תוספים ל-Gmail. תוספים ל-Google Workspace משתמשים בכל אותן פונקציות לטיפול בווידג'טים, Action אובייקטים ותגובות לפעולות. עם זאת, בתוספים ל-Google Workspace, אובייקטים של אירועי פעולה כוללים עוד יותר מידע שפונקציית קריאה חוזרת יכולה לפעול לפיו.

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

• תצוגה מקדימה של טריגרים של קישורים ב-Google Docs, ב-Sheets וב-Slides, אפשר להגדיר תצוגה מקדימה של קישורים לשירותי צד שלישי על סמך דפוסי כתובות URL ספציפיים. כשמשתמשים יוצרים אינטראקציה עם קישור שתואם לתבנית, התג linkPreviewTriggers מופעל ואובייקט אירוע שמכיל את הקישור מועבר לפונקציית הקריאה החוזרת של הטריגר. תוסף יכול להשתמש באובייקט האירוע הזה כדי ליצור צ'יפ חכם וכרטיס שמציגים מידע על הקישור בתוך אפליקציית המארח. אתם יכולים גם ליצור פעולות בווידג'ט כדי לאפשר למשתמשים ליצור אינטראקציה עם כרטיס התצוגה המקדימה והתוכן שלו.

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

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

בטבלה הבאה מתואר המבנה ברמה העליונה של אובייקטים של אירועים בתוספים ל-Google Workspace. מבנה אובייקט האירוע כולל שדה ברמה העליונה commonEventObject למידע שלא תלוי במארח. כל אובייקט של אירוע יכול לכלול גם אחד מהשדות הבאים ברמה העליונה שספציפיים למארח, בהתאם לאפליקציה המארחת הפעילה: gmailEventObject,‏ calendarEventObject או driveEventObject.

כדי לשמור על תאימות לאחור, אובייקטים של אירועים בתוספים של Google Workspace כוללים גם את כל השדות המקוריים שנעשה בהם שימוש באובייקטים של אירועים של פעולות בתוספים של Gmail. השדות האלה מפורטים בטבלה שלמטה בקטע 'שדות מקוריים של תוסף Gmail'; המידע בשדות האלה מועתק למבנה אובייקט חדש.

אובייקט אירוע נפוץ

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

בנוסף לדף הבית ולטריגרים לפי הקשר, התוספים יוצרים ומעבירים אובייקטים של אירועים אל פונקציות של קריאה חוזרת לפעולה כשמשתמש מקיים אינטראקציה עם ווידג'טים. פונקציית הקריאה החוזרת של התוסף יכולה לשלוח שאילתה לאובייקט האירוע המשותף כדי לקבוע את התוכן של הווידג'טים הפתוחים בלקוח של המשתמש. לדוגמה, התוסף יכול לאתר את הטקסט שהמשתמש הזין בווידג'ט TextInput באובייקט eventObject.commentEventObject.formInputs.

קלט של טופס לבחירת תאריך ושעה

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

אובייקט של אירוע ב-Chat

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

מטען ייעודי

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

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}