ユニバーサル アクション

ユニバーサル アクションは、ユーザーが新しいタブを開くことができるメニュー項目要素です 新しい UI カードを表示したり、特定の Apps Script 関数を実行したりするときに、 選択済みです。実際の動作は カード アクション ユニバーサルアクションは アドオンのすべてのカードに 表示されなくなります。

ユニバーサル アクションを使用すると、ユーザーがいつでもアクセス アドオンのどの部分とやり取りするかにかかわらず、 できます。以下に、ユニバーサル アクションのユースケースの例を示します。

  • 設定ウェブページを開きます(または設定カードを表示します)。
  • ユーザーにヘルプ情報を表示します。
  • 新しいワークフロー(「新しい顧客の追加」など)を開始します。
  • ユーザーがアドオンに関するフィードバックを送信できるカードを表示します。

現在のコンテキストに依存しないアクションがある場合、 普遍的な活動にすることを検討してください

ユニバーサル アクションの使用

ユニバーサル アクションはアドオンのプロジェクトで構成されています マニフェストをご覧ください。新しい P-MAX キャンペーンを アドオンのユーザーは常に利用できます。ユーザーが カードを表示すると、定義した共通のアクションが常に カードメニューの カード アクション そのカードに定義した値が表示されます。ユニバーサル アクションは、 アドオンのマニフェストで定義されている順序と同じ順序で適用できます。

ユニバーサル アクションの設定

アドオンのマニフェストでユニバーサル アクションを設定します。 マニフェスト をご覧ください。

アクションごとに、メニューに表示するテキストを指定します。 できます。次に、アクションが実行されたことを示す openLink フィールドを指定します。 新しいタブでウェブページを直接開きます。別の方法として、 呼び出しを行う Apps Script コールバック関数を指定する runFunction フィールド ユニバーサル アクションが選択されると実行されます。

runFunction を使用すると、通常は指定されたコールバック関数が次の処理を行います。 次の選択肢があります。

  • ビルドされた UI カードを返すことにより、すぐに表示する UI カードを作成します。 UniversalActionResponse 渡されます。
  • おそらく他のタスクの実行後に、ビルドされた UniversalActionResponse オブジェクト。
  • 新しいカードへの切り替えや URL の開かないバックグラウンド タスクを実行します。 この場合、コールバック関数は何も返しません。

このコールバック関数を呼び出すと、このコールバック関数には イベント オブジェクト には、開いているカードとアドオンのコンテキストに関する情報が含まれています。

次のコード スニペットは、 ユニバーサル アクションを使用する Google Workspace アドオン Gmail を拡張できます。このコードではメタデータ スコープを明示的に設定して、 オープン メッセージの送信者を特定できます。

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

上記の例で定義されている 3 つのユニバーサル アクションは、次の処理を行います。

  • google.com を開くhttps://www.google.com が 新しいタブで開きます。
  • [連絡先の URL を開く] は、開く URL を決定する関数を実行します。 新しいタブで開きます。 OpenLink オブジェクト。「 コードは送信者のメールアドレスを使用して URL を作成します。
  • [設定を開く] は、以下で定義されている createSettingsCards() 関数を実行します。 プロジェクトを作成します。この関数は、有効な UniversalActionResponse アドオン設定などの情報を含むカードのセットを含むオブジェクト。 関数がこのオブジェクトのビルドを完了すると、UI には 表示されます(詳しくは 複数のカードを返品する場合)。
  • バックグラウンド同期を実行 は、runBackgroundSync() プロジェクトを作成します。この関数はカードを作成しません。代わりに UI を変更しないその他のバックグラウンド タスクを実行します。以降、 関数が UniversalActionResponse 関数の終了時に新しいカードは表示されません。代わりに、 関数の実行中に読み込みインジケーター スピナーが表示されます。

openContactURL() を作成する方法の例を次に示します。 createSettingsResponse() 関数と runBackgroundSync() 関数:

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}