___

IndoorAtlas Cordova plugin v3

All functions that are part of the IndoorAtlas Cordova plugin are scoped under the IndoorAtlas singleton object. For example the function #initialize can be used in code as IndoorAtlas.initialize(...).

The classes returned by the plugin, such as FloorPlan (= IndoorAtlas.FloorPlan) are not supposed to be constructed by the user directly.

Basic usage

Before you start, make sure you are familiar with the main phases of deploying IndoorAtlas technology. In particular, your physical location must be fingeprinted with the IndoorAtlas Map Creator 2 application before any of the below APIs will return meaningful values.

First, add IndoorAtlas plugin to the config.xml file of your project

<plugin name="cordova-plugin-indooratlas" spec="git+https://github.com/IndoorAtlas/cordova-plugin.git" />

Then you can initialize in Cordova's "deviceready" callback or later, e.g.,

document.addEventListener('deviceready', () => {
  // start positioning
  IndoorAtlas.initialize({ apiKey: YOUR_IA_API_KEY })
   .watchPosition(position => {
     console.log(
       "latitude: " + position.coords.latitude + ", " +
       "longitude: " + position.coords.longitude + ", " +
       "floor: " + position.coords.floor);
  });

  // auto-stop positioning after 60 seconds
  setTimeout(() => IndoorAtlas.clearWatch(), 60000);
}, false);

All methods return the IndoorAtlas singleton object to allow chaining like in the above example.

___

initialize

Initializes IndoorAtlas location manager object with provided API key. Must be called before using other methods. Should be called in Cordova's deviceready callback or later.

initialize(configuration: object): object
Parameters
configuration (object)
Name Description
configuration.apiKey string IndoorAtlas API key
Returns
object: returns this to allow chaining
Example
IndoorAtlas.initialize({ apiKey: "3795eee9-efaf-47db-8347-316b6bb0c834" })

watchPosition

Starts IndoorAtlas positioning

watchPosition(onPosition: function (Position), options: object): object
Parameters
onPosition (function (Position)) a callback that executes when the position changes with an IndoorAtlas.Position object as the parameter.
options (object) distance filter options (optional)
Name Description
options.minChangeMeters number (optional) Distance filter. If set, determines the minimum distance (in meters) the position has to change before the next position is reported. If not set, all changes in position are returned, which happens approximately once a second.
Returns
object: returns this to allow chaining
Example
IndoorAtlas.watchPosition(position => {
    console.log(`
        ${position.coords.latitude}
        ${position.coords.longitude}
        ${position.coords.floor}`);
});

clearWatch

Stops IndoorAtlas positioning. Other watches are not cleared by this opertation.

clearWatch(): object
Returns
object: returns this to allow chaining
Example
IndoorAtlas.watchPosition(position => {
   // do some positioning
});
// stop after 10 seconds
setTimeout(() => { IndoorAtlas.clearWatch(); }, 10000);

watchFloorPlan

Start observing floor plan changes

watchFloorPlan(onFloorPlanChange: function (FloorPlan)): object
Parameters
onFloorPlanChange (function (FloorPlan)) a callback that executes when the floor plan changes. null if not currently on any floor plan.
Returns
object: returns this to allow chaining
Example
IndoorAtlas.watchFloorPlan(floorPlan => {
    if (floorPlan) {
        console.log(`entered floor plan ${floorPlan.name}`);
    }
});

clearFloorPlanWatch

Stop observing floor plan changes

clearFloorPlanWatch(): object
Returns
object: returns this to allow chaining

watchVenue

Start observing venue changes

watchVenue(onVenueChange: function (Venue)): object
Parameters
onVenueChange (function (Venue)) a callback that executes when the venue changes. null if not currently near any venue.
Returns
object: returns this to allow chaining

clearVenueWatch

Stop observing venue changes

clearVenueWatch(): object
Returns
object: returns this to allow chaining

onStatusChanged

Start observing status changes

onStatusChanged(onStatus: function (CurrentStatus)): object
Parameters
onStatus (function (CurrentStatus)) a callback that executes when the IndoorAtlas service status changes.
Returns
object: returns this to allow chaining
Example
IndoorAtlas.onStatusChanged(console.log);

removeStatusCallback

Stop observing status changes

removeStatusCallback(): object
Returns
object: returns this to allow chaining

watchOrientation

Start observing for device orientation & heading changes

watchOrientation(onOrientation: function (Orientation), options: object): object
Parameters
onOrientation (function (Orientation)) a callback that executes when the orientation of the device changes. Contains the heading and other orientation angles.
options (object) distance filter options (optional)
Name Description
options.minChangeDegrees number (optional) Change filter. If set, determines the minimum angle in degrees that the device has to be rotated (about any axis) before a new orientation is reported.
Returns
object: returns this to allow chaining
Example
IndoorAtlas.watchOrientation(orientation => {
    console.log(`heading: ${orientation.trueHeading} degrees`);
});

clearOrientationWatch

Stop observing orientation changes

clearOrientationWatch(): object
Returns
object: returns this to allow chaining

requestWayfindingUpdates

Request wayfinding from the current location of the user to the given coordinates

requestWayfindingUpdates(destination: object, onWayfindingRoute: function (Route)): object
Parameters
destination (object)
Name Description
destination.latitude number Destination latitude in degrees
destination.longitude number Destination longitude in degrees
destination.floor number Destination floor number as defined in the mapping phase
onWayfindingRoute (function (Route)) a callback that executes when the user's location is changed, gives the shortest route to the given destination as an object { legs } , where legs is a list of IndoorAtlas.RouteLeg objects.
Returns
object: returns this to allow chaining
Example
const destination = { latitude: 60.16, longitude: 24.95, floor: 2 };
IndoorAtlas.requestWayfindingUpdates(destination, route => {
    console.log(`the route has ${route.legs.length} leg(s)`);
});

removeWayfindingUpdates

Stop wayfinding. Typically called after arriving to the destination (determined with #requestWayfindingUpdates) or if the user cancels the wayfinding session.

removeWayfindingUpdates(): object
Returns
object: returns this to allow chaining
Example
IndoorAtlas.removeWayfindingUpdates()

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.

setPosition(position: object): object
Parameters
position (object)
Name Description
position.coordinates Coordinates Like IndoorAtlas.Coordinates , must have at least latitude and longitude members
Returns
object: returns this to allow chaining
Example
IndoorAtlas.setPosition({ latitude: 60.16, longitude: 24.95, floor: 2 });

lockIndoors

Disable or re-enable indoor-outdoor detection

lockIndoors(locked: boolean): object
Parameters
locked (boolean) if true keep positioning indoors and disable automatic indoor-outdoor detection. If false , re-enable automatic indoor-outdoor detection
Returns
object: returns this to allow chaining
Example
IndoorAtlas.lockIndoors(true);

lockFloor

Disable automatic floor detection and lock the floor level to a given number

lockFloor(floorNumber: number): object
Parameters
floorNumber (number) The floor number (integer) to lock the positioning to. Use floor nubmers as defined in the mapping phase
Returns
object: returns this to allow chaining
Example
IndoorAtlas.lockFloor(3);

unlockFloor

Re-enable automatic floor detection after locking the floor with #lockFloor

unlockFloor(): object
Returns
object: returns this to allow chaining
Example
IndoorAtlas.unlockFloor();

getTraceId

Returns the IndoorAtlas trace ID for this session in a callback.

getTraceId(onTraceId: function (string)): object
Parameters
onTraceId (function (string)) A callback that returns the trace ID string. Called only once on success.
Returns
object: returns this to allow chaining
Example
IndoorAtlas.getTraceId(traceId => console.log(traceId));

Position

Describes an indoor or outdoor location with coordinates, uncertainties and metadata such as IndoorAtlas floor plan and venue objects.

Position(data: any)
Parameters
data (any)
Instance Members
coords
floorPlan
venue
timestamp
floorCertainty

Coordinates

An IndoorAtlas.Coordinates object is attached to a IndoorAtlas.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.

Coordinates(data: any)
Parameters
data (any)
Instance Members
latitude
longitude
accuracy
heading
floor

FloorPlan

A data object describing a floor plan. Can be obtained with #watchFloorPlan or as the Position#floorPlan member of the position returned by #watchPosition.

FloorPlan(data: any)
Parameters
data (any)
Instance Members
id
name
url
floorLevel
bearing
bitmapHeight
bitmapWidth
heightMeters
widthMeters
metersToPixels
pixelsToMeters
bottomLeft
center
topLeft
topRight
pointToCoordinate(x, y)
coordinateToPoint(lat, lon)

Venue

A data object describing a venue, also known as a building or location. Can be obtained with #watchVenue or as the Position#venue member of the object returned by #watchPosition.

Venue(data: any)
Parameters
data (any)
Instance Members
id
name
floorPlans

CurrentStatus

IndoorAtlas service status obtained with #onStatusChanged.

CurrentStatus(code: any, message: any)
Parameters
code (any)
message (any)
Static Members
OUT_OF_SERVICE
TEMPORARILY_UNAVAILABLE
AVAILABLE
LIMITED
Instance Members
code
name
message

Orientation

Describes the heading and orientation of the device. Obtained with #watchOrientation

Orientation(data: any)
Parameters
data (any)
Instance Members
trueHeading
roll
pitch
quaternion

Route

Describes a wayfinding route consisting of IndoorAtlas.RoutingLegs. Obtained with #requestWayfindingUpdates

Route(data: any)
Parameters
data (any)
Instance Members
legs

RoutingLeg

Wayfinding route leg object

RoutingLeg(data: any)
Parameters
data (any)
Instance Members
begin
end
direction
edgeIndex
length

RoutingPoint

Wayfinding route point

RoutingPoint(data: any)
Parameters
data (any)
Instance Members
latitude
longitude
floor
nodeIndex