Add capabilities to shortcuts

Capabilities in shortcuts.xml let you declare the types of actions users can take to launch your app and directly perform a specific task. 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, do the following:

1. Create a shortcuts.xml resource by following the instructions in Create static shortcuts.

2. 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 destination: the destination in your app the action launches to fulfill the user request. Define app destinations using intent elements nested within the capability.

   • Parameter mappings: each intent might contain parameters to be passed as extra data of the intent.

The following example demonstrates a capability definition in shortcuts.xml for actions.intent.START_EXERCISE, a BII that lets users 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 BII parameter exercise.name and how to pass the parameter value—collected from the user—as extra data in the intent.

Associate shortcuts with a capability

Once you define 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, when a user begins a run in your fitness tracking app by asking Assistant, "Hey Google, start a run in ExampleApp." Assistant can use a shortcut to launch an instance of a capability that defines a valid exercise entity of "run" for the exercise.name parameter.