הרחבת ממשק המשתמש של ההודעה

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

גישה לממשק המשתמש של התוסף להודעות

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

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

פיתוח תוסף להודעות

כדי להוסיף לתוסף פונקציונליות של הודעות, פועלים לפי השלבים הכלליים הבאים:

1. מוסיפים את השדות המתאימים למניפסט של פרויקט התוסף, כולל ההיקפים שנדרשים לפונקציונליות של ההודעות. חשוב להוסיף שדה של טריגר מותנה למניפסט, עם ערך של unconditional {}.
2. מטמיעים פונקציית הפעלה לפי הקשר שיוצרת ממשק משתמש להודעה כשמשתמש בוחר את התוסף בהודעה.
3. מטמיעים את הפונקציות המשויכות שנדרשות כדי להגיב לאינטראקציות של המשתמש עם ממשק המשתמש.

טריגרים לפי הקשר

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

טריגרים הקשריים מוגדרים במניפסט של פרויקט התוסף. הגדרת הטריגר מציינת ל-Gmail איזו פונקציית טריגר תופעל ובאילו תנאים. לדוגמה, קטע המניפסט הזה מגדיר טריגר ללא תנאי שקורא לפונקציית הטריגר onGmailMessageOpen() כשפותחים הודעה:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

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

פונקציית טריגר לפי הקשר

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

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

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

הערה: ברוב המקרים צריך להפעיל היקפי גישה ב-Gmail באמצעות אסימון הגישה שסופק על ידי אובייקט האירוע והפונקציה GmailApp.setCurrentMessageAccessToken(accessToken) לפני שמשתמשים בפונקציות אחרות של שירות Gmail.

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

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

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }