This section outlines the upgrade path from HERE Maps API for JavaScript 3.0 to version 3.1 and describes in greater details the backward-incompatible changes.
Version 3.1 of Maps API for JavaScript introduces the new default WebGL-based rendering engine that provides efficient vector rendering, increases map performance and gives richer experience for developer and the end user. The new rendering engine brings a number of changes in how API behaves as well as it shifts a set of functionalities related to the 2D HTML5 Canvas engine to the "legacy" modules.
The HERE Maps API for JavaScript version 3.1. introduces a new way to authenticate the application. Instead of the app_id and app_code pair, the HERE Maps API for JavaScript uses the apikey. The code below shows how to instantiate H.service.Platform in the new version of the API:
var platform = new H.service.Platform({
'apikey': '{YOUR_API_KEY}'
});
In order to enable smooth transition from version 3.0 to 3.1, the HERE Maps API for JavaScript has two auxiliary modules. These modules ensure that applications that do not have access to the latest browser technology still can benefit from the HERE services. The following modules were added:
In order to use the modules, just include them on the page. Be sure to include these files after the module they depend on. For example:
<!DOCTYPE html>
<html>
<head>
...
<meta name="viewport" content="initial-scale=1.0,
width=device-width" />
<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"
type="text/javascript" charset="utf-8"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-core-legacy.js"
type="text/javascript" charset="utf-8"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"
type="text/javascript" charset="utf-8"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service-legacy.js"
type="text/javascript" charset="utf-8"></script>
...
</head>
Note how *-legacy modules immediately follow core and service modules.
The HERE Maps API for JavaScript version 3.1 contains a new default rendering engine. The engine uses an HTML5 WebGL canvas element and enables rendering of rich and customizable vector maps. The engine is capable of rendering both vector and raster data, thus, the changes become automatic for the application that utilizes the JavaScript API. However, if the base layer in use does not send CORS requests, this might affect the application. You can still use the HTML5 canvas 2D rendering engine if the application cannot be run in the modern browser that supports WebGL rendering. In order to make the most of the WebGL engine, use the new vector tiles.
In the Maps API for JavaScript version 3.0, the map with raster tiles was initialized as follows:
// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();
// Instantiate (and display) a map object:
var map = new H.Map(
document.getElementById('mapContainer'),
defaultLayers.normal.map,
{
zoom: 10,
center: { lat: 52.5, lng: 13.4 }
});
The snippet below shows how to switch to the vector tiles:
// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();
// Instantiate (and display) a map object:
var map = new H.Map(
document.getElementById('mapContainer'),
defaultLayers.vector.normal.map,
{
zoom: 10,
center: { lat: 52.5, lng: 13.4 }
});
The snippet below shows how to use the canvas 2D rendering engine in supported legacy browsers:
// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();
// Instantiate (and display) a map object:
var map = new H.Map(
document.getElementById('mapContainer'),
defaultLayers.raster.normal.map,
{
zoom: 10,
center: { lat: 52.5, lng: 13.4 },
engineType: H.map.render.RenderEngine.EngineType.P2D
});
HERE API keys provide simple and secure authentication of your application. Utilize the API key credentials key-rotation feature to ensure continued security of your application over time. This is done by creating a second API key for your application and deleting the original key when it is no longer required. You can use a maximum of two API keys at once for each application.
We have created a detailed document for all of the customers who are required to upgrade from the Legacy API.
Important place to visit for all other generic help.