Pinning Shortcuts and Widgets

Some devices running the Android O Developer Preview allow your app to pin shortcuts and widgets onto the launcher.

Pinning shortcuts

Pinned shortcuts, similar to app shortcuts, allow users to quickly start a specific task in your app. Unlike app shortcuts, however, pinned shortcuts appear in the launcher as separate icons. Figure 1 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 won'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());
}

You can also create a specialized activity that helps users create shortcuts, complete with custom options and a confirmation button. Figure 2 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. When the user attempts to create a shortcut, the system starts this specialized activity. The user then sets options for the shortcut. When the user selects the confirmation button, 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(). Finally, your app finishes the activity used for creating the customized shortcut.

For more information about how to work with app shortcuts, see the App Shortcuts guide, as well as the ShortcutManager and ShortcutInfo class references.

Pinning widgets

On devices running Android O, the launchers that allow you to create pinned shortcuts also allow you to pin app widgets onto the launcher. Similar to pinned shortcuts, these pinned widgets give users access to specific tasks in your app.

In your app, you can create a request for the system to pin a widget onto a supported launcher by completing the following sequence of steps:

1. Create the widget in your app's manifest file, as shown in the following snippet:

   <manifest>
   ...
     <application>
       ...
       <receiver android:name="MyAppWidgetProvider">
           <intent-filter>
               <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
           </intent-filter>
           <meta-data android:name="android.appwidget.provider"
                      android:resource="@xml/my_appwidget_info" />
       </receiver>
     </application>
   </manifest>
   

2. Call the requestPinAddWidget() method, as shown in the following code snippet:

   AppWidgetManager mAppWidgetManager =
           context.getSystemService(AppWidgetManager.class);
   
   AppWidgetProviderInfo myWidgetProviderInfo = new AppWidgetProviderInfo();
   ComponentName myProvider = myWidgetProviderInfo.provider;
   
   if (mAppWidgetManager.isRequestPinAppWidgetSupported()) {
       // Create the PendingIntent object only if your app needs to be notified
       // that the user allowed the widget to be pinned. Note that, if the pinning
       // operation fails, your app isn't notified.
       Intent pinnedWidgetCallbackIntent = new Intent( ... );
   
       // Configure the intent so that your app's broadcast receiver gets
       // the callback successfully. This callback receives the ID of the
       // newly-pinned widget (EXTRA_APPWIDGET_ID).
       PendingIntent successCallback = PendingIntent.createBroadcast(context, 0,
               pinnedWidgetCallbackIntent);
   
       mAppWidgetManager.requestPinAppWidget(myProvider, null,
               successCallback.getIntentSender());
   }
   

Note: If your app doesn't need to be notified of whether the system successfully pinned a widget onto a supported launcher, you can pass in null as the third argument to requestPinAddWidget().