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.
This getting started guide demonstrates how to start a project using the Mappedin Web SDK. Following this guide results in a working demo with a map that you can interact with (zoom, pan, rotate etc).
Mappedin Web SDK v6 is available as @mappedin/mappedin-js@beta 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
Run these shell commands to set up a new project and install the Mappedin Web SDK.
Note that the Mappedin SDK 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.
yarn create vite mappedin-quickstartcd mappedin-quickstartyarn 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 Web SDK 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// https://developer.mappedin.com/v6/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.
- Log into the Mappedin Editor.
- Click on the
Developers
tab. - Click
Generate API Key
. - Enter a name for the key.
- Click
Generate Key
. - Store the
key
andsecret
is a safe and secure place.
Get a Map Id
Each map has a unique identifier used by Mappedin SDK to load a map. To get the mapId
of a map:
- Log into the Mappedin Editor.
- Click on the
Developers
tab. - Select the desired map from the dropdown.
- The
mapId
will be shown in the code snippet.
Find your Map Id from URL
- Publish your map by setting it from
Draft
toLive
- Open your map
- Grab your map Id from the URL. It is located between /map/{mapId}?floor=xyz.
Not seeing your map?
- Use of the Mappedin SDK 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 changeDraft
toLive
.
Local Development without NPM
While NPM is highly recommended for version control and to receive the latest bug fixes and features, the Mappedin Web SDK may also be imported from a CDN.
In this example JSDelivr will be used to demonstrate importing the mappedin-js
package. The Mappedin Web SDK 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/mappedin.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 Web SDK 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.