דפי בית

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

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

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

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

דף הבית של התוסף מוצג במקרים הבאים:

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

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

הגדרת דף הבית

תוספים ל-Google Workspace משתמשים בשדה addOns.common.homepageTrigger כדי להגדיר את תוכן התוסף בדף הבית שמוצג כברירת מחדל (לא תלוי הקשר) באפליקציות המארחות במניפסט של התוסף:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

• ‫runFunction: שם הפונקציה ב-Google Apps Script שהמסגרת של תוספי Google Workspace מפעילה כדי לעבד כרטיסי תוספים בדף הבית. הפונקציה הזו היא פונקציית ההפעלה של דף הבית. הפונקציה הזו צריכה ליצור מערך של אובייקטים מסוג Card שמרכיבים את ממשק המשתמש של דף הבית, ולהחזיר את המערך. אם מוחזר יותר מכרטיס אחד, אפליקציית המארח מציגה את כותרות הכרטיסים ברשימה שהמשתמש יכול לבחור מתוכה (ראו החזרת כמה כרטיסים).

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

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

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

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

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

קטע המניפסט הבא שווה לדוגמה הקודמת, למרות שההגדרה homepageTrigger של ברירת המחדל וההגדרה של Gmail הושמטו:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

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

הגדרת דף הבית של Chat

בניגוד לאפליקציות אחרות של Google Workspace, תוספים שמרחיבים את Chat לא מציגים דף בית בחלונית הגישה המהירה בצד שמאל, ולא משתמשים ב-addOns.common.homepageTrigger במניפסט. במקום זאת, דף הבית שלכם מוצג ב-Chat ככרטיסייה במסך הבית של הצ'אט הישיר עם אפליקציית Chat.

כדי להפעיל ולהגדיר טריגר של דף הבית של האפליקציה בתוסף Chat במסוף Google Cloud:

1. במסוף Google Cloud, לוחצים על תפריט > ממשקי API ושירותים > ממשקי API ושירותים מופעלים > Google Chat API > הגדרה.

   מעבר אל Google Chat API Configuration

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

3. בקטע Connection settings > Triggers (הגדרות חיבור > טריגרים), מציינים את handler של דף הבית של האפליקציה בשדה App home (דף הבית של האפליקציה) בהתאם לארכיטקטורה של התוסף:

   • ‫HTTP: מזינים את כתובת ה-URL של נקודת הקצה מסוג HTTPS שמטפלת בבקשות של דף הבית של האפליקציה (או משאירים את השדה ריק כדי שכתובת ה-URL של נקודת הקצה הנפוצה מסוג HTTP תקבל את כל האירועים).
   • ‫Google Apps Script: מזינים את שם פונקציית הקריאה החוזרת של Google Apps Script שיוצרת ומחזירה את כרטיס דף הבית (ברירת המחדל היא onAppHome).

4. לוחצים על שמירה.

כשמשתמש פותח את הכרטיסייה דף הבית בצ'אט ישיר עם אפליקציית Chat שלכם, ‏ Chat שולח אירוע הפעלה של דף הבית של האפליקציה לנקודת הקצה או לפונקציה שלכם. כדי להציג את דף הבית, מחזירים אובייקט RenderActions עם פעולת ניווט pushCard (או משתמשים ב-updateCard כשמעדכנים את דף הבית בתגובה ללחיצה על לחצן בכרטיס של דף הבית):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

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

אובייקטים של אירועים בדף הבית

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

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

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• ‫commonEventObject.userLocale ו-commonEventObject.userTimezone (מידע על ההגבלות מופיע במאמר גישה ללוקאל ולאזור הזמן של המשתמש).

ב-Chat, אובייקט האירוע App Home כולל גם את השדה chat עם מידע על המשתמש ועל מועד האינטראקציה:

• ‫chat.user: המשתמש ב-Chat שפתח את הכרטיסייה דף הבית.
• ‫chat.eventTime: חותמת הזמן שבה המשתמש פתח את הכרטיסייה דף הבית.

פרטים נוספים מופיעים במאמר בנושא אובייקט אירוע.

כרטיסים אחרים שלא קשורים להקשר

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

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