Compass

Obtains the direction that the device is pointing.

Permissions

Android

app/res/xml/config.xml

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

BlackBerry WebWorks

No permissions are required.

iOS

config.xml

<plugin name="Compass" value="CDVLocation" />

Windows Phone

Properties/WPAppManifest.xml

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

Reference: Application Manifest for Windows Phone

Tizen

No permissions are required.

compass.getCurrentHeading

Get the current compass heading.

navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions);

Description

The compass is a sensor that detects the direction or heading that the device is pointed, typically from the top of the device. It measures the heading in degrees from 0 to 359.99, where 0 is north.

The compass heading information is returned via a CompassHeading object using the compassSuccess callback function.

Supported Platforms

Android
iOS
Tizen
Windows Phone 7 and 8 ( if available in hardware )
Windows 8

Quick Example

function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};

function onError(error) {
    alert('CompassError: ' + error.code);
};

navigator.compass.getCurrentHeading(onSuccess, onError);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass 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.compass.getCurrentHeading(onSuccess, onError);
    }

    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
        alert('Heading: ' + heading.magneticHeading);
    }

    // onError: Failed to get the heading
    //
    function onError(compassError) {
        alert('Compass Error: ' + compassError.code);
    }

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

compass.watchHeading

At a regular interval, get the compass heading in degrees.

var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);

Description

The compass is a sensor that detects the direction or heading that the device is pointed. It measures the heading in degrees from 0 to 359.99.

The compass.watchHeading gets the device's current heading at a regular interval. Each time the heading is retrieved, the headingSuccess callback function is executed. Specify the interval in milliseconds via the frequency parameter in the compassOptions object.

The returned watch ID references the compass watch interval. The watch ID can be used with compass.clearWatch to stop watching the compass.

Supported Platforms

Android
iOS
Tizen
Windows Phone 7 and 8 (if available in hardware)
Windows 8

Quick Example

function onSuccess(heading) {
    var element = document.getElementById('heading');
    element.innerHTML = 'Heading: ' + heading.magneticHeading;
};

function onError(compassError) {
    alert('Compass error: ' + compassError.code);
};

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

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass 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 `watchHeading`
    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 compass
    //
    function startWatch() {

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

        watchID = navigator.compass.watchHeading(onSuccess, onError, options);
    }

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

    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
        var element = document.getElementById('heading');
        element.innerHTML = 'Heading: ' + heading.magneticHeading;
    }

    // onError: Failed to get the heading
    //
    function onError(compassError) {
        alert('Compass error: ' + compassError.code);
    }

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

iOS Quirks

In iOS compass.watchHeading can also get the device's current heading when it changes by a specified number of degrees. Each time the heading changes by the specified number of degrees or more, the headingSuccess callback function executes. Specify the degrees of change via the filter parameter in the compassOptions object. Clear the watch as usual by passing the returned watch ID to compass.clearWatch. This functionality replaces the previously separate, iOS-only watchHeadingFilter and clearWatchFilter functions, which were removed in version 1.6.

Only one watchHeading can be in effect at one time in iOS. If a watchHeading uses a filter, calling getCurrentHeading or watchHeading uses the existing filter value to specify heading changes. Watching heading changes with a filter is more efficient than with time intervals.

compass.clearWatch

Stop watching the compass referenced by the watch ID parameter.

navigator.compass.clearWatch(watchID);

watchID: The ID returned by compass.watchHeading.

Supported Platforms

Android
iOS
Tizen
Windows Phone 7 and 8 ( if available in hardware )
Windows 8

Quick Example

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

// ... later on ...

navigator.compass.clearWatch(watchID);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass 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 `watchHeading`
    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 compass
    //
    function startWatch() {

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

        watchID = navigator.compass.watchHeading(onSuccess, onError, options);
    }

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

    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
        var element = document.getElementById('heading');
        element.innerHTML = 'Heading: ' + heading.magneticHeading;
    }

    // onError: Failed to get the heading
    //
    function onError(compassError) {
        alert('Compass error: ' + compassError.code);
    }

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

compass.watchHeadingFilter

No longer supported as of 1.6, see compass.watchHeading for equivalent functionality.

compass.clearWatchFilter

No longer supported as of 1.6. See compass.clearWatch.

compassSuccess

onSuccess callback function that provides the compass heading information via a compassHeading object.

function(heading) {
    // Do something
}

Parameters

heading: The heading information. (compassHeading)

Example

function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};

compassError

onError callback function for compass functions.

Example

function(CompassError) {
    // Handle the error
}

compassOptions

An optional parameter to customize the retrieval of the compass.

Options

frequency: How often to retrieve the compass heading in milliseconds. (Number) (Default: 100)
filter: The change in degrees required to initiate a watchHeading success callback. (Number)

Android Quirks

filter is not supported.

Tizen Quirks

filter is not supported.

Windows Phone 7 and 8 Quirks

filter is not supported.

compassHeading

A CompassHeading object is returned to the compassSuccess callback function.

Properties

magneticHeading: The heading in degrees from 0 - 359.99 at a single moment in time. (Number)
trueHeading: The heading relative to the geographic North Pole in degrees 0 - 359.99 at a single moment in time. A negative value indicates that the true heading cannot be determined. (Number)
headingAccuracy: The deviation in degrees between the reported heading and the true heading. (Number)
timestamp: The time at which this heading was determined. (milliseconds)

Description

The CompassHeading object is returned to the compassSuccess callback function.

Android Quirks

trueHeading is not supported, but reports the same value as magneticHeading
headingAccuracy is always 0 because there is no difference between the magneticHeading and trueHeading.

iOS Quirks

trueHeading is only returned when location services are enabled via navigator.geolocation.watchLocation()
For iOS 4 devices and above, heading factors in the device's current orientation, not in reference to its absolute position, for apps that supports that orientation.

CompassError

A CompassError object is returned to the compassError callback function when an error occurs.

Properties

code: One of the predefined error codes listed below.

Constants

CompassError.COMPASS_INTERNAL_ERR
CompassError.COMPASS_NOT_SUPPORTED

Description

When an error occurs, the CompassError object is passed as a parameter to a compassError callback function.

Compass

API Reference

Guides

Android

app/res/xml/config.xml

BlackBerry WebWorks

iOS

config.xml

Windows Phone

Properties/WPAppManifest.xml

Tizen