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.
Limitations
Foreground app invocation is only available for the following BIIs:
actions.intent.CREATE_MONEY_TRANSFER
actions.intent.CREATE_TAXI_RESERVATION
actions.intent.OPEN_APP_FEATURE
actions.intent.ORDER_MENU_ITEM
actions.intent.PAUSE_EXERCISE
actions.intent.RECORD_EXERCISE
actions.intent.RECORD_FOOD_OBSERVATION
actions.intent.RESUME_EXERCISE
actions.intent.START_EXERCISE
actions.intent.STOP_EXERCISE
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.xml
file, add an<intent>
tag to the BII<capability>
you want to support foreground app invocation. - Within the
<intent>
tag, add an<extra>
tag. - In the
<extra>
tag, setandroid:key
to"requiredForegroundActivity"
, and setandroid:value
to 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:APP_PACKAGE_NAME/ACTIVITY_NAME
- In the foreground activity you specified for
"requiredForegroundActivity"
, implement theonNewIntent()
method to handle a deep link intent with theSINGLE_TOP
flag 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.
Example
The following snippet from an example shortcuts.xml
file shows how to add the
requiredForegroundActivity
attribute:
<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>
User permissions

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.
If your router starts in the same task stack as your business logic activity,
forward the intent using the bitwise OR of SINGLE_TOP
, CLEAR_TOP
,
and NEW_TASK
:
Kotlin
Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK
Java
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-05-04 UTC.