Build App Actions

App Actions allow users to launch functionality in your Android app by asking Google Assistant, or by using Android shortcuts suggested by Assistant. These are the primary steps to extending your Android app with App Actions:

  1. Identify the in-app functionality to trigger and its matching built-in intent (BII).
  2. Provide fulfillment details for the built-in intent.
  3. Push shortcuts for your App Action to Assistant.
  4. Preview your App Actions on a test device.
  5. Create a test release of your app.
  6. Request App Actions review and deployment.

You can optionally define dynamic shortcuts to provide to Assistant so it can suggest them to your users. Try creating an App Action using a sample app, by following the App Actions codelab.

Requirements

Before you start developing App Actions, meet the following requirements:

  • Have a Google account with access to the Google Play Console.
  • App Actions are only available for apps published to the Google Play Store. Also, make sure that your app is not intended to be used in a work profile, as App Actions are not supported by Managed Google Play.
  • Have a physical or virtual device on which to test your App Actions.
  • Install the latest version of Android Studio.
  • Use the same Google account to sign in to Android Studio, the Google app on your test device, and the Google Play Console.
  • Set up and test that Assistant is working on your test device by long-pressing the Home button.

Match built-in intents with app functionality

Start by identifying the functionality in your Android app that users may want to jump to directly with a spoken request. You can do this by finding built-in intents that match your app's core capabilities. Review the built-in intent reference to find appropriate BIIs for your use cases. Built-in intents model user queries for tasks they want to perform in your app, so look for BIIs that match key functionality and user flows in your app.

There are common BIIs that almost any Android app can use, such as extending your native in-app search to Assistant with the actions.intent.GET_THING BII, or enabling users to launch specific app features with their voice by implementing the actions.intent.OPEN_APP_FEATURE BII. There are also a number of BII that enable vertical, or category-specific, use cases. For example, a food ordering app might use the actions.intent.ORDER_MENU_ITEM BII. To ensure a great user experience and avoid possible approval delays, make sure that each BII you implement is relevant to your in-app functionality.

App Actions work by starting Android intents from the Assistant app to take users directly to specific content in your app. You can define these intents to launch an activity explicitly by specifying the targetClass and targetPackage fields. If your app already implements Android deep link URLs, you have the option to configure the intent to use a deep link for fulfillment. For more details, see Test your activity deep links.

Provide fulfillment details for built-in intents

Most of building an App Action is declaring a capability in the shortcuts.xml resource file of your Android app, where you specify your selected BII and their corresponding fulfillment. A BII models the user query for a task, and a fulfillment intent provides Assistant with information on how to perform the task.

In your shortcuts.xml file, built-in intents are represented as <capability> elements and each fulfillment is represented as an <intent> element:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="menuItem.name"
                android:key="query">
            </parameter>
        </intent>
    </capability>

For most BII, you extract intent parameters from the user query based on schema.org entities. Your app then uses those BII parameters to direct users to the desired functionality. For example, the above code maps the menuItem.name BII parameter to the query Android intent parameter.

If you are fulfilling actions using deep links, you use the urlTemplate field to define the deep link URL Assistant generates:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myfoodapp://browse{?query}" />
            <parameter android:name="menuItem.name"
                android:key="query"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

For important details about adding App Actions to the shortcuts.xml file, reference Create shortcuts.xml. The schema page also describes how to specify parameter values your app expects.

Push shortcuts for your App Action to Assistant (optional)

Once you've defined a capability for your action, users can easily launch your action by saying something like, "Hey Google, order a pizza on ExampleApp." Assistant can suggest Android shortcuts for your actions to users at relevant times, making it easy for them to discover and replay your actions. Assistant can suggest both dynamic and static shortcuts. To push dynamic shortcuts to Assistant, use the Google Shortcuts Integration library. This Jetpack library enables Assistant to ingest your shortcuts, and suggest them to users at the appropriate time.

For more details, see Push dynamic shortcuts to Assistant.

Preview your App Actions

During development and testing, use the Google Assistant plugin for Android Studio to test that App Actions work for your app. The plugin creates a preview of your App Actions in Assistant (for your Google account). Using the test tool, you can test your fulfillments on a physical test device or emulator by providing BIIs with input parameters you expect to receive from users.

While previewing your App Actions, you can also trigger queries by voice on the device itself. This functionality is only available for queries listed in the built-in intents reference for App Actions. We recommend that you use voice triggering only for demonstration purposes rather than for regular testing.

You can also use a draft version of the app for testing using the developer tools for the Google Play Console. For more information on using Google Play Console to deploy a draft of your app, see Prepare and release rollout. We highly encourage you to test your app in draft mode before submitting it for review.

Create a test release

Create an internal or closed test release of your app when you're ready to test your App Actions with additional testers. By default, your internal and closed release testers can access App Actions that have already been reviewed and approved.

To grant testing access to all App Actions, including unapproved actions, instruct your testers to join the App Actions Development Program Google Group. By joining this group, your testers have access to all App Actions in your closed and internal test releases without having to create previews using the App Actions test tool. It may take up to 3 hours after joining the group for access to become available.

Request App Actions review and deployment

App Actions won't be available to users of your published or open test releases until they've been reviewed and approved. The App Actions review does not affect your Android app review and deployment status in Google Play. Even if your app submission is approved and published to the Play store, your shortcuts.xml may still be under review by Google. App Actions will not work for your end users until that review is also approved.

When you subsequently deploy your app, App Actions stay activated. However, redeployed versions are subject to review by Google. If the new version is not working properly or contains policy violations, Google reserves the right to deactivate App Actions for your app.

To submit your App Actions for review, do the following:

  1. Meet the App Actions deployment requirements. These requirements help to optimize your app for Assistant and ensure that users enjoy a seamless experience when using App Actions.
  2. Accept the Actions on Google Terms of service in the Google Play Console (Pricing & distribution > Consent):

    Actions on Google Terms of Service in the Google Play console.

  3. Upload your app (containing actions.xml) to the Google Play Console as normal for publishing.

  4. After you upload your app to the Play Console, we'll contact you at the email in Play Console with more information regarding the status of your App Actions review. You can also contact Actions on Google Developer Support with questions regarding your App Actions review status. In the contact form, provide your App Package ID and choose "App Action review" in the How can we help you? selection box.

Activities you wish to launch with App Actions using Android deep links must be set up with deep link URLs, and have a corresponding intent filters in the Android app manifest.

To test that your activities are accessible and that they can be triggered using App Actions using deep links, run the following adb command:

adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

For example:

adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

If your activity doesn't launch correctly with the adb command, then check the following:

  • In your app manifest file, the activity has android:exported=true so it can be launched using intents from Google Assistant.
  • If using App Links URLs, follow all the steps in Handling Android App Links.