Plans Embed API

The Plans Embed API lets you embed an interactive floorplan or siteplan in your web page without directly using the Plans JavaScript SDK (analogous to embedding Youtube videos).

Example

Plans are embedded using the <iframe> tag. The viewerToken URL parameter is mandatory, and depending on the type of viewer token the planCode parameter may also be required. Other parameters for customising the appearance and configuring the SDK are optional.

<iframe width="500" height="500" src="https://api.locatrix.com/plans-embed/v1/plan?viewerToken=YOUR_VIEWER_TOKEN&planCode=YOUR_PLAN_CODE"></iframe>

Embedded plan

Loading plans using viewer tokens

Viewer tokens allow you to grant access to the plans within a client/campus/building/floor without allowing users to access anything else. They are signed using your API secret, so that end users can’t ask the viewer to load a plan they aren’t allowed to see. This is an extension of the exact same logic for SAS tokens used in the Plans Static API, however we have simplified the process so that tokens are generated on our servers using an API request, instead of requiring you to implement a specific algorithm on your server.

You can obtain viewer tokens on your server by calling the Locatrix ESAPI using:

  • GET https://api.locatrix.com/esapi/api/v1/Floors/{floor code}
  • GET https://api.locatrix.com/esapi/api/v1/Buildings/{building code}
  • GET https://api.locatrix.com/esapi/api/v1/Campuses/{campus code}
  • GET https://api.locatrix.com/esapi/api/v1/Clients/{client code}

Viewer tokens are labelled by their access level:

  • The "allAreas" token will load the entire plan associated with the resource and allow users to see all areas of it. It does not permit access to any other plans.
  • The "allAreasAndChildren" token is similar to the "allAreas" token, however it permits access to every plan associated with the resource and all of its children.

For example, the "allAreas" token associated with a campus will only allow you to load that campus’s site plan. However, the "allAreasAndChildren" token for that campus will grant you access to the site plan, as well as the floorplans of every floor in every building within the campus. Because only campuses and floors have plans directly associated with them, the "allAreas"token is not available for buildings and clients.

You should only use viewer tokens that grant users access to the resources that they need to see. If they only need to see two floors out of 50 in a building, you should get viewer tokens for those specific floors and use those, rather than using an "allAreasAndChildren" viewer token for the entire building and leaking information.

Be careful to ensure your use of viewer tokens is consistent with your application’s security model. If your app provides floor-level access control, use viewer tokens from individual floors. If your app provides building-level access control, then it’s OK to use viewer tokens for entire buildings.

In the future, we will provide additional access levels for only loading specific parts of the plan that an end user is allowed to see.

You can get viewer tokens on your server:

GET https://api.locatrix.com/esapi/api/v1/Client/clnt_vqk8dllmayur3r5tx6z3rerj4
==>
{
  "code": "clnt_vqk8dllmayur3r5tx6z3rerj4",
  "name": "Contoso Corporation",
  ...
  "viewerTokens": {
    "allAreas": null,
    "allAreasAndChildren": "djI6YWxsQXJlYXM6Y2xudF92cWs4ZGxsbWF5dXIzcjV0eDZ6M3Jlcmo0OnB0bnJfY2FkcjBnNjc1cmJrMGZ2MDNmbTVmZXd6NzoxNjIwMDg5NjE5LDI2YTgwYjFjLWI5MWUtYzkyNi02YTNiLWVhZGFjMDM3OWNlMyx1NmRCYlRzZXNwSFBDaTZjMVBydjl1Vzh0TzcyYjNzM1BDbXQ5MHhKeFNzJTNk",
    "expiry": "2020-09-16T15:42:05.3936024Z"
  }
}

And then use them to set the src of the iframe:

<iframe width="500" height="500" src="https://api.locatrix.com/plans-embed/v1/plan?viewerToken=djI6YWxsQXJlYXM6Y2xud
    F92cWs4ZGxsbWF5dXIzcjV0eDZ6M3Jlcmo0OnB0bnJfY2FkcjBnNjc1cmJrMGZ2MDNmbTVmZXd6NzoxNjIwMDg5NjE5LDI2YTgwYjFjLWI5MWUtY
    zkyNi02YTNiLWVhZGFjMDM3OWNlMyx1NmRCYlRzZXNwSFBDaTZjMVBydjl1Vzh0TzcyYjNzM1BDbXQ5MHhKeFNzJTNk&planCode=pln_gqfz7uu59qze049ro3uxyk8t6"></iframe>