App shortcuts to home screen

New versions of Android install automatically a shortcut to the home screen when the user installs an application. It’s a handy feature which adds the user engagement with the application. It’s also possible to add those shortcuts yourself and it’s also possible to create a deep link to your application, e.g. you can initiate a feature directly from a shortcut without going through all of the menus. This tutorial will show you how to achieve that.

Basics

To install and to uninstall a shortcut to the home screen you first have to create the Intent which is called when the user presses on the shortcut and then the intent and the required info is brodacasted to the operating system. The operating system will take care of adding and removing the icon to the home screen.

To be able to install shortcuts to the home screen you need to declare the INSTALL_SHORTCUT permission in the AndroidManifest.xml file:

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

Also to be able to uninstall shortcuts you need to have to UNINSTALL_SHORTCUT permission in the AndroidManifest.xml file:

<uses-permission android:name="com.android.launcher.permission.UNINSTALL_SHORTCUT" />

Example

package com.caphal.android.shortcuts;

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

public class ShortcutActivity extends Activity {

    private static final String DATA = "caphal://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
        Intent sIntent = createShortcutIntent();

        // Create intent for installing the shortcut
        Intent addIntent = new Intent();
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_INTENT, sIntent);
        // Set the name of the shortcut
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "Example shortcut");
        // Set the icon of the shortcut
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,
                Intent.ShortcutIconResource.fromContext(this,
                        R.drawable.ic_launcher));
        addIntent.setAction("com.android.launcher.action.INSTALL_SHORTCUT");

        // Send broadcast to install shortcut
        sendBroadcast(addIntent);
    }

    /**
     * onClickHandler for uninstall button
     * 
     * @param view
     */
    public void onUninstallShortcutClick(View view) {

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

        Intent addIntent = new Intent();
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_INTENT, sIntent);
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "Example shortcut");
        addIntent.setAction("com.android.launcher.action.UNINSTALL_SHORTCUT");

        // Send broadcast to uninstall shortcut
        sendBroadcast(addIntent);
    }
}

Install

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

In order to install a shortcut first a start intent is needed. This intent is sent when the user presses the shorcut 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 when we have the shortcut intent we need to create another intent. This intent is used to signal the operating system so that it will create the shortcut. The install intent takes the shortcut intent, shortcut name and shortcut icon as parameters. You also need to set the intent action to:

addIntent.setAction("com.android.launcher.action.INSTALL_SHORTCUT");

so that the operating system knows to install the shortcut. After sending the broadcast you should have a shortcut on the home screen.

Uninstall

Uninstall process is pretty much the same thing as installation. First you need the shortcut intent and the you need to send another intent with parameters to the operating system to uninstall the shortcut.

In the above example the uninstallation is triggered when the user presses the uninstall button. The onUninstallShortcutClick method is set as the button onClick handler.

We first call the same createShortcutIntent method to get an Intent with the same content as with the shortcut installation. This is important since the Intent has to have the some content as the Intent that was used when the shortcut was installed. Otherwise the operating system cannot remove the shortcut.

After getting the shortcut Intent, we send a broadcast with:

addIntent.setAction("com.android.launcher.action.UNINSTALL_SHORTCUT");

action to uninstall the installed shortcut. This should trigger a toast to the user that the shortcut was removed.

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

Main activity Shortcut installed Started from shortcut Shortcut removed

Source code

Source code for the whole example project is available here

Further reading

Comments

comments powered by Disqus