このページは Cloud Translation API によって翻訳されました。

shortcuts.xml を作成する

実装するアプリ内機能とそれに対応する組み込みインテント（BII）を特定したら、shortcuts.xml リソースファイルで capability 要素を定義して、機能がサポートする BII を宣言します。BII を capability として宣言すると、アプリでそのセマンティックインテントのサポートが登録され、Google アシスタントを使用するインテントの音声クエリフルフィルメントが有効になります。

アシスタントは自然言語処理を使用して、ユーザークエリからパラメータを抽出します。組み込みインテントのリファレンスに、関連するユーザークエリから各 BII が抽出できるフィールドが記載されています。たとえば、ユーザーがアプリで [actions.intent.GET_FOOD_OBSERVATION][] ケーパビリティを呼び出します。「OK Google, ExampleApp に先週金曜日のランチで何を食べたの？」と話しかけたときは、ユーザーリクエストから次の 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 を定義できます。次に、単一の BII を必要とする 2 つ目のインテントを定義できます。パラメータ foodObservation.forMeal: 特定の日のすべての食事をレポートします（例: 「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_EXERCISE BII ケーパビリティを呼び出すアプリのショートカット「ランニングを開始」を宣言できます。

このショートカットには intent、shortLabel、longLabel といった属性が含まれているため、アシスタント、あるいは Android ランチャーのアプリアイコンを長押ししたときなどの能動的なサーフェスでチップとして提案と処理ができます。アクションショートカットは、下で説明しているように、<capability-binding> タグを使用して capability に関連付けることで、エンティティショートカットとして機能させることもできます。
エンティティショートカット。エンティティショートカットは、capability の音声クエリフルフィルメントでサポートされているパラメータ値のリストを提供します。たとえば、START_EXERCISE ケーパビリティの exercise.name BII パラメータにバインドされているエクササイズタイプ（「ハイキング」「ラン」など）のリストを備えたエンティティショートカットなどです。ユーザーの発話がエンティティと一致する場合は、未加工のユーザークエリ値ではなく shortcutId ID がインテントに渡されます。

Entity ショートカットでは intent 属性、shortLabel 属性、longLabel 属性が定義されないため、能動的なサーフェスでは推奨されません。詳しくは、App Actions のインラインインベントリをご覧ください。

注: エンティティショートカットとして宣言された静的ショートカットは、LauncherApps API によりドロップされます。つまり、Android ランチャーで使用できるということです。

capability スキーマ

次の表に、shortcuts.xml の capability 要素の App Actions スキーマを示します。タグを含める場合は、「任意」という記載がない限りすべての属性が必須です。

shortcuts.xml タグ	親要素	属性
`<capability>`	`<shortcuts>`	`android:name` `app:queryPatterns`（カスタムインテントの場合にのみ適用）
`<intent>`	`<capability>`	`android:action`（任意） `android:targetClass`（任意） `android:targetPackage`（任意） `android:data`（任意）
`<url-template>`	`<intent>`	`android:value`
`<extra>`	`<intent>`	`android:key` `android:value` フォアグラウンドアプリ呼び出しにのみ適用されます。
`<parameter>`	`<intent>`	`android:name` `android:key` `android:mimeType`（カスタムインテントの場合にのみ適用） `android:required`（任意） `app:shortcutMatchRequired`（任意）
`<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"` `"bar": "456"`	`https://example.com/test?foo=123&bar=456`
`https://example.com/test?utm_campaign=appactions{&foo,bar}`	`"foo": "123"` `"bar": "456"`	`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.name BII パラメータに 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>`	`android:shortcutId` `android:shortcutShortLabel` `android:shortcutLongLabel`（任意） `android:icon`（任意）
`<intent>`	`<shortcut>`	`android:action` `android:targetClass`（任意） `android:targetPackage`（任意） `android:data`（任意）
`<capability-binding>`	`<shortcut>`	`android:key`
`<parameter-binding>`	`<capability-binding>`	`android:key`（任意） `android:value`
`<extra>`	`<shortcut>`	`android:name`（任意） `android:value` 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: このショートカットを関連付ける capability BII パラメータの名前。例: 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: sameAs URL の値

詳しくは、列挙型パラメータ値の照合をご覧ください。

インテントフルフィルメントのオプション

<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, ExampleApp でラテを注文して」のようなユーザークエリがあると、アプリは 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, ラテを注文して」 from ExampleApp" と表示されている場合、アプリは生成された 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 の場合、このフィールドは必須ではありません。カスタムインテントのパラメータの場合は、サポートされているセマンティックタイプを宣言する必要があります。

詳細については、カスタムインテントをご覧ください。

shortcuts.xml を作成する

概要

静的ショートカット

capability スキーマ

capability スキーマの説明

<capability>

<intent>

<url-template>

<extra>

<parameter>

<shortcut-fulfillment>

<parameter>（<shortcut-fulfillment> の場合）

<slice>

shortcut スキーマ

shortcut スキーマの説明

<shortcut>

<intent>

<capability-binding>

<parameter-binding>

<extra>

インテント フルフィルメントのオプション

パラメータ データと照合

インテント Extra の使用

Android のディープリンクに URL テンプレートを使用する

列挙パラメータ値と照合する

機能

App Actions のインライン インベントリ

カスタム インテント

<parameter>（`<shortcut-fulfillment>` の場合）

インテントフルフィルメントのオプション

パラメータデータと照合

App Actions のインラインインベントリ

カスタムインテント