Migration Guide

Mappedin SDK for React Native version 6.0 is a major release that includes a number of changes to the SDK. Mappedin SDK for React Native v6 uses a GeoJSON-based rendering engine, rebuilt from the ground up. It works in unison with MapLibre which enables outdoor base maps as well as data visualization features. By using GeoJSON as the core data format, v6 can integrated with existing external data sources. This guide explains the steps needed to migrate from version 5.

Support for Declarative Components

Mappedin SDK for React Native v6 supports declarative components. This means that you can use the MapView component to render the map and include child components such as Marker and Label. MapView replaces MiMapView. Refer to the Getting Started Guide for more information on how to use declarative components.

Imperative components are still supported.

New Hooks

Hook to access MapView and MapData

Mappedin SDK for React Native v6 includes new hooks to access the MapView, Mappedin.MapData and Mappedin.TEvents.

Hook for Events

Mappedin SDK for React Native v6 introduces a new event system. This means that you can use the useEvent hook to subscribe to events and trigger a callback when they occur.

Example of handling a click event:

v5

onClick={({ payload }) => {
  // The user clicked.
}}

v6

  useEvent("click", (payload: Mappedin.TClickPayload) => {
    // The user clicked.
  });

Initialization Changes

The options for getting a map have changed.

v5 Initialization

const venueOptions: TGetVenueOptions = {
  venue: VENUE,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
};

const RenderMap = () => {
  return (
    <SafeAreaView style={styles.fullSafeAreaView}>
      <MiMapView style={styles.mapView} key="mappedin" options={venueOptions} />
    </SafeAreaView>
  );
};

v6 Initialization

const App = () => {
  return (
    <View>
      <MapView
        mapData={{
          key: KEY,
          secret: SECRET,
          mapId: MAP_ID,
        }}
      options={{}}
      >
      </MapView>
    </View>
  );
};

Component Access

Mappedin.<collection> has been replaced by Mappedin.MapData.getByType(<collection>)

For example:

In v5 access nodes using Mappedin.nodes, which contains an array of Node objects.

In v6 access nodes using MapData.getByType('node'), which returns an array of Node objects.

Mappedin.getCollectionItemById is replaced by Mappedin.MapData.getById(<collection>, id)

The following classes have been redesigned. Refer to the chart below for a mapping of similar classes.

v5 Component	v6 Component
MappedinPolygon	Mappedin.Space
MappedinMapGroup	Mappedin.FloorStack
MappedinMap	Mappedin.Floor
MappedinCoordinate	Mappedin.Coordinate
MappedinNode	Mappedin.Node

MapViewStore.state no longer exists. These states are now available within their respective classes Mappedin.BlueDot.state and Mappedin.StackedMaps.state.

UI Components

FloatingLabels have been replaced with Label (declarative) and Mappedin.Labels (imperative).

FloatingLabels.labelAllLocations() has been replaced with Labels.all().

Tooltips have not been carried over from v5 and Marker should be used instead.

Updating UI Components

setPolygonColor, clearPolygonColor and other methods of changing the state of UI objects on the map is now performed using MapViewControl.updateState(), which also supports initial for returning properties to their original state.

Mappedin.Camera.animate() has been renamed to Mappedin.Camera.animateTo().

Mappedin.Markers.animate() has been renamed to Mappedin.Markers.animateTo().

Interactivity

MapViewStore.addInteractivePolygon() has been replaced by updating the state of each space to be interactive as shown below.

// Set each space to be interactive.
mapData.getByType('space').forEach(space => {
    mapView.updateState(space, {
        interactive: true,
    });
});

Event names passed from MapView.on() have been changed and are now defined in Mappedin.TEvents.

v5 Event	v6 Event
E_SDK_EVENT.CLICK	click
E_SDK_EVENT.MAP_CHANGED , E_SDK_EVENT.MAP_CHANGED_WITH_REASON	floor-change
E_SDK_EVENT.OUTDOOR_VIEW_LOADED	outdoor-view-loaded

Map Metadata

Classes containing enterprise map metadata have been renamed.

v5 Component	v6 Component
MappedinCategory	Mappedin.EnterpriseCategory
MappedinLocation	Mappedin.EnterpriseLocation
MappedinVenue	Mappedin.EnterpriseVenue

Wayfinding & Directions

MappedinNavigatable.directionsTo() is replaced by MapViewControl.getDirections().

MapViewControl.getDirections() only supports getting directions between two locations. For multi destination directions, use MapViewControl.getDirectionsMultiDestination().

Journey is now Navigation.

v5 Multi Destination Directions

const directions = getDirections(start, [dest1, dest2]);

v6 Multi Destination Directions

const directions = getDirectionsMultiDestination(start, [dest1, dest2]);

Camera

v5 Camera.tilt in radians is replaced by v6 Mappedin.Camera.pitch in degrees. Camera.minPitch and Camera.maxPitch are now available to set the minimum and maximum pitch values.

v5 Camera.rotation in radians is replace in v6 by Mappedin.Camera.bearing in degrees clockwise rotation is now positive.

v5 Camera.zoom, Camera.minZoom and Camera.maxZoom used meters from ground level. In v6 these now use mercator zoom level units.

The following camera methods and accessors have been renamed.

v5 Method	v6 Method
Camera.position()	Camera.center()
Camera.setSafeAreaInsets()	Camera.setScreenOffsets()
Camera.getSafeAreaInsets()	Camera.screenOffsets()
MapView.Camera.on(...)	useEvent(...)
E_CAMERA_EVENT.USER_INTERACTION_START	useEvent('user-interaction-start')
E_CAMERA_EVENT.USER_INTERACTION_END	useEvent('user-interaction-end')
E_CAMERA_EVENT.CHANGED	useEvent('camera-change')

Search

OfflineSearch has been moved to Mappedin.MapData.search(). The results returned in SearchResult are more structured:

const results = mapData.Search.query('levis');
// results
{
	places: SearchResultPlaces[];
	enterpriseLocations?: SearchResultEnterpriseLocations[];
	enterpriseCategories?: SearchResultEnterpriseCategory[];
}

Multi Language

The methods to work with maps in multiple languages have been changed.

// Specify a non default language when getting map data.
const options = {
    key: 'key',
    secret: 'secret',
    mapId: 'mapId',
    language: 'en',
};
// Get supported languages.
const supportedLanguages = mapData.getByType('enterprise-venue')[0].languages;
// Change languages
await mapData.changeLanguage('es');

Blue Dot

Blue Dot events have moved from BlueDot.on() to useEvent().

v5

const blueDotChangeHandler = ({ map, nearestNode, position, bearing }) => {
    // Do something with the new values
};
mapView.BlueDot.on(E_BLUEDOT_EVENT.POSITION_UPDATE, blueDotChangeHandler);

v6

// Position update
useEvent('blue-dot-position-update', e => {
    console.log('blue-dot-position-update', e.coordinate, e.floor, e.accuracy, e.heading);
});

// State change
useEvent('blue-dot-state-change', e => {
    console.warn('blue-dot-state-change', e.state, e.action);
});

// Error
useEvent('blue-dot-error', e => {
    console.error('blue-dot-error', e);
});

BlueDot.updateBearing() functionality has been moved to the Mappedin.BlueDot.update() method and is provided using the heading property. In v6, to remove the heading unset it in the update method as shown below, otherwise it will use the heading provided from the browser.

mapView.BlueDot.update({ heading: undefined });

PositionUpdater has been removed. The same functionality can be achieved by calling BlueDot.enable({ watchBrowserPosition: false }) and then calling the Mappedin.BlueDot.update() method.

Blue Dot rotation mode was set when enabling Blue Dot in v5 using TEnableBlueDotOptions.useRotationMode. In v6, this is set by calling Mappedin.BlueDot.follow and setting the Mappedin.TFollowMode.

The v5 behavior of TEnableBlueDotOptions.allowImplicitFloorLevel has changed. In v5 it assumed the user was always on the default map if no level update was provided by the indoor positioning provider. In v6, if the floor cannot be determined Blue Dot will render on every floor by default. If the position update has a floorLevel, it will only render on that floor. To force it to render on all floors set floorOrFloorId to undefined:

mapView.BlueDot.update({ floorOrFloorId: undefined });

Blue Dot smoothing has not been carried over from v5.