Steps to upgrade

Introduction

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.

Upgrade Steps?

API Key Instead of "app_id" and "app_code"

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}'
});

Legacy Modules

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:

mapsjs-core-legacy.js -brings HTML5 canvas rendering engine and its associated functionality
mapsjs-service-legacy.js - provides the access to the legacy platform services (for example, HTML5 meta-info tile)

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.

WebGL as a Default Engine

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
    });

Register on HERE platform for ApiKey

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.

Step 1: Register your app

If you don't already have a HERE account, see Get a HERE account.
Sign in to the HERE platform.
Open the Access Manager from the Launcher.
On the Apps tab, click Register new app and provide the requested information.
Click Register. The platform creates a new app with a unique app ID.
On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Step 2: Get an API key

Sign in to the HERE platform.
Open the Access Manager from the Launcher.
On the Apps tab, click the app you created in Step 1 or an existing app for which you want to generate an API key and provide the requested information.
On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Who should Upgrade?

We have created a detailed document for all of the customers who are required to upgrade from the Legacy API.

Please download

Generic Resources

Important place to visit for all other generic help.