cordova-plugin-indooratlas

3.4.1

___

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

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

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) positioning 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.
options.minIntervalSeconds number (optional) Time filter. The minimum amount of time measured in seconds that must be elapsed before an update event is generated. Setting this to 0 disables time based updates. Maximum update frequency is determined from values of distance filter and time filter. Update is generated when either of conditions specified by these filters are met. Default value is 2.
options.positioningMode string (optional) positioning mode. One of: HIGH_ACCURACY , LOW_POWER or CART . Default is HIGH_ACCURACY
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. Also clears any other watches.

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. Also a #POI can be given as a destination.

requestWayfindingUpdates(destination: (object | POI), onWayfindingRoute: function (Route)): object
Parameters
destination ((object | POI))
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()

requestWayfindingRoute

Request a single-shot wayfinding route. Also a #POI can be given as a source or destination.

requestWayfindingRoute(from: (object | POI), to: (object | POI), onWayfindingRoute: function (Route)): object
Parameters
from ((object | POI))
Name Description
from.latitude number Starting location latitude in degrees
from.longitude number Starting location longitude in degrees
from.floor number Starting location floor number as defined in the mapping phase
to ((object | POI))
Name Description
to.latitude number Destination latitude in degrees
to.longitude number Destination longitude in degrees
to.floor number Destination floor number as defined in the mapping phase
onWayfindingRoute (function (Route)) a callback that executes with 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 from = { latitude: 60.16, longitude: 24.95, floor: 2 };
const to = { latitude: 60.161, longitude: 24.951, floor: 3 };
IndoorAtlas.requestWayfindingRoute(from, to, route => {
    console.log(`the route has ${route.legs.length} leg(s)`);
});

watchGeofences

Start monitoring for geofence events (entering or exiting geofences).

watchGeofences(onTriggeredGeofence: geofenceCallback): object
Parameters
onTriggeredGeofence (geofenceCallback) A callback which is executed when a geofence is entered or exited.
Returns
object: Returns this to allow chaining

clearGeofenceWatch

Stop monitoring enter/exit events for geofences.

clearGeofenceWatch(): object
Returns
object: Returns this to allow chaining

addDynamicGeofence

Add a geofence to be monitored for enter/exit.

addDynamicGeofence(geofence: Geofence): object
Parameters
geofence (Geofence) The geofence to be monitored.
Returns
object: Returns this to allow chaining
Example
IndoorAtlas.addDynamicGeofence(new IndoorAtlas.Geofence({
  id: '12345678-90ab-cdef-1234-567890abcdef',
  name: 'My geofence',
  floor: 1,
  coordinates: [
    [65.1234, 25.51234],
    [65.1254, 25.51234],
    [65.1254, 25.51334],
    [65.1234, 25.51334],
    [65.1234, 25.51234]
  ]
}));

removeDynamicGeofence

Removes a dynamic geofence from being monitored.

removeDynamicGeofence(geofence: (string | Geofence)): any
Parameters
geofence ((string | Geofence)) Either a Geofence object or a geofence ID string.
Returns
any: Returns this to allow chaining
Example

Provide a whole geofence object

var geofence = new IndoorAtlas.Geofence({ ... });
// ...
IndoorAtlas.removeDynamicGeofence(geofence);

Or just an geofence ID string

IndoorAtlas.removeDynamicGeofence('12345678-90ab-cdef-1234-567890abcdef');

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.latitude number Latitude in degrees
position.longitude number Longitude in degrees
position.floor number Integer floor number (optional)
position.accuracy number Accuracy radius in meters (optional)
Returns
object: returns this to allow chaining
Example
IndoorAtlas.setPosition({ latitude: 60.16, longitude: 24.95, floor: 2 });

lockIndoors

Enable or disable indoor-outdoor detection. Disabled by default.

lockIndoors(locked: boolean): object
Parameters
locked (boolean) if false , enable automatic indoor-outdoor detection. If true , disable automatic indoor-outdoor detection and keep positioning indoors.
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));

geofenceCallback

Callback function triggered on geofence events

geofenceCallback(transitionType: string, geofence: Geofence)

Type: Function

Parameters
transitionType (string) Event type, either 'ENTER' , 'EXIT' or 'UNKNOWN'
geofence (Geofence) Triggered geofence.

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
geofences
pois

POI

POI, or Point Of Interest, is a special position inside a building

POI(data: any)
Parameters
data (any)
Static Members
fromGeoJSON(geoJson)
Instance Members
id
name
floor
latitude
longitude
payload
toGeoJSON()

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 or #requestWayfindingRoute

Route(route: any)
Parameters
route (any)
Instance Members
error
isSuccessful
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

Geofence

A geofence describes a region of interest. Entering or exiting geofences will trigger SDK events caught by #watchGeofences. The geofences contained in a Venue are sent together with the venue (see #watchVenue and #watchPosition).

Geofence(data: any)
Parameters
data (any)
Static Members
fromGeoJSON(geoJson)
Instance Members
id
name
floor
coordinates
payload
toGeoJSON()