メッセージ UI を拡張する

Gmail を拡張する Google Workspace アドオンは、ユーザーがメッセージを読んでいるときにユーザー インターフェースを提供できます。これにより、アドオンはメッセージの内容に応じたタスクを自動化できます。たとえば、メッセージに関連する追加情報の表示、取得、送信などです。

Google Workspace アドオンのメッセージ UI にアクセスする

アドオンのメッセージ UI を表示するには、2 つの方法があります。1 つ目は、アドオンがすでに開いている状態でメッセージを開く方法です（たとえば、Gmail の受信トレイ ウィンドウでアドオンのホームページを表示している場合など）。2 つ目は、メッセージを表示しているときにアドオンを起動する方法です。

いずれの場合も、アドオンはアドオン マニフェストで定義されている対応する コンテキスト トリガー関数を実行します。アドオンが開いている間にユーザーが別のメッセージに切り替えた場合も、トリガーが実行されます。コンテキスト トリガー関数は、そのメッセージのメッセージ UI を作成します。この UI は Gmail によってユーザーに表示されます。

メッセージ アドオンを作成する

次の一般的な手順に沿って、アドオンにメッセージ機能を追加できます。

  1. メッセージ機能に必要な スコープなど、適切なフィールドをアドオン スクリプト プロジェクト マニフェストに追加します。マニフェストに 条件付きトリガー フィールド を追加し、 unconditional の値を{}に設定してください。
  2. ユーザーがメッセージでアドオンを選択したときにメッセージ UI を作成するコンテキスト トリガー関数を実装します。
  3. ユーザーの UI 操作に応答するために必要な関連関数を実装します。

コンテキスト トリガー

ユーザーがメッセージを読んでいるときにサポートを提供するために、アドオンはマニフェストで コンテキスト トリガーを定義できます。ユーザーがトリガー条件*を満たす Gmail メッセージを開くと（アドオンが開いている場合）、トリガーが起動します。起動した トリガーは、アドオンのユーザー インターフェースを作成して Gmail に表示するために返すコンテキスト トリガー関数 を実行します。この時点で、ユーザーは操作を開始できます。

コンテキスト トリガーは、アドオンのプロジェクト マニフェストで定義されます。 トリガー定義では、どの条件でどのトリガー関数を起動するかを Gmail に伝えます。たとえば、次のマニフェスト スニペットでは、メッセージが開かれたときにトリガー関数 onGmailMessageOpen() を呼び出す無条件トリガーを設定します。

{
  ...
  "addOns": {

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

コンテキスト トリガー関数

すべてのコンテキスト トリガーには、アドオンのユーザー インターフェースを作成する対応する トリガー関数が必要です。この関数は、マニフェストの onTriggerFunction フィールドで指定します。この関数を実装して、アクション イベント オブジェクト引数を受け取り、単一の Card オブジェクトまたは Card オブジェクトの配列を返します。

特定の Gmail メッセージに対してコンテキスト トリガーが起動すると、 この関数が呼び出され、 アクション イベント オブジェクトが渡されます。 多くの場合、トリガー関数は、このイベント オブジェクトから提供されるメッセージ ID を使用して メッセージ テキストやその他の詳細情報を Apps Script の Gmail サービスを使用して取得します。 ほとんどの場合、他の Gmail サービス関数を使用する前に、イベント オブジェクトから提供されるアクセス トークンと GmailApp.setCurrentMessageAccessToken(accessToken) 関数を使用して 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}