# Get Started

## Prerequisites

The HERE Navigation on Demand (HNoD) Service Package SDK has generally been developed and tested for Mac OS and Linux. There may be some issues if this is used with Windows OS. HNoD Service Package SDK depends upon node.js version 10 or higher and npm version 6 or higher. These need to be installed before you can start using the HNoD SDK.

WINDOWS USERS: Make sure you have the Windows Subsystem for Linux enabled. Please refer to Microsoft documentation for more details on how to do that. Then set npm script shell to bash using the following command:

npm config set script-shell bash


## Quick Start

This section will let you jump right in without further explanations. If you want to understand things in more detail, read the later sections.

Open a terminal at the location where the SDK was unpacked and run the following commands.

WARNING: Do not use yarn install for these steps! This will not work with the way the SDK's internal dependencies are structured. If you already started using yarn, delete node_modules before retrying.

# 1. Install the SDK's dependencies (from the unpacked SDK's root folder)
npm install
# 2. Install the SDK
# 3. Go to example folder
cd examples/hello-world
# 4. Link example to the installed SDK
# 5. Install the example's dependencies
npm install
# 6. Build example
npm run build
# 7. Setup credentials for simulator (replace with provided values)
export HNOD_APP_ID="<app_id>"
export HNOD_APP_CODE="<app_code>"
export HNOD_ACCESS_KEY_ID_OLP="<access_key>"
export HNOD_ACCESS_KEY_SECRET_OLP="<access_key_secret>"
# 8. Start hosting simulator in local webserver
npm start
# Simulator is now available at http://localhost:8081 (see below for details)


Open a browser (preferably Chrome) at http://localhost:8081. When prompted, enter the device id: jondoe. Click on the Launcher icon (9 dots) in the dock area at the bottom left of the screen. This will open the launcher card. From there, you can trigger the "Hello World" example by clicking on the example icon.

More details on these steps and how to create a new service package can be found in the following sections.

## Install the SDK

After unpacking the SDK archive, you will need to run the following commands from the root folder (where the package.json is located).

WARNING: Do not use yarn install! This will not work with the way the SDK's internal dependencies are structured.

npm install


The first command will install the SDK's dependencies.

DISCLAIMER: There are currently npm warnings output. We are working to reduce these. In the meantime, please do not be concerned.

INFO: The dependencies include npm packages that are provided locally as files. This is done because those packages are not published to a (public) npm repository yet. npm and yarn implement installing dependencies differently. npm uses a flat structure where all packages share the same node_modules, so the dependency lookup will find the same packages even for transitive dependencies. On the other hand, yarn creates a nested node_modules folder for each package, duplicating each transitive dependency. That way, yarn would try to download each package again from a (public) npm respository which will fail. This is why you can't use yarn install here (and also not for the examples). However, you are free to use yarn for the other scripts in package.json (e.g. build and start).

The second command makes the HNoD SDK available on your system under the name @here/hnod-sdk. In order for this to work, npm creates global symlinks (see Uninstall the SDK for how to clean this up again). Afterwards the HNoD Service Package SDK can be used as a dependency from other npm packages by calling npm link @here/hnod-sdk. This needs to be called before npm install for that dependent package.

The SDK also provides various command line tools, which will be available (via the aforementioned symlinks) on your system after executing npm link. You should be able to call them from your terminal without further setup (if not, something might be wrong with your npm or node installation). DISCLAIMER: At the moment, this does not properly work on Windows.

The following tools are provided:

• hnod-generate generates the basic scaffold of a new HNoD Service Package project
• hnod-bundler creates an HNoD Service Package archive (zip) file from code
• hnod-runner runs a local HNoD environment on localhost, accessible via browser

## Build Example Service Package

In the examples folder there is both a coffee and a hello-world example Service Package. We will focus on the hello-world example now, but the instructions will also work for the other example.

Before the examples can be compiled, their dependencies need to be installed. As part of this step, the example needs to be made aware of the previously installed HNoD SDK. To achieve this, run the following commands.

WARNING: Do not use yarn install!

cd examples/hello-world # or examples/coffee
npm install


The npm link @here/hnod-sdk command will point the example project to use the SDK (that was installed via npm link) by creating a symlink in node_modules. That way, the install step will not try to download the SDK from an external npm repository (which would fail). Instead, the install step is able to find the SDK and correctly set up the dependencies.

We can now build the example Service Package. From the according example folder run the following command.

npm run build


Internally, this command uses the SDK's hnod-bundler tool, which is configured via the hnod.bundler.json file. That json file specifies the main code entrypoints, the service package's metadata, and the name of the output folder (in this case it's output). A new Service Package zip archive will be created by this command in the output folder. For the hello-world example, this will be called hello.world.zip.

This package archive can now either be used by the hnod-runner tool to test the package locally (see Run a Service Package locally), or it can be uploaded to the HNoD Portal.

## Run a Service Package locally

In order to test example Service Packages locally, first, you need to provide a set of credentials. Please refer to Set Up Credentials for more details on how to do that.

When you have set up the credentials you can start to use the simulation environment with the following command. Make sure that the Service Package archive file listed in hnod.runner.json exists by building it first.

hnod-runner


Both the examples and the generated Service Package scaffold have a start script in their package.json, so instead you can use npm start (which will call hnod-runner for you).

The URL to the testing environment will be printed on the console (in this case localhost:8081) depending on which port was configured in the hnod.runner.json file. Open this URL in a browser (prefer to use Chrome as this is most heavily tested) to start up the local HNoD simulator. If everything went well, you will be prompted to enter a device id.

Enter the device id: jondoe

Afterwards, the application will load and you should be able to see the map in the background and the card stack UI in the foreground. The examples can be accessed via the Launcher card, which can be opened by clicking the Launcher icon (9 dots) in the dock area in the lower left corner of the window.

## Debug a Service Package

You can debug your Service Package by using the Developer tools of the browser. However, if you used all the default settings to build your Service Package archive, the Javascript code that you will see in the browser's devtool will not be very readable for debugging purposes.

To get more debugger-friendly code, you have to tell hnod-bundler to create a dev package with the mode argument. The examples and also the generated Service Package scaffold do not require you to call this command yourself, as this is hidden in the package.json scripts section. Add the --mode development argument there as follows:

  ...
"scripts": {
...
"build:bundle": "hnod-bundler --config hnod.bundler.json --mode development",
...
}


This will result in a Development Service Package. While this is nicer to debug, do not upload a package built in this mode to the HNoD Portal!

## Create a new Service Package

The SDK comes with a generator tool that will create a scaffold of a service package that can then be adapted. To create a new service package project run the following commands:

mkdir my-new-sp && cd my-new-sp
hnod-generate


The generator tool will ask if you installed the SDK via npm link. Answer this with yes, so that the generator will automatically call npm link @here/hnod-sdk before installing the dependencies. You do not have to run these steps yourself. This is needed for the install step to be successful if you installed the HNoD SDK via the instructions in this guide.

The scaffold already comes with some example code (in typescript) and build scripts. To build the newly generated project run the following command:

npm run build


The build command compiles the typescript and then calls the SDK's bundler tool (hnod-bundler). The bundler tool is configured via the file hnod.bundler.json. The file points to code entrypoints and contains the metainformation about the service package (e.g. name, description, ...). The result of this command is a new Service Package archive (zip file) in the specified output folder (by default the folder name is output).

Please refer to Run a Service Package locally for instructions on how to test the Service Package.

## Upload a Service Package to the Portal

At this time, the only way to upload a Service Package is via the HNoD Portal website. You have to login and switch to the Service Packages tab. If you belong to multiple organizations, make sure that you select the correct organization. The Service Packages tab will display an upload area where you can drop the zip file(s) previously created by the hnod-bundler tool.

In the future, we plan to provide a command line tool with the SDK to facilitate uploading a Service Package.

## Uninstall the SDK

When you want to stop using the sdk or upgrade to a new version, you will need to uninstall the SDK. To unlink the SDK, execute the following command from the sdk folder (where npm link was called previously).

npm unlink


This will remove the global symlinks that npm created. Afterwards you can safely delete the whole SDK folder. Be aware that code depending on the SDK (e.g. the examples) will no longer compile after this step.

## Troubleshoot

If any problems are encountered/mistakes are made when installing/setting up the SDK (i.e. running npm install at the wrong time or running yarn install instead) please delete both node_modules and package-lock.json (or yarn.lock respectively) before restarting the process. Otherwise npm will cache some of the incorrect configurations.