実装するアプリ内機能とそれに対応する組み込みインテント（BII）を特定したら、shortcuts.xml リソース ファイルで capability 要素を定義して、機能がサポートする BII を宣言します。BII を capability として宣言すると、アプリでそのセマンティック インテントのサポートが登録され、Google アシスタントを使用するインテントの音声クエリ フルフィルメントが有効になります。
アシスタントは自然言語処理を使用して、ユーザークエリからパラメータを抽出します。組み込みインテントのリファレンスに、関連するユーザークエリから各 BII が抽出できるフィールドが記載されています。たとえば、ユーザーが「OK Google, 先週の金曜日に ExampleApp で何を食べたかを尋ねて」と話しかけてアプリの [actions.intent.GET_FOOD_OBSERVATION][] ケーパビリティを呼び出す場合、アシスタントはユーザー リクエストから次の BII パラメータを抽出します。
foodObservation.forMeal= "https://schema.googleapis.com/MealTypeLunch"foodObservation.startTime= "2024-09-06T00:00:00"foodObservation.endTime= "2024-09-06T23:59:59"
アシスタントは、capability で定義されたフルフィルメント intent に BII パラメータを渡します。ユーザーによるさまざまな形の BII 呼び出しに対応するため、あるケーパビリティに 1 つ以上の intent 要素を定義できます。たとえば、上記の例の両方の BII パラメータを必要とするフルフィルメント intent を定義できます。さらに、1 つの BII パラメータ foodObservation.forMeal を必要とする 2 つ目のインテントを定義できます。これにより、特定の日のすべての食事を報告できます（「OK Google, ExampleApp に昼食は何を食べたか聞いて」など）。
概要
App Actions を構成するには、アプリ プロジェクトの res/xml ディレクトリに配置された shortcuts.xml ファイルを使用します。次に、アプリ マニフェストに shortcuts.xml への参照を作成します。次の手順で、アプリ マニフェストに shortcuts.xml への参照を追加します。
アプリのマニフェスト ファイル（
AndroidManifest.xml）で、インテント フィルタがandroid.intent.action.MAINアクションとandroid.intent.category.LAUNCHERカテゴリに設定されているアクティビティを見つけます。次のように、
MAINとLAUNCHERの両方のインテント フィルタを含むActivityの<meta-data>タグを使用して、AndroidManifest.xmlにshortcuts.xmlへの参照を追加します。<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />
上記の例では、APK 内の xml/shortcuts.xml ファイルの XML リソースを宣言しています。ショートカットの構成の詳細については、Android デベロッパー向けドキュメントの静的ショートカットを作成するをご覧ください。
shortcuts.xml で App Actions のケーパビリティを定義する際のコンパイル エラーを回避するには、Android プロジェクトに Jetpack ライブラリ androidx.core:core:1.6.0 以上が必要です。詳細については、Android Jetpack のスタートガイドをご覧ください。
静的ショートカット
capability を定義する際、shortcuts.xml で静的な shortcut 要素を宣言して、ケーパビリティの機能を拡張できます。静的ショートカットは、Google Play Console にリリースをアップロードするときにアシスタントによって取り込まれます。静的ショートカットは、新しいリリースを作成することによってのみ作成、更新できるため、アプリの一般的なアクティビティやコンテンツを強調するのに最も便利な方法です。
静的ショートカットを使用して次の App Actions 機能を有効にできます。
ケーパビリティ ショートカット。事前定義された
intentパラメータ値を含むcapabilityのインスタンスを起動するショートカットを作成します。たとえば、フィットネス アプリ内でSTART_EXERCISEBII ケーパビリティを呼び出すアプリのショートカット「ランニングを開始」を宣言できます。このショートカットには
intent、shortLabel、longLabelといった属性が含まれているため、アシスタント、あるいは Android ランチャーのアプリアイコンを長押ししたときなどの能動的なサーフェスでチップとして提案と処理ができます。アクション ショートカットは、下で説明しているように、<capability-binding>タグを使用してcapabilityに関連付けることで、エンティティ ショートカットとして機能させることもできます。エンティティ ショートカット。エンティティ ショートカットは、
capabilityの音声クエリ フルフィルメントでサポートされているパラメータ値のリストを提供します。たとえば、START_EXERCISEケーパビリティのexercise.nameBII パラメータにバインドされているエクササイズ タイプ（「ハイキング」「ラン」など）のリストを備えたエンティティ ショートカットなどです。ユーザーの発話がエンティティと一致する場合は、未加工のユーザークエリ値ではなくshortcutIdID がインテントに渡されます。Entityショートカットではintent属性、shortLabel属性、longLabel属性が定義されないため、能動的なサーフェスでは推奨されません。詳しくは、App Actions のインライン インベントリをご覧ください。
capability スキーマ
次の表に、shortcuts.xml の capability 要素の App Actions スキーマを示します。タグを含める場合は、「任意」という記載がない限りすべての属性が必須です。
| shortcuts.xml タグ | 親要素 | 属性 |
|---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
フォアグラウンド アプリ呼び出しにのみ適用されます。 |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
インライン インベントリの場合にのみ適用 |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Android Slice にのみ適用 |
capability スキーマの説明
このセクションでは、capability スキーマの要素について説明します。
<capability>
アプリがサポートする App Action インテントを定義する capability。shortcuts.xml ファイル内の各 <capability> 要素には、アクションのフルフィルメントを処理する <intent> が少なくとも 1 つ必要です。
属性:
android:name: 組み込みインテント Action ID（[actions.intent.GET_FOOD_OBSERVATION][] など）。サポートされている組み込みインテントの一覧については、組み込みインテントのリファレンスをご覧ください。app:queryPatterns: このインテントに関して想定されるユーザーからのクエリの文字列配列リソース。この属性はカスタム インテントにのみ適用されます。これは、すでに BII にはユーザーが行おうとしているタスクやユーザーが求める情報を表現する一般的なモデルが含まれているためです。
<intent>
アプリ内機能を使用してユーザークエリをどのように処理するかを定義する Android intent 要素。デベロッパーは 1 つの capability に複数の <intent> タグを指定できます。アシスタントは、すべての必須パラメータが指定されている capability の最初の <intent> を使用して、ユーザークエリの実行を試みます。
属性:
android:action: インテントのActionタイプ。デフォルトはACTION_VIEWです。android:targetClass: ターゲット Activity クラス（例:"com.example.exercise.ExerciseActivity"）android:targetPackage: ターゲット Activity クラスを含むパッケージ（例:"com.example.exercise）android:data: このフィールドは、<url-template>によって上書きされます（intent内に同タグが宣言されている場合）。
<url-template>
デバイスで開くディープリンク URI を組み立てるためのテンプレート。テンプレートの必須パラメータがすべて利用可能な場合、組み込みインテント パラメータを使用してテンプレートを展開できます。HTTP URL テンプレートの例については、URL テンプレートについての Wikipedia 記事をご覧ください。テンプレートの形式は、RFC6570 URI テンプレートの仕様に準拠しています。
URL テンプレートの値の例を次に示します。
| テンプレート | 値 | 展開された値 |
|---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} |
"foo": "123" |
https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} |
"foo": "123" |
myapp://example/123 |
URL テンプレートの構成の詳細については、フルフィルメントの URL テンプレートをご覧ください。
<extra>
intent の追加データを定義します。App Actions の場合、このフィールドは、capability の [フォアグラウンド アプリ呼び出し] を有効にする目的でのみ使用されます。
<parameter>
BII パラメータをインテントのパラメータ値にマッピングします。詳細については、パラメータ データと照合をご覧ください。
属性:
android:name: このintentパラメータに関連付ける BII パラメータの名前。名前はこの BII パラメータのリーフレベルのフィールド（例:foodObservation.aboutFood.name）にする必要があります。android:key: BII パラメータ値のデベロッパー定義のキー。たとえば、message.recipient.nameBII パラメータにcontact_nameを定義できます。android:mimeType: パラメータの mimeType（text/*など）。このフィールドは、カスタム インテントのパラメータでのみ必須です。android:required: このインテントをフルフィルメントに使用するためにユーザークエリにこのパラメータを含める必要があるかどうかを宣言します。このパラメータが指定されていない場合、アシスタントはcapabilityに定義された次のintentを使用してユーザークエリの処理を試みます。
<shortcut-fulfillment>
指定したパラメータのインライン インベントリのショートカットで定義された intent をフルフィルメントに使用するように指定します。詳しくは、ショートカット インテントを使用したフルフィルメントをご覧ください。
<parameter>（<shortcut-fulfillment> の場合）
1 つの BII パラメータをインライン インベントリのショートカット フルフィルメントにマッピングする属性（任意）。詳しくは、ショートカット インテントを使用したフルフィルメントをご覧ください。
属性:
android:name: インライン インベントリのショートカット フルフィルメントに関連付ける BII パラメータの名前。名前はこの BII パラメータのリーフレベルのフィールド（例:menuItem.name）にする必要があります。
<slice>
アシスタントが、この capability に一致するクエリの結果を Android Slice として埋め込めるようにします。詳細については、App Actions を Android Slice と統合するをご覧ください。
shortcut スキーマ
次の表に、App Actions 機能を有効にするために使用される shortcut 要素の属性を示します。タグを含める場合は、「任意」という記載がない限りすべての属性が必須です。
| shortcuts.xml タグ | 親要素 | 属性 |
|---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
Enum パラメータの照合にのみ適用。 |
shortcut スキーマの説明
このセクションでは、shortcut スキーマの要素について説明します。
<shortcut>
shortcuts.xml で定義され、App Actions に関連する特定の属性を備えた Android <shortcut>。shortcutShortLabel フィールドと shortcutLongLabel フィールドの文字列値は、APK の文字列リソースを介して参照されます。
属性:
android:shortcutId: このショートカットの ID。android:shortcutShortLabel: 短いショートカット フレーズを表す文字列リソース。たとえば、"@string/callDavidShort"で「David に電話」という値を表します。android:shortcutLongLabel: 長いショートカット フレーズを表す文字列リソース。たとえば、"@string/callDavidLong"で「David に音声通話をかける」という値を表します。
<intent>
このショートカットに関連付けられている Android インテント。この intent は、ユーザーが音声またはタップでショートカットを起動すると実行されます。
shortcut インテントの属性は capability の intent の属性と同じです。
<capability-binding>
shortcut を App Actions capability に関連付けます。この要素を shortcut に追加すると、Assistant を使用した音声フルフィルメントが可能になります。
属性:
android:key: このshortcutがバインドされているcapabilityのandroid:name属性。例:actions.intent.START_EXERCISE。
<parameter-binding>
shortcut を App Actions capability の 1 つのパラメータに関連付ける属性（任意）。parameter-binding が shortcut に定義されている場合は、ショートカットを使用してインライン インベントリのエンティティを BII パラメータに指定できます。詳しくは、App Actions のインライン インベントリをご覧ください。
属性:
android:key: このショートカットを関連付けるcapabilityBII パラメータの名前。例:exercise.name。android:value:entity値。単一のentityかリソースリストを指定できます。
<extra>
ショートカットの extra バンドルデータ。sameAs は App Actions の shortcut 要素に関連する唯一のデータです。sameAs URL は、エンティティを明確に識別する参照ウェブページを参照します。インテント パラメータ タイプが schema.org/Enumeration のサブタイプである場合に限り、列挙値を指定するために使用されます。schema.org/Enumeration のサブタイプであるパラメータ フィールドの場合は必須です（例: MealTypeBreakfast）。
属性:
android:key: App Actions でサポートされている値（sameAs）android:value:sameAsURL の値
詳しくは、列挙型パラメータ値の照合をご覧ください。
インテント フルフィルメントのオプション
<capability> 内で intent 要素を定義して、アシスタントがそのケーパビリティに一致するユーザー音声コマンドにどのように応答するか、またはそれをどのように実行するかを宣言します。アプリのフルフィルメント デスティネーションを intent で起動する方法は、アプリ ナビゲーションの構造に応じて複数の方法で構成できます。
次のフルフィルメント オプションがあります。
明示的インテント:
intentのtargetClass属性とtargetPackage属性を定義して、特定のアプリ コンポーネントを起動します。これは推奨される App Actions フルフィルメントの方法です。ディープリンク:
intent要素内で<url-template>タグを定義し、Android のディープリンクを使用してアプリのデスティネーションを起動します。この方法は、すでにアプリ ナビゲーションでディープリンクを使用している場合に便利です。インテント データ:
intentのandroid:data属性でフルフィルメント URI を指定できます。このフィールドは、<url-template>のデータによって上書きされます（intent内に同タグも定義されている場合）。
パラメータ データと照合
デフォルトでは、アシスタントはユーザークエリから抽出した BII パラメータを、capability で定義された Android intent の extra データとしてアプリに送信します。
あるいは、動的パラメータのプレースホルダを含む capability 内で <url-template> タグを宣言することもできます。このテンプレートは、App Links URL、カスタム スキーム、インテント ベースの URL のいずれかを使用して Android アクティビティの 1 つにマッピングされます。
インテント Extra の使用
次の例は、capability フルフィルメントに定義された明示的インテントを示しています。
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
上記のサンプルで「OK Google, ランニングを開始して」のようなユーザークエリがあると、アプリは targetPackage と targetClass のコンポーネントを呼び出す intent を受信します。このコンポーネントは、key = "exercise"、value = "Running" という Extra を受け取ります。
Android のディープリンクに URL テンプレートを使用する
すでにアプリがアプリリンクの URL を処理できるようになっている場合は、動的パラメータがあると、intent で <url-template> を定義し、フルフィルメントに対して Android のディープリンクを生成できます。次のサンプルで <url-template> を定義しています。
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://start{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
上記のサンプルで「OK Google, ランニングを開始」のようなユーザークエリがあると、アプリは生成された URL（myapp://start?exercise=Running）を受信します。
BII パラメータを URL 内の位置にマッピングするには、<parameter> タグの android:name 属性を使用します。この属性は、ユーザーからの情報に置き換える URL テンプレートの android:key 値に対応します。android:key 値は、<url-template> 内に記述し、中かっこ（{}）で囲む必要があります。
列挙パラメータ値と照合する
一部の BII パラメータは、フルフィルメント インテントに列挙値を提供します（たとえば、RECORD_FOOD_OBSERVATION BII でサポートされているテキスト値など）。このパラメータに対して、アシスタントはユーザーのクエリ（「Breakfast」）を、sameAs の値が列挙型スキーマ URL（https://schema.googleapis.com/MealTypeBreakfast）と一致するエンティティと照合します。サポートされている entity に列挙値を関連付けるには、shortcut で sameAs 関連付けを宣言します。次のサンプルは、インライン エンティティ ショートカットの sameAs 関連付けを示しています。
<shortcut android:shortcutId="meal_breakfast" >
<capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
<parameter-binding android:key="foodObservation.forMeal" />
</capability-binding>
<extra
android:key="sameAs"
android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>
<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
<intent targetPackage="com.example.app" targetClass="com.example.app.Class">
<parameter android:name="foodObservation.forMeal" android:key="for_meal" />
</intent>
</capability>
上の例で、RECORD_FOOD_OBSERVATION ケーパビリティが「breakfast」という食事の種類との照合をトリガーすると、次の Extra がフルフィルメント intent とともに送信されます。
key = "for_meal"value = "meal_breakfast"
機能
shortcuts.xml では、以下の App Actions 機能を利用できます。
App Actions のインライン インベントリ
一部の BII パラメータでは、ショートカットを使用して、shortcuts.xml で指定された一連のサポートされているエンティティへのエンティティ抽出をガイドできます（インライン インベントリ）。詳しくは、インライン インベントリをご覧ください。
カスタム インテント
shortcuts.xml でカスタム インテントを宣言することで、利用可能な BII と一致しないアプリの機能を音声対応にできます。カスタム インテントは、BII 定義と機能的には同じですが、shortcuts.xml には以下の 2 つの追加属性が必要です。
app:queryPatterns: カスタム インテントのさまざまなクエリパターンを宣言する配列リソース。android:mimeType: カスタム インテントのパラメータ タイプ。パラメータ タイプがわかっている BII の場合、このフィールドは必須ではありません。カスタム インテントのパラメータの場合は、サポートされているセマンティック タイプを宣言する必要があります。
詳細については、カスタム インテントをご覧ください。