Notification

Visual, audible, and tactile device notifications.

Permissions

Android

app/res/xml/plugins.xml

<plugin name="Notification" value="org.apache.cordova.Notification"/>

app/AndroidManifest.xml

<uses-permission android:name="android.permission.VIBRATE" />

Bada

manifest.xml

<Privilege>
    <Name>SYSTEM_SERVICE</Name>
</Privilege>

BlackBerry WebWorks

www/plugins.xml

<plugin name="Notification" value="org.apache.cordova.notification.Notification" />

www/config.xml

<feature id="blackberry.ui.dialog" />

iOS

App/Supporting Files/Cordova.plist

<key>Plugins</key>
<dict>
    <key>Notification</key>
    <string>CDVNotification</string>
</dict>

webOS

No permissions are required.

Windows Phone

No permissions are required.

notification.alert

Shows a custom alert or dialog box.

navigator.notification.alert(message, alertCallback, [title], [buttonName])

message: Dialog message (String)
alertCallback: Callback to invoke when alert dialog is dismissed. (Function)
title: Dialog title (String) (Optional, Default: "Alert")
buttonName: Button name (String) (Optional, Default: "OK")

Description

Most Cordova implementations use a native dialog box for this feature. However, some platforms simply use the browser's alert function, which is typically less customizable.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )
Bada 1.2 & 2.x
webOS

Quick Example

// Android / BlackBerry WebWorks (OS 5.0 and higher) / iPhone
//
function alertDismissed() {
    // do something
}

navigator.notification.alert(
    'You are the winner!',  // message
    alertDismissed,         // callback
    'Game Over',            // title
    'Done'                  // buttonName
);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Notification Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova is ready
    //
    function onDeviceReady() {
        // Empty
    }

    // alert dialog dismissed
    function alertDismissed() {
        // do something
    }

    // Show a custom alert
    //
    function showAlert() {
        navigator.notification.alert(
            'You are the winner!',  // message
            alertDismissed,         // callback
            'Game Over',            // title
            'Done'                  // buttonName
        );
    }

    </script>
  </head>
  <body>
    <p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
  </body>
</html>

Windows Phone 7 Quirks

Ignores button names, always uses 'OK'
There is no built in browser alert, so if you want to just write alert('foo'); you can assign window.alert = navigator.notification.alert;
alert + confirm calls are non-blocking, and result is only available asyncronously.

notification.confirm

Shows a customizable confirmation dialog box.

navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])

message: Dialog message (String)
confirmCallback: - Callback to invoke with index of button pressed (1, 2 or 3). (Function)
title: Dialog title (String) (Optional, Default: "Confirm")
buttonLabels: Comma separated string with button labels (String) (Optional, Default: "OK,Cancel")

Description

Function notification.confirm displays a native dialog box that is more customizable than the browser's confirm function.

confirmCallback

The confirmCallback is called when the user has pressed one of the buttons on the confirmation dialog box.

The callback takes the argument buttonIndex (Number), which is the index of the pressed button. It's important to note that the index uses one-based indexing, so the value will be 1, 2, 3, etc.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )
Bada 1.2 & 2.x

Quick Example

// process the confirmation dialog result
function onConfirm(buttonIndex) {
    alert('You selected button ' + buttonIndex);
}

// Show a custom confirmation dialog
//
function showConfirm() {
    navigator.notification.confirm(
        'You are the winner!',  // message
        onConfirm,              // callback to invoke with index of button pressed
        'Game Over',            // title
        'Restart,Exit'          // buttonLabels
    );
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Notification Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova is ready
    //
    function onDeviceReady() {
        // Empty
    }

    // process the confirmation dialog result
    function onConfirm(buttonIndex) {
        alert('You selected button ' + buttonIndex);
    }

    // Show a custom confirmation dialog
    //
    function showConfirm() {
        navigator.notification.confirm(
            'You are the winner!',  // message
            onConfirm,              // callback to invoke with index of button pressed
            'Game Over',            // title
            'Restart,Exit'          // buttonLabels
        );
    }

    </script>
  </head>
  <body>
    <p><a href="#" onclick="showConfirm(); return false;">Show Confirm</a></p>
  </body>
</html>

Windows Phone 7 Quirks

Ignores button names, always 'OK|Cancel'.
There is no built-in browser function for window.confirm
- You can bind window.confirm by assigning window.confirm = navigator.notification.confirm;.
Calls to alert and confirm are non-blocking and result is only available asyncronously.

Bada 2.x Quirks

confirm uses the browser's built-in alert function.

Bada 1.2 Quirks

Ignore button names, always 'OK|Cancel'.

notification.beep

The device will play a beep sound.

navigator.notification.beep(times);

times: The number of times to repeat the beep (Number)

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )
Bada 1.2 & 2.x

Quick Example

// Beep twice!
navigator.notification.beep(2);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Notification Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova is ready
    //
    function onDeviceReady() {
        // Empty
    }

    // Show a custom alert
    //
    function showAlert() {
        navigator.notification.alert(
            'You are the winner!',  // message
            'Game Over',            // title
            'Done'                  // buttonName
        );
    }

    // Beep three times
    //
    function playBeep() {
        navigator.notification.beep(3);
    }

    // Vibrate for 2 seconds
    //
    function vibrate() {
        navigator.notification.vibrate(2000);
    }

    </script>
  </head>
  <body>
    <p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
    <p><a href="#" onclick="playBeep(); return false;">Play Beep</a></p>
    <p><a href="#" onclick="vibrate(); return false;">Vibrate</a></p>
  </body>
</html>

Android Quirks

Android plays the default "Notification ringtone" specified under the "Settings/Sound & Display" panel.

iPhone Quirks

Ignores the beep count argument.
There is no native beep API for iPhone.
- Cordova implements beep by playing an audio file via the media API.
- The user must provide a file with the desired beep tone.
- This file must be less than 30 seconds long, located in the www/ root, and must be named beep.wav.

Windows Phone 7 Quirks

WP7 Cordova lib includes a generic beep file that is used.

notification.vibrate

Vibrates the device for the specified amount of time.

navigator.notification.vibrate(milliseconds)

time: Milliseconds to vibrate the device. 1000 milliseconds equals 1 second (Number)

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7
Bada 1.2 & 2.x

Quick Example

// Vibrate for 2.5 seconds
//
navigator.notification.vibrate(2500);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Notification Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for Cordova to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova is ready
    //
    function onDeviceReady() {
        // Empty
    }

    // Show a custom alert
    //
    function showAlert() {
        navigator.notification.alert(
            'You are the winner!',  // message
            'Game Over',            // title
            'Done'                  // buttonName
        );
    }

    // Beep three times
    //
    function playBeep() {
        navigator.notification.beep(3);
    }

    // Vibrate for 2 seconds
    //
    function vibrate() {
        navigator.notification.vibrate(2000);
    }

    </script>
  </head>
  <body>
    <p><a href="#" onclick="showAlert(); return false;">Show Alert</a></p>
    <p><a href="#" onclick="playBeep(); return false;">Play Beep</a></p>
    <p><a href="#" onclick="vibrate(); return false;">Vibrate</a></p>
  </body>
</html>

iPhone Quirks

time: Ignores the time and vibrates for a pre-set amount of time.

navigator.notification.vibrate();
navigator.notification.vibrate(2500);   // 2500 is ignored

Notification

API Reference

Guides

Android

app/res/xml/plugins.xml

app/AndroidManifest.xml

Bada

manifest.xml

BlackBerry WebWorks

www/plugins.xml

www/config.xml

iOS

App/Supporting Files/Cordova.plist

webOS

Windows Phone