@redia-as/libry-universal-wayfinding-maps-sdk

v28.0.0

Published

5 months ago

# Changelog ## Breaking 🔥 ## New features update mapspeople sdk to 4 ## Fixes

Downloads

0High
0Medium
0Low

Libry Universal Wayfinding

Changelog

Breaking 🔥

New features

update mapspeople sdk to 4

Fixes

Use on website

Getting started

Include the JavaScript library in the <head/> of your HTML file.

<script src="https://unpkg.com/@redia-as/libry-universal-wayfinding-maps-sdk@{VERSION}/dist/main.umd.js"></script>

Replace the {VERSION} with your preferred version or "latest" to always get the latest version. Go here for a list of all available versions.

Note: As this is still work-in-progress, using latest can break stuff.

Include the following code in the <body>of your html file and replace the {CUSTOMER_ID}, {BRANCH_ID} and {API_KEY}.

<script src="https://unpkg.com/@redia-as/libry-universal-wayfinding-maps-sdk@latest/dist/main.umd.js"></script>
<div id="wayfinding-map" style="width: 400px; height: 300px;"/>
<script>
    window.addEventListener("DOMContentLoaded", () => {
        window.libryWayfinding.init(
        "{CUSTOMER_ID}",
        "{BRANCH_ID}",
        "{API_KEY}",
        'prod' // can be 'staging' or 'prod'
      ).then(async () => {
          const wayfindingId = getWayfindingId(); // Your function for getting the wayfindingId.
          const hasLocations = window.libryWayfinding.wayfindingIdHasLocations(wayfindingId); // Check if a wayfindingId has any locations that can be shown on the map
          if (hasLocations) {
              await window.libryWayfinding.createMap({
                // Container ID of the html element holding the map
                container: "wayfinding-map",
                center: { lng: 10.7528, lat: 59.9086 }, // can be ommited and the center will be the coordinates of the deviceLocation.
                zoom: 19.0,
                deviceLocation: {
                    floor: 3
                    lngLat: { lng: 10.7528, lat: 59.9086 },
                    heading: 70
                },
                // Shows a dot indicating the current device/user location
                showDevicePosition: true
            });
            // Wait for the map to load with the ready event.
            window.libryWayfinding.once("ready", map () => {
                // It is now safe to interact with the map.
                
                // Add the wayfinding marker.
                map.addPoiMarkerByWayfindingId(wayfindingId, {
                    color: "red",
                    onClick: (e, markerOpts) => {
                        alert(`You clicked ${wayfindingId}`)
                    }
                })
                // Add another custom marker.
                map.addMarker({
                    color: "yellow",
                    imgUrl: "marker.png",
                    flyTo: true,
                    location: { 
                    lngLat: { lng: 10.7528, lat: 59.9086 },
                    floor: 3
                    },
                    onClick: (e, markerOpts) => {
                    alert(`You clicked ${wayfindingId}`)
                    }
                })
            })
          }
          else {
              // There are no locations to show. Dont show map.
          }
      });
    })
</script>

Environment

'prod' or 'staging' can be given in the init function to either use real production or the test environment.

Markers

There a 3 ways to add a marker to the map:

Custom marker
POI marker
Wayfinding marker

Custom marker

map.addMarker({
location: { 
    lngLat: { lng: 10.7528, lat: 59.9086 },
    floor: 3
},
color: "red",
flyTo: true,
onClick: (e, markerOpts) => {
    alert(`You clicked a marker!`)
}
})

POI marker

const poi = 12345 // Some poi.
map.addPoiMarker(poi, {
imgUrl: "marker.png",
flyTo: true,
onClick: (e, markerOpts) => {
    alert(`You clicked ${poi}`)
}
})

Wayfinding marker

For more about wayfinding ids, see Wayfindind IDs.

const wayfindingId = getWayfindingId(); // Your function for getting the wayfindingId.
map.addPoiMarkerByWayfindingId(wayfindingId, {
color: "red",
onClick: (e, markerOpts) => {
    alert(`You clicked ${wayfindingId}`)
}
})

Clearing all markers

map.clearMarkers()

Routes

You can draw routes on the map from an origin and a destination point.

Custom route to a destination

map.findWayToLocation({
    lngLat: { lng: 10.7528, lat: 59.9086},
    floor: 0
},{
    lngLat: { lng: 10.7328, lat: 59.9586},
    floor: 2
})

Route to a wayfindingId

const wayfindingId = getWayfindingId();
map.findWayToLocation({
    // You can also omit the origin point and the device location will then be used.
    lngLat: { lng: 10.7528, lat: 59.9086},
    floor: 0
}, wayfindingId)

Clearing all routes

map.clearRoutes()

Check if there are any locations of a wayfindingId

Quite often you dont want to show a map if there are no locations for a wayfindingId. You can use the wayfindingIdHasLocations function to check just that and then call createMap to show the map.

const wayfindingId = getWayfindingId(); // Your function for getting the wayfindingId.
const hasLocations = await  window.libryWayfinding.wayfindingIdHasLocations(wayfindingId);

Tours

A tour is a collection of locations that can be navigated through on the map. You create a tour with a wayfinding id that refers to a collection of wayfinding ids.

const wayfindingId = getWayfindingId(); // Your function for getting the wayfindingId.
map.createTour(wayfindingId, 
// The maker that will be used for each location.
{
color: "red",
imgUrl: "marker.png",
flyTo: true,
onClick: (e, markerOpts) => {
    alert(`You clicked ${wayfindingId}`)
}
})
tour.next(); // call to go to the next marker
tour.back();// call to go to the previous marker
tour.show(wayfindingId); // call to go to a specific marker

Show the current user's location on the map

To show the current user's location on the map you need to update the device location of the map with the updateDeviceLocation() method. You can use the browsers geolocation api or other sources to get the current user's location. This is a contrived example. You can just use the useGeolocationApi(true) method to achieve the same functionality. Most likely you would use this method when integrating with a native app, where you get the coords from the device.

window.libryWayfinding.on("ready", (map) => {
  // Update the longitude and latitude
  navigator.geolocation.getCurrentPosition((position) => {
    map.updateDeviceLocation({
      lngLat: {
        lng: position.coords.longitude,
        lat: position.coords.latitude,
      },
    });
  });

  // You can also update the floor, accuracy and heading.
  navigator.geolocation.getCurrentPosition((position) => {
    map.updateDeviceLocation({
      accuracy: position.coords.accuracy,
      heading: position.coords.heading,
      floor: 3,
      lngLat: {
        lng: position.coords.longitude,
        lat: position.coords.latitude,
      }
    });
  });

})

Use in a WebView eg. ios/android/react-native

Map provider requirements

Map providers that base their solution on these libraries should be compatible or atleast easier to be made compatible.

Google Maps JS API
Mapbox GL JS

The following requirements must be satisfied for the map provider implementation

Add a marker on the map
- with a lng, lat and floor option.
- optional color
- optional image url
- optional onClick handler
Device/user position
- Set the current position of device/user based on coordinates (not only browser Geolocation).
  - Why? We need to be able to set the current position with coordinates to integrate with native apps, without asking the user for browser permission to access geolocation (they already did natively in-app)
Floor control
- Set and get floor
- Emit event when floor is changed (eg. by a floor selector ui control)
Wayfinding
- Draw a route on the map between two coordinates taking in consideration difference in floor level.
Rotate map
- Why? We need to control the rotation/heading of the device, eg. for use with devices like posters and static hardware.
Static map
- Map can be set in a non-interactive state.

Requirements for SDK endpoints

The json objects described hereunder

Wayfinding IDs

A wayfinding id is an identifying map that describes the material that is to be found. Its shape dependes on what library backend system your are integrating with. The object can be used as is or as a base64 encoded string.

Requirements for FBS-MapsPeople integration

{
    "branchId": "",
    "faust": "",
    "holdings": [{
        "id": "", //Not wayfinding id, but an unique id that you supply
        "departmentId": "",
        "locationId": "",
        "subLocationId": "",
        "shelfMark": "",
    },
    ]
}

Currently the 'faust' is required and the 'holdings' is optional.

Requirements for IMS-MapsPeople integration

{
    "branchId": "",
    "faust": "",
    "holdings": [{
        "id": "", //Not wayfinding id, but an unique id that you supply
        "departmentId": "",
        "locationId": "",
        "subLocationId": ""
    },
    ]
}