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-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 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 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 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.

Map Id from Dashboard

Find your Map Id from URL

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

Find Map Id

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 change Draft to Live.

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.