Catch back button and exit PhoneGap application

This article shows an example, how to respond, when user of your mobile application taps on Back button and how to exit application, after getting user confirmation, that he or she is willing to do so. It also explains, why you shouldn't do it at all, if you plan to ship your application to multiple platforms, including Apple iOS.

You catch back button being press as every other ordinary PhoneGap event -- i.e. by adding proper event listener to your application's device ready event:

document.addEventListener("backbutton", app.backButtonHandler, true);

In referenced function you can implement some sort of question, veryfing, that user really wants to exit:

backButtonHandler: function()
{
    navigator.notification.confirm
    (
        'Are you sure, you want to exit?', //Message body.
        app.onExitConfirm, //Callback after button is tapped.
        'Exit application?', //Message title.
        'Exit,Stay'//Buttons -- Will be shown in reversed order!
    );
}

Finally, declare another function, which you reference in above code, that will handle user input:

onExitConfirm: function(button)
{
    if (button == 1) navigator.app.exitApp();
}

Then entire code could look like this:

var app = 
{
    init: function()
    {
        document.addEventListener('deviceready', app.deviceReadyHandler, false);
    },

    deviceReadyHandler: function()
    {
        document.addEventListener("backbutton", app.backButtonHandler, true);
    },

    backButtonHandler: function()
    {
        navigator.notification.confirm
        (
            'Are you sure, you want to exit?', // message
            app.onExitConfirm, // callback to invoke with index of button pressed
            'Exit application?', // title
            'Yes,No'// buttonLabels
        );
    },

    onExitConfirm: function(button)
    {
        if (button == 1) navigator.app.exitApp();
    }
};

app.init();

As you can see, navigator.app.exitApp() is all you need to force exit of your application.

However, on some certain systems (like iOS), you should not force application exit programmatically! You have to have a really good reasons for that and be prepared that 9 times out of 10 Apple Store will refuse to publish your application, if it find programmatic application exit in it.

This topic is covered for example in StackOverflow], Google Groups or in iOS Human Interface Guidelines (page 65 -- section "Don’t Quit Programmatically").

This is reasonable, as on most mobile platforms, an application left by user, by pressing Back or Home is put to suspend (not even in background). It uses a very small amount of resources, so does not slows down other applications or the system itself. And is quite faster to restore, once user takes any steps to go back to it.

So consider programmatic application exit only, if you're developing an internal project or you target mobile platform that are not so strict in this as iOS (for example -- Android).

Leave a Reply