Suggest shortcuts using the In-App Promo SDK

To promote features of your app and make it easier to use, you can suggest Assistant shortcuts to your users. Assistant shortcuts are concise phrases that a user can utter to trigger functionality within your app.

Though Assistant shortcuts can be created manually by your users, the In-App Promo SDK enables you to proactively suggest and implement Assistant shortcuts. By suggesting shortcuts, you ensure your users have clear, simple paths back to their favorite activities in your app without the added effort of setting up the shortcuts.

For example, if a user performs a search for "heavy metal workout" in your music app, you might suggest an Assistant shortcut directly to those search results in the future. When you suggest a shortcut, a prompt appears in your app that displays the proposed phrase for the shortcut and asks the user if the shortcut should be created. In this example, you suggest the phrase, "start my heavy metal workout." The user accepts the suggestion and can then launch the shortcut by saying, "Hey Google, start my heavy metal workout "

For more information about ways to grow your app's audience, see Grow your apps with app actions.

The In-App Promo SDK provides the following methods:

  • lookupShortcut checks whether the shortcut you want to suggest already exists. The method also checks for any issues that prevent the shortcut from being created. If the shortcut can't be created, LookupShortcut returns the reasons why.

  • createShortcutSuggestionIntent returns an intent that you can use to prompt the user to create the suggested shortcut.

  • createShortcutSettingsIntent returns an intent that you can use to move the user to the Assistant Shortcut settings for your app.

Prerequisites and limitations

This section describes prerequisites and requirements for using suggestions, and limitations you may encounter.

Development prerequisites

To use suggestions, your development environment must meet the following prerequisites.

  • Ensure that your Android app is extended to use App Actions.

  • Include com.google.android.googlequicksearchbox within the <queries> tags in your manifest. For example:

    <manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

  • Use Android App Bundles to publish your apps.

Device requirements

To test your suggestions on a device, your device must meet the following requirements.

  • The latest version of the Google app is installed.

  • Android version is M (API level 23) or later.

Known limitations

This section describes limitations with suggestions.

Suggestions are supported only in English. For users to see your suggestions, they must set the Assistant language on their device to English.

Implement suggestions

When implementing suggestions, you need to update your build.gradle file, set up the suggestions client, and then define the suggestions that you want to give users.

To implement suggestions in your app:

  1. Add the library dependency to your build.gradle file.

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. Define an instance of AssistantShortcutSuggestionsClient.

    Kotlin

    val shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build()

    Java

    AssistantShortcutSuggestionsClient shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build();

    Where:

    • CONTEXT (required) is the application context.

    • VERIFY_INTENTS (required) determines whether to verify every intent created when suggesting shortcuts to users. When true, the intents created by AssistantShortcutSuggestionsClient are verified. If an intent is invalid, an exception is returned.

    • CUSTOM_EXECUTOR (optional) is a custom executor for running asynchronous tasks. If not provided, the SDK uses a single-threaded executor for the task.

  3. Use the lookupShortcut method to determine if the shortcut you want to suggest is valid and whether the shortcut already exists. We recommend that you implement lookupShortcut to verify that the intents created by your suggestions are valid, even if you don't plan on checking for existing user shortcuts.

    1. Create an app shortcut intent. The shortcut intent represents the shortcut that you want to suggest to a user. The following example describes a shortcut to order the user a beverage.

      Kotlin

      val menuItem = mapOf(
    "@type" to "MenuItem",
    "@context" to "http://schema.googleapis.com",
    "name" to "Fresh Lemon Honey Jasmine Green Tea",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.ORDER_MENU_ITEM")
    .setPackageName("my.app.package")
    .setIntentParamName("menuItem")
    .setIntentParamValue(menuItem)
    .build()

      Java

        Map menuItem = new HashMap<>();
  menuItem.put("@type", "MenuItem");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build();

    2. Pass the shortcut intent to the lookupShortcut method.

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
if (!result.isShortcutPresent) {
    // app can suggest to create a shortcut
} else {
    // app can remind that the user has a shortcut for this app action
}

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // app can suggest to create a shortcut
    } else {
      // app can remind that the user has a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. Create the suggestion using the shortcut intent.

    There are two methods you can use to create a suggestion:

    • createShortcutSuggestionIntent returns an Android intent that you use to start the shortcut suggestion activity in the context of your app.

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        AppShortcutSuggestion orderShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
      .addOnSuccessListener(intent ->
          getApplication().startActivity(
              intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
      )
      .addOnFailureListener(e ->
          Log.e(TAG, "Failed to get shortcut suggestion intent", e);
      );

      Where PHRASE is the utterance that you want to suggest to the user as a shortcut. For example, if you wanted the user to say "Hey Google, order my bubble tea" as a shortcut, you would replace PHRASE with "order my bubble tea".

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("order my bubble tea")
    .build()

      Java

      AppShortcutSuggestion orderShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("order my bubble tea")
        .build();

    • createShortcutSettingsIntent returns an Android intent that moves the user to the shortcut settings interface in the Assistant app.

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        shortcutsClient.createShortcutSettingsIntent()
    .addOnSuccessListener(intent ->
        getApplication().startActivity(
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    )
    .addOnFailureListener(e ->
        Log.e(TAG, "Failed to get shortcut settings intent", e);
    );

  5. Call startActivity using the Android intent returned during the previous step.

Troubleshooting suggestions

This section lists issues and exceptions that you may encounter when suggesting shortcuts.

GoogleInstallationUnsupportedException: Cannot bind to service

Due to package visibility filtering GoogleInstallationUnsupportedException: Cannot bind to service may happen on Android 11 and later. Make sure that com.google.android.googlequicksearchbox is included within the <queries> tag in your manifest:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"Failed to verify the APK signature"

The following error can occur if you do not submit your production app as an app bundle:

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

Ensure that you submit your app as an Android App Bundle.

"Failed to get user shortcuts"

The "Failed to get user shortcuts" error message can happen if you recently added an account to the device, and if the new account’s shortcut data hasn't been cached on the device yet.

To sync the shortcut data on the device, add or delete an Assistant shortcut using the Assistant app's interface.

Shortcut Creation Activity immediately closes without showing any content

The Shortcut Creation Activity can close without displaying any content if you didn’t create a preview using the App Actions Test Tool, or if the preview expired. Update your preview and try again.