ユニバーサル アクションは、ユーザーが新しいウェブページを開いたり、新しい UI カードを表示したり、選択した Apps Script の関数を実行したりできるメニュー項目の要素です。オペレーションはカード アクションとよく似ていますが、現在のアドオンのコンテキストに関係なく、ユニバーサル アクションはアドオン内のすべてのカードに必ず配置されます。
ユニバーサル アクションを使用すると、アドオンのどの部分を操作するかにかかわらず、常に特定の機能にアクセスできます。ユニバーサル アクションのユースケースの例を次に示します。
- 設定ウェブページを開きます（または設定カードを表示します）。
- ユーザーにヘルプ情報を表示する
- 「新規顧客を追加」などの新しいワークフローを開始します。
- アドオンについてユーザーがフィードバックを送信できるカードを表示する。
現在のコンテキストに依存しないアクションがある場合は、必ずユニバーサル アクションにする必要があります。
ユニバーサル アクションの使用
ユニバーサル アクションは、アドオンのプロジェクト マニフェストで構成されます。構成済みのユニバーサル アクションは、アドオンのユーザーがいつでも利用できます。ユーザーがカードを表示している場合、定義したユニバーサル アクションのセットは、常に、カードに定義したカード アクションの後にカードメニューに表示されます。ユニバーサル アクションは、アドオンのマニフェストで定義されているのと同じ順序でカード メニューに表示されます。
ユニバーサル アクションの構成
アドオンのマニフェストでユニバーサル アクションを構成します。詳細については、マニフェストをご覧ください。
アクションごとに、そのアクションのメニューに表示するテキストを指定します。次に、アクションで新しいタブで直接ウェブページを開く必要があることを示す openLink フィールドを指定できます。または、runFunction フィールドを指定して、ユニバーサル アクションが選択されたときに実行する Apps Script コールバック関数を指定することもできます。
runFunction が使用される場合、指定されたコールバック関数は通常、次のいずれかを行います。
- ビルドされた
UniversalActionResponseオブジェクトを返すことで、すぐに表示する UI カードを作成します。 - ビルドされた
UniversalActionResponseオブジェクトを返すことで、他のタスクを行った後に URL を開きます。 - 新しいカードに切り替えたり URL を開いたりしないバックグラウンド タスクを実行します。 この場合、コールバック関数は何も返しません。
このコールバック関数が呼び出されると、開いているカードとアドオンのコンテキストに関する情報を含むイベント オブジェクトが渡されます。
例
次のコード スニペットは、Gmail を拡張しながらユニバーサル アクションを使用する Google Workspace アドオンのマニフェストの抜粋の例を示しています。このコードでは、アドオンが誰にメッセージを送信したかを判別できるように、メタデータ スコープが明示的に設定されています。
"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を返しないため、関数の終了時に UI で新しいカードは表示されません。代わりに、関数の実行中に UI に読み込みインジケーター スピナーが表示されます。
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.
}