Pointr Web SDK FAQ¶
- Can I use Pointr Web SDK with multiple instances?
- How to retrieve all sites?
- How to retrieve all buildings?
- How to start with a selected site?
- How to start with a selected building?
- How to disable search UI component?
- How to get all pois for a site?
- How to get all pois for a type code?
- How to zoom in?
- How to configure initial zoom level?
- How to change orientation?
- How to go to a site?
- How to go to a building?
- How to go to a building with a specific level?
- How to scroll to a specific coordinate?
- How to fit bounds to a set of coordinates?
- How to start map with a highlighted POI?
- How to highlight a POI?
- How to search a POI in a site?
- How to search a POI in a site and prioritize the given building’s results?
- How to start the map with populated results on the search view?
- How to show Directions between two POIs?
- How to show Direction between a POI and a custom point?
- How to make routes accessible?
- How to implement a custom level selector?
- Is it possible to add custom markers, animations or other customization features?
- Is there any support for purely 2D maps or Orthogonal projections?
- How to add language support for static texts?
- What are the known limitations for Pointr Web SDK?
- How to restrict the map view to a fixed bounding box and prevent scrolling beyond it?
Can I use Pointr Web SDK with multiple instances?¶
No, Pointr Web Sdk MapWidget is a singleton object and does not allow for creation of multiple instances. After it is created, you can access the global instance via the PointrWebSDK.MapWidget.getInstance() method.
Example Usage:
const existingMapWidget = PointrWebSDK.MapWidget.getInstance();
this.mapWidget = existingMapWidget || new PointrWebSDK.MapWidget(options);
How to retrieve all sites?¶
To retrieve all available sites, you can use siteBuildingManager.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To get all sites data, loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, () => {
const sites = pointrWeb.getSiteBuildingManager().getAllSites();
sites.forEach((site) => console.log(site));
});
How to retrieve all buildings?¶
To retrieve all available buildings, you can use siteBuildingManager.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To get all buildings data, loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, () => {
const buildings = pointrWeb.getSiteBuildingManager().getAllBuildings();
buildings.forEach((building) => console.log(building));
});
How to start with a selected site?¶
To start with a specific selected site, you can provide siteExternalIdentifier option.
const options = new PointrWebSDK.Options({
apiUrl: "https://API_URL",
clientInternalIdentifier: CLIENT_INTERNAL_IDENTIFIER,
clientSecret: CLIENT_SECRET
siteExternalIdentifier: "YOUR_EXTERNAL_IDENTIFIER", // Add external identifier of site as an option
});
pointrWeb = new PointrWebSDK.MapWidget(options)
pointrWeb.start()
How to start with a selected building?¶
To start with a specific selected building, you can provide buildingExternalIdentifier option.
const options = new PointrWebSDK.Options({
apiUrl: "https://API_URL",
clientInternalIdentifier: CLIENT_INTERNAL_IDENTIFIER,
clientSecret: CLIENT_SECRET,
buildingExternalIdentifier: "YOUR_EXTERNAL_IDENTIFIER", // External identifier of building
});
pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
How to disable search UI component?¶
To disable search component you can set shouldEnableSearch option to false.
const options = new PointrWebSDK.Options({
apiUrl: "https://API_URL",
clientInternalIdentifier: CLIENT_INTERNAL_IDENTIFIER,
clientSecret: CLIENT_SECRET,
shouldEnableSearch: false, // ADD shouldEnableSearch option and set it to false. Default is true
});
pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
How to get all pois for a site?¶
You can use poiManager to get all available pois for a given site.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To gel all pois data loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, async () => {
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier(SITE_EXTERNAL_IDENTIFIER);
const pois = await pointrWeb
.getPoiManager()
.getPoisBySite(site.siteInternalIdentifier);
console.log(pois);
});
How to get all pois for a type code?¶
You can use poiManager to get all available pois for a given site. Then filter for the type code you need
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To gel all pois data loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, async () => {
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier(SITE_EXTERNAL_IDENTIFIER);
const pois = await pointrWeb
.getPoiManager()
.getPoisBySite(site.siteInternalIdentifier);
const helpDeskPois = Object.values(pois).filter((poi) => poi.properties.typeCode === "help-desk")
});
How to zoom in?¶
You can manage zoom operations with zoomTo function.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To get zoom level map should be ready
mapView.on(mapView.events.mapReady, () => {
const zoomController = pointrWeb
.getUiController()
.getZoomSelectorViewController();
pointrWeb.zoomTo(zoomController.getZoom() + 1); // Sets given zoom level. In example we're zooming in with increasing current zoom level 1
});
How to configure initial zoom level?¶
It’s possible to configure the starting zoom level for the map. But there is no option to achieve this from the dashboard. However, it can be changed on configuration from “initialZoomLevel” value in Web SDK startup:
It is possible to configure the starting zoom level for the map of Web SDK via the “initialZoomLevel” configuration of the SDK. Currently, this is the only option and there is no configuration possible via PC Dashboard.
<script>
document.addEventListener("DOMContentLoaded", function () {
const options = new PointrWebSDK.Options({
container: "pointr-map",
apiUrl: "https://sample-app-v8-api.pointr.cloud",
clientInternalIdentifier: "72df7035-cdea-4c19-93b8-6deff5177894",
clientSecret: "c93f0101-36ed-4129-8f95-558f4cd8e82f",
siteInternalIdentifier: 2,
initialZoomLevel: 20
})
const pointrWeb = new PointrWebSDK.MapWidget(options)
pointrWeb.start()
})
</script>
Within the configuration parameter, there is a range (0-24) that adjusts how close to Earth the user will see a given location. The larger the number, the more zoomed in the user will see the location
- 0 denotes a ‘zero zoom’ and will show much more of the Earth
- 24 denotes a ‘maximum zoom’ and will show a given location’s finer details
There are 3 different modes according to the zoom levels;
- 0< x <15: Earth mode
- 15< x <17: Site mode
- 17< x <24: Building mode
How to change orientation?¶
You can manage orientation using setBearing and setPitch functions.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapViewController = pointrWeb.getUiController().getMapViewController()
const mapView = mapViewController.getView()
// To change the orientation map should be ready
mapView.on(mapView.events.mapReady, () => {
mapViewController.setBearing(90) // Sets the map's bearing (rotation). The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.
mapViewController.setPitch(60) // The pitch to set, measured in degrees away from the plane of the screen (0-60).
});
How to go to a site?¶
loadAndSet function is able to change a site.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To load and set a site map should be ready first
mapView.on(mapView.events.mapReady, () => {
pointrWeb.loadAndSet(SITE_OBJECT);
});
How to go to a building?¶
loadAndSet function is able to change a building.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To load and set a building map should be ready first
mapView.on(mapView.events.mapReady, () => {
pointrWeb.loadAndSet(BUILDING_OBJECT);
});
How to go to a building with a specific level?¶
loadAndSet function is able to change a building.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To load and set a building map should be ready first
mapView.on(mapView.events.mapReady, () => {
pointrWeb.loadAndSet(BUILDING_OBJECT, LEVEL_OBJECT);
});
How to scroll to a specific coordinate?¶
You can use the scrollTo() method to navigate to a specific coordinate and adjust the zoom level. Additionally, the method includes an optional parameter shouldDisableBuildingAndSiteUpdate, which determines whether the current site and building information should be preserved upon the coordinate change.
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// You can set coordinates beforehand to use in scrollTo()
const latlng = new PointrWebSDK.LatLng({ lat: 37.7749, lng: -122.4194 });
// Set the zoom
const zoom = 18
//Set shouldDisableBuildingAndSiteUpdate (optional)
const shouldDisableBuildingAndSiteUpdate = true
// Use scrollTo() to navigate to a coordinate and change the zoom
mapView.scrollTo(latlng, zoom, shouldDisableBuildingAndSiteUpdate)
How to fit bounds to a set of coordinates?¶
You can use the fitBounds() method to adjust the map view to fit the specified bounds based on an array of LatLng objects.
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// Create the coordinates array of the bounds you want to fit to
const coordinates = [
new PointrWebSDK.LatLng({ lat: 37.7749, lng: -122.4194 }),
new PointrWebSDK.LatLng({ lat: 37.7749, lng: -122.4195 }),
new PointrWebSDK.LatLng({ lat: 37.7750, lng: -122.4195 }),
new PointrWebSDK.LatLng({ lat: 37.7750, lng: -122.4194 }),
// Add more LatLng objects as needed
];
const mapView = pointrWeb.getUiController().getMapViewController().getView();
mapView.fitBounds(coordinates);
How to start map with a highlighted POI?¶
To start the map with a highlighted POI you can use highlightPoiIdentifier option.
const options = new PointrWebSDK.Options({
apiUrl: "https://API_URL.pointr.cloud",
clientInternalIdentifier: CLIENT_INTERNAL_IDENTIFIER,
clientSecret: CLIENT_SECRET
siteExternalIdentifier: "SITE_EXTERNAL_IDENTIFIER", // Add external identifier of site that contains building
buildingExternalIdentifier: "BUILDING_EXTERNAL_IDENTIFIER" // Add External identifier of building,
highlightPoiIdentifier: "poiInternalIdentifier" // Add poi internalIdentifier
});
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
How to highlight a POI?¶
To highlight a POI you can use highlight function.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To highlight a poi map should be ready first
mapView.on(mapView.events.mapReady, async () => {
// NOTE: If site has not been set, 2 lines below should be added
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier("SITE_EXTERNAL_IDENTIFIER");
pointrWeb.loadAndSet(site);
const poi = await pointrWeb.getPoiManager().get("POI_FID");
pointrWeb.highlight(poi);
});
How to search a POI in a site?¶
To search you can use search function.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To get all pois data loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, async () => {
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier("SITE_EXTERNAL_IDENTIFIER");
const searchResults = await pointrWeb.search("MY_QUERY", site);
});
How to search a POI in a site and prioritize the given building’s results?¶
To prioritize one building’s results in search you can use search function with site and building function
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
// To get all pois data loaded event should fire first
pointrWeb.on(pointrWeb.events.dataLoaded, async () => {
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier("SITE_EXTERNAL_IDENTIFIER");
const building = pointrWeb
.getSiteBuildingManager()
.getBuildingWithExternalIdentifier("BUILDING_EXTERNAL_IDENTIFIER");
const searchResults = await pointrWeb.search("MY_QUERY", site, building);
});
How to start the map with populated results on the search view?¶
Below code sample can be used.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const searchViewController = pointrWeb
.getUiController()
.getSearchViewController();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// To populate search results mapReady event should fire first
mapView.on(mapView.events.mapReady, async () => {
const site = pointrWeb
.getSiteBuildingManager()
.getSiteWithExternalIdentifier("SITE_EXTERNAL_IDENTIFIER");
const searchResults = await pointrWeb.search("QUERY", site);
searchViewController.results = searchResults;
searchViewController.populateQuery("QUERY");
searchViewController.populateResults();
searchViewController.getView().showResults();
});
How to show Directions between two POIs?¶
Below code sample can be used.
// create options
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
const mapView = pointrWeb.getUiController().getMapViewController().getView();
const navigationViewController = pointrWeb
.getUiController()
.getNavigationViewController();
// To highlight a poi map should be ready first
mapView.on(mapView.events.mapReady, async () => {
const startPoi = await pointrWeb.getPoiManager().get("POI_FID");
const destinationPoi = await pointrWeb.getPoiManager().get("POI2_FID");
pointrWeb.highlight(startPoi);
pointrWeb.highlight(destinationPoi);
pointrWeb.hidePoiDetails();
navigationViewController.populate(startPoi, destinationPoi);
navigationViewController.startNavigation();
});
How to show Direction between a POI and a custom point?¶
To represent a custom point you need to create Feature object that contains bid, sid and geometry information
// Create feature to be able to start navigation
// For navigation to set bid(building internal identifier) and lvl(level index) is required
const destionationPoint = new PointrWebSDK.Feature(
{ bid: 1, lvl: 1 },
{ type: "Point", coordinates: [longitude, latitude] }
);
const mapViewController = pointrWeb.getUiController().getMapViewController();
const navigationViewController = pointrWeb
.getUiController()
.getNavigationViewController();
const mapView = mapViewController.getView();
// Map needs to be ready to start navigation
mapView.on(mapView.events.mapReady, async () => {
// Get starting poi
const startPoi = await pointrWeb.getPoiManager().get("POI_ID");
pointrWeb.highlight(startPoi);
pointrWeb.hidePoiDetails();
// Populate navigation with poi object and destination feature
navigationViewController.populate(startPoi, destionationPoint);
navigationViewController.startNavigation();
});
How to make routes accessible?¶
Before v8.14:
If you set navigationViewController’s mode to accessible all paths will be accessible. It can be set to DEFAULT, COMFORTABLE, ACCESSIBLE.
mapView.on(mapView.events.mapReady, async () => {
// valid values -> DEFAULT, COMFORTABLE, ACCESSIBLE
navigationViewController.setMode("ACCESSIBLE");
});
With 8.14.0 and later:
A new toggle is added to the navigation view to switch between accessible and non-accessible routes. The default value is non-accessible. If you want to start with accessible routes, you can set option shouldStartAccessibilityEnabled to true. The code above will still provide accessible routes but option is simpler and it will set ui components accordingly.
const options = new PointrWebSDK.Options({
apiUrl: "https://API_URL.pointr.cloud",
clientInternalIdentifier: CLIENT_INTERNAL_IDENTIFIER,
clientSecret: CLIENT_SECRET
shouldStartAccessibilityEnabled: true
});
const pointrWeb = new PointrWebSDK.MapWidget(options);
pointrWeb.start();
How to implement a custom level selector?¶
To implement a level selector first you need to fetch current building’s levels
let levels;
const mapViewController = pointrWeb.getUiController().getMapViewController();
const mapView = mapViewController.getView();
mapView.on(mapView.events.currentBuildingChanged, (event) => {
if (event.newCurrentBuilding !== undefined) {
levels = event.newCurrentBuilding?.levels;
}
});
These levels can be used to generate a custom level selector To change a level using sdk:
// set first level of building
const levelObject = new PointrWebSDK.Level(levels[0]);
const uiController = pointrWeb.getUiController();
uiController.setLevel(levelObject);
If you want to hide pointr web sdk’s level selector you can hide it using css.
#pointr-levels {
display: none !important;
}
Is it possible to add custom markers, animations or other customization features?¶
The answer for this is usually no, some customization is possible with a custom style.json and it is possible using custom Javascript to overlay things on top of the map, but none of this is provided by the SDK itself, it must be done by the application itself.
Is there any support for purely 2D maps or Orthogonal projections?¶
That is not possible, our maps are always 3D using a perspective projection, if disabling perspective is needed what can be done is have walls and objects with zero height and lock the camera to have a pitch of 0.
How to add language support for static texts?¶
If you want to start your application with one language that is not English (USA) you can use languageCode option. You can use these language codes:
"en_GB",
"en_US",
"de",
"fr",
"el",
"es",
"hi",
"tr",
"ar",
"pt",
"zh_CN",
"zh_TW";
If you want to support multiple languages you need to set shouldEnableLanguageSelector option to true. After this you can select the languages you want to support. languageList option expects an array of codes. For example, if you only need English (USA) and Spanish support you need to set languageList option to [“en_US”, “es”].
Please note that the WebSDK automatically switches to the browser language if the browser language matches any of the languageCodes under languageList options. If the browser language does NOT match any of the languageCodes in languageList option, it will switch to default language “en_US” which also can be overrriden by languageCode option with another default language.
It is also possible to set selected language using API:
languageSelectorViewController.setSelectedLanguage("fr")
Note
Arabic is supported from Web SDK v8.8+ onwards
What are the known limitations for Pointr Web SDK?¶
Web SDK might not work if its container’s width is smaller than 320px.
How to restrict the map view to a fixed bounding box and prevent scrolling beyond it?¶
We have a hidden function for restricting the map view to a fixed bounding box. To achieve this, you should use the setMaxBounds() function.
const mapView = pointrWeb.getUiController().getMapViewController().getView();
// Map should be ready
mapView.on(mapView.events.mapReady, () => {
// Set bounds to New York, New York
const bounds = [
[-74.04728500751165, 40.68392799015035], // Southwest coordinates
[-73.91058699000139, 40.87764500765852] // Northeast coordinates
];
mapView.setMaxBounds(bounds)
});