実装するアプリ内機能とそれに対応する組み込みインテント(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_EXERCISE
BII ケーパビリティを呼び出すアプリのショートカット「ランニングを開始」を宣言できます。このショートカットには
intent
、shortLabel
、longLabel
といった属性が含まれているため、アシスタント、あるいは Android ランチャーのアプリアイコンを長押ししたときなどの能動的なサーフェスでチップとして提案と処理ができます。アクション ショートカットは、下で説明しているように、<capability-binding>
タグを使用してcapability
に関連付けることで、エンティティ ショートカットとして機能させることもできます。エンティティ ショートカット。エンティティ ショートカットは、
capability
の音声クエリ フルフィルメントでサポートされているパラメータ値のリストを提供します。たとえば、START_EXERCISE
ケーパビリティのexercise.name
BII パラメータにバインドされているエクササイズ タイプ(「ハイキング」「ラン」など)のリストを備えたエンティティ ショートカットなどです。ユーザーの発話がエンティティと一致する場合は、未加工のユーザークエリ値ではなくshortcutId
ID がインテントに渡されます。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.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> |
|
<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
: このショートカットを関連付ける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, 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 の場合、このフィールドは必須ではありません。カスタム インテントのパラメータの場合は、サポートされているセマンティック タイプを宣言する必要があります。
詳細については、カスタム インテントをご覧ください。