Explanation of new map retrieval mechanism…
Striving to provide tools that are simple and robust, Visioglobe has recently unveiled a new mechanism for retrieving Map Bundles.
Until Novembre 2015, the service in charge of storing and providing latest maps was the VisioMapManager. However after a long and successful duty of almost 4 years, needs have changed.
The expansion of features in the SDKs and VisioMapEditor required a more scalable and flexible service. After a few months of development and testing, VisioMapServer is now going to slowly replace its predecessor over 2016.
This brings several changes, in the map administration as well as in the code. This article will describe all the changes to help with the migration.
Why? Problems it solves:
Problem |
VisioMapManager (previous system) |
VisioMapServer (new system) |
Hosting setup, performance |
Uses .php scripts, database server, needs very particular configuration, hard to scale and setup, also limits sending compressed files. |
Ease of deployment: Based on just serving files, mostly .json and .zip files, and CORS setup for VisioKiosk/VisioWeb. The new system is also Content Delivery Network (CDN) friendly in case of hyper-growth. It can send compressed files, thus potentially reducing network transfer by 4x. |
License Information for VisioMove |
It uses a template which lives on a database, which then triggers the downloading of a license. |
Increased reliability: License embedded on Map Bundle. |
Have a robust migration plan for dropping support of old map formats and adding support of new map features and formats (using Data Version). |
Not possible |
Future proof: SDK and Map Bundle contain version compatibility information. Old SDKs will not try to read Map Bundles it does not know how to handle. Future SDKs will not try to read dropped (old) formats. |
VisioKiosk/VisioWeb2D: Be able to tell if a map is newer than another |
Not possible for VisioKiosk or VisioWeb |
Simplified Caching: description file contains easily readable timestamp |
VisioKiosk/VisioWeb2D: Download the whole map to be hosted on an internal network. |
Not possible to do cleanly. |
Script Friendly: The whole map and support files can be downloaded. |
What is this about Data Version?
A Map Bundle has two versions, the SDK version that determines the features that are available, for example footprints, and the SDK Minimum Version that determines the minimum version of SDK that can properly read or parse the map.
There are the following tricky scenarios:
-
Old SDK does not handle new Map Bundle – There are other Map Bundle changes, for example optimizations on the rendering or load speed, that break backward compatibility (for example between VisioKiosk 1.7.10 and 1.7.14), so it is important that an old SDK does not try to read this new Map Bundle.
-
Map Bundle doesn’t have feature support – The Map Bundle changes that add new features such that it can be read by previous SDK versions, without taking advantage of these features. Nevertheless, for certain applications, it is important to know if these features are supported.
-
New SDK does not handle old Map Bundle – This is a future proof case, where a SDK would drop support for using very old Map Bundles
All are handled by having an sdk_version and sdk_min_version tied to the Map Bundle (in the description.json file) and having the SDK’s know the minimum data version they support (via SDK API’s VgEngine::
Example of different scenarios of SDK/Application (top) referencing a Map Bundle (bottom) with given versions. We can imagine in this scenario that the Data was published with a new sdk_version to take advantage of some new features. Three scenarios are shown: a) An old application that has not been updated, will not use the new data. b) An application that can read the data, but perhaps does not need the features of sdk_version 4. c) An application using a very recent SDK, whose data format has changed significantly; In this case, the application will not load the data (perhaps waiting for the data to be published) |
How is this all achieved?
The new architecture adds an extra level of indirection – a description .json file – that describes the different properties of the map and where to get the Map Bundle (.zip file) or the main map file (map.json for VisioKiosk), for example:
{ name: "com.visioglobe.sdk/visioislandmultibuilding", timestamp: "20151222114822", zip_file: "map.editor.zip", secret_code: 123456, sdk_version: "4.0.0", // for Move it would be like 2.1.7, or Kiosk 1.7.19 sdk_min_version: "2.0.0", // for Move generally be like 2.1.0 sdk_type: "move" // or "kiosk" or "web2d" }
One thing you will notice, is that the secret code is available on the description file, this moves the “secrecy” of the login/password to the URL used to access the map, which uses HTTPS for retrieval. With VisioMapManager, the map was downloaded on VisioMove with a URL like:
https://mapmanager.visioglobe.com/public/download?map_id=XX&username=YY&password=ZZ
With VisioMapServer, the new url will be of the form: https://mapserver.visioglobe.com/mxxxxxx/map.zip
How will this impact existing applications?
Once your publishing target is changed from VisioMapManager to VisioMapServer, old applications (that don’t reference VisioMapServer), will no longer get map updates; new applications (referencing VisioMapServer) will get map updates.
Action Plan: What do you need to do:
We encourage you to migrate to the new architecture. For that, you need to do 5 simple steps:
-
Request your account manager to configure your VisioMapEditor map to publish to VisioMapServer
-
Republish your map on VisioMapEditor, this will publish the map on VisioMapServer, ready for your application. Recover the new hash URL from your user profile on VisioMapEditor. See below.
You can also see the difference on how the publish window looks when publishing on VisioMapManager and VisioMapServer:
-
Update your application to use VisioMapServer, you can at this point, also update to the latest SDK. For VisioKiosk/VisioWeb2D, it simply means updating the library files, and the URL used for the map
Since version 2.1.5 released on September 2015, VisioMove support the new hash management. The old credential method (mapname, username, secret) has been flagged as deprecated and the sample was using the new hash way to fetch the latest version of the sample VisioIsland map.
If your data are hosted on a specific server, you will have to specify it with mServerURL = …
Since version 1.7.15 released on September 2015, VisioKiosk and VisioWeb2D SDKs support the VisioMapServer. Since it already uses a hash-based identifiers, the developers just have to replace the old mapURL with the new one.
-
If you update your SDK, please notify your account manager to update the Map’s target SDK within VisioMapEditor. Currently, the Map’s target SDK are not updated automatically, to avoid breaking compatibility (for example in the case of VisioKiosk 1.7.14 and 1.7.9)
-
Publish your application on the application’s store.
The future of VisioMapManager:
Visioglobe is going to setup new clients using the VisioMapServer and encourage old clients to update their VisioMapEditor Maps and Applications/Websites to use the VisioMapServer.
VisioMapManager will continue to function, even after 2016, to serve un-updated applications. We will work with clients to determine if VisioMapManager can be turned off in early 2017 or before.