App Actions lets users talk to Google Assistant and jump directly into specific app destinations when they say something like, "Hey Google, order me a ride on Example App." With foreground app invocation, you can further improve the experience when a user already has your app open.
Foreground app invocation lets built-in intents (BIIs) be matched without requiring the app name to be mentioned while a specific activity is in the device foreground.
For example, a user has your rideshare app in the foreground and says or types, "Order me a ride to Mountain View" to Google Assistant. Your app uses this input to set the destination field to Mountain View. Then, when the user says or types, "Order me a ride from SFO," your app can set the pickup location while preserving the state of your app.
Foreground app invocation is only available for the following BIIs:
To get locale support and example queries related to foreground app invocation for a specific BII, see the built-in intent reference.
Support foreground app invocation
Adding support for foreground app invocation involves adding fulfillment behavior based on a desired foreground activity. When that activity is in the foreground and the App Action is invoked, Assistant passes the deep link intent with an additional flag to that activity so your app can update its state.
To implement foreground app invocation for a BII, do the following:
- In your
shortcuts.xmlfile, add an
<intent>tag to the BII
<capability>you want to support foreground app invocation.
- Within the
<intent>tag, add an
- In the
"requiredForegroundActivity", and set
android:valueto the activity that you want to require to be in the foreground. Specify the activity without any class abbreviations, using your app package name, followed by a forward slash (/), followed by the activity name:
- In the foreground activity you specified for
"requiredForegroundActivity", implement the
onNewIntent()method to handle a deep link intent with the
SINGLE_TOPflag set. Assistant passes the deep link intent with this flag as fulfillment when the specified activity is in the foreground.
- Treat calls to
onNewIntent()as updates to your foreground activity, and manage state in that activity using parameters extracted from the deep link.
If your app uses a router activity to let all external deep links trigger a single gatekeeping router activity, see Handle router activities.
The following snippet from an example
shortcuts.xml file shows how to add the
<capability name="actions.intent.CREATE_TAXI_RESERVATION"> <!-- Trigger with foreground app invocation if MainActivity is in the foreground. --> <intent android:targetClass="com.example.app.MainActivity" android:targetPackage="com.example.app"> <parameter android:name="taxiReservation.dropoffLocation.name" android:key="dropoff" /> <extra android:key="requiredForegroundActivity" android:value="com.example.app/com.example.app.MainActivity" /> </intent> <!-- This won't trigger if MainActivity is in the foreground. --> <intent android:targetClass="com.example.app.MainActivity" android:targetPackage="com.example.app"> <parameter android:name="taxiReservation.dropoffLocation.name" android:key="dropoff" /> </intent> </capability>
For foreground app invocation to work for a user, the user must have the Use text from screen device setting enabled. The location and exact name of this setting can vary by OEM or device manufacturer. For instance, the device setting might instead be called Use screen context on a user's device.
To reach this Android setting on a Pixel phone, first go to Settings > Apps & notifications > Default apps > Assist app. Then, on the Assist and voice input screen, enable Use text from screen.
Test your invocation
To try your foreground app invocation, follow these steps:
- Follow the instructions in the User permissions section to enable the Use text from screen device setting.
- Open your app to the activity you listed as the required foreground activity.
- Press & hold the home button to open the Assistant as an overlay on the current app. Provide a query that corresponds to the BII you implemented without mentioning the app name itself. When successful, your app updates itself based on your query while maintaining state and without restarting the activity.
Handle router activities
Some apps handle all external deep links using a single gatekeeping router activity. The router activity then starts the appropriate business logic activity (after any checks and validations) and returns the business logic activity to the foreground.
Triggering a deep link can cause the router activity to be added to the top of the task stack, above the foreground activity. For apps that use a router activity, you must make sure that the router activity delivers the intent sent by Google Assistant to the current foreground activity instance. How you achieve this requirement changes depending on where your router activity starts.
Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK
Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK
If your router starts in a separate task stack from your business logic
activity, forward the intent with the
SINGLE_TOP flag to the business
logic activity instead.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-01-09 UTC.