How to create a shortcut on the Home Screen on Android with Phone Gap

Home Shortcuts

This is the plugin to create/delete Shortcuts (Android) in Apache Cordova/PhoneGap!

The Shortcut plugin for Apache Cordova allows you to create or delete the shortcut in the home of any andorid device.

Usage Instructions

Add the following xml to your config.xml to always use the latest version of this plugin:

<gap:plugin name="com.plugins.shortcut" />

or to use this exact version:

<gap:plugin name="com.plugins.shortcut" version="0.1.1" />

Docs

Documentation for this plugin can be viewed here.

Android Install/Uninstall Shortcut Example

Nowadays many android apps installs a shortcut on home screen when you install the app and run it for the first time. This is a nice strategy to engage user by compiling them to use your app. Most of times when a user install an app, the app is deep buried in list of apps making it almost difficult to discover. So its always a good idea to make a shortcut right on home screen.

Android comes with simple yet undocumented API to add and remove shortcuts of any app on home screen. Let us check how to do this.

1. Install Shortcut on Home screen

Android provide us an intent class com.android.launcher.action.INSTALL_SHORTCUT which can be used to add shortcuts to home screen. In following code snippet we create a shortcut of activity MainActivitywith the name HelloWorldShortcut.

First we need to add permission INSTALL_SHORTCUT to android manifest xml.

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

The addShortcut() method create a new shortcut on Home screen.

private void addShortcut() {
    //Adding shortcut for MainActivity
    //on Home screen
    Intent shortcutIntent = new Intent(getApplicationContext(),
            MainActivity.class);
    
    shortcutIntent.setAction(Intent.ACTION_MAIN);
    Intent addIntent = new Intent();
    addIntent
            .putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);
    addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "HelloWorldShortcut");
    addIntent.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,
            Intent.ShortcutIconResource.fromContext(getApplicationContext(),
                    R.drawable.ic_launcher));
    addIntent
            .setAction("com.android.launcher.action.INSTALL_SHORTCUT");
    getApplicationContext().sendBroadcast(addIntent);
}

Note how we create shortcutIntent object which holds our target activity. This intent object is added into another intent as EXTRA_SHORTCUT_INTENT. Finally we broadcast the new intent. This adds a shortcut with name mentioned as
EXTRA_SHORTCUT_NAME and icon defined by EXTRA_SHORTCUT_ICON_RESOURCE.

Note: One thing worth noting here is when you define your activity that is invoked from shortcut, you must define android:exported=”true” attribute in <activity> tag. You’ll see this in our demo.

2. Uninstall Shortcut from Home screen

Similar to install, uninstalling or removing shortcut in Android uses an Intent (UNINSTALL_SHORTCUT) to perform the task. In following code we remove the shortcut added on home screen.

Again we need a permission to perform uninstall shortcut task. Add following permission to Android manifest xml.

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

The removeShortcut() method does exactly reverse of addShortcut(). Most of the code is similar except removeShortcut calls UNINSTALL_SHORTCUT intent.

private void removeShortcut() {
    
    //Deleting shortcut for MainActivity
    //on Home screen
    Intent shortcutIntent = new Intent(getApplicationContext(),
            MainActivity.class);
    shortcutIntent.setAction(Intent.ACTION_MAIN);
    
    Intent addIntent = new Intent();
    addIntent
            .putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);
    addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "HelloWorldShortcut");
    addIntent
            .setAction("com.android.launcher.action.UNINSTALL_SHORTCUT");
    getApplicationContext().sendBroadcast(addIntent);
}

Let us check the full functionality by creating a demo application.

3. Demo Application

The demo application is very simple. The user interface has two buttons: one to add shortcut to home screen and another to remove it.

Following is the simple layout consiting of two buttons.

layout/activity_main.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">
        
    <Button
        android:id="@+id/buttonAddShortcut"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Add Shortcut" />
    <Button
        android:id="@+id/buttonRemoveShortcut"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Remove Shortcut" />
    
</LinearLayout>

The layout looks something like following:
android_add_shortcut_demo

The MainAcitivity is the activity class that handles user interface events. We add OnClickListener event handlers to both Add and Remove shortcut buttons. Each calls appropriate method to perform the task.

MainActivity.java

package net.viralpatel.android;
import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
public class MainActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        //Add listener to add shortcut button
        Button add = (Button) findViewById(R.id.buttonAddShortcut);
        add.setOnClickListener(new OnClickListener() {
            
            @Override
            public void onClick(View v) {
                addShortcut(); //Add shortcut on Home screen
            }
        });
        
        //Add listener to remove shortcut button
        Button remove = (Button) findViewById(R.id.buttonRemoveShortcut);
        remove.setOnClickListener(new OnClickListener() {
            
            @Override
            public void onClick(View v) {
                removeShortcut(); //Remove shortcut from Home screen
            }
        });    
    }
    
    private void addShortcut() {
        //Adding shortcut for MainActivity
        //on Home screen
        Intent shortcutIntent = new Intent(getApplicationContext(),
                MainActivity.class);
        
        shortcutIntent.setAction(Intent.ACTION_MAIN);
        Intent addIntent = new Intent();
        addIntent
                .putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "HelloWorldShortcut");
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,
            Intent.ShortcutIconResource.fromContext(getApplicationContext(),
                        R.drawable.ic_launcher));
        addIntent
                .setAction("com.android.launcher.action.INSTALL_SHORTCUT");
        getApplicationContext().sendBroadcast(addIntent);
    }
    
    private void removeShortcut() {
        
        //Deleting shortcut for MainActivity
        //on Home screen
        Intent shortcutIntent = new Intent(getApplicationContext(),
                MainActivity.class);
        shortcutIntent.setAction(Intent.ACTION_MAIN);
        
        Intent addIntent = new Intent();
        addIntent
                .putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);
        addIntent.putExtra(Intent.EXTRA_SHORTCUT_NAME, "HelloWorldShortcut");
        addIntent
                .setAction("com.android.launcher.action.UNINSTALL_SHORTCUT");
        getApplicationContext().sendBroadcast(addIntent);
    }
    
}

Also following is the Android manifest file for reference.

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="net.viralpatel.android"
    android:versionCode="1"
    android:versionName="1.0" >
    <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="15" />
    
    <uses-permission
        android:name="com.android.launcher.permission.INSTALL_SHORTCUT" />
    <uses-permission
        android:name="com.android.launcher.permission.UNINSTALL_SHORTCUT" />
    
    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <activity
            android:name=".MainActivity"
            android:label="@string/title_activity_main"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
   </application>
</manifest>

Screenshots of App

On clicking Add Shortcut button a toast message appears saying the shortcut has been successfully added on home screen.
android_install_shortcut_success

If you check the home screen, you will find the shortcut present.
android_shortcut_home_screen

The remove shortcut button triggers UNINSTALL_SHORTCUT intent and removes the shortcut from home screen. It also prints a toast message with confirmation.
android_unistall_shortcut_demo

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s