Getting Started

Mappedin SDK version 6 is currently in an alpha state while Mappedin perfects a new design. Breaking changes may occur, which will be posted in the v6 release notes.

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

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

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" />
    <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 Trial API key Terms and Conditions
// https://developer.mappedin.com/web/v6/trial-keys-and-maps/
const options = {
  key: '65ca6d27d53f21f234ae6395',
  secret: '0b25fc24d564c644443663d0b4d083605090d349975d0983fc96e06a5b1934dd',
  mapId: '65c0ff7430b94e3fabd5bb8c'
};

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

init();

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

Finding mapID

MapID can be found in the URL of your editor. Please refer to the screenshot below.

finding map ID in URL

Not seeing your map?

Use of the Mappedin SDK requires a Pro or Enterprise Map Account. Trial API Keys will only work for Mappedin demo maps.
Remember to click the 'Share' button to publish your map!

how to publish your map

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@alpha/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@alpha/lib/esm/index.js";

  // See Trial API key Terms and Conditions
  // https://developer.mappedin.com/web/v6/trial-keys-and-maps/
  const options = {
    key: "65ca6d27d53f21f234ae6395",
    secret: "0b25fc24d564c644443663d0b4d083605090d349975d0983fc96e06a5b1934dd",
    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@alpha/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@alpha/lib/esm/index.js";

      // See Trial API key Terms and Conditions
      const options = {
        key: "65ca6d27d53f21f234ae6395",
        secret: "0b25fc24d564c644443663d0b4d083605090d349975d0983fc96e06a5b1934dd",
        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.