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

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

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

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

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

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

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

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

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

• פעולות בווידג'ט. אובייקטים של אירועים מספקים אינטראקטיביות של ווידג'טים, באמצעות אותו מודל פעולות שבו משתמשים תוספים של Gmail. תוספים ל-Google Workspace משתמשים באותן פונקציות של widget handler, באובייקטים 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' והם לא חלק מ-commonEventObject.

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

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

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

בנוסף לדף הבית ולטריגרים לפי הקשר, תוספים יוצרים ומעבירים אובייקטים של אירועים אל פונקציות של קריאה חוזרת (callback) לפעולות כשמשתמשים מקיימים אינטראקציה עם ווידג'טים. פונקציית הקריאה החוזרת של התוסף יכולה לשלוח שאילתה לאובייקט האירוע המשותף כדי לקבוע את התוכן של הווידג'טים הפתוחים בלקוח של המשתמש. לדוגמה, התוסף יכול לאתר את הטקסט שמשתמש הזין בווידג'ט 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"
  }
}