App shortcuts to home screen

Depending on the Android launcher you might get a shortcut to your home screen automatically when you install a new application to your device. Shortcuts are a handy feature to increase the user engagement with your application and also open specific parts of the application quickly. That is, you can initiate a feature directly from a shortcut without going through all of the menus. This tutorial will show you how to create shortcuts to your application.

Basics

To install a shortcut to the home screen you first have to create the Intent which is called when the user presses on the shortcut.

When the intent is done, then you create an ShortcutInfoCompat and pass it to the ShortcutManagerCompat which sends the request to the Android operating system.

Example

package com.tanelikorri.android.shortcuts;

import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.view.View;
import android.widget.Toast;

import androidx.appcompat.app.AppCompatActivity;
import androidx.core.content.pm.ShortcutInfoCompat;
import androidx.core.content.pm.ShortcutManagerCompat;
import androidx.core.graphics.drawable.IconCompat;

public class ShortcutActivity extends AppCompatActivity {

    private static final String DATA = "tanelikorri://shortcut";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_shortcut);

        // Check if the app was started from the shortcut
        if (DATA.equals(getIntent().getDataString())) {
            Toast.makeText(this, "App started from shortcut",
                    Toast.LENGTH_SHORT).show();
        }
    }

    /**
     * This method creates the shortcut Intent which is fired when the user
     * presses the icon on the home screen
     *
     * @return Shortcut Intent
     */
    private Intent createShortcutIntent() {
        Intent intent = new Intent(this, ShortcutActivity.class);
        intent.setAction(Intent.ACTION_MAIN);
        // Include data to know when the app is started from the shortcut
        intent.setData(Uri.parse(DATA));

        return intent;
    }

    /**
     * onClick handler for install button
     *
     * @param view
     */
    public void onInstallShortcutClick(View view) {

        // Get the shortcut intent
        final Intent sIntent = createShortcutIntent();

        if (ShortcutManagerCompat.isRequestPinShortcutSupported(this)) {
            ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(this, "id")
                    // Shortcut label
                    .setShortLabel("Example shortcut")
                    // Shortcut icon
                    .setIcon(IconCompat.createWithResource(this, R.mipmap.ic_launcher))
                    .setIntent(sIntent)
                    .build();
            ShortcutManagerCompat.requestPinShortcut(this, shortcut, null);
        } else {
            Toast.makeText(this, R.string.shortcut_not_supported, Toast.LENGTH_LONG).show();
        }
    }
}

Install

The shortcut install is triggered when the user pressed the install button on the example application. The onInstallShortcutClick function is set as the onClick handler for the button, so the function is executed.

In order to install a shortcut a start intent is needed. This intent is sent when the user presses the shortcut icon on the home screen. In the above example application the shortcut intent creation is done in the createShortcutIntent method. The intent itself is pretty standard. The Activity class is attached and the action is set to ACTION_MAIN. In addition a data uri is added to the intent, but more on this later.

Now the shortcut intent is ready and we need to create ShortcutInfoCompat instance with the shortcut information and pass that to the ShortcutManagerCompat.requestPinShortcut(). The ShortcutInfoCompat instance is created with the ShortcutInfoCompat.Builder. With the builder you can set the shortcut labels, icon and the shortcut intent.

The created ShortcutInfoCompat instance is then passed to ShortcutManagerCompat.requestPinShortcut which requests the Android operating system to add a shortcut.

Uninstall

Previous version of Android had the ability to uninstall installed shortcuts programmatically. This support was removed in 2015 due to its being too flaky, i.e. app could remove any shortcut not only its own.

Start from shortcut

The one extra thing I mentioned earlier was the data added to the shortcut Intent. This enables us to identify when the application was openened from the home screen shortcut.

To achieve this, I added a check to the Activity onCreate method where I check if the Intent data matches with shortcut Intent data. If it does, a Toast is shown to the user.

This allows the developer to add deep links to the application. You can create shortcut to an Activity and start an operation based on the included data.

Screenshots

Source code

Source code for the whole example project is available here

Further reading

• ShortcutManagerCompat | Android Developers