Javascript API Reference

The API must be loaded from:

https://cdn.wayfinder.acquiredigital.com/live/js-api/wf.js

ACQ Class

The Wayfinder Web application is all contained withing the ACQ class. All other classes, methods and functions can be called once the ACQ class has been initialised.

Init

ACQ.init(canvas_div, settings, callback)
Parameters:
- canvas_div: HTMLElement
- settings: Object (see below)
- callback: function (optional)
Initialises Wayfinder Web, validates the passed api_key, downloads the required files, creates a new canvas inside the specified div and draws the 3D map to that space. If you're yet to setup an API key, please ask your account manager for your unique key.
The settings object can contain any of the following properties to override some of the defaults within the maps. If you omit a field then a default value or colour will be chosen:
Settings Example

{
apiKey: "your-key-here",
controls: "default",
disableUnusedMeshes:true,
startupMapId: 120,
detectQueryString: true,
routeShowDestination: true,
text:{
route: {
notfound: 'Use Caution – No Walkable Route',
notrequired: 'No route required',
notavailable: 'Route could not be created'
},
ui: {
from: 'From',
to: 'To',
accessibleRouting: 'Accessible Routing',
near: 'Near:',
categories: 'Categories',
amenities: 'Amenities',
selectDestination: 'Select a destination...',
noMatchesFound: 'No matches found'
}
},
map:{
shadows: true,
lowerQuality: false,
antialiasing: true,
tilt: 45,
angle: 45,
perspective: true,
popupInfo: true,
zoomToRoute: false,
routeTilt: 80,
transitionTime: 500,
initialZoomMode: 0,
background: {
color: {
r: 255,g: 255,b: 255
}
},
routeHandoffStartIcon : {
visible: true,
size: null,
url: "<https://cdn.wayfinder.acquiredigital.com/live/js-api/yah.png>"
},
icon: {
scale: 5
},
label:{
style: {
fontName: 'arial',
sizeInPx: 30,
padding: 10,
alignment: 'center'
},
color: {
r: 255,g: 0,b: 0
},
hover: {
r:0,g:255,b:255
},
selected: {
r:255,g:255,b:0
}
},
destinations: {
hover: {
r:0, g:255,b:255
},
selected: {
r:0, g:0,b:255
}
},
routeLine : {
color: {
r: 255,
g: 255,
b: 255
},
size: 0.25
},
routeDot: {
color: {
r: 0,
g: 0,
b: 0
},
size: 0.3
}
},

autoCloseOnRoute:true,
dontLoadCSS:false
}

See Init() Settings below for more information.

Notes:

Any fields not specified above will go to defaults (which is what the above are)
Colors: You can specify as {r:0, g:0, b:0} (and the numbers are between 0 and 255) or '#000000'
label style: Padding is in pixels, as is the font size. You must ensure that any font you use is available and loaded (if not a standard web font) BEFORE you call ACQ.init(). If you load a custom font, the name field will be from your CSS file.

Events

ready

This event is fired when the first map at the site has loaded successfully and is ready to be manipulated. This event must be setup before you call init() For example:

ACQ.addEventListener("ready", function() {
    console.log("READY FIRED!");
})

error

This event is fired if for some reason the map rendering or loading did not complete successfully.the first map at the site has loaded successfully and is ready to be manipulated. This event must be setup before you call init() For example:

ACQ.addEventListener("error", function(e) {
    console.log("Map load error: " + e.detail);
})

Init() Settings Object

The Settings object is a collection of options that define how the Wayfinder should be styled and rendered.

Properties

apiKey

Type: string
The project specific API key generated via the CMS. This is required to validate the usage of the API as well as to retrieve the required project.

controls

Type: string optional, defaults to "default"
- "default": Loads the default Acquire Web Wayfinder controls and UI. Quickest and easiest way to get up and running.
- "custom": Loads none of the Acquire Web Wayfinder controls. Allowing for maximum customization.

startupMapId

Type: integer optional
IF null or not supplied the API will automatically choose which map to show first. If you specify the ID of a map, this will be shown first. You can retrieve a list of Map IDs by calling ACQ.map.getMapIds() . However you cannot call this until after initialization. You should use this to get the list so you can code this into the settings. These ID numbers will not change and so you are safe to use them.

detectQueryString

Type: boolean optional
Defaults to true, if set then this will look for specific values in the query string so that a route is automatically generated. This is mainly used if you use the special map hand-off from our kiosk software and don't use our mapapp.co service.
Available in V1.0.16 and onwards

autoCloseOnRoute

Type: boolean optional. As of 1.0.22 defaults to true on mobile browsers, else defaults to false.
If set to true, then when you route, the directions box will close so you can see the route. If false, the box stays open.

disableFloorNames

Type: boolean optional, defaults to false.

If set to true, removes floor names from all lists and destination description.

disableRouting

Type: boolean optional, defaults to false.

If set to true, removes the route button when viewing a destination.

showEmptyCategories,

Type: boolean optional, defaults to false.

If set to true, categories which have no destinations assigned will be shown in the category menu, otherwise they will not be rendered.

routeShowDestination

Type: boolean optional, defaults to true.
If set to true, then when the route is generated and the start and destination are not on the same map, the map switches to the destination's map. If set to false it switches to the starting point map.
Available in V1.0.17 and onwards

listsShowAllDestinations

Type: boolean optional, defaults to false.

If set to true, then each destination drop will show all destinations when there a shop has multiple, with additional destination information which include the floor name or location. If set to false it will show just the nearest shop.

Available in V1.5.0 and onwards

dontLoadCSS

Type: boolean optional, defaults to false.
When set to True, the Wayfinder API will not load the CSS from our CDN. This allows you to load your own style and replace the look and feel of the controls. We don't recommend doing this, instead we'd prefer you to just override the individual styles that you need to change.
The default CSS is located and hosted here:
The text section requires API version 1.0.17
- text {}
  - route {}

notfound

- - Type: string
  - Set to override the text that is displayed when no route could be generated.

notrequired

Type: string
Set to override the text that is displayed when a route isn't needed (start and end point are the same)

notavailable

Type: string
Set to override the text that is displayed when route generation isn't available right now
ui: {}

from

Type: string
Set to override the text that is displayed next to the list of destinations in the FROM position

to

Type: string
Set to override the text that is displayed next to the list of destinations in the TO position

accessibleRouting

Type: string
Set to override the text that is displayed next to the switch that toggles between accessible routing and normal routing

near

Type: string
Set to override the text that is prefixed when a 'Near' description exists

amenities

Type: string
Set to override the text that is displayed for the amenities dialog

selectDestination

Type: string
Set to override the text that is displayed in the destination drop-downs when no destination is selected

noMatchesFound

Type: string
- Set to override the text that is displayed when no items are found in one of the above dialogs
map {}
This object contains settings specific to how the map renders. All parts ore optional, including this its self.

shadows

Type: boolean optional, defaults to true.
Controls if shadows for the buildings and the rest of the map can cast shadows. This improves the visual experience of the map, but at a cost of performance, both GPU and memory. On desktop browsers this should not be an issue, but on very lower power devices, typically earlier/older model smart phone might cause issues if the maps are very large.

lowerQuality

Type: boolean optional, defaults to false.
If shadows are enabled, this changes the shadow type from being soft, to sharp. This reduces the memory usage and increases the performance of the rendered map. This might be a better alternative to disabling the shadows completely.
Also, if the map models contain reflective surfaces (specular lighting effects) then setting this to true will also disable this feature. Without This is an extra level of complication

antialiasing

Type: boolean optional, defaults to true.
Controls if the map is rendered with anti-aliasing. When enabled this smooths the edges of the model so they don't look jagged. Turning this off will vastly decrease the visual of the map, but may increase performance. Turning this off should only be a last resort.

popupInfo

Type: boolean optional, defaults to true.
If true, then when clicking on destinations on the map the information box will expand, if false, the box stays collapsed.

tilt

Type: integer optional, defaults to 45.
Controls the angle the map is tilted by on startup. This is only supported in perspective mode. 0 would be looking from the side, whereas 90 is looking straight down. Wayfinder limits the range from 20 to 89 degrees.
Available in V1.0.15 and onwards

angle

Type: integer optional, defaults to 45.
Controls the angle the map is rotated by on startup, in degrees, between 0 and 360.
Available in V1.0.15 and onwards

perspective

Type: boolean optional, defaults to true.
Sets the map view mode on startup. If true you will get perspective view, if false you will get a top down orthographic view.
Available in V1.0.15 and onwards

zoomToRoute

Type: boolean optional, defaults to false.
When enabled the map will pan and zoom into the route.
Available in V1.0.15 and onwards

routeTilt

Type: integer optional, defaults to 80.
If zoomToRoute is enabled then when a route is visible the map tilt angle is changed to this amount and restored back to where it was before the route was generated when the route is cleared.
Available in V1.0.15 and onwards

transitionTime

Type: integer optional, defaults to 500.
Time taken in milliseconds for the map to pan and zoom automatically. This is used when zoomToRoute is active, but it is also used when you select a destination or amenity from the menu to pan the map to centre the selection.
Available in V1.0.15 and onwards

initialZoomMode

Type: integer optional, defaults to 0.
0: Map is shown at default position and size
1: Map is zoomed to show the entire map within the constraints of zoom range
2: Map is zoomed to show the actives on the map
Available in V1.0.22 and onwards
- map.icon {}

scale

Type: float optional, defaults to 5.
Changes the size of the areas used to render the amenity icons.
Available in V1.0.18 onwards
map.routeHandoffStartIcon {}
Available in V1.0.18 onwards
visible
Type: bool optional, defaults to true.
If the map is in 'hand off' mode then this specifys if a marker should be shown at the start node.
size
Type: float optional, defaults to null
Set the size of this icon. If not specified or null, then map.icon.scale will be used.

url

Type: float optional, defaults to https://cdn.wayfinder.acquiredigital.com/live/js-api/yah.png*.*

Allows you to specify the graphic to shown at the start location. This should be a PNG of around 128 pixels squareChanges the size of the areas used to render the amenity icons.

map.background {}
This optional element contains settings purely regarding what is rendered behind the map.
- - - color{}
    - Type: object or string optional, defaults to white.
    - Allows you to specify the background color rendered behind the map. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
    - { r: 255, g: 255, b: 255 }

map.label {}
This optional element contains default settings for rendering the labels on the top of the map.
- map.label.style{}
- This object allows you to configure the style of the text used to render the labels on the map

fontName

Type: string optional, defaults to 'arial'.
Allows you to specify the font family in use. If you choose anything other than the default web fonts you must ensure you have loaded them before calls to init() or labels will not be rendered correctly.

sizeInPx

Type: integer optional, defaults to 30
Allows you to change the font size for rendering. This is in pixels (px). The renderer will try to use this size, but if the label text will not fit in the allocated space the size will be progressively reduced until it does. If the size falls below 7 then the text on the label will not be rendered.

padding

Type: integer optional, defaults to 10
An amount of pixels to pad around the edge of the label bounds. This effectively shrinks the size of the label, but may increase the asthetic rendering of it.

alignment

Type: string optional, defaults to 'center'
Allows you to change the alignment of the text within a label. Valid values are 'left', 'right' or 'center'.

map.label.color{}

Type: object or string optional, defaults to black.
Allows you to override the default color of a label within the map. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 0, g: 0, b: 0 }

map.label.hover{}

Type: object or string optional, defaults to black.
Allows you to override the color a label is rendered when the mouse is hovered over it. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 0, g: 0, b: 0 }

map.label.selected{}

Type: object or string optional, defaults to black.
Allows you to override the color a label is rendered when actually selected. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 0, g: 0, b: 0 }

map.destinations {}
This optional element contains default settings for rendering the shapes within the map.

map.destinations.hover{}

Type: object or string optional, defaults to light orange.
Allows you to override the color a shape is rendered when the mouse is hovered over it. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 224, g: 152, b: 76 }

map.destinations.selected{}

Type: object or string optional, defaults to light blue.
Allows you to override the color a shape is rendered when actually selected. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 76, g: 162, b: 224 }
map.routeLine {}
This optional element contains settings for how a line should be rendered when a route has been found between two places

map.routeLine.color{}

Type: object or string optional, defaults to white.
Allows you to override the color of a line when a route is rendered within the map. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 255, g: 255, b: 255 }

map.routeLine.size

Type: float optional, defaults to 0.25
Allows you to override the thickness of the route line. This is the radius of the line in map coordinates.
map.routeDot {}
This optional element contains settings for how the animated ball that moves along a route should be drawn.

map.routeDot.color{}

Type: object or string optional, defaults to white.
Allows you to override the color of the ball that moves along the route. This can be specified as a hex RGB string (eg: '#FFFFFF' or '#FFF') or as an object as follows:
{ r: 255, g: 255, b: 255 }

map.routeDot.size

Type: float optional, defaults to 0.3
- Allows you to override the size of the ball that moves along the route line. This is the radius and is in map coordinates.

Canvas Class

Canvas Class

ACQ.Canvas
The canvas acts as the container for the Wayfinder Map and the Wayfinder Map UI.

Methods

enablePopOverLabels

enablePopOverLabels()
ACQ.canvas.enablePopOverLabels()

disablePopOverLables

disablePopOverLables()
ACQ.canvas.disablePopOverLables()

zoomMap

zoomMap()
ACQ.canvas.zoomMap(amount)
Zooms the map in and out by an arbitrary amount
Destination Class

Destination Class

Methods

set

set(object_id, is_node)
ACQ.destination.set(object_id, is_node)
Parameters:
- object_id: string
- is_node: boolean optional
Searches for and sets the active destination to the passed objectId.

find

find(destination, is_node, mode)
ACQ.destination.find(destination, is_node, openRouting)
Parameters:
- destination: object
- is_node: boolean optional
- mode: integer, defaults to 0. 0=pan and show, 1=show info, 2=show routing
Search for a destination from its object. If a match is found the camera focuses on the mesh and ACQ.Destination.set() is triggered setting the active destination.

findByName

findByName(name)
ACQ.destination.findByName(name)
Parameters:
- name: string
Returns: Promise <array>
Search for a destination by its name. The name can be a partial match and only has to start with the string provided. The function expects a promise, and the resolution contains an array of matched destinations. Note: Passing an empty string will return all destinations. Results are returned in alphabetical order. Typically used as follows:

ACQ.destination.findByName("Destination Name").then((a)=>{ 
	if (a.length) ACQ.destination.find(a[0]);
});

findById

findById(destinationId)
ACQ.destination.findById(destinationId)
Parameters:
- destinationId**:** string
Returns: Promise <object>
Search for a destination by its Id. The function expects a promise, and the resolution contains the found destination, else the promise is rejected

findByMeshId

findByMeshId(meshID)
Available in V1.0.20 and onwards
ACQ.destination.findByMeshId(meshID)
Parameters:
- meshID**:** string
Returns: Promise <object>
Search for a destination by its mesh ID. The function expects a promise, and the resolution contains the found destination array, else the promise is rejected

focus

focus(mesh_id)
ACQ.destination.focus(mesh_id)
Parameters:
- mesh_id: string
Searches for passed mesh_id, if found the map the mesh belongs to is loaded and the camera pans to the mesh's location. In addition the selected mesh is updated with the found mesh and the destination UI component updates with the new mesh data.

routeBetween

routeBetween(startDestinationId, targetDestinationId)
ACQ.destination.routeBetween(startId, targetId)
Parameters:
- startId: string
- targetId: string
Returns: Promise
Attempts to produce a route between the two destinations provided. If the route was established the promise is successful, else it is rejected. Note that this does not set any destinations as active.

setColours

setColours(destinationId, default, hover, active, labelDefault, labelHover, labelActive)
ACQ.destination.setColours(destinationId, default, hover, active, labelDefault, labelHover, labelActive)
Parameters:
- destinationId: string
- default: object or null
- hover: object or null
- active: object or null
- labelDefault: object or null
- labelHover: object or null
- labelActive: object or null
Returns: Promise
Attempts to change the colours that the destination and label will be rendered with on the map from the defaults. If any of the parameters are set to null then they will not be changed. The objects should be as follows: (values are between 0 and 255)

{ r : 0,    g:  0,   b :  0}        // Black
{ r : 255,  g:  0,   b :  0}        // Red
{ r : 255,  g:  255,   b :  0}      // Yellow
{ r : 255,  g:  128,   b :  0}      // Orange
{ r : 0,    g:  255,   b :  0}      // Green

Events

changed

This event is triggered when the destination is successfully changed. The detail property contains the new destination object (which is the same type that is passed into find() and returned by findByName() above. Typically you watch for notifications by calling:

ACQ.destination.addEventListener("changed", ......)

Map Class

Map Class

ACQ.Map

getMapTilt

getMapTilt()
WF.map.getMapTilt()
Returns the tilt angle of the map in degrees. 0 would be looking at it from the size, 90 would be looking straight down. This only works in perspective mode.
Available in V1.0.15 and onwards

setMapTilt

setMapTilt()
WF.map.setMapTilt(angle)
Sets the tilt angle of the map in degrees. 0 would be looking at it from the size, 90 would be looking straight down. This only works in perspective mode.
Available in V1.0.15 and onwards

getMapAngle

getMapAngle()
WF.map.getMapAngle()
Returns the rotation angle of the map in degrees.
Available in V1.0.15 and onwards

setMapAngle

setMapAngle()
WF.map.setMapAngle(angle)
Sets rotation angle of the map in degrees.
Available in V1.0.15 and onwards

Methods

getMapIds

Returns an array of IDs relating to all the floors in the project.
View Controls
You can switch between Orthographic and Perspective views by using the following commands:
These can only be called after "ready" has been fired from the map system.

WF.map.enableOrthographicView()
WF.map.enablePerspectiveView()

You can also change the zoom level in steps by calling the following. Note these values are relative zooming, not absolute values.

// Zooms out by 60 points
WF.canvas.zoomMap(-60)

// Zooms in by 60 points
WF.canvas.zoomMap(60)

You can also dynamically get and set the angle and tilt of the map (from V1.0.15)

WF.map.getMapTilt()
WF.map.setMapTilt()

WF.map.getMapAngle()
WF.map.setMapAngle()

Code Examples
Some examples and code snippets that we will add to in time:
Programmatically finding a destination by name and highlighting it on the map:

ACQ.destination.findByName("Macys").then((e)=>{
       if (e.length) {
              if (e[0].floor != WF.map.getActiveMapId()) 
                     ACQ.map.loadFloor(e[0].floor).then(()=>ACQ.destination.focus(e[0].object));
              else
                     ACQ.destination.focus(e[0].object)
       }
});

Javascript API Reference

This is an index of all the classes, methods, and interfaces in the Wayfinder Web JavaScript API.

ACQ Class

Init

Notes:

Events

ready

error

Init() Settings Object

Properties

apiKey

controls

startupMapId

detectQueryString

autoCloseOnRoute

disableFloorNames

disableRouting

showEmptyCategories,

routeShowDestination

listsShowAllDestinations

dontLoadCSS

notfound

notrequired

notavailable

from

to

accessibleRouting

near

categories

amenities

selectDestination

noMatchesFound

shadows

lowerQuality

antialiasing

popupInfo

tilt

angle

perspective

zoomToRoute

routeTilt

transitionTime

initialZoomMode

scale

visible

Type: bool optional, defaults to true.

size

url

map.background {}

fontName

sizeInPx

padding

alignment

map.label.color{}

map.label.hover{}

map.label.selected{}

map.destinations.hover{}

map.destinations.selected{}

map.routeLine.color{}

map.routeLine.size

map.routeDot.color{}

map.routeDot.size

Canvas Class

Methods

enablePopOverLabels

disablePopOverLables

zoomMap

Destination Class

Methods

set

find

findByName

findById

findByMeshId

focus

routeBetween

setColours

Events

changed

Map Class

Type: `bool` optional, defaults to true.