PhoneGap notifications — early API reference

About this version

This page preserves the official documentation for Version 1.0.0. Commands, supported platforms and API behavior below belong to that historical version. For active projects, consult the current Apache Cordova documentation.

Reference sections

• Notification
• notification.alert
• notification.beep
• notification.confirm
• notification.vibrate

Notification

Visual, audible, and tactile device notifications.

Methods

• notification.alert
• notification.confirm
• notification.beep
• notification.vibrate

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 PhoneGap 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 (OS 4.6)
• BlackBerry WebWorks (OS 5.0 and higher)
• iPhone

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
);

// BlackBerry (OS 4.6) / webOS
//
navigator.notification.alert('You are the winner!');
    

Full Example

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

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

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

    // PhoneGap 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>

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 (OS 4.6)
• BlackBerry WebWorks (OS 5.0 and higher)
• iPhone

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="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // PhoneGap 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.
  • PhoneGap 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.

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). (Number)
• 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.

Supported Platforms

• Android
• BlackBerry WebWorks (OS 5.0 and higher)
• iPhone

Quick Example

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

// 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="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

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

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

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

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 (OS 4.6)
• BlackBerry WebWorks (OS 5.0 and higher)
• iPhone

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="phonegap-1.0.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // PhoneGap 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