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 への参照を追加します。

  1. アプリのマニフェスト ファイル(AndroidManifest.xml)で、インテント フィルタが android.intent.action.MAIN アクションと android.intent.category.LAUNCHER カテゴリに設定されているアクティビティを見つけます。

  2. 次のように、MAINLAUNCHER の両方のインテント フィルタを含む Activity<meta-data> タグを使用して、AndroidManifest.xmlshortcuts.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 ケーパビリティを呼び出すアプリのショートカット「ランニングを開始」を宣言できます。

    このショートカットには intentshortLabellongLabel といった属性が含まれているため、アシスタント、あるいは Android ランチャーのアプリアイコンを長押ししたときなどの能動的なサーフェスでチップとして提案と処理ができます。アクション ショートカットは、下で説明しているように、<capability-binding> タグを使用して capability に関連付けることで、エンティティ ショートカットとして機能させることもできます。

  • エンティティ ショートカット。エンティティ ショートカットは、capability の音声クエリ フルフィルメントでサポートされているパラメータ値のリストを提供します。たとえば、START_EXERCISE ケーパビリティの exercise.name BII パラメータにバインドされているエクササイズ タイプ(「ハイキング」「ラン」など)のリストを備えたエンティティ ショートカットなどです。ユーザーの発話がエンティティと一致する場合は、未加工のユーザークエリ値ではなく shortcutId ID がインテントに渡されます。

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

capability スキーマ

次の表に、shortcuts.xmlcapability 要素の 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 インテントを定義する capabilityshortcuts.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 インテントの属性は capabilityintent の属性と同じです。

<capability-binding>

shortcut を App Actions capability に関連付けます。この要素を shortcut に追加すると、Assistant を使用した音声フルフィルメントが可能になります。

属性:

  • android:key: この shortcut がバインドされている capabilityandroid:name 属性。例: actions.intent.START_EXERCISE

<parameter-binding>

shortcut を App Actions capability の 1 つのパラメータに関連付ける属性(任意)。parameter-bindingshortcut に定義されている場合は、ショートカットを使用してインライン インベントリのエンティティを 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 で起動する方法は、アプリ ナビゲーションの構造に応じて複数の方法で構成できます。

次のフルフィルメント オプションがあります。

  • 明示的インテント: intenttargetClass 属性と targetPackage 属性を定義して、特定のアプリ コンポーネントを起動します。これは推奨される App Actions フルフィルメントの方法です。

  • ディープリンク: intent 要素内で <url-template> タグを定義し、Android のディープリンクを使用してアプリのデスティネーションを起動します。この方法は、すでにアプリ ナビゲーションでディープリンクを使用している場合に便利です。

  • インテント データ: intentandroid:data 属性でフルフィルメント URI を指定できます。このフィールドは、<url-template> のデータによって上書きされます(intent 内に同タグも定義されている場合)。

パラメータ データと照合

デフォルトでは、アシスタントはユーザークエリから抽出した BII パラメータを、capability で定義された Android intentextra データとしてアプリに送信します。

あるいは、動的パラメータのプレースホルダを含む 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 でラテを注文して」のようなユーザークエリがあると、アプリは targetPackagetargetClass のコンポーネントを呼び出す intent を受信します。このコンポーネントは、key = "exercise"value = "Running" という Extra を受け取ります。

すでにアプリがアプリリンクの 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 に列挙値を関連付けるには、shortcutsameAs 関連付けを宣言します。次のサンプルは、インライン エンティティ ショートカットの 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 の場合、このフィールドは必須ではありません。カスタム インテントのパラメータの場合は、サポートされているセマンティック タイプを宣言する必要があります。

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