Accelerometer

Captures device motion in the x, y, and z direction.

Permissions

Android

app/res/xml/config.xml

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

BlackBerry WebWorks

www/plugins.xml

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

www/config.xml

<feature id="blackberry.system"  required="true" version="1.0.0.0" />
<feature id="org.apache.cordova" required="true" version="1.0.0" />

iOS

config.xml

<plugin name="Accelerometer" value="CDVAccelerometer" />

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_SENSORS" />
</Capabilities>

Reference: Application Manifest for Windows Phone

Tizen

No permissions are required.

accelerometer.getCurrentAcceleration

Get the current acceleration along the x, y, and z axes.

navigator.accelerometer.getCurrentAcceleration(accelerometerSuccess, accelerometerError);

Description

The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current device orientation, in three dimensions along the x, y, and z axis.

These acceleration values are returned to the accelerometerSuccess callback function.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Tizen
Windows Phone 7 and 8
Windows 8

Quick Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
};

function onError() {
    alert('onError!');
};

navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);

Full Example

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

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

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

    // device APIs are available
    //
    function onDeviceReady() {
        navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);
    }

    // onSuccess: Get a snapshot of the current acceleration
    //
    function onSuccess(acceleration) {
        alert('Acceleration X: ' + acceleration.x + '\n' +
              'Acceleration Y: ' + acceleration.y + '\n' +
              'Acceleration Z: ' + acceleration.z + '\n' +
              'Timestamp: '      + acceleration.timestamp + '\n');
    }

    // onError: Failed to get the acceleration
    //
    function onError() {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>getCurrentAcceleration</p>
  </body>
</html>

iOS Quirks

iOS doesn't recognize the concept of getting the current acceleration at any given point.
You must watch the acceleration and capture the data at given time intervals.
Thus, the getCurrentAcceleration function yields the last value reported from a watchAccelerometer call.

accelerometer.watchAcceleration

At a regular interval, get the acceleration along the x, y, and z axis.

var watchID = navigator.accelerometer.watchAcceleration(accelerometerSuccess,
                                                       accelerometerError,
                                                       [accelerometerOptions]);

Description

The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current position. The accelerometer can detect 3D movement along the x, y, and z axis.

The accelerometer.watchAcceleration method retrieves the device's current Acceleration at a regular interval, executing the accelerometerSuccess callback function each time. Specify the interval in milliseconds via the acceleratorOptions object's frequency parameter.

The returned watch ID references the accelerometer's watch interval, and can be used with accelerometer.clearWatch to stop watching the accelerometer.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Tizen
Windows Phone 7 and 8
Windows 8

Quick Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
};

function onError() {
    alert('onError!');
};

var options = { frequency: 3000 };  // Update every 3 seconds

var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

Full Example

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

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

    // The watch id references the current `watchAcceleration`
    var watchID = null;

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

    // device APIs are available
    //
    function onDeviceReady() {
        startWatch();
    }

    // Start watching the acceleration
    //
    function startWatch() {

        // Update acceleration every 3 seconds
        var options = { frequency: 3000 };

        watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
    }

    // Stop watching the acceleration
    //
    function stopWatch() {
        if (watchID) {
            navigator.accelerometer.clearWatch(watchID);
            watchID = null;
        }
    }

    // onSuccess: Get a snapshot of the current acceleration
    //
    function onSuccess(acceleration) {
        var element = document.getElementById('accelerometer');
        element.innerHTML = 'Acceleration X: ' + acceleration.x         + '<br />' +
                            'Acceleration Y: ' + acceleration.y         + '<br />' +
                            'Acceleration Z: ' + acceleration.z         + '<br />' +
                            'Timestamp: '      + acceleration.timestamp + '<br />';
    }

    // onError: Failed to get the acceleration
    //
    function onError() {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <div id="accelerometer">Waiting for accelerometer...</div>
  </body>
</html>

iOS Quirks

The API calls the success callback function at the interval requested, but restricts the range of requests to the device between 40ms and 1000ms. For example, if you request an interval of 3 seconds, (3000ms), the API requests data from the device every 1 second, but only executes the success callback every 3 seconds.

accelerometer.clearWatch

Stop watching the Acceleration referenced by the watchID parameter.

navigator.accelerometer.clearWatch(watchID);

watchID: The ID returned by accelerometer.watchAcceleration.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Tizen
Windows Phone 7 and 8
Windows 8

Quick Example

var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

// ... later on ...

navigator.accelerometer.clearWatch(watchID);

Full Example

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

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

    // The watch id references the current `watchAcceleration`
    var watchID = null;

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

    // device APIs are available
    //
    function onDeviceReady() {
        startWatch();
    }

    // Start watching the acceleration
    //
    function startWatch() {

        // Update acceleration every 3 seconds
        var options = { frequency: 3000 };

        watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
    }

    // Stop watching the acceleration
    //
    function stopWatch() {
        if (watchID) {
            navigator.accelerometer.clearWatch(watchID);
            watchID = null;
        }
    }

    // onSuccess: Get a snapshot of the current acceleration
    //
    function onSuccess(acceleration) {
        var element = document.getElementById('accelerometer');

        element.innerHTML = 'Acceleration X: ' + acceleration.x + '<br />' +
                            'Acceleration Y: ' + acceleration.y + '<br />' +
                            'Acceleration Z: ' + acceleration.z + '<br />' +
                            'Timestamp: '      + acceleration.timestamp + '<br />';
    }

    // onError: Failed to get the acceleration
    //
    function onError() {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <div id="accelerometer">Waiting for accelerometer...</div>
        <button onclick="stopWatch();">Stop Watching</button>
  </body>
</html>

Acceleration

Contains Accelerometer data captured at a specific point in time.

Properties

x: Amount of acceleration on the x-axis. (in m/s^2) (Number)
y: Amount of acceleration on the y-axis. (in m/s^2) (Number)
z: Amount of acceleration on the z-axis. (in m/s^2) (Number)
timestamp: Creation timestamp in milliseconds. (DOMTimeStamp)

Description

An Acceleration object is populated and returned by any of the API's Accelerometer methods. Acceleration values include the effect of gravity (9.81 m/s^2), so that when a device lies flat and facing up, x, y, and z values returned should be 0, 0, and 9.81.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Tizen
Windows Phone 7 and 8
Windows 8

Quick Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
};

function onError() {
    alert('onError!');
};

navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);

Full Example

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

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

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

    // device APIs are available
    //
    function onDeviceReady() {
        navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);
    }

    // onSuccess: Get a snapshot of the current acceleration
    //
    function onSuccess(acceleration) {
        alert('Acceleration X: ' + acceleration.x + '\n' +
              'Acceleration Y: ' + acceleration.y + '\n' +
              'Acceleration Z: ' + acceleration.z + '\n' +
              'Timestamp: '      + acceleration.timestamp + '\n');
    }

    // onError: Failed to get the acceleration
    //
    function onError() {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>getCurrentAcceleration</p>
  </body>
</html>

accelerometerSuccess

onSuccess callback function that provides the Acceleration information.

function(acceleration) {
    // Do something
}

Parameters

acceleration: The acceleration at a single moment in time. (Acceleration)

Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
};