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

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

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

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

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

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

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

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

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

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

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

{
  ...
  "addOns": {

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

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

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

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

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

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