Migration Guide
On November 22, 2021 we released the Mappedin Web SDK v4. This short migration guide explains the steps needed to migrate from version 1.
- The SDK is available on NPM at https://www.npmjs.com/package/@mappedin/mappedin-js
- API reference on our Developer Portal at https://docs.mappedin.com/web-sdk-api/v4/v4.1.5/
Initialization
- Removed
mappedin.initialize
in favor ofgetVenue
andshowVenue
. This makes it easier to create applications where the map is not displayed immediately but the venue data is used such as directories of locations.getVenue
downloads the map data from the server. - Added
showVenue
method, which renders the map in the givenHTMLElement
and resolves when the map is interactive. That is when you can add interactive polygons or draw labels on the map.
showVenue<T extends Mappedin>(
el: HTMLElement,
venue: T,
options?: TMapViewOptions): Promise<MapView>
In v4, the map is initialized by getting the data and then displaying it. It also simplifies the options for rendering the map.
async function init() {
const venueData = await getVenue({
clientId: '<clientId>',
clientSecret: '<clientSecret>',
venue: '<venue>',
});
const mapView = await showVenue(document.getElementById('mappedin-map'), venueData);
}
document.addEventListener('DOMContentLoaded', init);
In v1, the map would be initialized like this:
const options = {
mapview: {
antialias: 'AUTO',
mode: Mappedin.modes.TEST,
},
venue: {
venue: '<venue>',
clientId: '<clientId>',
clientSecret: '<clientSecret>',
perspective: 'Website',
things: {
venue: ['slug', 'name'],
maps: ['name', 'elevation', 'shortName'],
},
},
};
Mappedin.initialize(options, document.getElementById('mappedin-map'));
The two types of labels
Floating Label, previously called Smart Labels are the default type of label. These labels feature a marker at a given location, followed by text describing that location. Legacy labels were renamed to a more descriptive name Flat Label. Their text is drawn on top of the location polygon.
Both accept an their own appearance objects to customize their appearance. Floating label marker default size has been reduced slightly.
Using Floating Labels and customizing their appearance:
mapView.labelAllLocations({
appearance: {
marker: {
size: 12,
backgroundColor: {
active: '#bf4320',
inactive: '#efefef',
},
},
},
});
Using Flat Labels and customizing their appearance:
mapView.labelAllLocations({
flatLabels: true,
appearance: {
color: '#0055bb',
},
});
Improved events
Removed old Events (onPolygonClicked, etc) in favor of new ENUM
-based events with payload type checking:
- E_SDK_EVENT.STATE_CHANGE
- E_SDK_EVENT.POLYGON_CLICKED
- E_SDK_EVENT.NOTHING_CLICKED
- E_SDK_EVENT.MAP_CHANGED
You can import the events with import { E_SDK_EVENT } from "@mappedin/mappedin-js";
.
To listen to polygon clicks, you can start listening to that event in the init
function after showVenue
has resolved and the polygons have been made interactive:
mapView.addInteractivePolygonsForAllLocations();
mapView.on(E_SDK_EVENT.POLYGON_CLICKED, (polygon) => {
console.log(`Polygon with id ${polygon.id} clicked!`);
});
Upgraded API for getting directions
- Removed Navigator in favor of new Journey API
MapView.Journey {
draw: (directions: MappedinDirections, options?: TJourneyOptions) => void;
setStep: (step: number) => void;
clear: () => void;
}
Simplified BlueDot API
API Documentation for the new simplified BlueDot API is at https://docs.mappedin.com/web-sdk-api/v4/v4.1.5/classes/BlueDotLayer.html.
MapView.BlueDot.enable({ showBearing: true });
MapView.BlueDot.disable();
To listen to BlueDot position updates you can now do the following:
mapView.BlueDot.on(E_BLUEDOT_EVENT.POSITION_UPDATE, (payload) => console.log(payload));
Available BlueDot events:
- BLUEDOT_POSITION_UPDATE
- BLUEDOT_STATE_CHANGE
Simplified Camera API
New simplified Camera API (Documentation) moved from mapView.CameraControls
MapView.Camera {
zoom,
tilt,
rotation,
focusOn(),
set(),
animate()
}
We can react to to camera events (E_CAMERA_EVENT) by setting the listener:
mapView.Camera.on(E_CAMERA_EVENT.ROTATION_CHANGED, (payload) => {
console.log(payload, 'radians');
});
Available camera events are:
- USER_INTERACTION_START
- USER_INTERACTION_END
- ZOOM_CHANGED
- ROTATION_CHANGED
- TILT_CHANGED
Setting camera rotation, tilt or zoom (or a combination of these) is easy with the new set
method:
mapView.Camera.set({
rotation: Math.PI, // radians
});
Tooltip changes
Aligned tooltip API to be closer to Markers so that it takes a position indicated by a node or a coordinate followed by an options object.
createTooltip(
node: MappedinNode | MappedinCoordinate,
options:
| TCreateTextTooltipOptions
| TCreateCustomInnerHTMLTooltipOptions
| TCreateCustomTooltipOptions
Using geocoordinates
mapView.getPositionLatLon
and mapView.convertTo3DMapPosition
are deprecated. Use MappedinMap.createCoordinate()
instead to create a marker based on latitude and longitude.
const coordinate = venue.maps[1].createCoordinate(43.52091191291561, -80.53964096309828);
mapView.createMarker(coordinate, `<div style="background: white; padding: 4px">Hello world</div>`, {
anchor: MARKER_ANCHOR.CENTER,
});
Path display
When calculating path widths, we previously used scaled units. In v4 these are set in meters. The default nearRadius
value in PathOptions has been changed from 20 to 1.8. Correspondingly the farRadius
is now 2.3 * nearRadius
by default. These values are approximately the same, however some variation may occur depending on the venue scale. oldNearRadiusInMetres = 20 * map.scale
will give you the exact value to use with v4 to keep the path width identical. Documentation at https://docs-staging.mappedin.net/web-sdk-api/v4/v4.1.5/modules.html#TPathOptions
The default for drawing a path was changed so that the path pulse fires only once and the animation takes longer. To keep the previous infinite pulse behavior you can set the following path options when drawing a Journey:
mapView.Journey.draw(directions, {
pathOptions: {
pulseIterations: Infinity,
},
});
Other deprecations
mapView.colors
deprecated. UsemapView.setHoverColor
for hover, and pass color directly elsewhere- Removed Outdoor Context
- Removed
VIEW_STATE