Built-in intents for App Actions

Beta: This page describes App Actions functionality you can add to your app today using the Android Shortcuts framework. This framework integration is in the Beta release stage. If you are maintaining a production implementation of App Actions, refer to the Actions.xml documentation.

Built-in intents (BIIs) allow your app to express its fulfillment capabilities to Google. By declaring capabilities in your shortcuts.xml file and mapping intent parameters to the fulfillment, you make it possible for Google Assistant to launch your app to a specific screen, in response to a query, to allow the user to complete a task.

Built-in intents are grouped according to app categories. Each category represents a set of common tasks that users frequently want to perform on their apps. The full list of available built-in intents, their parameters, and example queries usable for testing is in the built-in intent reference.

Many built-in intents include additional deployment requirements and recommendations. These requirements and recommendations help us ensure that your app delivers the best possible experience to your users.

Figure 1. Invoking the START_EXERCISE BII with a voice query to Assistant.

Figure 2. Launching the app to a specific screen to begin the START_EXERCISE task.

Figure 3. Displaying a widget in response to a query.

​

Implement BIIs and handle intent parameters

For App Actions, you declare capabilities and handle built-in intent parameters in your shortcuts.xml file. To implement a built-in intent and handle parameters, follow these steps:

1. Declare the capability with the chosen BII.
2. Add nested parameter elements for each BII field you want to add.
   1. If you’re using targetClass or targetPackage, map them to the Android intent extras using a name you choose.
   2. If you’re using a deep link URL, use the named parameters in the query string of the URL template.

To handle a built-in intent parameter, map the BII parameter to the corresponding parameter of an explicit Android intent in your capability; then, you can use its value in your app. Your app is not required to handle BII parameters. However, your app should attempt to handle data fields marked as "Recommended" in the built-in intent reference.

You can define multiple intent fulfillments, each with their own set of recommended parameters. Google selects the appropriate fulfillment based on the capability parameters it identified from the user's query and the ones that were declared in an intent.

For example, the actions.intent.START_EXERCISEintent recommends your app to handle the exercise.name built-in intent parameter. You can still implement the same built-in intent in your app with no parameters. You might do this if you wanted to handle user queries without the specific exercise name, like "Ask ExampleApp to start tracking exercise". The following snippet has a fallback to a fulfillment with no required parameters if the parameters are not included in the user's query:

<?xml version="1.0" encoding="utf-8"?>
<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:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

Google Assistant does its best to provide the most relevant information to the user when returning parameter values to your app. For example, user queries for ordering pizza from ExampleRestaurant's mobile app don't always include a location. To better serve the user, Assistant may choose to provide latitude and longitude values of the nearest ExampleRestaurant to that app.

As an additional requirement, your app should not directly perform an action that modifies a user's real-world state (for example, transferring money, placing an order, or sending a message) without first confirming with the user.

Note: App Actions, like all Actions that support built-in intents, trigger on a number of factors, including quality and relevancy to the user's request. Based on those factors, Google may exercise discretion in surfacing your Action in response to user requests.

Disambiguation

In certain cases, the arguments passed to your app (either via <url-parameter> or via intent extras) may not uniquely identify the item that you want to show to the user. In this case, we recommend using the argument value as a search argument, and taking the user to the search page of the app so that they can disambiguate and choose the right item.

For example, if a user’s query is “Order from ExampleRestaurant” for the built-in intent ORDER_MENU_ITEM, you can present to the user a list of restaurants whose names match the term "ExampleRestaurant".

Language and locale support

The locales supported for development and testing by each App Action built-in intent are listed in the built-in intent reference. Some built-in intents have different locale support for developer testing and for user triggering from Assistant.