ShortcutManager

public class ShortcutManager
extends Object

The ShortcutManager manages an app's shortcuts. Shortcuts provide users with quick access to activities other than an app's main activity in the currently-active launcher. For example, an email app may publish the "compose new email" action, which will directly open the compose activity. The ShortcutInfo class contains information about each of the shortcuts themselves.

Static Shortcuts and Dynamic Shortcuts

There are several different types of shortcuts:

• Static shortcuts are declared in a resource XML file, which is referenced in the publisher app's AndroidManifest.xml file. These shortcuts are visually associated with an app's launcher icon.

  Static shortcuts are published when an app is installed, and the details of these shortcuts change when an app is upgraded with an updated XML file. Static shortcuts are immutable, and their definitions, such as icons and labels, cannot be changed dynamically without upgrading the publisher app.

• Dynamic shortcuts are published at runtime using this class's APIs. These shortcuts are visually associated with an app's launcher icon. Apps can publish, update, and remove dynamic shortcuts at runtime.

Only main activities—activities that handle the MAIN action and the LAUNCHER category—can have shortcuts. If an app has multiple main activities, these activities have different sets of shortcuts.

Static shortcuts and dynamic shortcuts are shown in a supported launcher when the user long-presses on an app's launcher icon. Note that the actual gesture may be different depending on the launcher app.

Each launcher icon can have at most getMaxShortcutCountPerActivity() number of static and dynamic shortcuts combined.

Pinning Shortcuts

Apps running in the foreground can also pin shortcuts at runtime, subject to user permission, using this class's APIs. Each pinned shortcut is a copy of a static shortcut or a dynamic shortcut. Although users can pin a shortcut multiple times, the system calls the pinning API only once to complete the pinning process. Unlike static and dynamic shortcuts, pinned shortcuts appear as separate icons, visually distinct from the app's launcher icon, in the launcher. There is no limit to the number of pinned shortcuts that an app can create.

Pinned shortcuts cannot be removed by publisher apps. They're removed only when the user removes them, when the publisher app is uninstalled, or when the user performs the clear data action on the publisher app from the device's Settings app.

However, the publisher app can disable pinned shortcuts so they cannot be started. See the following sections for details.

Updating and Disabling Shortcuts

When a dynamic shortcut is pinned, even when the publisher removes it as a dynamic shortcut, the pinned shortcut will still be visible and launchable. This allows an app to have more than getMaxShortcutCountPerActivity() number of shortcuts.

For example, suppose getMaxShortcutCountPerActivity() is 5:

1. A chat app publishes 5 dynamic shortcuts for the 5 most recent conversations (c1, c2, ..., c5).
2. The user pins all 5 of the shortcuts.
3. Later, the user has started 3 additional conversations (c6, c7, and c8), so the publisher app re-publishes its dynamic shortcuts. The new dynamic shortcut list is: c4, c5, ..., c8. The publisher app has to remove c1, c2, and c3 because it can't have more than 5 dynamic shortcuts.
4. However, even though c1, c2, and c3 are no longer dynamic shortcuts, the pinned shortcuts for these conversations are still available and launchable.
5. At this point, the user can access a total of 8 shortcuts that link to activities in the publisher app, including the 3 pinned shortcuts, even though an app can have at most 5 dynamic shortcuts.
6. The app can use updateShortcuts(List) to update any of the existing 8 shortcuts, when, for example, the chat peers' icons have changed.

Disabling Static Shortcuts

When an app is upgraded and the new version no longer uses a static shortcut that appeared in the previous version, this deprecated shortcut isn't published as a static shortcut.

If the deprecated shortcut is pinned, then the pinned shortcut will remain on the launcher, but it's disabled automatically. When a pinned shortcut is disabled, this class's APIs cannot update it.

Disabling Dynamic Shortcuts

Publishing Static Shortcuts

In order to add static shortcuts to your app, first add <meta-data android:name="android.app.shortcuts" /> to your main activity in AndroidManifest.xml:

<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>
 

<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 is what the user sees when they
         launch this shortcut. -->
    <categories android:name="android.shortcut.conversation" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>
 

android:shortcutId

Mandatory shortcut ID.

This must be a string literal. A resource string, such as @string/foo, cannot be used.

android:enabled

Default is true. Can be set to false in order to disable a static shortcut that was published in a previous version and set a custom disabled message. If a custom disabled message is not needed, then a static shortcut can be simply removed from the XML file rather than keeping it with enabled="false".

android:icon

Shortcut icon.

android:shortcutShortLabel

Mandatory shortcut short label. See setShortLabel(CharSequence).

This must be a resource string, such as @string/shortcut_label.

android:shortcutLongLabel

Shortcut long label. See setLongLabel(CharSequence).

This must be a resource string, such as @string/shortcut_long_label.

android:shortcutDisabledMessage

When android:enabled is set to false, this attribute is used to display a custom disabled message.

This must be a resource string, such as @string/shortcut_disabled_message.

intent

Intent to launch when the user selects the shortcut. android:action is mandatory. See Using intents for the other supported tags. You can provide multiple intents for a single shortcut so that the last defined activity is launched with the other activities in the back stack. See TaskStackBuilder for details.

Note: String resources may not be used within an <intent> element.

categories

Specify shortcut categories. Currently only SHORTCUT_CATEGORY_CONVERSATION is defined in the framework.

Publishing Dynamic Shortcuts

Apps can publish dynamic shortcuts with setDynamicShortcuts(List) or addDynamicShortcuts(List). The updateShortcuts(List) method can also be used to update existing, mutable shortcuts. Use removeDynamicShortcuts(List) or removeAllDynamicShortcuts() to remove dynamic shortcuts.

The following code snippet shows how to create a single dynamic shortcut:

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));
 

Publishing Pinned Shortcuts

Apps can pin an existing shortcut (either static or dynamic) or an entirely new shortcut to a supported launcher programatically using requestPinShortcut(ShortcutInfo, IntentSender). You pass two arguments into this method:

• A ShortcutInfo object – If the shortcut already exists, this object should contain only the shortcut's ID. Otherwise, the new ShortcutInfo object must contain an ID, an intent, and a short label for the new shortcut.

• A PendingIntent object – This intent represents the callback that your app receives if the shortcut is successfully pinned to the device's launcher.

  Note: If the user doesn't allow the shortcut to be pinned to the launcher, the pinning process fails, and the Intent object that is passed into this PendingIntent object isn't executed.

  Note: Due to background execution limits introduced in Android O, it's best to use a manifest-declared receiver to receive a callback.

  Also, to prevent other apps from invoking the receiver, add the attribute assignment android:exported="false" to the receiver's manifest entry.

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

if (mShortcutManager.isRequestPinShortcutSupported()) {

    // This example defines a new shortcut; that is, this shortcut hasn't
    // been published before.
    ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder()
            .setIcon(myIcon)
            .setShortLabel("My awesome shortcut")
            .setIntent(myIntent)
            .build();

    PendingIntent resultPendingIntent = null;

    // Create the following Intent and PendingIntent objects only if your app
    // needs to be notified that the user allowed the shortcut to be pinned.
    // Use a boolean value, such as "appNeedsNotifying", to define this behavior.
    if (appNeedsNotifying) {
        // We assume here the app has a manifest-declared receiver "MyReceiver".
        Intent pinnedShortcutCallbackIntent = new Intent(context, MyReceiver.class);

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

        resultPendingIntent = successCallback.getIntentSender();
    }

    mShortcutManager.requestPinShortcut(pinShortcutInfo, resultPendingIntent);
}
 

Note: As you add logic in your app to make requests to pin shortcuts, keep in mind that not all launchers support pinning of shortcuts. To determine whether your app can complete this process on a particular device, check the return value of isRequestPinShortcutSupported(). Based on this return value, you might decide to hide the option in your app that allows users to pin a shortcut.

Custom Activity for Pinning Shortcuts

You can also create a specialized activity that helps users create shortcuts, complete with custom options and a confirmation button. In your app's manifest file, add ACTION_CREATE_SHORTCUT to the activity's <intent-filter> element, as shown in the following snippet:

<manifest>
    ...
    <application>
        <activity android:name="com.example.MyCustomPromptToPinShortcut" ... >
            <intent-filter
                    action android:name="android.intent.action.ACTION_CREATE_SHORTCUT">
            ...
            </intent-filter>
        </activity>
        ...
    </application>
</manifest>
 

When you use this specialized activity in your app, the following sequence of steps takes place:

1. The user attempts to create a shortcut, triggering the system to start the specialized activity.
2. The user sets options for the shortcut.
3. The user selects the confirmation button, allowing your app to create the shortcut using the createShortcutResultIntent(ShortcutInfo) method. This method returns an Intent, which your app relays back to the previously-executing activity using setResult(int).
4. Your app calls finish() on the activity used for creating the customized shortcut.

Shortcut Intents

Dynamic shortcuts can be published with any set of Intent flags. Typically, FLAG_ACTIVITY_CLEAR_TASK is specified, possibly along with other flags; otherwise, if the app is already running, the app is simply brought to the foreground, and the target activity may not appear.

The setIntents(Intent[]) method can be used instead of setIntent(Intent) with TaskStackBuilder in order to launch an activity with other activities in the back stack. When the user selects a shortcut to load an activity with a back stack, then presses the back key, a parent activity from the same app will be shown instead of the user being navigated back to the launcher.

Static shortcuts can also have multiple intents to achieve the same effect. In order to associate multiple Intent objects with a shortcut, simply list multiple <intent> elements within a single <shortcut> element. The last intent specifies what the user sees when they launch a shortcut.

Static shortcuts cannot have custom intent flags. The first intent of a static shortcut will always have FLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_CLEAR_TASK set. This means, when the app is already running, all the existing activities will be destroyed when a static shortcut is launched. If this behavior is not desirable, you can use a trampoline activity, or an invisible activity that starts another activity in onCreate(Bundle), then calls finish(). The first activity should include an attribute setting of android:taskAffinity="" in the app's AndroidManifest.xml file, and the intent within the static shortcut should point at this first activity.

Showing New Information in a Shortcut

In order to avoid confusion, you should not use updateShortcuts(List) to update a shortcut so that it contains conceptually different information.

For example, a phone app may publish the most frequently called contact as a dynamic shortcut. Over time, this contact may change. When it does, the app should represent the changed contact with a new shortcut that contains a different ID, using either setDynamicShortcuts(List) or addDynamicShortcuts(List), rather than updating the existing shortcut with updateShortcuts(List). This is because when the shortcut is pinned, changing it to reference a different contact will likely confuse the user.

On the other hand, when the contact's information has changed, such as the name or picture, the app should use updateShortcuts(List) so that the pinned shortcut is updated too.

Shortcut Display Order

• First show static shortcuts (if isDeclaredInManifest() is true), and then show dynamic shortcuts (if isDynamic() is true).
• Within each category of shortcuts (static and dynamic), sort the shortcuts in order of increasing rank according to getRank().

Shortcut ranks are non-negative, sequential integers that determine the order in which shortcuts appear, assuming that the shortcuts are all in the same category. Ranks of existing shortcuts can be updated with updateShortcuts(List). You can also use addDynamicShortcuts(List) and setDynamicShortcuts(List).

Ranks are auto-adjusted so that they're unique for each target activity in each category (static or dynamic). For example, if there are 3 dynamic shortcuts with ranks 0, 1 and 2, adding another dynamic shortcut with a rank of 1 represents a request to place this shortcut at the second position. In response, the third and fourth shortcuts move closer to the bottom of the shortcut list, with their ranks changing to 2 and 3, respectively.

Rate Limiting

Calls to setDynamicShortcuts(List), addDynamicShortcuts(List), and updateShortcuts(List) may be rate-limited when called by background apps, or apps with no foreground activity or service. When you attempt to call these methods from a background app after exceeding the rate limit, these APIs return false.

Apps with a foreground activity or service are not rate-limited.

Rate-limiting is reset upon certain events, so that even background apps can call these APIs until the rate limit is reached again. These events include the following:

• An app comes to the foreground.
• The system locale changes.
• The user performs the inline reply action on a notification.

When rate-limiting is active, isRateLimitingActive() returns true.

Resetting rate-limiting for testing

If your app is rate-limited during development or testing, you can use the Reset ShortcutManager rate-limiting development option or the following adb command to reset it:

$ adb shell cmd shortcut reset-throttling [ --user USER-ID ]
 

Handling System Locale Changes

Apps should update dynamic and pinned shortcuts when the system locale changes using the ACTION_LOCALE_CHANGED broadcast.

When the system locale changes, rate-limiting is reset, so even background apps can add and update dynamic shortcuts until the rate limit is reached again.

Backup and Restore

When an app has the android:allowBackup="true" attribute assignment included in its AndroidManifest.xml file, pinned shortcuts are backed up automatically and are restored when the user sets up a new device.

Categories of shortcuts that are backed up

• Pinned shortcuts are backed up. Bitmap icons are not backed up by the system, so launcher apps should back them up and restore them so that the user still sees icons for pinned shortcuts on the launcher. Apps can always use updateShortcuts(List) to re-publish icons.
• Static shortcuts aren't backed up, but when an app is re-installed on a new device, they are re-published from the AndroidManifest.xml file.
• Dynamic shortcuts aren't backed up.

Because dynamic shortcuts are not restored, it is recommended that apps check currently-published dynamic shortcuts using getDynamicShortcuts() each time they are launched, and they should re-publish dynamic shortcuts when necessary.

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.
            }
        }
    }
    // ...
}
 

Backup/restore and shortcut IDs

Because pinned shortcuts are backed up and restored on new devices, shortcut IDs should contain either stable, constant strings or server-side identifiers, rather than identifiers generated locally that might not make sense on other devices.

Report Shortcut Usage and Prediction

Launcher apps may be capable of predicting which shortcuts will most likely be used at a given time by examining the shortcut usage history data.

In order to provide launchers with such data, publisher apps should report the shortcuts that are used with reportShortcutUsed(String) when a shortcut is selected, or when an action equivalent to a shortcut is taken by the user even if it wasn't started with the shortcut.

For example, suppose a navigation app supports "navigate to work" as a shortcut. It should then report when the user selects this shortcut and when the user chooses to navigate to work within the app itself. This helps the launcher app learn that the user wants to navigate to work at a certain time every weekday, and it can then show this shortcut in a suggestion list at the right time.

Launcher API

Direct Boot and Shortcuts

Summary

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long millis, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long millis) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object.

Public methods

boolean addDynamicShortcuts (List<ShortcutInfo> shortcutInfoList)

Intent createShortcutResultIntent (ShortcutInfo shortcut)

void disableShortcuts (List<String> shortcutIds)

void disableShortcuts (List<String> shortcutIds, 
                CharSequence disabledMessage)

void enableShortcuts (List<String> shortcutIds)

List<ShortcutInfo> getDynamicShortcuts ()

int getIconMaxHeight ()

int getIconMaxWidth ()

List<ShortcutInfo> getManifestShortcuts ()

int getMaxShortcutCountPerActivity ()

List<ShortcutInfo> getPinnedShortcuts ()

boolean isRateLimitingActive ()

boolean isRequestPinShortcutSupported ()

void removeAllDynamicShortcuts ()

void removeDynamicShortcuts (List<String> shortcutIds)

void reportShortcutUsed (String shortcutId)

boolean requestPinShortcut (ShortcutInfo shortcut, 
                IntentSender resultIntent)

boolean setDynamicShortcuts (List<ShortcutInfo> shortcutInfoList)

boolean updateShortcuts (List<ShortcutInfo> shortcutInfoList)