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

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

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

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

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

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

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

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

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

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

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

{
  ...
  "addOns": {

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

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

לכל טריגר לפי הקשר צריכה להיות פונקציית טריגר תואמת שמרכיבת את ממשק המשתמש של התוסף. מציינים את הפונקציה הזו בשדה 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();

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

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