ユニバーサル アクションは、メニュー項目要素です。ユーザーは、メニュー項目要素を選択して、新しいウェブページを開いたり、新しい 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.
}