Skip to main content
Version: 6.0

Getting Started

Mappedin SDK version 6 is currently in a beta state while Mappedin perfects new features and APIs. Open the v6 release notes to view the latest changes.
Using Mappedin JS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

This getting started guide demonstrates how to start a project using Mappedin JS. Following this guide results in a working demo with a map that you can interact with (zoom, pan, rotate etc).

Mappedin JS v6 is available as @mappedin/mappedin-js in NPM.

Video Walkthrough​

Local Development​

For local development, start a project using Vite. Refer to the Vite Getting Started guide for setup details. Guides are written in TypeScript (JavaScript), as the SDK is written in Typescript and uses comprehensive types.

1. Create a Project​

Note that Mappedin JS version 6 is currently in an beta state. Therefore you must append @beta when adding the Mappedin package. Failing to do so will add the current production release of version 5, which does not support maps in the Free, Pro or Plus tiers.

Run these shell commands to set up a new project and install Mappedin JS.

yarn create vite mappedin-quickstart
cd mappedin-quickstart
yarn add @mappedin/mappedin-js@beta

2. Update index.html, main.ts​

Modify & update the contents of index.html to match the following.

<!DOCTYPE html>
<html>
	<head>
		<title>Mappedin JS v6 Getting Started</title>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8" />
		<style>
			* {
				margin: 0;
				padding: 0;
			}
			html,
			body {
				width: 100%;
				height: 100%;
			}
			#mappedin-map {
				height: 100%;
				width: 100%;
				position: relative;
			}
		</style>
	</head>
	<body>
		<div id="mappedin-map"></div>
		<script type="module" src="src/main.ts"></script>
	</body>
</html>

Create or update a file under the src directory called main.ts. Write the following contents to the file.

import { getMapData, show3dMap } from '@mappedin/mappedin-js';
import '@mappedin/mappedin-js/lib/index.css';

// See Demo API key Terms and Conditions
// /docs/demo-keys-and-maps
const options = {
	key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
	secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
	mapId: '65c0ff7430b94e3fabd5bb8c',
};

async function init() {
	const mapData = await getMapData(options);
	const mapView = await show3dMap(document.getElementById('mappedin-map') as HTMLDivElement, mapData);
}

init();

3. Run the Project​

To run the demo (with hotloading), use the following command:

yarn run dev

The following CodeSandbox demonstrates what should be shown.

This should result in a prompt showing the project being served at http://127.0.0.1:5173 (default port). The 3D rendered map can be zoomed, panned and rotated via mouse or fingers.

Create a Key & Secret​

A key and secret to use Mappedin Demo maps can be found on the Demo Keys & Maps Page. To use your own maps, create your own unique key and secret.

Using maps with your own key and secret requires a Pro or Enterprise Map Account.

  1. Log into the Mappedin Editor.
  2. Click on the Developers tab.
  3. Click Generate API Key.
  4. Enter a name for the key.
  5. Click Generate Key.
  6. Store the key and secret is a safe and secure place.

Generate Key on Mappedin Dashboard

Get a Map Id​

Each map has a unique identifier used by Mappedin JS to load a map. To get the mapId of a map:

  1. Log into the Mappedin Editor.
  2. Click on the Developers tab.
  3. Select the desired map from the dropdown.
  4. The mapId will be shown in the code snippet.

Map Id from Dashboard

Find your Map Id from URL​

  1. Publish your map by setting it from Draft to Live
  2. Open your map
  3. Grab your map Id from the URL. It is located between /map/{**mapId**}?floor=xyz.

Find Map Id

Not seeing your map?​

  • Use of Mappedin JS requires a Pro or Enterprise Map Account. Demo API Keys will only work for Mappedin demo maps.
  • Remember to set the map to Live. To do so click on the Share Maps button and change Draft to Live.

Share Map -&gt; Live

Authenticating with a Bearer Token​

Mappedin JS can also be authenticated with a short lived bearer token. This can be used to prevent exposing an API key and secret by generating a token on the server side. The server can securely store the API key and secret, allowing the client to use the token to authenticate with Mappedin JS.

To do so, make a request to the API Key REST endpoint sending the API key and secret. The following TypeScript example shows how to do this using a fetch request. Additional examples can found in the API Key REST documentation.

async function getAccessToken(): Promise<string> {
	// See Trial API key Terms and Conditions
	// https://developer.mappedin.com/docs/demo-keys-and-maps
	const response = await fetch('https://app.mappedin.com/api/v1/api-key/token', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			key: 'YOUR_KEY',
			secret: 'YOUR_SECRET',
		}),
	});

	const data: TokenResponse = await response.json();
	return data.access_token;
}

The API Key REST endpoint will return JSON that contains the bearer token.

{
	"access_token": "…",
	"expires_in": 172800
}

The bearer token can then be used to authenticate with Mappedin JS as shown in the following example.

const options = {
	accessToken: 'your-access-token',
};
const mapData = await getMapData(options);
const mapView = await show3dMap(document.getElementById('mappedin-map')
	as HTMLDivElement, mapData);

Local Development without NPM​

While NPM is highly recommended for version control and to receive the latest bug fixes and features, Mappedin JS may also be imported from a CDN.

In this example JSDelivr will be used to demonstrate importing the mappedin-js package. Mappedin JS is also available on unpkg. Please feel free to reach out if the SDK is not available on a preferred CDN.

Import the SDK stylesheet in the document <head> and any other necessary styles for the app.

<link href="https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@beta/lib/index.css" rel="stylesheet" />
<style>
	* {
		margin: 0;
		padding: 0;
	}
	html,
	body {
		width: 100%;
		height: 100%;
	}
	#mappedin-map {
		height: 100%;
		width: 100%;
		position: relative;
	}
</style>

In the <body>, include the element which the map will attach too and the script to asynchronously load the MapView.

<div id="mappedin-map"></div>
<script type="module">
	import { getMapData, show3dMap } from 'https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@beta/lib/esm/index.js';

	// See Demo API key Terms and Conditions
	// https://developer.mappedin.com/web/v6/demo-keys-and-maps/
	const options = {
		key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
		secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
		mapId: '65c0ff7430b94e3fabd5bb8c',
	};

	getMapData(options).then(async (mapData) => {
		const mapView = await show3dMap(document.getElementById('mappedin-map'), mapData);
	});
</script>

Putting it all together, the entire HTML document should resemble the following.

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<meta http-equiv="X-UA-Compatible" content="ie=edge" />
		<link href="https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@beta/lib/index.css" rel="stylesheet" />
		<style>
			* {
				margin: 0;
				padding: 0;
			}
			html,
			body {
				width: 100%;
				height: 100%;
			}
			#mappedin-map {
				height: 100%;
				width: 100%;
				position: relative;
			}
		</style>
		<title>Mappedin JS v6 Getting Started with JSDelivr</title>
	</head>
	<body>
		<div id="mappedin-map"></div>
		<script type="module">
			import {
				getMapData,
				show3dMap,
			} from 'https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@beta/lib/esm/index.js';

			// See Demo API key Terms and Conditions
			const options = {
				key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
				secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
				mapId: '65c0ff7430b94e3fabd5bb8c',
			};

			getMapData(options).then(async (mapData) => {
				const mapView = await show3dMap(document.getElementById('mappedin-map'), mapData);
			});
		</script>
	</body>
</html>

With only the above document, a map will be rendered into the window. Just like with NPM, the 3D rendered map can be zoomed, panned and rotated via mouse or fingers.

Debug Mode​

Use Debug Mode to get a closer look at how various map components behave and interact. Here's how to enable it:

1. Enable Debug Mode​

To activate the debug interface, call the following function in your code:

mapView.enableDebug();

enableDebug displays a panel on the right side of the map, revealing several tools and controls for direct interaction with the map’s elements.

2. Navigating the Debug Panel​

The debug panel provides access to a variety of controls:

Geometry Controls

  • Adjust individual geometry settings, such as color, opacity, visibility. These controls make it easy to see how different elements respond to changes.

Interactivity

  • Use toggles to turn interactivity on/off
  • Change colors and hover effects to highlight specific areas

Scene Controls

  • Manage the overall scene settings, such as scaling, positioning, and group management. Toggle the visibility of groups or containers within the scene
  • Adjust padding, scale, and watermark positioning
  • Markers & Labels — Add, remove, or edit markers and labels directly through the panel

Camera Controls

  • Fine-tune camera settings, including zoom levels, pitch, and center position
  • Set minimum and maximum zoom levels
  • Adjust the focus to a specific area or level

enable debug