擴充 Gmail 的 Google Workspace 外掛程式可在使用者讀取郵件時提供使用者介面。如此一來,Google Workspace 外掛程式就能自動執行會回應訊息內容的工作,例如顯示、擷取或傳送與訊息相關的其他資訊。
存取外掛程式訊息 UI
有兩種方法可以查看外掛程式的訊息 UI。第一種方法是在外掛程式已開啟的情況下 (例如在 Gmail 收件匣視窗中查看外掛程式首頁) 開啟郵件。第二種方式是在查看訊息時啟動外掛程式。
這兩種情況都會導致外掛程式執行對應的情境觸發條件函式 (在外掛程式資訊清單中定義)。如果使用者在外掛程式仍處於開啟狀態時切換至其他訊息,系統也會執行觸發條件。關聯觸發函式會為該訊息建構訊息 UI,然後 Gmail 向使用者顯示該訊息。
建立訊息外掛程式
您可以遵循下列一般步驟,在外掛程式中新增訊息功能:
- 將適當欄位新增至外掛程式指令碼專案資訊清單,包括訊息功能所需的範圍。請務必在資訊清單中新增條件式觸發條件欄位,並將
unconditional
值設為{}
。 - 實作內容相關觸發條件函式,在使用者選取訊息中的外掛程式時建構訊息 UI。
- 實作回應使用者 UI 互動所需的相關聯函式。
內容比對觸發條件
為了協助使用者在讀取訊息時提供協助,Google Workspace 外掛程式可以在資訊清單中定義內容觸發條件。使用者開啟符合觸發條件*的 Gmail 郵件 (已開啟外掛程式) 時,觸發條件就會啟動。觸發的觸發條件會執行關聯觸發條件函式,藉此建構外掛程式使用者介面,並傳回該函式以供 Gmail 顯示。從那時起,使用者就可以開始與之互動。
內容比對觸發條件是由外掛程式的專案資訊清單所定義。觸發條件定義會告知 Gmail 要在哪些條件下觸發哪些觸發函式。舉例來說,此資訊清單程式碼片段會設定無條件觸發條件,在訊息開啟時呼叫觸發函式 onGmailMessageOpen()
:
{ ... "addOns": { "common": { ... }, "gmail": { "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ], ... }, ... } ... }
內容比對觸發函式
每個內容比對觸發條件都必須有對應的觸發條件函式,用來建構外掛程式的使用者介面。請在資訊清單的 onTriggerFunction
欄位中指定這個函式。您實作此函式以接受動作事件物件引數,並傳回單一 Card
物件或 Card
物件的陣列。
當特定 Gmail 郵件觸發內容相關觸發條件時,它會呼叫這個函式,並將動作事件物件傳遞給該函式。觸發函式通常會使用這個事件物件提供的訊息 ID,透過 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();
然後,觸發條件函式就可以對這些資料採取行動,擷取其介面所需的資訊。舉例來說,匯總銷售數字的外掛程式可收集訊息內文中的銷售數據,並將這些資料整理以顯示在資訊卡中。
觸發函式必須建構並傳回建構的 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];
}