App Shortcuts

If your app targets Android 7.1 (API level 25) or higher, you can define shortcuts to specific actions in your app. These shortcuts can be displayed in a supported launcher. Shortcuts let your users quickly start common or recommended tasks within your app.

Each shortcut references one or more intents, each of which launches a specific action in your app when users select the shortcut. Examples of actions you can express as shortcuts include the following:

• Navigating users to a particular location in a mapping app.
• Sending messages to a friend in a communication app.
• Playing the next episode of a TV show in a media app.
• Loading the last save point in a gaming app.

You can publish the following types of shortcuts for your app:

• Static shortcuts are defined in a resource file that is packaged into an APK. Therefore, you must wait until you update your entire app to change the details of these static shortcuts.
• Dynamic shortcuts are published at runtime using the ShortcutManager API. During runtime, your app can publish, update, and remove its dynamic shortcuts.

• Pinned shortcuts are published at runtime and also use the ShortcutManager API. During runtime, your app can attempt to pin the shortcut, at which time the user receives a confirmation dialog asking their permission to pin the shortcut. The pinned shortcut appears in supported launchers only if the user accepts the pinning request.

  Note: Users can also create pinned shortcuts themselves by copying your app's static and dynamic shortcuts onto the launcher.

You can publish up to five shortcuts (static shortcuts and dynamic shortcuts combined) at a time for your app. Some launcher apps, however, don't show every static and dynamic shortcut you've created for your app.

There is no limit to the number of pinned shortcuts to your app that users can create. Even though your app cannot remove pinned shortcuts, it can still disable them.

Note: Although other apps can't access the metadata within your shortcuts, the launcher itself can access this data. Therefore, these metadata should conceal sensitive user information.

Using Static Shortcuts

Static shortcuts should provide links to generic actions within your app, and these actions should remain consistent over the lifetime of your app's current version. Good candidates for static shortcuts include viewing sent messages, setting an alarm, and displaying a user's exercise activity for the day.

To create a static shortcut, complete the following sequence of steps:

1. In your app's manifest file (AndroidManifest.xml), find an activity whose intent filters are set to the android.intent.action.MAIN action and the android.intent.category.LAUNCHER category.

2. Add a <meta-data> element to this activity that references the resource file where the app's shortcuts are defined:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" />
       </activity>
     </application>
   </manifest>
       

3. Create a new resource file: res/xml/shortcuts.xml.

   In this new resource file, add a <shortcuts> root element, which contains a list of <shortcut> elements. Each <shortcut> element, in turn, contains information about a static shortcut, including its icon, its description labels, and the intents that it launches within the app:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.ComposeActivity" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
       

For more details about how to configure shortcuts in a resource file, see the ShortcutManager API reference.

Note: If you associate multiple intents with a shortcut, the system launches the activity corresponding to the shortcut's last intent in the resource file, with other activities in the back stack. In this case, when the user selects a shortcut then presses the back key, your app launches the activity corresponding with the shortcut's second-to-last intent listed in the resource file. This behavior pattern continues upon repeated presses of the back button, until the user clears the back stack that a shortcut created. When the user next presses the back button, the system navigates them back to the launcher.

Using Dynamic Shortcuts

Dynamic shortcuts should provide links to specific, context-sensitive actions within your app. These actions can change between uses of your app, and they can change even while your app is running. Good candidates for dynamic shortcuts include calling a specific person, navigating to a specific location, and viewing the current score for a specific game.

The ShortcutManager API allows you to complete the following operations on dynamic shortcuts:

• Publish: Use setDynamicShortcuts() to redefine the entire list of dynamic shortcuts, or use addDynamicShortcuts() to augment an existing list of dynamic shortcuts.
• Update: Use the updateShortcuts() method.
• Remove: Remove a set of dynamic shortcuts using removeDynamicShortcuts(), or remove all dynamic shortcuts using removeAllDynamicShortcuts().

An example of creating a dynamic shortcut and associating it with your app appears in the following code snippet:

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

ShortcutInfo shortcut = new ShortcutInfo.Builder(this, "id1")
    .setShortLabel("Web site")
    .setLongLabel("Open the web site")
    .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

Using Pinned Shortcuts

On Android 8.0 (API level 26) and higher, you can create pinned shortcuts. Unlike static and dynamic shortcuts, pinned shortcuts appear in supported launchers as separate icons. Figure 2 shows the distinction between these two types of shortcuts.

Note: When you attempt to pin a shortcut onto a supported launcher, the user receives a confirmation dialog asking their permission to pin the shortcut. If the user doesn't allow the shortcut to be pinned, the launcher cancels the request.

To pin a shortcut to a supported launcher using your app, complete the following sequence of steps:

1. Use isRequestPinShortcutSupported() to verify that the device's default launcher supports in-app pinning of shortcuts.

2. Create a ShortcutInfo object in one of two ways, depending on whether the shortcut already exists:

   1. If the shortcut already exists, create a ShortcutInfo object that contains only the existing shortcut's ID. The system finds and pins all other information related to the shortcut automatically.
   2. If you're pinning a new shortcut, create a ShortcutInfo object that contains an ID, an intent, and a short label for the new shortcut.

3. Attempt to pin the shortcut to the device's launcher by calling requestPinShortcut(). During this process, you can pass in a PendingIntent object, which notifies your app only when the shortcut is pinned successfully.

   Note: If the user doesn't allow the shortcut to be pinned to the launcher, your app doesn't receive a callback.

   After a shortcut is pinned, your app can update its contents using the updateShortcuts() method.

The following code snippet demonstrates this process:

ShortcutManager mShortcutManager =
        context.getSystemService(ShortcutManager.class);

if (mShortcutManager.isRequestPinShortcutSupported()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            mShortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.
    PendingIntent successCallback = PendingIntent.getBroadcast(context, 0,
            pinnedShortcutCallbackIntent, 0);

    mShortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

Note: See also the support library APIs, isRequestPinShortcutSupported() and requestPinShortcut(), which work on Android 7.1 (API level 25) and lower. The support library falls back to the deprecated EXTRA_SHORTCUT_INTENT extra to attempt the pinning process.

You can also create a specialized activity that helps users create shortcuts, complete with custom options and a confirmation button. Figure 3 shows an example of this type of activity in the Gmail app.

In your app's manifest file, add ACTION_CREATE_SHORTCUT to the activity's <intent-filter> element. This declaration sets up the following behavior when the user attempts to create a shortcut:

1. The system starts your app's specialized activity.
2. The user sets options for the shortcut.

3. The user selects the confirmation button.

   At this point, your app creates the shortcut using the createShortcutResultIntent() method. This method returns an Intent, which your app relays back to the previously-executing activity using setResult().

4. Your app calls finish() on the activity used for creating the customized shortcut.

Tracking Shortcut Usage

To determine the situations during which static and dynamic shortcuts should appear, the launcher examines the activation history of shortcuts. You can keep track of when users complete specific actions within your app by calling the reportShortcutUsed() method, passing in the ID of a shortcut, when either of the following events occur:

• The user selects the shortcut with the given ID.
• The user opens the app and manually completes the action corresponding to the same shortcut.

Disabling Shortcuts

Because your app and its users can pin shortcuts to the device's launcher, it's possible that these pinned shortcuts could direct users to actions within your app that are out of date or that no longer exist. To manage this situation, you can disable the shortcuts that you don't want users to select by calling disableShortcuts(), which removes the specified shortcuts from the static and dynamic shortcuts list and disables any pinned copies of these shortcuts. You can also use an overloaded version of this method to define an error message that should appear when users attempt to launch a disabled shortcut.

Note: If you remove some of your app's static shortcuts when you update your app, the system disables these shortcuts automatically.

Testing Shortcuts

To test your app's shortcuts, install your app on a device containing a launcher that supports shortcuts. You should then be able to perform the following actions:

• Long-tap on your app's launcher icon to view the shortcuts that you've defined for your app.
• Tap and drag a shortcut to pin it to the device's launcher.

You can use these interactions to test the effects of adding, updating, disabling, and removing shortcuts.

Assigning Multiple Intents

When creating a shortcut using ShortcutInfo.Builder, you can use setIntents() instead of setIntent(). By calling setIntents(), you can launch multiple activities within your app when the user selects a shortcut, placing all but the last activity in the list on the back stack. If the user then decides to press the device's back button, they will see another activity in your app instead of returning to the device's launcher.

Rate Limiting

When using the setDynamicShortcuts(), addDynamicShortcuts(), or updateShortcuts() methods, keep in mind that you might only be able to call these methods a specific number of times in a background app, an app with no activities or services currently in the foreground. In a production environment, you can reset this rate limiting by bringing your app to the foreground.

If you encounter rate limiting during development or testing, you can select Developer Options > Reset ShortcutManager rate-limiting from the device's settings, or you can enter the following command in adb:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Backup and Restore

If you allow users to back up and restore your app when changing devices by including the android:allowBackup="true" attribute assignment in your app's manifest file, keep the following points about app shortcuts in mind:

• Static shortcuts are re-published automatically, but only after the user re-installs your app on a new device.
• Dynamic shortcuts aren't backed up, so you must include logic in your app to re-publish them when a user opens your app on a new device.
• Pinned shortcuts are restored to the device's launcher automatically, but the system doesn't back up icons associated with pinned shortcuts. Therefore, you should save your pinned shortcuts' images in your app so that it's easy to restore them on a new device.

The following code snippet shows how best to restore your app's dynamic shortcuts and how to check whether your app's pinned shortcuts were preserved:

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ShortcutManager shortcutManager =
                getSystemService(ShortcutManager.class);

        if (shortcutManager.getDynamicShortcuts().size() == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (shortcutManager.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}

Best Practices

When designing and creating your app's shortcuts, you should follow these guidelines:

Follow the shortcuts design guidelines

To make your app's shortcuts visually consistent with the shortcuts used for system apps, follow the App Shortcuts Design Guidelines.

Publish only four distinct shortcuts

Although the API currently supports a combination of up to five static shortcuts and dynamic shortcuts for your app at any given time, it's recommended that you publish only four distinct shortcuts at any time to improve the shortcuts' visual appearance in the launcher.

Limit shortcut description length

Space is limited within the menu that shows your app's shortcuts in the launcher. When possible, limit the length of the "short description" of a shortcut to 10 characters, and limit the length of the "long description" to 25 characters.

Maintain shortcut and action usage history

For each shortcut that you create, consider the different ways in which a user can accomplish the same task directly within your app. Remember to call reportShortcutUsed() in each of these situations so that the launcher maintains an accurate history of the actions representing your shortcuts.

Update shortcuts only when their meaning is retained

When changing dynamic and pinned shortcuts, call updateShortcuts() only when changing the information of a shortcut that has retained its meaning. Otherwise, you should use one of the following methods, depending on the type of shortcut you're recreating:

• Dynamic shortcuts: addDynamicShortcuts() or setDynamicShortcuts().
• Pinned shortcuts: requestPinShortcut().

For example, if you created a shortcut for navigating to a supermarket, it would be appropriate to just update the shortcut if the name of the supermarket changed but its location stayed the same. If the user started shopping at a different supermarket location, however, it would be better to create a new shortcut.

Dynamic shortcuts aren't preserved during backup and restore

Dynamic shortcuts aren't preserved when a device undergoes a backup and restore operation. For this reason, it's recommended that you check the number of objects returned by getDynamicShortcuts() each time you launch your app and re-publish dynamic shortcuts as needed, as shown in the code snippet within the Backup and Restore section.

Additional code samples

The Android AppShortcuts sample further demonstrates the use of the APIs covered on this page.