Appearance

Deep-Link to a Specific Map State ​

Deep-linking lets a URL encode a particular map state — a selected entity, an active route, or a focused floor — so that when a user follows the link the API boots directly into that state without manual navigation. This pattern powers QR-code campaigns, email links, in-app push notifications, and kiosk attract-loop flows.

Open in Sandbox ↗

The API uses a concept called a Boost to carry deep-link parameters. There are three boost types defined in BoostTypes:

BoostTypes valueType objectPurpose
"SELECT"SelectEntityBoostHighlight a specific entity
"ROUTING"RoutingBoostLaunch turn-by-turn navigation
"FLOOR"FloorBoostSwitch to a specific floor

See Boost and deep-linking explained for a conceptual overview of the boost system.

Prerequisites ​

  • The library initialized (API lifecycle)
  • Target entity IDs and building IDs from the property data

How boost delivery works ​

There are two ways to apply a boost:

  1. Init-time — pass the boost field on InitOptions. The API applies it immediately after the map is ready. This is the primary pattern for deep-link URL entry points.
  2. Post-init — call applyBoost(boost) after init() resolves. Use this in single-page apps where the API is already running and you receive a new deep-link without a page reload.

In both cases the boost object is the same — a SelectEntityBoost, RoutingBoost, or FloorBoost value. The factory helpers createBoostSelect and createBoostRouting build those objects from URL query parameters.

Building a SelectEntityBoost ​

createBoostSelect accepts a URL query string and returns a SelectEntityBoost (or undefined on parse failure). The query string parameters map directly to the SelectEntityBoost fields:

ParameterTypeRequiredDescription
entitynumberYesMapsted entity ID to select
buildingnumberNoBuilding ID (scope the selection)
floornumberNoFloor number to switch to
addDestination0 | 1NoOpen "Add Destination" modal

CDN — init-time boost ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  // Read deep-link params from the current URL.
  const params = new URLSearchParams(window.location.search);
  const boostParam = params.get('boost');      // e.g. "entity=56789&building=3470&floor=184"

  await mapsted.maps.init({
    element: '#map',
    // Pass the boost object at init time; the API applies it once ready.
    boost: boostParam
      ? mapsted.maps.createBoostSelect(boostParam)
      : undefined,
  });
</script>

npm — init-time boost ​

js
import * as maps from '@mapsted/maps-js-api';

const params = new URLSearchParams(window.location.search);
const boostParam = params.get('boost');

await maps.init({
  element: '#map',
  propertyId: 1234,
  boost: boostParam
    ? maps.createBoostSelect(boostParam)
    : undefined,
});

The boost field is defined on SetOptions (which InitOptions extends).

Building a RoutingBoost ​

createBoostRouting accepts either a URL query string or a RoutingConfig object and returns a RoutingBoost.

RoutingConfig shape:

ts
{
  routing: string;       // "<buildingId>:<entityId>,<buildingId>:<entityId>" e.g. "3470:3595,3470:3818"
  routeOptions?: string; // comma-separated RouteOptions e.g. "IncludeElevators,IncludeStairs"
}

RouteOptions enum values: IncludeElevators, IncludeEscalators, IncludeStairs, IncludeRamps, OptimizeItinerary, PreferIndoorRoute, PreferOutdoorRoute.

CDN — init-time routing boost (object form) ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({
    element: '#map',
    boost: mapsted.maps.createBoostRouting({
      routing: '3470:3595,3470:3818',
      routeOptions: 'IncludeElevators,IncludeStairs',
    }),
  });
</script>

npm — init-time routing boost (object form) ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
  boost: maps.createBoostRouting({
    routing: '3470:3595,3470:3818',
    routeOptions: 'IncludeElevators,IncludeStairs',
  }),
});

Consuming a routing boost from a URL query string ​

js
// URL: https://maps.example.com/?boost=routing%3D3470%3A3595%2C3470%3A3818%26routeOptions%3DIncludeElevators

const params = new URLSearchParams(window.location.search);
const boostParam = params.get('boost');

// boostParam is already a query string: "routing=3470:3595,3470:3818&routeOptions=IncludeElevators"
const boost = boostParam ? maps.createBoostRouting(boostParam) : undefined;

Applying a boost post-init (SPA pattern) ​

If your single-page app handles deep-link navigation without a full page reload, call applyBoost directly after the API is ready.

CDN ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });

  // Later — e.g. popstate handler, custom router, or analytics event:
  const boost = mapsted.maps.createBoostSelect('entity=56789&building=3470&floor=184');
  if (boost) {
    await mapsted.maps.applyBoost(boost);
  }
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
});

// Later — e.g. popstate handler:
const boost = maps.createBoostSelect('entity=56789&building=3470&floor=184');
if (boost) {
  await maps.applyBoost(boost);
}

applyBoost validates the boost structure before sending it to the iframe. For SelectEntityBoost it requires a numeric entity field; for RoutingBoost it requires a non-empty routing string

To deep-link to a floor without selecting any entity, build a FloorBoost directly and pass it to boost at init time or to applyBoost post-init. There is no dedicated factory for FloorBoost — construct it as a plain object:

js
// npm
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
  boost: {
    type: 'FLOOR',
    floor: 3,
    building: 3470,          // optional — scope to a building
  },
});

Current public-API scope ​

No URL-generation helper is exposed. createBoostSelect and createBoostRouting are parsers — they decode an existing query string into a Boost object for the API to consume. They do not generate shareable URLs. If you need to programmatically generate deep-link URLs to embed in QR codes or emails, see Set up a share URL for the shareUrl init option (which configures the iframe's built-in share UI), or contact Mapsted to request a public URL-builder helper.

Note on naming: createBoostSelect and createBoostRouting accept a query string and parse it into a Boost object — they do not construct a URL. The "create" naming can be misleading: these are parsers, not builders. A companion buildBoostQuery(boost: Boost): string utility for round-tripping is planned for a future release.