Web SDK v4 - Migration guide | Web SDK v4 | Mappedin Developer Portal

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://developer.mappedin.com/docs/web/latest

Initialization

Removed mappedin.initialize in favor of getVenue and showVenue. 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 given HTMLElement 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://developer.mappedin.com/docs/web/latest/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
});

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://developer.mappedin.com/docs/web/latest/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. Use mapView.setHoverColor for hover, and pass color directly elsewhere
Removed Outdoor Context
Removed VIEW_STATE

Web SDK v4 - Migration guide