Creating Android App Shortcuts in Launcher

Overview :

Android 7.1 allows you to define shortcuts to specific actions in your app. These shortcuts can be displayed in a supported launcher, such as the one provided with Nexus and Pixel devices. Shortcuts let your users quickly start common or recommended tasks within your app:

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.

Static Shortcuts :

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

Overview :

Provides links to generic actions within your app eg : Settings an Alarm, Displaying user activities for the day

Creating Static Shortcuts:

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

• Your shortcut.xml will be under xml under res folder and will look like this

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

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. eg : calling a specific person, navigating to a specific location, and viewing the current score for a specific game.
• To create a Dynamic Shortcut you will have to use these codes in your activity where you like to initialise the Shortcut.
• Add Below Permissions :

<uses-permission android:name=”com.android.launcher.permission.INSTALL_SHORTCUT” />
<uses-permission android:name=”com.android.launcher.permission.INSTALL_SHORTCUT” />

• Create a Shortcut :

@TargetApi(25)
private void addShortcut(){
Intent shortcut = new Intent("com.android.launcher.action.INSTALL_SHORTCUT");
// Shortcut name
shortcut.putExtra(Intent.EXTRA_SHORTCUT_NAME, getString(R.string.app_name));
shortcut.putExtra("duplicate", false); // Just create once
// Setup current activity shoud be shortcut object
ComponentName comp = new ComponentName(this.getPackageName(), "."+this.getLocalClassName());
shortcut.putExtra(Intent.EXTRA_SHORTCUT_INTENT, new Intent(Intent.ACTION_MAIN).setComponent(comp));
// Set shortcut icon
ShortcutIconResource iconRes = Intent.ShortcutIconResource.fromContext(this, R.drawable.icon);
shortcut.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE, iconRes);
sendBroadcast(shortcut);
}

ShortcutManager uses system service so this has to be in an activity and remember this only works on Android 7.1 so it's good to add the annotation @TargetApi(25) to this code to avoid compile errors and add version check before calling these methods.

if (Build.VERSION.SDK_INT >= 25) {
    createShorcut();
}else{
    removeShorcuts();
}

• Removing shortcuts:

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
    shortcutManager.disableShortcuts(Arrays.asList("shortcut"));
    shortcutManager.removeAllDynamicShortcuts();

• Delete Shortcut :

@TargetApi(25)
private void delShortcut(){
Intent shortcut = new     Intent("com.android.launcher.action.UNINSTALL_SHORTCUT");
// Shortcut name
shortcut.putExtra(Intent.EXTRA_SHORTCUT_NAME, getString(R.string.app_name));
String appClass = this.getPackageName() + "." +this.getLocalClassName();
ComponentName comp = new ComponentName(this.getPackageName(), appClass);
shortcut.putExtra(Intent.EXTRA_SHORTCUT_INTENT, new Intent(Intent.ACTION_MAIN).setComponent(comp));
sendBroadcast(shortcut);
}

Best Practices :

• 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().

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.