Gmail を拡張する Google Workspace アドオンを使用すると、ユーザーがメールを読んでいるときにユーザー インターフェースを提供できます。これにより、Google Workspace アドオンは、メッセージに関連する追加情報の表示、取得、送信など、メッセージ コンテンツに応答するタスクを自動化できます。
アドオン メッセージ UI にアクセスする
アドオンのメッセージ UI を表示する方法は 2 つあります。1 つ目は、アドオンがすでに開いているとき(たとえば、Gmail の受信トレイ ウィンドウでアドオンのホームページを表示しているとき)にメッセージを開く方法です。2 つ目は、メッセージを表示した状態でアドオンを起動する方法です。
いずれの場合も、アドオンのマニフェストで定義されている、対応するコンテキスト トリガー関数が実行されます。アドオンが開いているときにユーザーが別のメッセージに切り替えた場合も、トリガーが実行されます。コンテキスト トリガー関数により、そのメッセージのメッセージ 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
オブジェクトの配列をビルドして返す必要があります。たとえば、次の例では、メッセージの件名と送信者のみを一覧表示する 1 つのカードを使用してアドオンをビルドします。
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];
}