Capabilities in shortcuts.xml
allow you to declare the types of actions users
can take to launch your app and jump directly to performing a specific task. For
example, Google Assistant App Actions use capabilities to enable
developers to extend in-app features to built-in intents (BII), allowing
users to activate and control those features using spoken commands. A capability
consists of the name of the action and an intent
targeting the destination in
your app that resolves the user intent.
Define capabilities in shortcuts.xml
You define capability
elements in a shortcuts.xml
resource file in your
Android app development project. To define a capability
element:
- Create a
shortcuts.xml
resource by following the instructions in Create static shortcuts. Next, include the following required information in your capability:
Capability name: The action you want your app to support. Refer to the component documentation for the feature that requires capability definitions. App Actions voice-enabled commands use the BII
Action ID
for capability names, which are located in Built-in intents reference. For instance, theGET_THING
BII lists itsAction ID
asactions.intent.GET_THING
.App destination: The destination in your app the action launches to fulfill the user request. Define app destinations using
intent
elements nested within thecapability
.Parameter mappings: Each
intent
may contain parameters to be passed asextra
data of the intent. For example, each App Actions BII includes fields representing information users often provide in queries that trigger the BII.
The following example demonstrates a capability definition in shortcuts.xml
for actions.intent.START_EXERCISE
, a BII that enables users to use spoken
commands with Assistant to begin a workout in a fitness app:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.sampleApp"
android:targetClass="com.example.sampleApp.ExerciseActivity">
<parameter
android:name="exercise.name"
android:key="exerciseType"/>
</intent>
</capability>
</shortcuts>
In the preceding example, the <capability>
android:name
attribute refers to
the START_EXERCISE
BII. If a user invokes this BII by asking Assistant, "Hey
Google, start a run in ExampleApp," Assistant fulfills the user request using
information provided in the nested intent
element. The intent
in this sample
defines the following details:
- The
android:targetPackage
sets the target application package for this intent. - The
android:targetClass
field specifies the destination activity:com.example.sampleApp.ExerciseActivity
. - The intent
parameter
declares support for a built-in intent parameterexercise.name
, and how to pass the parameter value, collected from the user, as extra data in theintent
.
Associate shortcuts with a capability
Once you have defined a capability, you can extend its functionality by
associating static or dynamic shortcuts with it. How shortcuts are linked to
a capability
depends on the feature being implemented and the actual words
included in a user's request. For example, imagine a scenario where a user
begins a run in your fitness tracking app by asking Assistant, “Hey Google,
start a run in ExampleApp." Assistant could use a shortcut to launch an
instance of a capability
that defines a valid exercise entity of "run" for the
exercise.name
parameter.
For more information about associating shortcuts to App Actions, see App Actions overview.