Cordova API Documentation

Available Methods and Objects for IndoorAtlas Cordova Plugin.

Methods

Objects (Read-Only)

IndoorAtlas.initialize

Initializes IndoorAtlas’ IALocationManager object with provided API key and secret. This method must be called before you start a positioning session.

IndoorAtlas.initialize(initializationSuccess,
               initializationError,
               {key: APIKEY, secret: APISECRET});

Parameters

  • initializationSuccess: The callback that notifies that IALocationManager was successfully instantiated.
  • initializationError: The callback that executes if an error occurs.
  • configOptions: Configuration options that contains IndoorAtlas API key and secret.

Example

// onSuccess Callback
var onSuccess = function() {
  alert('IndoorAtlas was successfully initialized');
};

// onError Callback receives a PositionError object
function onError(error) {
  alert('Code: '+ error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.initialize(onSuccess,
                       onError,
                       {key: 'API KEY', secret: 'API SECRET'});

IndoorAtlas.getCurrentPosition

Returns the device’s current position to the geolocationSuccess callback with a Position object as the parameter. If there is an error, the geolocationError callback is passed a PositionError object.

IndoorAtlas.getCurrentPosition(geolocationSuccess,
                               geolocationError,
                               [geolocationOptions]);

Parameters

  • geolocationSuccess: The callback that is passed the current position.
  • geolocationError: (Optional) The callback that executes if an error occurs.
  • geolocationOptions: (Optional) The geolocation options.

Example

// onSuccess Callback
// This method accepts a Position object, which contains the
// current GPS coordinates
var onSuccess = function(position) {
  alert('Latitude: ' + position.coords.latitude + '\n' +
        'Longitude: ' + position.coords.longitude + '\n' +
        'Altitude: ' + position.coords.altitude + '\n' +
        'Accuracy: ' + position.coords.accuracy + '\n' +
        'Heading: ' + position.coords.heading + '\n' +
        'Floor: ' + position.coords.floor + '\n' +
        'Timestamp: ' + position.timestamp);
};

// onError Callback receives a PositionError object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
}

IndoorAtlas.getCurrentPosition(onSuccess, onError);

IndoorAtlas.watchPosition

Returns the device’s current position when a change in position is detected. When the device retrieves a new location, the geolocationSuccess callback executes with a Position object as the parameter. If there is an error, the geolocationError callback executes with a PositionError object as the parameter.

var watchId = IndoorAtlas.watchPosition(geolocationSuccess,
                                        geolocationError,
                                        {timeout: TIMEOUT});

Parameters

  • geolocationSuccess: The callback that is passed the current position.
  • geolocationError: (Optional) The callback that executes if an error occurs.
  • timeout: (Optional) timeout for not receiving location.

Returns

  • String: returns a watch id that references the watch position interval. The watch id should be used with IndoorAtlas.clearWatch to stop watching for changes in position.

Example

// onSuccess Callback
//   This method accepts a `Position` object, which contains
//   the current GPS coordinates
function onSuccess(position) {
  alert('Latitude: ' + position.coords.latitude + '\n' +
        'Longitude: ' + position.coords.longitude);
};

// onError Callback receives a PositionError object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

// Options: throw an error if no update is received every 30 seconds.
var watchID = IndoorAtlas.watchPosition(onSuccess, onError, {timeout: 30000});

geolocationOptions

Optional parameters to set the timeout of the operation.

Options - timeout: The maximum length of time (milliseconds) that is allowed to pass from the call to IndoorAtlas.getCurrentPosition or IndoorAtlas.watchPosition until the corresponding geolocationSuccess callback executes. If the geolocationSuccess callback is not invoked within this time, the geolocationError callback is passed a PositionError.TIMEOUT error code. (Number)

IndoorAtlas.setPosition

Indicate current location to positioning service. This method can be used to pass a hint to the system e.g. when location is already known. This is completely optional and should only be used to shorten time it takes for the first fix. It is not recommended that this method is called with approximate locations with low or medium accuracy.

IndoorAtlas.setPosition(geolocationSuccess,
                        geolocationError,
                        {regionId: REGIONID, coordinates: [LATITUDE, LONGITUDE]});

Parameters

  • geolocationSuccess: The callback that is passed when position is set.
  • geolocationError: The callback that executes if an error occurs.
  • regionId: Region Id.
  • coordinates: Coordinates of the location.

Example

// onSuccess Callback
function onSuccess() {
  alert('Position was set successfully');
};

// onError Callback receives a PositionError object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

// Options: pass region id or coordinates.
IndoorAtlas.setPosition(onSuccess, onError, {regionId: '00000001-0002-0003-0004-000000000005', coordinates: [37.784013, -122.406872]});

geolocationOptions

geolocationOptions can consist any one or both of the following

  • regionId: Id of IARegion object. (String)
  • coordinates: A set of geographic coordinates. (Coordinates)

IndoorAtlas.clearWatch

Stop watching for changes to the device’s location referenced by the watchID parameter.

IndoorAtlas.clearWatch(watchID);

Parameters

  • watchID: The id of the watchPosition interval to clear. (String)

Example

// Options: watch for changes in position, and use the most
// accurate position acquisition method available.
var watchID = IndoorAtlas.watchPosition(onSuccess, onError);

// ...later on...

IndoorAtlas.clearWatch(watchID);

IndoorAtlas.watchRegion

Returns when a change in region is detected. When the device enters a region, the onEnterRegion callback executes with a Region object as the parameter. When the device exits a region, the onExitRegion callback executes with a Region object as the parameter. If there is an error, the geolocationError callback executes with a PositionError object as the parameter.

var watchId = IndoorAtlas.watchRegion(onEnterRegion,
                                      onExitRegion,
                                      geolocationError);

Parameters

  • onEnterRegion: The callback when device enters a region.
  • onExitRegion: The callback when device exits a region.
  • geolocationError: (Optional) The callback that executes if an error occurs.

Returns

  • String: returns a watch id that references the watch position interval. The watch id should be used with IndoorAtlas.clearRegionWatch to stop watching for changes in region.

Example

// onEnterRegion Callback
//   This method accepts a `Region` object, which contains
//   IARegion information
function onEnterRegion(region) {
  alert('Entered region: ' + region.regionId);
};

// onExitRegion Callback
//   This method accepts a `Region` object, which contains
//   IARegion information
function onExitRegion(region) {
  alert('Exited region: ' + region.regionId);
};

// onError Callback receives a PositionError object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

// Options: throw an error if no update is received every 30 seconds.
var watchID = IndoorAtlas.watchRegion(onEnterRegion, onExitRegion, onError);

IndoorAtlas.clearRegionWatch

Stop watching for changes to the device’s region referenced by the watchID parameter.

IndoorAtlas.clearRegionWatch(watchID);

Parameters

  • watchID: The id of the watchRegion interval to clear. (String)

Example

// Options: watch for changes in position, and use the most
// accurate position acquisition method available.
var watchID = IndoorAtlas.watchRegion(onEnterRegion, onExitRegion, onError);

// ...later on...

IndoorAtlas.clearRegionWatch(watchID);

IndoorAtlas.fetchFloorPlanWithId

Fetches floor plan information for the provided floor plan ID. Note that error callback can be called if you are requesting floor plan that is private and belongs to another account.

IndoorAtlas.fetchFloorPlanWithId(floorPlanId,
                                 successCallback,
                                 errorCallback);

Parameters

  • floorPlanId: The floor plan ID.
  • successCallback: The callback for successful fetch.
  • errorCallback: The callback that executes if an error occurs.

Example

var successCallback = function(floorplan) {
  alert("Floor plan url: " + floorplan.url);
};

var errorCallback = function(error) {
  alert('Message: ' + error.message);
};

IndoorAtlas.fetchFloorPlanWithId('FLOORPLANID', successCallback, errorCallback);

IndoorAtlas.setDistanceFilter

Sets the distance for the distance filter feature. The minimum distance measured in meters that the device must move horizontally before an update event is generated.

IndoorAtlas.setDistanceFilter(successCallback,
                              errorCallback,
                              {distance: DISTANCE});

Parameters - successCallback: The callback for completing setting distance filter. - errorCallback: The callback that executes if an error occurs. - distance: Settings to be set for the filter, i.e distance.

Example

// onSuccess Callback
function onSuccess() {
  alert('Distance filter was set');
};

// onError Callback receives an error object
function onError(error) {
  alert('Message: ' + error.message);
};

IndoorAtlas.setDistanceFilter(onSuccess, onError, {distance: 10});

IndoorAtlas.pointToCoordinate

Converts point to a corresponding coordinate.

IndoorAtlas.pointToCoordinate({x: X, y: Y},
                              floorplanId,
                              successCallback,
                              errorCallback);

Parameters - successCallback: The callback for successful conversation. - errorCallback: The callback that executes if an error occurs. - x: X coordinade of the point. - y: Y coordinade of the point. - floorplanId: Floor plan ID.

Example

// onSuccess Callback
function onSuccess() {
  alert('Point was converted to coordinate');
};

// onError Callback receives an error object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.pointToCoordinate({x: 10, y: 10}, 'FLOORPLANID', onSuccess, onError);

IndoorAtlas.coordinateToPoint

Converts coordinate to a corresponding point.

IndoorAtlas.coordinateToPoint({latitude: LATITUDE, longitude: LONGITUDE},
                              floorplanId,
                              successCallback,
                              errorCallback);

Parameters - successCallback: The callback for successful conversation. - errorCallback: The callback that executes if an error occurs. - latitude: Latitude of the location. - longitude: Longitude of the location.

Example

// onSuccess Callback
function onSuccess() {
  alert('Coordinate was converted to point');
};

// onError Callback receives an error object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.coordinateToPoint({latitude: 60.17, longitude: 24.94}, 'FLOORPLANID', onSuccess, onError);

IndoorAtlas.getFloorCertainty

Returns the floor certainty of the current floor plan. Value for floor certainty is between 0 and 1.0, where 1.0 is the highest certainty that the current floor plan is the correct one.

IndoorAtlas.getFloorCertainty(successCallback, errorCallback);

Parameters - successCallback: The callback that is passed and which receives the floor certainty value. - errorCallback: The callback that executes if an error occurs.

Example

// onSuccess Callback
function onSuccess(data) {
  alert('Floor certainty is: '+ data.floorCertainty);
};

// onError Callback receives an error object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

    IndoorAtlas.getFloorCertainty(onSuccess, onError);

IndoorAtlas.getTraceId

Returns the traceId.

IndoorAtlas.getTraceId(successCallback, errorCallback);

Parameters - successCallback: The callback that is passed and which receives the traceId. - errorCallback: The callback that executes if an error occurs.

Example

// onSuccess Callback
function onSuccess(data) {
  alert('TraceId is: '+ data.traceId);
};

// onError Callback receives an error object
function onError(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.getTraceId(onSuccess, onError);

IndoorAtlas.didUpdateAttitude

Add callback for getting attitude updates.

IndoorAtlas.didUpdateAttitude(onAttitudeUpdate, errorCallback);

Parameters - onAttitudeUpdate: The callback that receives attitude updates. - errorCallback: The callback that executes if an error occurs.

Example

var onAttitudeUpdate = function(attitude) {
  alert('X: ' + attitude.x + '\n' +
        'Y: ' + attitude.y + '\n' +
        'Z: ' + attitude.z + '\n' +
        'W: ' + attitude.w + '\n' +
        'Timestamp: ' + attitude.timestamp);
};
var onError = function(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.didUpdateAttitude(onAttitudeUpdate, onError);

IndoorAtlas.removeAttitudeCallback

Stop receiving callbacks for attitude updates.

IndoorAtlas.removeAttitudeCallback();

IndoorAtlas.didUpdateHeading

Add callback for getting heading updates.

IndoorAtlas.didUpdateHeading(onHeadingUpdate, errorCallback);

Parameters - onHeadingUpdate: The callback that receives heading updates. - errorCallback: The callback that executes if an error occurs.

Example

var onHeadingUpdate = function(heading) {
  alert('True Heading: ' + heading.trueHeading + '\n' +
        'Timestamp: ' + heading.timestamp);
};

var onError = function(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.didUpdateHeading(onHeadingUpdate, onError);

IndoorAtlas.removeHeadingCallback

Stop receiving callbacks for heading updates.

IndoorAtlas.removeHeadingCallback();

IndoorAtlas.onStatusChanged

Add callback for getting status updates.

 IndoorAtlas.onStatusChanged(onStatusChange, errorCallback);

Parameters - onStatusChange: The callback that receives status updates. - errorCallback: The callback that executes if an error occurs.

Example

var onStatusUpdate = function(status) {
  alert('Message: ' + status.message + '\n' +
        'Type: ' + status.type);
};

var onError = function(error) {
  alert('Code: ' + error.code + '\n' +
        'Message: ' + error.message);
};

IndoorAtlas.onStatusChanged(onStatusChange, onError);

IndoorAtlas.setSensitivities

Set sensitivities for orientation and heading updates.

IndoorAtlas.setSensitivities(onSuccess,
                             onError,
                             {orientationSensitivity: ORIENTATIONSENSITIVITY, headingSensitivity: HEADINGSENSITIVITY});

Parameters - orientationSensitivity: Value in degrees for orientation filter. - headingSensitivity: Value in degrees for heading filter.

Example

function onSuccess() {
  alert('Sensitivities were set');
};

function onError(error) {
  alert(error);
};

IndoorAtlas.setSensitivities(onSuccess, onError, {orientationSensitivity: 10, headingSensitivity: 5});

Position

Contains IndoorAtlas.Position coordinates, region and timestamp, created by the IndoorAtlas API.

Properties

  • coords: A set of geographic coordinates. (Coordinates)
  • region: A data object describing a typed region in IndoorAtlas namespace. (Region)
  • timestamp: Creation timestamp for coords. (DOMTimeStamp)

Coordinates

A IndoorAtlas.Coordinates object is attached to a Position object that is available to callback functions in requests for the current position. It contains a set of properties that describe the geographic coordinates of a position.

Properties

  • latitude: Latitude in decimal degrees. (Number)
  • longitude: Longitude in decimal degrees. (Number)
  • altitude: Height of the position in meters above the ellipsoid. (Number)
  • accuracy: Accuracy level of the latitude and longitude coordinates in meters. (Number)
  • altitudeAccuracy: Accuracy level of the altitude coordinate in meters. Altitude accuracy is not yet implemented in IndoorAtlas API. Value of this property will always be null (Number)
  • heading: Direction of travel, specified in degrees counting clockwise relative to the true north. (Number)
  • speed: Current ground speed of the device, specified in meters per second. (Number)
  • floor: The logical floor level of building. (Number)

Region

A data object describing a typed region in IndoorAtlas namespace. A IndoorAtlas.Region object is attached to a Position object that is available to callback functions in requests for the current position. IndoorAtlas.Region object is also returned by IndoorAtlas.watchRegion callbacks. It represents IARegion object.

Properties

  • regionId: Returns regions id. (String)
  • regionType: Returns region’s type. Possible values are Region.TYPE_FLOORPLAN, Region.TYPE_VENUE Region.TYPE_UNKNOWN. (Number)
  • transitionType: Specifies if the region was entered or exited. Possible values are Region.TRANSITION_TYPE_ENTER,Region.TRANSITION_TYPE_EXIT and Region.TRANSITION_TYPE_UNKNOWN. (Number)
  • timestamp: Creation timestamp for region. (DOMTimeStamp)

PositionError

The IndoorAtlas.PositionError object is passed to the geolocationError callback function when an error occurs with LocationServices.

Properties

  • code: One of the predefined error codes listed below.
  • message: Error message describing the details of the error encountered.

FloorPlan

A data object describing a floor plan in IndoorAtlas namespace. It represents IAFloorPlan object.

Properties

  • id: Floor plan ID. (String)
  • name: Floor plan name. (String)
  • url: URL for bitmap resource. (String)
  • floorLevel: The logical floor level of building. Does not always match with numbering scheme of floors used in building. Ground level is 0. Levels below the ground are represent with negative integers. First underground level is -1. Levels above the ground are represent with positive integers. First level above ground level is 1. (Number)
  • bearing: The approximate bearing of left side of floor plan in degrees East of true North. (Number)
  • bitmapHeight: Heigh of bitmap in pixels. (Number)
  • bitmapWidth: Width of bitmap in pixels. (Number)
  • heightMeters: Height of floor plan bitmap placed on the surface of earth in meters. (Number)
  • widthMeters: Width of floor plan bitmap placed on the surface of earth in meters. (Number)
  • metersToPixels: Meters to pixels conversion factor Multiply distance in meters by this factor to get distance in pixels. (Number)
  • pixelsToMeters: Pixels to meters conversion factor. Multiply distance in pixels by this factor to get distance in meters. (Number)
  • bottomLeft: Corresponding WGS84 coordinate of bottom left corner of floor plan bitmap placed on the surface of earth. Represented as array in lon,lat sequence. (Array)
  • center: Corresponding WGS84 coordinate of center of floor plan bitmap placed on the surface of earth. Represented as array in lon,lat sequence. (Array)
  • topLeft: Corresponding WGS84 coordinates of top left corner of floor plan bitmap placed on the surface of earth. Represented as array in lon,lat sequence. (Array)
  • topRight: Corresponding WGS84 coordinate of top right corner of floor plan bitmap placed on the surface of earth. Represented as array in lon,lat sequence. (Array)

Constants

PositionError

  • PositionError.PERMISSION_DENIED
    • Returned when users do not allow the app to retrieve position information. This is dependent on the platform.
  • PositionError.POSITION_UNAVAILABLE
    • Returned when the device is unable to retrieve a position. In general, this means the device is not connected to a network or can’t get a position fix.
  • PositionError.TIMEOUT
    • Returned when the device is unable to retrieve a position within the time specified by the timeout included in geolocationOptions. When used with IndoorAtlas.watchPosition, this error could be repeatedly passed to the geolocationError callback every timeout milliseconds.
  • PositionError.INVALID_ACCESS_TOKEN
    • Returned when provided API key and secret are not valid
  • PositionError.INITIALIZATION_ERROR
    • Returned when start of a positioning session is attempted without calling IndoorAtlas.initialize.
  • PositionError.FLOOR_PLAN_UNAVAILABLE
    • Returned when requested floor plan while calling IndoorAtlas.fetchFloorPlanWithId is private and belongs to another account.
  • PositionError.UNSPECIFIED_ERROR
    • Returned when an unspecified runtime error occurs.

CurrentStatus

  • CurrentStatus.STATUS_OUT_OF_SERVICE
    • Location service is not available and the condition is not expected to resolve itself soon.
  • CurrentStatus.STATUS_TEMPORARILY_UNAVAILABLE
    • Location service temporarily unavailable.
  • CurrentStatus.STATUS_AVAILABLE
    • Location service running normally.
  • CurrentStatus.STATUS_LIMITED
    • Location service is running but with limited accuracy and functionality.

Region

  • Region.TRANSITION_TYPE_ENTER
    • Specifies that the region was entered.
  • Region.TRANSITION_TYPE_EXIT
    • Specifies that the region was exited.
  • Region.TRANSITION_TYPE_UNKNOWN
    • Plugin was not able to determine if region was entered or exited.
  • Region.TYPE_FLOORPLAN
    • A floor plan region.
  • Region.TYPE_VENUE
    • A venue region.
  • Region.TYPE_UNKNOWN
    • An unknown region.