Foreground app invocation

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:

1. In your shortcuts.xml file, add an <intent> tag to the BII <capability> you want to support foreground app invocation.
2. Within the <intent> tag, add an <extra> tag.
3. In the <extra> tag, set android:key to "requiredForegroundActivity", and set android: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
4. In the foreground activity you specified for "requiredForegroundActivity", implement the onNewIntent() method to handle a deep link intent with the SINGLE_TOP flag set. Assistant passes the deep link intent with this flag as fulfillment when the specified activity is in the foreground.
5. 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:

1. Follow the instructions in the User permissions section to enable the Use text from screen device setting.
2. Open your app to the activity you listed as the required foreground activity.
3. 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:

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