Assistant can proactively suggest your Android dynamic shortcuts to users at
contextually relevant times, enabling users to easily discover and replay your
voice-enabled functionality. Android shortcuts provide users with quick
methods to perform an action or access content in an app. For example, you could
push a shortcut for each note a user creates in your note taking app. You make
your dynamic links eligible to be displayed on Google surfaces, like Assistant,
by adding the Google Shortcuts Integration Jetpack library to your project. This
library allows Assistant to ingest dynamic shortcuts you push using the
ShortcutManagerCompat
class, which is a Jetpack wrapper for the
ShortcutManager
API.
By adding the Google Shortcuts Integration library to your app, dynamic
shortcuts you push to Google are visible to users as voice shortcut suggestions
in the Assistant app. You can push an unlimited number of dynamic shortcuts to
Assistant when you add the Google Shortcuts Integration library as an app
dependency, and use the pushDynamicShortcut()
method of the
ShortcutManagerCompat
library.
Configure your development project
Adding dynamic shortcuts functionality to your app requires the Google Shortcuts Integration library, which is an Android Jetpack library. This section describes how to configure your app development project to include this library and set the Android SDK version to the level.
To add this Jetpack library and configure your project, follow these steps:
Update your
gradle.properties
file to handle Jetpack libraries:gradle.properties
android.useAndroidX=true # Automatically convert third-party libraries to use AndroidX android.enableJetifier=true
Add the Jetpack library dependencies to your
build.gradle
:app/build.gradle
dependencies { implementation "androidx.core:core:1.6.0" implementation "androidx.core:core-google-shortcuts:1.0.1" ... }
In the preceding sample code, you list two Jetpack libraries as dependencies. The
androidx.core:core:1.6.0
library contains theShortcutManagerCompat
class which you use to push dynamic shortcuts to Google.The
androidx.core:core-google-shortcuts:1.0.1
is the Google Shortcuts Integration library. This library contains no developer-facing API. By adding it as a dependency, it enables Assistant to ingest the dynamic shortcuts you push using theShortcutManagerCompat
class.
Push dynamic shortcuts
In order to push dynamic shortcuts that are eligible for display on Assistant,
you must first create the shortcut using the ShortcutInfoCompat.Builder()
class. You then push the shortcut using the
ShortcutManagerCompat.pushDynamicShortcut()
method. Shortcuts should be pushed
whenever a user completes a relevant action in your app. The following sample
code pushes a shortcut every time a user places an order in a food delivery app:
ExampleOrderActivity
Kotlin
// Define the dynamic shortcut for a menu item var intent = Intent(context, DisplayOrderActivity::class.java) var shortcutInfo = ShortcutInfoCompat.Builder(context, id) .setShortLabel("Cappuccino") .setLongLabel("Order another cappuccino") .addCapabilityBinding( "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino") ) .setIntent(intent) // Push the shortcut .build() // Push the shortcut ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)
Java
// Define the dynamic shortcut for a menu item Intent intent = new Intent(context, DisplayOrderActivity.class); intent.setAction(Intent.ACTION_VIEW); ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id) .setShortLabel("Cappuccino") .setLongLabel("Order another cappuccino") .addCapabilityBinding( "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")) .setIntent(intent) .build(); // Push the shortcut ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);
The id
referenced in the ShortcutInfoCompat.Builder
method in the preceding
sample code defines the shortcutId
of the resulting shortcut object. This id
must be to a unique string literal. For details, see the
Android Shortcuts documentation.
In the preceding example, the addCapabilityBinding
method binds the dynamic
shortcut to a capability
of the same android:name
defined in
shortcuts.xml
. This method allows you to associate the shortcut to a
semantic BII parameter.
Dynamic shortcuts can also be pushed without any particular BII parameter
association. When invoked by the user, Assistant triggers the intent
defined
in the shortcut to fulfill the action. The following example shows a dynamic
shortcut with no parameter association:
Kotlin
var intent: Intent = Intent(context, DisplayOrderActivity::class.java) intent.setPackage(this, "com.sample.app") intent.setAction(Intent.ACTION_VIEW) var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id) .setShortLabel("Order coffee") .setLongLabel("Order a cup of coffee") .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM") .setIntent(intent) .build() ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);
Java
Intent intent = new Intent(context, DisplayOrderActivity.class); intent.setPackage(this, "com.sample.app"); intent.setAction(Intent.ACTION_VIEW); ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id) .setShortLabel("Order coffee") .setLongLabel("Order a cup of coffee") .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM") .setIntent(intent) .build(); ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);
Test dynamic shortcuts with Assistant
When Google Assistant successfully ingests a dynamic shortcut from your application, it is eligible to appear as a Voice Shortcut suggestion in the Assistant Android app. The Assistant app suggests the most recent shortcuts pushed by your app.
To test your dynamic shortcuts with Assistant, follow these steps:
- Create a preview of your App Actions and make sure your test device or emulator is prepared for testing actions by following the same setup requirements as the Google Assistant Plugin.
- Open your app and complete an action that you have defined a dynamic shortcut to be pushed for. For example, if you push a shortcut whenever a note is created in your note taking app, then create a new note.
- Open Shortcuts in the Assistant Settings app on your device. Your dynamic shortcut should appear in the list for your app.