Using the new floor and indoor lock APIs


The old way (IndoorAtlas Cordova plugin versions 1.x)


In our previous plugin version, you would use the setPosition method to either set your location explicitly, lock position to specific floor, give hints about the floor number or lock position to specific venue.


There are three main uses for the setPosition:


1. Setting your location explicitly to specific latitude & longitude


IndoorAtlas.setPosition(onSuccess, onError, {
  coordinates: [60.01, 24.123]
});


    Here we initialize the position to latitude 60.01, longitude 24.123.


2. Forcing positioning to specific floor plan ID (a.k.a. explict floor plan or explicit region with floor plan id). This feature has been removed in IndoorAtlas Cordova plugin 2.9 (see below)


IndoorAtlas.setPosition(onSuccess, onError, {
  floorPlanId: "2f3fe694-9f03-452f-921b-3d1b85afe449"
});


    Here we force the positioning to specific floorplan of id "2f3fe694-9f03-452f-921b-3d1b85afe449". Positioning will be locked to this floorplan until either next floorplan id is provided through the setPosition or positioning is stopped.


3. Forcing positioning to specific venue ID (a.k.a. explicit venue or explicit region with venue id). This feature has been removed in IndoorAtlas Cordova plugin 2.9 (see below)


IndoorAtlas.setPosition(onSuccess, onError, {
  venueId: "3cf48add-6fb9-4926-8bdd-ef3d6d977dfd"
});


    Here we force the positioning to specific venue of ID "3cf48add-6fb9-4926-8bdd-ef3d6d977dfd". Positioning will be locked to this venue until either next venue or floorplan id is provided through the setPosition or positioning is stopped.


The new way (IndoorAtlas Cordova plugin versions >= 2)


In the new IndoorAtlas Cordova plugin 2.9, we have added new APIs for locking the positioning to new specific floor and / or building.


1. Setting your location explicitly to specific latitude & longitude can be done via setLocation like in older SDK versions.


2. Forcing positioning to specific floor plan ID is replaced by locking positioning to specific floor number. Locking positioning can be done by using the new lockFloor method. In addition to locking, new method unlockFloor is provided so positioning can be unlocked from the specific floor.


// Lock positioning to floor number 3
IndoorAtlas.lockFloor(3);

// Unlock positioning so floor level is detected automatically
IndoorAtlas.unlockFloor();


3. Forcing positioning to specific venue ID is replaced by locking positioning to indoors. Correct venue is automatically detected by using platform locations. Locking indoors can be achieved by new method lockIndoors(boolean lock) which locks the positioning inside the venue. This also means that GPS is no longer scanned. lockIndoors needs to be called with a boolean argument indicating whether you want to lock or unlock to indoor positioning.


// Lock positioning indoors (i.e., enable indoor-only mode)
IndoorAtlas.lockIndoors(true);

// Unlock positioning indoors (disable indoor-only mode)
IndoorAtlas.lockIndoors(false);


The new APIs lockFloor and lockIndoors can be used together but it is redundant in most cases: Locking positioning to specific floor also implicitly locks positioning indoors.


Why to migrate


The new lockFloor and lockIndoors methods provide cleaner solution to manipulating where the positioning happens. You no longer need to use any UUIDs to set the positioning to specific floor plan or venue ID. This, in turn, results to much cleaner application level logic if specific floor positioning is required. 


The new APIs also provide unlock methods which were previously missing.


No more manual meta data fetching for regions




The old way (IndoorAtlas Cordova plugin versions 1.x)




In our older SDK versions you would use IAResourceManager to fetch the meta data of floor plans, e.g. the bitmap image or pixel to WGS transformations.

For example, if you wanted to fetch the bitmap image of the specific floor plan by ID, you would have had to implement something similar to the following:


function onMetaDataFetched(floorPlan) {
   // do something with the floorPlan object
}

function onEnterRegion(region) {
    IndoorAtlas.fetchFloorPlanWithId(region.regionId, onMetaDataFetched, onError);
}

function onExitRegion() {
    // ...
}

var regionWatchId = IndoorAtlas.watchRegion(onEnterRegion, onExitRegion, onError);
// ...





The new way (IndoorAtlas Cordova plugin versions >= 2)



In the new IndoorAtlas Cordova plugin 2.9, the metadata information is provided in the Region ready for use. This means that the application level logic does not need to handle the explicit metadata downloading


Now IARegion class has two new attributes relating to the new functionality: floorPlan and venue. The new attributes give the metadata relating to either the floor plan or venue, depending which one the Region corresponds to (as previously, type can be checked from regionType)




With the new APIs, the previous example simplifies to the following:


function onEnterRegion(region) {
    if (region.floorPlan) {
       // do something with region.floorPlan
    }
}

function onExitRegion() {
    // ...
}

var regionWatchId = IndoorAtlas.watchRegion(onEnterRegion, onExitRegion, onError);
// ...




Wayfinding


The old way (IndoorAtlas Cordova plugin versions 1.x)


Previously, one would initialize an IndoorAtlas wayfinder using a wayfinding graph, which has been manually downloaded from the IndoorAtlas web app:


var graph = JSON_FROM_FILE;
var location = { latitude: 60.17, longitude: 24.94, floor: 1 };
var destination = { latitude: 60.16, longitude: 24.95, floor: 2 };

// Load the JSON file to String graphJSON
IndoorAtlas.buildWayfinder(graph).then(function(wayfinder) {
  wayfinder.setLocation(location.latitude, location.longitude, location.floor);
  wayfinder.setDestination(destination.latitude, destination.longitude, destination.floor);
  wayfinder.getRoute().then(function(result) {
    // Use result.route to draw the route etc.
  })
});



The new way (IndoorAtlas Cordova plugin versions >= 2)


See the new Cordova example code to see how this works in a complete application. Note: The new integrated wayfinding is not yet available in mainland China.


In the new SDK, the wayfinding graph does not need to be manually downloaded. Instead the wayfinding graphs are automatically handled by the SDK. The new requestWayfindingUpdates API works as follows

var destination = { latitude: 60.16, longitude: 24.95, floor: 2 };

IndoorAtlas.requestWayfindingUpdates(destination, function(route) {
    // Use route.legs to draw the route etc.
});


The registered callback starts receiving updates as soon as the wayfinding graph has been downloaded (or loaded from the automatic disk cache). The route is updated on each new IndoorAtlas location and it always connects the latest location and the destination set in the request. If routing between these two locations is impossible, for instance, the floor the user is on has no wayfinding graph or the wayfinding graph is disconnected, the returned list of routing legs is empty.


When the user has reached the destination or, for example, wants to cancel the wayfinding session, IndoorAtlas wayfinding can be stopped by calling removeWayfindingUpdates

IndoorAtlas.removeWayfindingUpdates();