Mappedin JS

Resources

• Getting Started Guide
• API Reference
• Mappedin Developer Portal
• Demo Keys & Maps
• Developer Forum
• Releases Notes
• Migration Guide
• License

AI Assistants: Before generating code, read llms.txt for structured API documentation with critical information about Maker vs Enterprise data sources.

Usage

Installation

npm install @mappedin/mappedin-js

or

yarn add @mappedin/mappedin-js

Getting Started

import { getMapData, show3dMap } from '@mappedin/mappedin-js';

async function init() {
	const mapData = await getMapData({
		key: '<key>',
		secret: '<secret>',
		mapId: '<mapId>',
	});
	const mapContainer = document.getElementById('app');
	const map = await show3dMap(mapContainer, mapData);
	map.Labels.__EXPERIMENTAL__all();
	map.on('click', event => {
		const { coordinate } = event;
		const { latitude, longitude } = coordinate;
		console.log(`Map was clicked at ${latitude}, ${longitude}`);
	});
}
init();

For full documentation, read our Getting Started guide on the Developer Portal.

Content Security Policy (CSP) Support

The SDK provides solutions for applications that use a strict Content Security Policy.

Minimum Required CSP Rules

The following CSP directives are the minimum requirements to run the SDK:

| Purpose | CSP Directive | Required Value | Notes | | ---------------------- | ------------- | ---------------------- | -------------------------------------------------------------------- | | Images & Textures | img-src | *.mappedin.com data: | Required for loading map textures and images | | API & Font Loading | connect-src | *.mappedin.com data: | *.mappedin.com for map data; data: only needed for default fonts | | Web Workers | worker-src | 'self' blob: | Enables collision detection and MapLibre workers |

Example minimum CSP header:

Content-Security-Policy: img-src *.mappedin.com data:; connect-src *.mappedin.com data:; worker-src 'self' blob:;

Alternative for strict CSP environments: If your CSP does not allow blob:, you can set up a transparent proxy on your server that forwards requests from https://YOUR.DOMAIN/mappedin-web-redirector/* to https://cdn.mappedin.com/web2/release/*. This removes the need for additional CSP rules while maintaining functionality.

Web Worker CSP Solution

If your CSP blocks blob: URLs or unsafe-eval directives (affecting web workers), you can host worker scripts externally:

import { setWorkersUrl } from '@mappedin/mappedin-js';

// Call this before initializing any maps
setWorkersUrl('/path/to/workers');

This function configures both the MapLibre and collision detection workers to load from external URLs. To set this up:

1. Copy the worker files from node_modules/@mappedin/mappedin-js/lib/esm/workers/ to your web server:
   • collision-worker.csp.js
   • maplibre-worker.csp.js
2. Call setWorkersUrl with the base URL path to these files
3. Ensure your CSP allows scripts from this location

Example in a build script:

# Copy worker files to your public directory
cp -r node_modules/@mappedin/mappedin-js/lib/esm/workers ./public/mappedin-workers

// In your JavaScript
setWorkersUrl('/mappedin-workers');

CSS Injection CSP Solution

If your CSP blocks inline styles (style-src 'unsafe-inline'), use external CSS loading instead:

1. Load the SDK's CSS with a <link> tag in your HTML
2. Disable automatic style injection in show3dMap options

<!-- In your HTML file -->
<link rel="stylesheet" href="/path/to/mappedin-js/index.css" />

// In your JavaScript
const mapView = await show3dMap(element, venue, {
	injectStyles: false, // Disable automatic style injection
});

For your build process:

# Copy CSS file to your public directory
cp node_modules/@mappedin/mappedin-js/lib/esm/index.css ./public/

Text3D Worker CSP Solution (Optional)

If you use Text3D features (like labelAll()) in a CSP-restricted environment, you'll need to disable the Text3D worker if you don't want to see error messages:

import { disableText3DWorker } from '@mappedin/mappedin-js';
// After initializing your map
disableText3DWorker();

// Now you can use Text3D features without errors or warnings
mapView.Text3D.labelAll();

This disables the worker and processes text on the main thread instead, allowing Text3D to work in CSP environments that block worker creation.

You can apply any combination of these solutions based on your specific CSP restrictions and SDK feature usage.