メッセージ UI の拡張

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

アドオン メッセージ UI へのアクセス

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

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

メッセージ アドオンの作成

メッセージ機能をアドオンに追加するには、次の手順を行います。

  1. メッセージ機能に必要なスコープを含む、適切なフィールドをアドオン スクリプト プロジェクトのマニフェストに追加します。必ず、マニフェストに条件付きトリガー フィールドを追加し、unconditional 値を {} にしてください。
  2. ユーザーがメッセージのアドオンを選択したときにメッセージ UI を作成するコンテキスト トリガー関数を実装します。
  3. ユーザーの 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 つだけ含む 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];
  }