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

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

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

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

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

יצירת תוסף לשליחת SMS

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

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];
  }