/ Author Introduction /
This article is contributed by Xiaweizi, sharing the development of desktop shortcuts, which I believe will be helpful to everyone! Thanks to the author for the wonderful article.
Xiaweizi’s blog address:
http://xiaweizi.cn/
/ Introduction /
The Shortcuts feature was introduced with Android 7.1 Nougat, mainly aimed at allowing users to define some common operation paths in the form of shortcuts. These shortcuts are displayed on supported devices, helping users quickly launch commonly used or recommended pages and actions.
Recently, there has been a demand for developing related shortcuts, so I summarized it here, hoping it can help everyone.
/ Overview /
Shortcuts generally exist in two ways:
One way is by long-pressing the application icon, which will pop up a list window displaying the operation paths that need to be executed. For applications without configured shortcuts, it usually only shows entry points for sharing or application information (different phones may display differently). If the application is configured with shortcuts, then the corresponding shortcut entry will be displayed in the list.
As shown in the image above, the difference between configured and non-configured shortcuts lies in whether custom shortcut entries are configured in the list.
The other way is in the form of desktop shortcuts, where the same action can have multiple identical desktop shortcuts.
As shown in the image above, for Chrome – Open New Tab, there can be multiple identical desktop shortcuts.
Types of Shortcuts
Each shortcut can carry one or more intents. When the user clicks on the shortcut, each intent will trigger the corresponding action in the application. Generally, the type of shortcut created depends on the specific form of the shortcut and what kind of behavior you want to assign to it. You can refer to the following examples:
-
In a weather application, wanting to view the trend of the weather for the past few days
-
In an email application, wanting to create a new email
-
In a map application, locating a specific position
-
In a chat application, sending a message to a specific friend
-
In a media application, playing the next episode of a TV show
-
In a game application, loading the last saved point of the game
You can publish the following types of shortcuts for your application
-
Static Shortcuts: These are directly packaged into the apk or apk bundle, and the shortcut entry exists once the application is installed.
-
Dynamic Shortcuts: These are created only when the application is running and can be updated, added, or deleted at any time.
-
Desktop Shortcuts: These can be actively added to the desktop with user authorization, and can also copy dynamic and static shortcuts to the desktop.
Shortcut Restrictions
Although an application can generally create five shortcuts, including static and dynamic, most devices can only display four.
However, there are no restrictions on desktop shortcuts, but desktop shortcuts cannot be removed unless the user actively deletes them; they can only be disabled to make the shortcut ineffective.
/ Usage /
Shortcuts can help users quickly access commonly used paths and pages, thus providing specific types of content for users.
Choosing Shortcut Types
How to choose the type of shortcut depends on whether your shortcut is application-driven or user-driven. Although static shortcut intents cannot be changed, dynamic ones can, but both belong to application-driven. If users want to customize their desired intent and present it in the form of desktop shortcuts, then this is user-driven.
How to understand this? Let’s take the example of JianShu:
Static Shortcuts: These are most suitable for those intents that do not change throughout the lifecycle of the program, completing the same action. Since the program can generally only display four shortcuts, static shortcuts are usually very useful and necessary for commonly used behaviors.
For example, in the image above, the “Search” entry in JianShu is quite common and does not require passing parameters or the parameters do not change, so it is recommended to use a static shortcut.
Dynamic Shortcuts: These are generally for operations that are sensitive to intents. The intent may change during the application run, and the shortcut needs to be updated.
For example, in JianShu, the entry for “My Public Articles” may switch accounts for multi-account reasons, and the parameters carried by the page to jump will change, so this requires using a dynamic shortcut.
Desktop Shortcuts: These allow users to customize jump intents.
For example, JianShu supports creating shortcuts to the desktop for followed individuals, allowing direct access to that person’s dynamic information next time, which is entirely user-initiated creation, so desktop shortcuts are used.
Creating Shortcuts
With the above types described, the following provides examples of creating these three types of shortcuts.
Creating Static Shortcuts
Static shortcuts provide common jumps within the application, which generally remain unchanged throughout the program’s lifecycle.
Complete the creation of static shortcuts through the following steps:
-
In AndroidManifest.xml, find the Activity configured with android.intent.action.MAIN and android.intent.category.LAUNCHER.
-
Add <meta-data> element to the Activity
<activity android:name=".MainActivity">
<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>
Create a new resource file: res/xml/shortcuts.xml
<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<shortcut
android:enabled="true"
android:icon="@drawable/add"
android:shortcutDisabledMessage="@string/static_disabled_message"
android:shortcutId="staticId"
android:shortcutLongLabel="@string/static_shortcut_long_label"
android:shortcutShortLabel="@string/static_shortcut_short_label">
<intent
android:action="android.intent.action.VIEW"
android:data="content://xiaweizi.com/fromStaticShortcut"
android:targetClass="com.example.xiaweizi.shortcutsdemo.TestActivity"
android:targetPackage="com.example.xiaweizi.shortcutsdemo" />
<categories android:name="android.shortcut.conversation" />
</shortcut>
</shortcuts>
The specific parameter configuration is explained as follows:
If there is data to be passed, there should be corresponding parsing
if (getIntent().getData() != null && TextUtils.equals(getIntent().getAction(), Intent.ACTION_VIEW)) {
Uri uri = getIntent().getData();
List<String> pathSegments = uri.getPathSegments();
if (pathSegments != null && pathSegments.size() > 0) {
tvTest.setText(pathSegments.get(0));
}
}
Final Running Effect:
Creating Dynamic Shortcuts
Dynamic shortcuts provide specific jumps or data passing within the application, which may change during application execution.
At this time, you need to use the API provided by ShortcutManager to perform corresponding operations for dynamic shortcuts:
-
Creating: Use setDynamicShortcuts() to redefine the complete list of dynamic shortcuts
-
Adding: Use addDynamicShortcut() to expand the existing dynamic shortcut list
-
Updating: Use updateShortcuts() method to update the existing dynamic shortcut list
-
Deleting: Use removeDynamicShortcuts() to remove a group of dynamic shortcuts, or use removeAllDynamicShortcuts() to remove all dynamic shortcuts
Taking creation as an example, the others are similar, please try it yourself, and refer to the code below for specific operations:
1. Create ShortcutInfo object
@TargetApi(Build.VERSION_CODES.N_MR1)
private ShortcutInfo createShortcutInfo1() {
return new ShortcutInfo.Builder(this, ID_DYNAMIC_1)
.setShortLabel(getString(R.string.dynamic_shortcut_short_label1))
.setLongLabel(getString(R.string.dynamic_shortcut_long_label1))
.setIcon(Icon.createWithResource(this, R.drawable.add))
.setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("http://xiaweizi.cn/")))
.build();
}
2. Call setDynamicShortcuts() to overwrite the previous one and reset the new dynamic shortcut list
private void setDynamicShortcuts() {
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.N_MR1) {
ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
List<ShortcutInfo> shortcutInfo = new ArrayList<>();
shortcutInfo.add(createShortcutInfo1());
shortcutInfo.add(createShortcutInfo2());
if (shortcutManager != null) {
shortcutManager.setDynamicShortcuts(shortcutInfo);
}
}
}
3. You can configure the font color of the label
@TargetApi(Build.VERSION_CODES.N_MR1)
private ShortcutInfo createShortcutInfo2() {
Intent intent = new Intent(this, TestActivity.class);
intent.setAction(Intent.ACTION_VIEW);
intent.putExtra("key", "fromDynamicShortcut");
ForegroundColorSpan colorSpan = new ForegroundColorSpan(Color.BLUE);
String label = getResources().getString(R.string.dynamic_shortcut_short_label2);
SpannableStringBuilder colouredLabel = new SpannableStringBuilder(label);
colouredLabel.setSpan(colorSpan, 0, label.length(), Spanned.SPAN_INCLUSIVE_INCLUSIVE);
return new ShortcutInfo.Builder(this, ID_DYNAMIC_2)
.setShortLabel(colouredLabel)
.setLongLabel(getString(R.string.dynamic_shortcut_long_label2))
.setIcon(Icon.createWithResource(this, R.drawable.link))
.setIntent(intent)
.build();
}
Final Running Effect:
Creating Desktop Shortcuts
In Android 8.0 (API 26) or higher, you can create desktop shortcuts. Unlike static and dynamic shortcuts, desktop shortcuts support separate icons displayed on the device.
If you want to create desktop shortcuts, follow these steps:
-
Use isRequestPinShortcutSupported() to verify if the device supports creating desktop shortcuts for the application
-
Depending on whether the shortcut already exists, create a ShortcutInfo object using one of the two methods:
-
If the shortcut already exists, create a ShortcutInfo object that only contains the existing shortcut id, and the system will automatically find and bring all related data associated with the shortcut
-
If you want to pin a new shortcut, create a ShortcutInfo object that contains the new shortcut id, intent, and short label
-
Try to pin the shortcut to the device desktop by calling requestPinShortcut(). During this process, a pendingIntent object can be passed in, which will notify the application only when the shortcut is successfully pinned.
Refer to the code below for specifics:
private void createPinnedShortcuts() {
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
if (shortcutManager != null && shortcutManager.isRequestPinShortcutSupported()) {
Intent intent = new Intent(this, TestActivity.class);
intent.setAction(Intent.ACTION_VIEW);
intent.putExtra("key", "fromPinnedShortcut");
ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(this, "my-shortcut")
.setShortLabel(getString(R.string.pinned_shortcut_short_label2))
.setLongLabel(getString(R.string.pinned_shortcut_long_label2))
.setIcon(Icon.createWithResource(this, R.drawable.add))
.setIntent(intent)
.build();
Intent pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo);
PendingIntent successCallback = PendingIntent.getBroadcast(this, 0,
pinnedShortcutCallbackIntent, 0);
boolean b = shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.getIntentSender());
Utils.showToast(this, "set pinned shortcuts " + (b ? "success" : "failed") + "!");
}
}
}
Final Running Effect:
Alright, this concludes the basic introduction to using shortcuts, and I believe you now have a certain understanding of the usage scenarios and specific implementations of shortcuts. Next, let’s start discussing advanced usage.
/ Advanced Usage of Shortcuts /
Once shortcuts are created, you may also need to manage them, such as dynamically updating or disabling certain shortcuts, at which point you need to understand some advanced usage.
Removing Shortcuts
For static shortcuts, since they are initially packaged into the apk or apk bundle, they cannot be changed unless a new version is released to overwrite the previous shortcuts; otherwise, they will always exist.
For dynamic shortcuts, since they can be created in code, they can also be removed in code, which has been introduced earlier.
As for desktop shortcuts, they are directly displayed on the desktop and are always visible; they can only be deleted under the following circumstances:
-
User actively removes them
-
Uninstalling the application associated with the shortcut
-
User clears all cached data in the application information
Shortcut Display Order
For all shortcuts of an application, the display rules are as follows:
-
Static Shortcuts: isDeclaredInManifest() returns true for shortcuts
-
Dynamic Shortcuts: ShortcutInfo.isDynamic() returns true for shortcuts
Within each type of shortcut, they will be sorted in ascending order according to ShortcutInfo.getRank(). The rank is a non-negative, consecutive integer, and you can update the ranks of existing shortcuts when calling updateShortcuts(List), addDynamicShortcuts(List), or setDynamicShortcuts(List).
The ranks are automatically adjusted, so they are unique for each type of shortcut. For example, if there are three dynamic shortcuts with ranks of 0, 1, and 2, and then a new dynamic shortcut with a rank of 1 is added, the last two will shift one position, and their ranks will become 2 and 3.
Shortcut Intents Configuration
If you want the application to perform multiple actions when the user activates a shortcut, you can configure it to trigger multiple activities. You can do this by assigning multiple intents, starting one activity to another, depending on the type of your shortcut.
When creating shortcuts using ShortcutInfo.Builder, you can use setIntents() instead of setIntent(). By calling setIntents(), you can trigger multiple activities when the user clicks the shortcut, placing all activities except the last one in the subsequent stack. If the back button is pressed at this time, the activities will be displayed in the order they were stored in the stack, rather than directly returning to the home page.
For example, configure multiple intents as follows:
@TargetApi(Build.VERSION_CODES.N_MR1)
private ShortcutInfo createShortcutInfo1() {
Intent intent1 = new Intent(Intent.ACTION_VIEW, Uri.parse("http://xiaweizi.cn/"));
Intent intent = new Intent(this, TestActivity.class);
intent.setAction(Intent.ACTION_VIEW);
intent.putExtra("key", "fromDynamicShortcut");
return new ShortcutInfo.Builder(this, ID_DYNAMIC_1)
.setShortLabel(getString(R.string.dynamic_shortcut_short_label1))
.setLongLabel(getString(R.string.dynamic_shortcut_long_label1))
.setIcon(Icon.createWithResource(this, R.drawable.add))
.setIntents(new Intent[]{intent, intent1})
.build();
}
Then it will trigger intent and intent1 once; at this time, intent will be pushed to the bottom of the intent1 stack, and clicking back will display intent’s information. As shown in the image:
Another issue is that static shortcuts cannot have custom intent flags; static shortcuts are always set to Intent.FLAG_ACTIVITY_NEW_TASK and Intent.FLAG_ACTIVITY_CLEAR_TASK, which means that when the static shortcut is launched while the application is already running, all activities in the application will be destroyed.
If you do not want this to happen, you can use a trampoline activity or start an invisible activity in Activity.onCreate(Bundle) and then call Activity.finish().
-
In AndroidManifest.xml, set android:taskAffinity=”” for the trampoline activity.
-
In the shortcut resource file, the intent in the static shortcut should reference the trampoline activity.
Updating Pinned Shortcuts
Each application can contain at most getMaxShortcutCountPerActivity() shortcuts, including both dynamic and static in total. However, there is no limit on the number of desktop shortcuts.
When dynamic shortcuts are placed on the desktop, even if the dynamic shortcut is removed in the code, the desktop shortcuts will still exist; therefore, desktop shortcuts are not limited by getMaxShortcutCountPerActivity.
Assuming the value of getMaxShortcutCountPerActivity() is 4:
-
The chat application publishes four dynamic shortcuts, representing the four most recent conversations (c1, c2, c3, c4)
-
The user copies all the shortcuts to the desktop
-
Then the user launches three additional recent conversations (c5, c6, and c7), which re-publishes the updated dynamic shortcuts, making the new shortcut list: c4, c5, c6, and c7. The application must remove c1, c2, and c3 since it can only display four shortcuts, but the three shortcuts already saved on the desktop can be accessed normally.
The user can now actually access a total of seven shortcuts, including four maximum dynamic shortcuts and three desktop shortcuts.
-
The application can use updateShortcuts(List) to update any of the seven shortcuts.
-
Using addDynamicShortcuts() and setDynamicShortcuts() can also update shortcut objects with the same shortcutId, but they cannot update non-dynamic shortcuts.
System Settings Changes
Changes in system settings, such as modifying the system language, cannot dynamically update shortcuts. At this time, you need to create a broadcast listener for Intent.ACTION_LOCALE_CHANGED, and when the broadcast is received, update the shortcuts to ensure there are no issues with the shortcut display.
Before handling:
After handling:
Tracking Shortcuts
To determine how static and dynamic shortcuts appear, each startup will check the activation history of the shortcuts. You can call the reportShortcutUsed() method passing in its shortcutId to improve the response speed of the action.
Shortcut Frequency Limitations
When using setDynamicShortcuts(), addDynamicShortcuts(), and updateDynamicShortcuts() methods, note that there may be a fixed limit on the number of times you can call these methods in the background; this limit is known as rate limiting. This feature is used to prevent the ShortcutManager from excessively consuming device resources.
When in rate limiting, isRateLimitingActive() returns true, but certain operations executed will reset this value, so even in background applications, you can call shortcutManager methods until you reach the rate limit again. These operations include:
-
The application returns to the foreground
-
Changes in system regional settings
-
User processes embedded interactive operations in the notification bar
If you encounter a limit on the number of calls during development or testing, you can reset the ShortcutManager call frequency limit in Developer Options -> Reset ShortcutsManager calling frequency limit. Or use the adb command
adb shell cmd shortcut reset-throttling [ --user your-user-id ]
/ Recommendations /
When designing and creating shortcuts, please follow the following recommendations:
Follow Design Guidelines
To ensure that the application’s shortcuts visually align with those used by system applications, please follow the shortcut design guidelines.
Only Publish Four Different Shortcuts
Although the API currently supports a maximum of five shortcuts (static and dynamic) for any application, it is still recommended to only publish four different shortcuts to improve the visual effect on the device.
Limit Shortcut Description Length
Shortcut menu space is limited, and when displaying applications on the desktop, this factor needs to be considered. If possible, limit the length of the shortcut’s shortLabel to 10 characters and the longLabel to 25 characters.
Record Shortcut and Its Action History
For each created shortcut, consider whether users can complete the same task in different ways within the application. Remember to call reportShortcutUsed() so that the launcher can improve the response speed of actions corresponding to the shortcut.
Update Only When the Meaning of Shortcuts Exists
When changing dynamic shortcuts, only call the updateShortcuts() method to change its information when the shortcut still maintains its meaning; otherwise, you should use addDynamicShortcuts() or setDynamicShortcuts() to create a shortcut with a new meaning and shortcutId.
For example, if we have created a shortcut to navigate to a supermarket, if the name of the supermarket changes but the location does not, it is appropriate to only update the information. However, if the user starts shopping at a supermarket in a different location, it is better to create a new shortcut.
Check Shortcuts Every Time the APP is Opened
During backup or restoration, dynamic shortcuts will not be saved; for this reason, it is recommended to check the number of objects in getDynamicShortcuts() when the APP starts and re-publish dynamic shortcuts.
Demo address:
https://github.com/xiaweizi/ShortcutsDemo
Official Demo:
https://github.com/googlesamples/android-AppShortcuts
Official Documentation:
https://developer.android.com/guide/topics/ui/shortcuts
Recommended Reading Explore the CameraX on Android platform, Lottie implementation behind cool animations, talk about my writing skills
Programming · Thinking · Career Welcome to scan and follow
Looking is also a form of recognition