How the Mapsted Maps JavaScript API Works

The Mapsted Maps JavaScript API uses an iframe architecture to embed interactive indoor maps in your web page.

Architecture Overview

┌──────────────────────────────────────────────┐
│  Your Web Page (parent)                      │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │  Mapsted Maps JavaScript API (JS API)  │  │
│  │  - init(), selectEntity()              │  │
│  │  - on(), off(), once()                 │  │
│  └──────────────────┬─────────────────────┘  │
│                     │ postMessage            │
│  ┌──────────────────▼─────────────────────┐  │
│  │  <iframe>                              │  │
│  │  Mapsted Maps Web App                  │  │
│  │  - React + OpenLayers                  │  │
│  │  - Floor data, tiles, POIs             │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

Communication Protocol

All communication between your code and the map happens via the browser's window.postMessage() API:

1. Commands (parent → iframe): Your code calls selectEntity(42) → API sends { type: 'SELECT', payload: { entityId: 42 } } to the iframe.
2. Events (iframe → parent): User clicks an entity → iframe sends { type: 'select', payload: { entityId: 42 } } → API dispatches via on('select', handler).

Security

• Origin validation: The API validates that incoming messages come from the expected iframe origin.
• Input sanitisation: All payloads are checked for prototype pollution, size limits, and structural validity.

See also: Lifecycle | Event System