In order to start developing your own solution, there are a number of requirements that need to be fulfilled in order to ensure a smooth development process.

The following subsections will guide you in how to get the necessary API keys for:

• MapsIndoors API Key

• A map engine provider, Google Maps or Mapbox

Get your MapsIndoors API Key​

In order to include MapsIndoors in your app, you need a MapsIndoors API key. If you do not yet have access to your MapsIndoors API key, you can use the demo API key 02c329e6777d431a88480a09 to follow the guide.

If you have access to the MapsIndoors CMS, you'll find your MapsIndoors API key as described here.

Unlock the power of indoor mapping with the MapsIndoors JavaScript SDK! Dive into a world where integrating indoor mapping solutions into your applications is not only possible but also incredibly efficient and customizable.

Why Choose MapsIndoors JavaScript SDK?

• Comprehensive Toolkit: Seamlessly manipulate maps and interact with MapsIndoors data to meet your specific requirements.

• Developer-Friendly: Utilize a range of npm-hosted web components to minimize UI creation overhead and simplify development.

• Adaptability: Tailor your map to adapt to various conditions and requirements with ease.

What’s in the Box?

• Multifaceted Interaction: Engage with MapsIndoors data in myriad ways.

• Map Manipulation: Alter and manage the map according to your unique needs and conditions.

• Web Components: Leverage pre-built components to streamline UI development.

Prefer a Ready-to-Use Solution? Consider our ! Crafted for those who'd rather leave UI and UX to the pros, this React-based application offers:

• Battle-Tested Experience: Proven search and wayfinding capabilities.

• Minimal Customization Needed: Especially suited for projects where quick implementation is key.

This guide will walk you through how to create your own MapsIndoors implementation from the ground up. You will gain experience with the MapsIndoors Software Development Kit (SDK) and the typical development process of using it. Furthermore, you will be able to gain an understanding of the basic concepts, tools and terminology commonly used when interacting with the SDK.

Following features are included in this Getting Started guide:

• Display an interactive map with MapsIndoors

• Implement search functionality to interact with the displayed map

• Generate and show directions between two points on the map

Parts of this guide rely on having access to a MapsIndoors Solution. The section will guide you on how to use our Demo API key if you do not have your own.

SDKs & Frameworks

MapsIndoors is built on top of an external map engine, either Mapbox or Google Maps.

You'll need an Access Token for your chosen map engine with the relevant APIs enabled and a MapsIndoors API key to get started building your own app. You can use either Mapbox or Google Maps as your map provider. You only need to obtain one type of token - choose the provider that best suits your needs.

Token Options

Note: While both providers support core mapping features, some specialized functionality may only be available with a specific provider. These cases will be clearly marked throughout the documentation.

To create a Mapbox Access Token, follow the steps provided in the link below:

Remember to enable relevant scopes on the Mapbox Access Token, such as:

To make sure you can use the full feature set of MapsIndoors you'll need to enable these services.

Being able to manage your own maps however and whenever you want makes you agile, independent of support and able to immediately act on your customer requests.

Customization and updating of your map is fast and easily done through the MapsIndoors CMS.\

Key features of the MapsIndoors CMS include:

• Add POIs and areas, like objects, work zones, or any relevant points of interest.

• Make floorplan changes

Getting your map visualization right means going beyond simple floorplan representation and elevating the map to a rich and user-friendly indoor mapping experience. \

The design and customization of your map visualization are crucial for creating a user-friendly, visually engaging, and functionally relevant mapping experience. The map visualization is your foundation for effective navigation, information accessibility, and overall user satisfaction. \

In MapsIndoors, key aspects of map visualization cover:

Real-World Geospatial Visualization

MapsIndoors enables the visualization of venue details, building structures, floor plans, rooms, and related data on georeferenced Google or Mapbox maps. This real-world geospatial context enhances the accuracy and relevance of the indoor map.

Map Design

Users can customize the appearance of their maps to align with branding and specific use cases. Whether in 2D or 3D, the ability to design the map's look and feel provides flexibility and coherence with organizational aesthetics.

Dynamic Maps

MapsIndoors supports dynamic maps that can display relevant content based on users, use cases, or zoom levels. This adaptability ensures that users receive the most pertinent information based on their context and needs.

Map Interaction

The platform includes built-in features for map interaction, such as a floor selector, zoom, pan, tilt, and search functionalities. These features make it easy for users to navigate and interact with maps in ways that are relevant to their specific requirements.\

Whether you’re building your map solution on Mapbox or Google Maps, we’ve got your back. Follow the guides and you’ll soon be up and running.

Wayfinding is a critical component of your indoor map solution enabling efficient route calculations and optimal navigation within indoor spaces.\

MapsIndoors’ wayfinding functionality is a comprehensive solution that seamlessly integrates local and global maps, considers various travel modes, utilizes entry points for smooth transitions, and breaks down routes into logical legs and steps, ultimately enhancing navigation and user satisfaction.\

Key elements to dig into when enabling wayfinding in your MapsIndoors solution are:

Outdoor to indoor navigation Turn-by-turn directions visualized on the map with estimated travel time and detailed descriptions.

Venue to Venue wayfinding

When you're getting routes between two of your own MapsIndoors venues and may require using public routes from Google Maps or Mapbox to get there.

Dynamic routes Automated route updates based on obstacles like furniture and changing floor plan layout.

Personalized routes User profiles allow for personalized guidance, based on what the user is allowed to see and where they are allowed to navigate. Getting the right people to the right destinations.

Accessible wayfinding Allow users with disabilities to effortlessly navigate your building by avoiding stairs and using elevators and ramps for navigation.

\

All the guidance is here for you. Happy wayfinding!

Documentation reflects the latest version.

You can find documentation on legacy versions here:

Data visualization in the form of displaying external dynamic data within your indoor map is crucial for enhancing the map's utility, relevance, real-time applicability and not least for customizing it to fit your specific use cases. \

MapsIndoor’s data visualization functionality is built to ensure a unified, up-to-date, and contextually relevant mapping experience for users. \

By altering your map data visualization dynamically, you will create a use-case-specific digital twin that only shows information that is relevant for solving your users’ needs.\

Integrate everything from live data sensors, calendar booking systems, ERP systems, and more to MapsIndoors.\

Follow our guides to customise your maps with the data integrations you need.

Offline Data

Currently, the Web SDK does not support offline mode.

Due to some slight differences in how the Web SDK handles Buildings and Venues compared to the Mobile SDKs, Buildings and Venues are treated as Locations, and as such, will be displayed with Labels. This is not always desirable behavior, and thus we also provide this small code snippet to remove them again.

mapsIndoorsInstance.setDisplayRule(['MI_BUILDING', 'MI_VENUE'], { visible: false });

MI_BUILDING and MI_VENUE are special Location Types used specifically for this purpose, to set Display Rules for Buildings and Venues.

Search Operations with MapsIndoors

Enhance your application's search capabilities with MapsIndoors data. The following topics offer a brief introduction to various functionalities you can implement. For in-depth guidance, click on the specific topics.

• Retrieve Specific Location: Use to obtain individual location objects.

• Querying Locations: Perform broader searches with .

  • Filter Customization: Fine-tune your searches with specialized query parameters.

• Using External IDs: Translate your unique IDs to MapsIndoors IDs using .

• Advanced Search Integration: Integrate MapsIndoors data into your existing search functionalities.

• Distance Matrix: Create a distance matrix when dealing with multiple locations.

• Utilizing MapsIndoors web components

  • Components: MapsIndoors search component, list component, etc.

  • Click Event Handling: Interactive retrieval of location details.

If you use Mapbox as your map engine, it provides the option of creating a heatmap as an alternative way to display datapoints on your map. The MapsIndoors SDK also provides support for integrating this heatmap into the MapsIndoors layers.

Creating a heatmap​

This guide will focus on how to display the heatmap layer in a visually pleasing way in your MapsIndoors solution. In order to actually create your heatmap, please refer to the documentation from Mapbox.

• Creating a heatmap with Mapbox:

• Creating a heatmap layer with Mapbox:

Inserting the heatmap layer between MapsIndoors layers

Once you have created your heatmaps with Mapbox, you will need a way to get it to work with the layers that MapsIndoors already applies to your Mapbox map. By following the guides above, you should be able to simply overlay it on top of everything. But in order for it to be integrated more seamlessly in the MapsIndoors layers, you could also choose to insert it between the tile layer and the layer containing the area polygons.

In order to insert a heatmap between layers on the web SDK, refer to the . Then use the following code snippet but replace map with your Mapbox instance, and insert the relevant parameters from the API Reference:

In order to access certain MapsIndoors apps, and certain custom apps, SSO (Single Sign-On) login can be used. This includes the MapsIndoors Auth SSO, as well as organization-specific authentication providers - see Configuration.

The MapsIndoors Auth SSO page is located at https://auth.mapsindoors.com/login.

MapsIndoors has the following apps where SSO can be used to sign in:

• MapsIndoors CMS

• MapsIndoors Standard Web App

• MapsIndoors Standard Web Kiosk

Unless an organization-specific provider is used, it is only possible to sign in for users invited orcreated via MapsIndoors CMS. Once a user exists in MapsIndoors, it is possible to sign in via username/password, or public authentication providers such as:

• Google

• Azure Active Directory (pending)

This is only authentication - authorization is still based on the user configuration in MapsIndoors. This also means that the security is extremely tight. MapsIndoors does not gain any access to the authentication provider, as it only expects an id_token (as opposed to an access token) in order to authenticate. Based on this external authentication, and then internal authorization, an internal access token is granted to the app - which is completely unrelated to the authentication provider and therefore only can be used to access MapsIndoors services. If an organization-specific authentication provider is used, then there are more options in regards to authorization - see .

Password Validation​

A password must be 16 characters or longer in order to be valid.

Password Reset​

You can reset your password via . Submit your e-mail address, and we'll send you a link to reset your password.

Enter your password twice on the Password Reset page to change it.

The language of MapsIndoors is independent of the chosen language on the device on which the app is used. This means that you need to explicitly tell MapsIndoors which language to use.

If you do not specify a language, MapsIndoors will show information in the default language defined in the MapsIndoors CMS. Likewise, if you specify a language that is not supported, MapsIndoors will also show information in the default language.

Additionally, aside from methods mentioned here, you can provide translations via the standard method for your device, such as using individual localized strings.

Configuring POI translations in CMS​

To provide multiple languages for items in the MapsIndoors CMS, such as "Meeting Room" or "Restroom", the translation must be provided by the user in the CMS. A translation can be provided in any language. In order to add support for additional languages that we currently do not support, please contact your MapsIndoors representative, and we will enable you to add translations in your desired language.

Once your language of choice has been created, you can add the translation by clicking on any POI, which will open a menu on the left side of the screen. Here, you will see the following menu point, where you can enter translations for the languages you wish. If a field is left empty, the fallback language is English. In the example below, English (en) and Danish (da) are the enabled languages.

Use Device Language

The web-app will automatically adjust the language to the language set in the user's browser settings, otherwise default to English. When using Safari, the device's language setting will be used. This is limited to the following languages, and will default to English if the selected language is not supported:

• English

• Danish

• Spanish

• Portuguese

Are your building and venue labels disrupting your user experience?

Traditionally, both Buildings and Venues are treated as Locations in the Web SDK, inherently displaying Labels which might not always align with the desired user experience. A conventional method to manage their visibility is illustrated below via a

It can be a best practice to set this display rule after initializing your MapsIndoors instance.

Here, MI_BUILDING and MI_VENUE are specific Location Types dedicated to facilitate display rule settings for Buildings and Venues respectively.

Enhancing User Interaction with Adaptive Zoom-Level Popups

Let's say a user zooms out to get a broad overview of a large campus or city area. At a lower zoom level, the display becomes less cluttered, paving the way for a more clear, bird's eye view of the venues available. Here’s where dynamic, zoom-dependent

Handling Label Collisions in MapsIndoors SDK with Mapbox

Overview

When utilizing the MapsIndoors SDK, managing label collisions—particularly at high zoom levels—can be crucial to maintain a clean and informative map display. The SDK's collision detection may sometimes hide labels of Points of Interest (POIs) that are situated closely together, to avoid visual clutter and overlap. This guide introduces a method to manually control label visibility at specific zoom levels.

Why It Matters

• Visibility vs Clarity: Ensuring labels are always visible might be vital for certain use cases or specific POIs. However, enabling labels to overlap can disrupt map clarity and user experience.

Introduction to Directions

As a key element in the MapsIndoors platform, we offer APIs for efficiently calculating and displaying the most optimal routes from anywhere in the world to any Location in MapsIndoors. In the case of travelling inside a Venue, this calculation can be done on a local map provided by MapsIndoors. In the case of travelling between Venues or from outdoors to indoors, MapsIndoors provides a seamless journey outline from a specified Origin through automatically selected Entry Points at the edge of your Venues to the specified destination. See illustration below:

In order to provide a route between Venues, MapsIndoors integrates with external and global map engines (Mapbox and Google Maps).

The central components that utilize a Directions experience is the

Searching the map and making sure you are able to find what you need is crucial for users navigating complex indoor spaces. Search functionality on an indoor map is a critical component for improving navigation, efficiency, and overall user satisfaction.\

Depending on your solution and use case, search can come into play in different ways. It could be specific locations, points of interest, or services within the indoor space, like enabling users to search for a meeting room, a desk, a booth, a coffee, an elevator, anything.

In MapsIndoors, searching is a crucial element of user interaction, allowing users to discover locations and filter map displays for a tailored experience. The search functionality covers all MapsIndoors geodata, and customization options are available to create a search experience that aligns with your specific use case.\

Key features of the searching functionality include:

• Filters for Precision

Often you may want to get directions starting from a user's actual current position instead of from another fixed Location. The following code snippet gives an example on how to implement this.

Further details on how user positioning works, and how to display it, can be found .

This results in directions queries originating from the user's current location.

MapsIndoors web components are intended to take advantage of pre-designed and already integrated HTML elements which will greatly reduce the complexity of your user-interface design and help minimize the amount of MapsIndoors specific SDK implementation code you'll need to write.

While the MapsIndoors components will not cover every full user experience, it will allow you to implement MapsIndoors more efficiently.

To learn more about each component, please see the component specific documentation at

There are two ways to change the appearance of the map content in MapsIndoors:

• Using Display Rules.

• Using Google Maps or Mapbox styling.

Each has its own purpose which will be explained below.

To get an overview of what Display Rules are and can be used for, read the page first.

In this tutorial, you will build your own app from the ground up, gaining experience with the typical development process when working with the MapsIndoors Software Development Kit (SDK). Furthermore, you should be able to gain an understanding of the basic concepts, tools and terminology commonly used when interacting with the SDK. The goal of this guide is to enable you to develop a basic app, that is able to display a map, and incorporate a few basic features such as searching, directions and Live Data integration.

Parts of this guide rely on having access to a MapsIndoors Solution which supports Live Data Integration. If you do not have access to this through your own Solution, we recommend using our demo API key to access one: mapspeople3d.

Take-Away Skills

This article assumes that you have already read the

In this article, we will discuss how to synchronize data for a subset of venues in MapsIndoors. There are multiple benefits to doing this, including performance and control over which data the user can search for.

Synchronizing data for a subset of venues reduces the time it takes to load the map, compared to synchronizing data for all venues. It also enables you to control which data the user can search for. For example, you may only want to synchronize data for venues located in a specific region.

To do this, you must not provide the MapsIndoors API key in the URL when loading the SDK. Instead, you set the MapsIndoors API key by calling the mapsindoors.MapsIndoors.setMapsIndoorsApiKey('MAPSINDOORS_API_KEY'); method before creating the MapsIndoors instance.

Here is an example of how to set which venues to synchronize data for, and then setting the MapsIndoors API key, to start the synchronization:

This will now synchronize data exclusively for these two venues, and only those venues.

How User Positioning Works in MapsIndoors

In order to show a user's position ("Blue Dot") on an indoor map with MapsIndoors, a Position Provider must be implemented. You can integrate a 3rd party positioning provider (IPS) to create this experience. For you the developer, this means that the MapsIndoors SDK offers an interface for such a Position Provider, but no building blocks for acquiring positioning.

This guide will show you how to use a third party positioning provider and implement it into your MapsIndoors application. Here we will start from the finished Getting Started app. This code can be found here: .

A full implementation of three different third party positioning providers can be found here

When using the MapsIndoors SDK, the system for detecting collisions will sometimes, at high zoom levels, result in the Labels of POI's that are close together being hidden, no matter what you do. Here we present a small workaround, so you can disable collisions for specific zoom levels.

Please note that on Web it is only possible to do this when using Mapbox as a map provider.

This is accomplished by checking if there is a zoom_changed event, and if there is, enabling or disabling the text-allow-overlap depending on the zoom levels.

Migrating to Mapbox V11

With the release of Mapbox V11, we are migrating the V4 SDK to use Mapbox v11 to make use of the new features offered by Mapbox. As this version bump can include breaking changes for your implementation. We will still be maintaining a V10 based SDK. This will retain the maven naming as of now. Where Mapbox V11 will move to:

For the migration of your Mapbox code implementation read the Mapbox guide here:

With MapsIndoors, you have a range of options for controlling how content is styled on the map, and how your users can interact with it. This guide takes you through some of these options, to help you find the best approach.

Visibility and rendering

The options you have for controlling visibility and rendering on the map are the following:

• Setting "Active From" and "Active To" dates

To query for a route, create a MPPoint from the Latitude, longitude and the z-index of the user, and use that on the DirectionsService.query function, like this:

val directionsService = MPDirectionsService(mContext)
//Create an Origin MPPoint with the users latitude, longitude and Z-index. If no Z-index is available just use 0.0
val origin = MPPoint(userLatitude, userLongitude, userZIndex)
val destination = destinationLocation.getPoint()
directionsService.setRouteResultListener { route, error ->
  //Handle the route result here
}
directionsService.query(origin, destination)

userLatitude, userLongitude. userZIndex and destinationLocation are all placeholder variable names where you insert your data.

Further details on how user positioning works, and how to display it, can be found here.

This results in directions queries originating from the user's current location.a

This guide assumes you have a basic understanding of HTML, CSS, and JavaScript. If you're new to web development, we recommend using an Integrated Development Environment (IDE) like Visual Studio Code to help manage your files and code.

Let's start by creating the necessary file structure:

1. Create a new project folder: Choose any location on your computer. Let's call this folder mapsindoors-tutorial. Ensure the folder is empty.

2. Create three empty files inside your mapsindoors-tutorial folder:

   • index.html: This file will be your application's entry point and contain the main HTML structure.

   • style.css: This file will contain the CSS styles for the HTML document.

   • script.js: This file will contain the JavaScript code for initializing and controlling the MapsIndoors map.

Now, open the index.html file in your code editor and add the following basic HTML structure. This includes the necessary boilerplate and links to the MapsIndoors Web SDK, your custom CSS, and your custom JavaScript file:

Next, open the style.css file and add the following styles. These styles ensure the map container can fill the page correctly.

Explanation:

• We've set up a standard HTML5 document (index.html).

• The <meta> tags ensure proper character display and responsiveness.

• The <title> tag sets the title for the browser tab.

Note: In this documentation, we indicate which file a code snippet belongs to by showing the filename on the first line in the code samples.

You have now created the basic project structure and included the MapsIndoors SDK and your custom CSS file.

External business POIs from the base map can clutter up your map with irrelevant content. This article describes how to hide unwanted features from the base map - and how to change the colours to better match your branding guidelines.

With Google Maps there are two methods to style the base map. Both style methods can be used across JavaScript, iOS and Android for a consistent look across platforms and apps.

Google Maps Cloud Styling

Cloud-based maps styling makes it easy to style, customize, and manage your maps using the Google Cloud Console, letting you create a customized map experience for your users without having to update your apps' code each time you make a style change.

Warning - paid feature: Functionality accessed by adding a map ID triggers a map load charged against the Dynamic Maps SKU for Android and iOS. See for more information. Use of Cloud Styling with JavaScript does not add any additional cost.

Follow the guidelines linked below to create a Style and associate it with a map ID.

To use a map ID with MapsIndoors, simply add the mapId parameter alongside other options in

Google Maps JSON Style (legacy method)

Use a JSON style declaration to control both colours and visual display of features like roads, parks and other points of interest. You can also hide features entirely.

The Styling Wizard can be an easy way to generate a JSON style:

To use a JSON style with MapsIndoors, simply add the styles array in . Here is an example hiding all Google-supplied POIs:

Starting with the V4 versions of our SDKs, MapsIndoors has introduced the functionality to have your map viewed in 3D, with the appropriate navigational features, rather than just a flat 2D image.

Requirements​

Regardless of your app platform, you need to use the Mapbox map provider in order to use this functionality. You also need to be using V4 of our MapsIndoors SDK's, the specific minimum version depending on the platform.

• Android SDK v4.0.0

• Web SDK v4.18.0

• iOS SDK v4.2.6

If you have fulfilled the above requirements, you can contact your MapsPeople representative to have the 3D map functionality enabled for your Solution(s).

Why 3D Maps?

3D indoor mapping solutions, such as MapsIndoors, can provide companies with a multitude of benefits by creating a detailed and interactive representation of their indoor spaces. One of the primary advantages of using 3D maps is the ability to enhance the overall user experience for employees, visitors, and customers. These interactive maps can help users effortlessly navigate complex facilities such as corporate campuses, shopping malls, airports, or hospitals. By offering a user-friendly interface and intuitive visual aids, 3D maps can facilitate wayfinding, reduce confusion, and improve overall satisfaction for anyone interacting with the indoor environment.

In addition to improving user experience, 3D indoor mapping solutions like MapsIndoors can significantly streamline various operations within a company, leading to increased efficiency and cost savings. With the integration of real-time data, facility managers can optimize space utilization according to the needs of the company. Furthermore, 3D maps can be integrated with other select enterprise systems supported by MapsIndoors, such as asset tracking and user positioning, to create a comprehensive and connected ecosystem that enhances the overall functionality and productivity of the organization. The value of using 3D maps for indoor mapping solutions is multifaceted and can ultimately contribute to a more efficient, user-friendly, and well-managed working environment.

Best Practices

While exact best practices will depend on your specific solution and implementation, we can provide some general pointers of things to consider when developing your solution to work with MapsIndoors 3D maps. Most of these will be specifically pertaining to the inclusion of 3D models in your solution, not to utilising 3D walls and 3D room extrusions.

• Use .glb file format

• Ideally 25-100kb size. You can go higher if you want, just be aware that it impacts load time.

• Keep your models as low-poly as possible.

• Consider whether all your locations need a 3D model.

Overview

From Mapbox v3 (Web) and v11 (Mobile), it's now possible to control what features (layers) should be shown or hidden at runtime. We are introducing three new methods to enhance the control and visibility of features on your Mapbox map. With these methods, you can easily manipulate the visibility of specific features, enhancing the user experience and providing more control over map customization. As an example, you could easily change between a 2D and a 3D map at runtime, without reloading the map data.

Methods

hideFeatures(features: string[]): void

This method allows you to hide specific Mapbox features by passing an array of feature identifiers. Once hidden, the features will no longer be visible on the map. This can be useful for scenarios where certain map elements need to be temporarily removed from view.

Parameters

• features (Array): An array of FeatureType objects representing the features to be hidden.

Switching between 2D and 3D features example:

Example when calling hide3DFeatures() function:

Example when calling hide2DFeatures() function:

getHiddenFeatures(): string[]

This method retrieves the currently hidden features on the map. It returns an array of feature identifiers representing the features that are currently not visible.

Returns

• string[]: An array of strings representing the identifiers of the currently hidden features.

Example

FeatureType(): string[]

This method retrieves all the available feature identifiers that can have their visibility set to "none". It returns an array of these feature identifiers, providing developers with an overview of the features that can be hidden.

Returns

• string[]: An array of strings representing the identifiers of the features that can be hidden.

Example

NOTE: MapboxFeatures() method is deprecated. It still works as expected but will be removed within next major release.

Conclusion

You now have powerful tools to control the visibility of features on your maps. By utilizing the hideFeatures, FeatureType, and getHiddenFeatures methods, you can enhance user experience and customize map displays according to your needs.

See example of the implementation .

What a user can see and do is by default controlled in the MapsIndoors CMS. When signing in with a username and password, or via one of the public authentication providers, authorization will be determined by the user configuration.

If an organization-specific authentication server is configured and used for signing in, there are more possibilities. Similar to the login methods mentioned above, authorization will by default be determined based on the MapsIndoors user configuration. However, if a user that can sign in via the authentication server, but does not exist in MapsIndoors, it will have its authorization determined via the authentication server. This will be done via OAuth claims that can be found on the id_token (or via the userinfo endpoint upon authentication). If no claims are provided, the user will still get read access to the solutions associated with the authentication provider. If claims are provided, they will be mapped to MapsIndoors access definitions, so that authorization can occur based on what claims are associated with the user in the authentication server.

There is a default mapping that will occur if claims are provided in the following format:

"custom:maps_access": [
  {
    "objectId": "012345678901234567891234",
    "objectType": "dataset",
    "role": "editor"
  },
  ...
]

There are three types of roles: admin, editor, and viewer. Authorization can be given on two levels: organization and dataset. A valid MapsIndoors ID must be provided as ObjectId. The claim allows for more than one access definition.

If a different mapping is needed - possibly due to reuse of existing claims, or limitations in the authentication server, this will also be possible. It will, however, require some additional configuration done by MapsPeople.

Overview​

Let's take a look at the events that MapsIndoors offers and how to utilize them.

Events are actions or occurrences that happen in the system you are programming, which the system tells you about so you can respond to them in some way if desired. -- MDN web docs

For example, if the user clicks on a Location on the map, then you can react to that action by presenting the user with additional info about the Location.

A code example is shown in the JSFiddle below, but will be run through bit by bit in this guide.

Ready Event

The ready event will be fired when MapsIndoors is done initializing and is ready to interact.

Building Changed Event

The building_changed event will be fired when the map is moved around and a new Building comes in focus.

This is also related to the Floor Selector which will update its view to show the Floors of the current Building.

The event handler is called with a object representing the building in focus.

Floor Changed Event

The floor_changed event will be fired when the Floor is changed; either by clicking the Floor Selector or by calling setFloor() on the MapsIndoors instance.

The event handler is called with the Floor Index of the current Floor.

Click Event

The click event will fire when the user clicks on a Location on the map.

The event handler is called with a object representing the Location clicked.

MapsIndoors languages are independent of the chosen languages on the device on which the app is used. This means that you need to explicitly tell MapsIndoors which language to use. The example below shows the 'Languages' section and drop-down from which you can select languages:

When a solution has only one language, that language will be the default one. You are able to add as many languages as you want to and choose which one should be the default one. Adding German and Danish languages:

Setting German as default language:

If you do not specify a language, MapsIndoors will show information in the default language defined in the MapsIndoors CMS. Likewise, if you specify a language that is not supported, MapsIndoors will also show information in the default language.

Additionally, aside from methods mentioned here, you can provide translations via the standard method for your device, such as using individual localised strings.

Configuring POI translations in CMS

To provide multiple languages for items in the MapsIndoors CMS, such as "Meeting Room" or "Restroom", the translation must be provided by the user in the CMS. A translation can be provided in any language that is defined for this specific solution. In order to add support for additional languages that we currently do not support, please contact your MapsIndoors representative, and we will enable you to add translations in your desired language.

Once your language of choice has been added as a supported language, you can add the translation by clicking on any POI, which will open a menu on the left side of the screen. Here, you will see the following menu point, where you can enter translations for the languages you wish. If a field is left empty, the fallback language is the default one. In the example below, English (en) and Danish (da) are the enabled languages:

Use Device Language

The MapsIndoors language can be aligned with the device language by supplying the current language code of the device.

The web-app will automatically adjust the language to the language set in the user's browser settings, otherwise default to English. When using Safari, the device's language setting will be used. This is limited to the following languages, and will default to English if the selected language is not supported:

• English

• Danish

• Spanish

• Portuguese

Enabling 2-Factor Authentication​

You can enable 2-Factor Authentication (2FA) in the MapsIndoors CMS. Click the avatar in the top-right corner, and click on "Settings". Follow the instructions to enable 2FA.

Disabling 2FA

After you've enabled 2FA, the page will show instructions on how to disable 2FA again.

If you lose access to your account and are unable to use 2FA for any reason, please , and we'll do our best to find a solution.

MapsIndoors provides support for both Mapbox GL JS v2 and v3. Our commitment to staying at the forefront of mapping technologies ensure that you have the flexibility to choose the Mapbox version that best align with your requirements.

Mapbox V3

In order to access Mapbox v3 and its options, use mapView:

For Mapbox v3, we exposed three new constructor parameters for Mapbox v3:

Your 3D maps are managed and customised through the use of Display Rules. For a more extensive and detailed explanation on Display Rules, . The following information can also be found in the articles detailing Display Rules, but 3D-specific information will be covered in this article.

The MapsIndoors CMS gives you the option of displaying your map in 3D. This is achieved by ensuring that any walls present in your solution are displayed as an extrusion, giving the user the appearance of a 3D map. The appearance of the walls can be customized to match your desired visual identity.

1. Visibility - Controls whether the 3D walls are visible on the map.

The DirectionsRenderer includes functionality to display an animated line that traces the route's path when displayed. You have control over the visual style and timing of this animation.

Accessing the Route Animation Controller

To customize the animation, you first need to access the dedicated animation controller object from your DirectionsRenderer instance. Use the getAnimation() method for this:

JavaScript

When getting the result route from a , we can use the DirectionsRenderer to display this Route on a map.

Once the miDirectionsServiceInstance and miDirectionsRendererInstance are initialized, the methods used from them should be agnostic to the map provider (whether it's Mapbox, Google Maps, etc.) with the exception of getting routes via TRANSIT, which requires Google as the external provider.

This example shows how to set up a query for a route and display the result on a Google Map using the DirectionsRenderer:

for Google Maps

for Mapbox

See all available directions render options in the

Creating Custom Stop Icons

Ready to add a touch of personality to your multi-stop routes? Let's dive into the world of custom stop icons! This article dives into the world of custom stop icon design for multi-stop routes within the MapsIndoors Javascript SDK. It explains how to leverage the interface to craft unique icons that perfectly match your application's style and branding.

Configuring the SSO is currently handled by MapsPeople. Therefore there needs to be an exchange of information - metadata and credentials related to the authentication server, and a unique redirect URL to MapsIndoors. In case of issues, these details must also be documented.

The list of supported providers currently includes Okta, Active Directory Federation Services, Azure Active Directory, Google and Amazon Cognito. However, any provider that can meet the OIDC requirements described below can be supported.

OIDC

OIDC () is the best option for enabling login to MapsIndoors via an authentication server, available from most authentication providers. OIDC is an open standard for authentication, built upon - an open standard for authorization.

Application User Roles are a feature that lets you define various roles you can assign to your users, or they can choose between themselves.

You might have parts of your map that can only be accessed by employees, so you define "Employee" and "Visitor" roles. When using the application to search for directions, users assigned to the "Visitor" role may be shown a different route from "Employee" users based on what they have access to.

How to Configure App User Roles

App User Roles are configured via the MapsIndoors CMS. Go to Solution Details > App Settings > App Configuration, and find App User Roles

Overview

In this guide, you will learn how to show a dot on the map, representing the user's current location.

The JSFiddle example below draws a MapsIndoors map, and adds a position control. Whenever a position is received or updated, if the user has not moved the map themselves, the map will pan to the new location. If the user has moved the map, it will not center on the new location until position control is clicked.

This is a continuation of the article

Navigating within buildings and complexes can be a challenge, especially when considering various obstacles and preferences. The new avoidHighwayTypes and excludeHighwayTypes parameters empower you to customize your indoor routes to suit your specific needs, ensuring a seamless and accessible journey.

Supported Highway Types:

Some locations in MapsIndoors can have additional polygon information. These polygons can be used to render a room or area in a special way or make geofences, calculating whether another point or location is contained within the polygon. If a MPLocation has polygons, these can be retrieved using:

As demonstrated above, a polygon's outer ring/path as well as holes are arranged as [longitude, latitude] pairs. As not all locations has polygons, the polygon array may be empty. On the contrary, some locations, like entire building floors, might have more than polygon.

When using the MapsIndoors SDK, the system for detecting collisions will sometimes, at high zoom levels, result in the Labels of POI's that are close together being hidden, no matter what you do. Here we present a small workaround, so you can disable collisions for specific zoom levels.

For Android, there are two ways of implementing this, and which you should use depends on your desired map behavior.

Google Maps for Android

If you wish for the collision behavior to change when the maps stops moving, you should use this piece of code. This would generally be the most performance-friendly option.

However, if you wish for the collision behavior to change when the maps starts moving instead, you should use this.

MapsIndoors is built on top of Google Maps or Mapbox depending on the SDK flavor you decide to use. On this page, you'll create the necessary keys with the relevant APIs enabled, retrieve a MapsIndoors API key and install the necessary dependencies to get started building your own app.

This is an example of enabling and disabling location clustering on the map as well as providing custom cluster tapping behaviour and custom cluster images.

Enabling and disabling clustering is done through the SolutionConfig, in the following way:

To create custom icons for clusters you can set a MPClusterIconAdapter either on the MPMapConfig when you are creating a new instance of MapControl or you can do it on runtime by setting a MPClusterIconAdapter directly on a MapControl object. Here is an example of doing it when creating a new MapControl:

Applying a ClusterIconAdapter on runtime can be done like this:

This is an example of displaying some details of a MapsIndoors location

Requirements for this tutorial will be to have a running fragment or activity with a MapsIndoors Map loaded and ready to use.

We need a view that shows the details of the location. Here we will use a TextView to display the name and description of a location:

Once the map is ready move the camera to a Venue:

We will then create a listener for when a user clicks on a marker to show the details of the selected location. This is done by setting a onLocationSelectedListener on your MapControl object. We will also listen to when the info window closes, to remove the DetailsTextView from the view. This is done by setting the onMarkerInfoWindowCloseListener on MapControl.

In this tutorial we will request a route and list the route parts. A MapsIndoors route is made of one or more legs, each containing one or more steps.

Start by creating a BaseAdapter implementation with a MPRoute property, and include all the required functions.

Inside the init section, setup a directions service, call the directions service and save the route result to your route property

Override the getCount function to return the number of steps

Override the getView function to create your views that should be displayed in the list

Use the MapsIndoors.getLocationsAsync() method to search for content in your MapsIndoors Solution.

Setup a query for the nearest single best matching location and display the result on the map

Application User Roles are a feature that lets you define various roles you can assign to your users, or they can choose between themselves.

You might have parts of your map that can only be accessed by employees, so you define "Employee" and "Visitor" roles. When using the application to search for directions, users assigned to the "Visitor" role may be shown a different route from "Employee" users based on what they have access to.

How to Configure App User Roles​

App User Roles are configured via the MapsIndoors CMS. Go to Solution Details > App Settings > App Configuration, and find App User Roles on the page. Here, you can configure existing roles, and add new ones.

Click Add App User Role and enter the name of the newly created Role in all defined languages for your Solution.

How to Assign/Change a Role to a User

Assigning or changing App User Roles to users is done in the app itself. The method depends on which platform you're developing for. Here are some examples:

To fetch User Roles from the SDK, you call MapsIndoors.getUserRoles() to retrieve a collection of MPUserRoles tied to a loaded solution:

To set User Roles, applyUserRoles is used:

For more information, see the .

Features Affected by App User Roles

The App User Roles are useful for setting limits on who can find certain Locations. App User Rules influence the map in three ways; which Locations are displayed on the map, whether they show up in search results, and the directions you can get.

For any Location defined on the map, there is a menu named Restrictions, where you are presented with options for limiting functionality certain App User Roles.

• Open for all - All users can view, search for, and get directions to this Location.

• Open for specific App User Roles - Select which App User Roles have access to viewing, searching and getting directions to this specific Location.

• Closed for All - No users will see this Location on the map.

The Map

If a Location has been restricted to certain App User Roles, it will not be displayed on the map for those who do not have permission.

Search

Similarly to the effect on the map, if a Location has restrictions, it will not show up in the search results for users without sufficient permissions.

Directions

App User Roles can be used to determine the directions users get. For instance, you can restrict Doors between two Locations to only be passable by a certain App User Role.

Note: If you restrict a Room to only be accessible to certain App User Roles, you restrict both directions to and through that Room. It effectively sets restrictions on all Doors leading to that Room as well.

Querying a multi-stop route

To query a multistop route a new overload MPDirectionsService.query has been introduced MPDirectionsService.query(from: MPPoint, to: MPPoint, stops: List<MPPoint>?, optimize: Boolean).

Showing and configuring a multi-stop route on the map

With the introduction of the multi-stop routes. There has also been added new functionality to the MPDirectionsRenderer to facilitate the new multi-stop routes.

You can still render the route as a Route with stops, using setRoute(route: MPRoute) on the DirectionsRenderer. But the interface of the MPDirectionsRenderer has been expanded with a defaultStopIcon as well as an overload of: setRoute(route: MPRoute, icons: HashMap<Integer, MPRouteStopIconProvider>?)

The defaultStopIcon can be configured to show any image. It can also be set to null, to not show any icon for the stops on the Route. We supply the MPRouteStopIconConfig that allows you to customize the default pin to fit your application.

To use your own images, you can extend the MPRouteStopIconProvider with your own class. Here is an example using a bitmap for the image

Adding a custom image to a specific waypoint

It is also possible to render an image specific to a single stop. By using setRoute(route: MPRoute, icons: HashMap<Integer, MPRouteStopIconProvider>?)

Here we will show a blue icon for the third stop. Leaving the first two indexes as null, means that the renderer will use the defaultStopIcon. If you want to render a specific known stop on an optimized route. You can find the ordering of the stops on an optimized route through MPRoute.orderedStopIndexes.

Crafting a Dynamic, Color-Transitioning Example

Here's a code snippet that alternates the building outline color every second, cycling through a palette of contrasting colors, it's not the most practical application, but it shows how to achieve it.

You may desire a way to change the stroke color based on user requirements to make the map meet different accessibility requirements.

This article builds on existing knowledge and assumes familiarity with the and the .

The MapsIndoors Javascript SDK empowers you to streamline navigation within venues using the multi-stop feature. This functionality allows you to obtain directions to multiple destinations within a venue effortlessly. Provide a sequence of stops, and MapsIndoors will generate the most efficient route, considering two options:

• Navigation with multiple stops: Navigate through the stops in the exact order you specify. This is ideal when the order of visits is crucial.

• Optimized multi-stop navigation (traveling salesman algorithm): Let MapsIndoors intelligently reorder your stops to create the fastest possible route, saving you valuable time.

Custom Properties are key/value data that can be associated with different geodata (Venue/Building/Location) within MapsIndoors. MapsIndoors supports two different types of Custom Properties:

• Language-specific Custom Properties

• Generic Custom Properties

Language-specific Custom Properties are meant for values that is displayed to the enduser in their preferred language. Using language-specific Custom Properties, it is possible to store a key/value combination in multiple different languages. The MapsIndoors SDKs allows for retrieval of the correct values based on the user's preferred language. If your Solution has multiple languages, you must provide the necessary translations for each Custom Property in each of these languages.

As opposed to static data, which does not change unless data is synchronized, Live Data can change in real time, and these changes can be instantly reflected on the map and in searches.

Common use-cases are:

• Changing the appearance of meeting rooms or workspace desks on a map, or in a list, based on occupancy information. For example, change the icon in order to indicate that a room is occupied.

• Changing the position of a POI representing a vehicle.

Support for Live Data requires that server-side integrations are in place. For example, visualizing live occupancy data requires that a calendar or booking system integration is in place. An integration like that is set up in

The language of MapsIndoors is independent of the chosen language on the device on which the app is used. This means that you need to explicitly tell MapsIndoors which language to use.

If you do not specify a language, MapsIndoors will show information in the default language defined in the MapsIndoors CMS. Likewise, if you specify a language that is not supported, MapsIndoors will also show information in the default language.

Additionally, aside from methods mentioned here, you can provide translations via the standard method for your device, such as using individual localized strings.

Configuring POI translations in CMS

To provide multiple languages for items in the MapsIndoors CMS, such as "Meeting Room" or "Restroom", the translation must be provided by the user in the CMS. A translation can be provided in any language. In order to add support for additional languages that we currently do not support, please contact your MapsIndoors representative, and we will enable you to add translations in your desired language.

As a key element in the MapsIndoors platform, we offer API's for effeciently calculating and displaying the most optimal routes from anywhere in the world to any Location inside a Building in MapsIndoors. In the case of travelling internally at a Venue, this calculation can be done on a local map provided by MapsIndoors. In the case of travelling between Venues or from outdoors to indoors, MapsIndoors provide a seamless journey outline from a specified Origin through automatically selected Entry Points at the edge of your Venues to the specified destination.

In order to provide a route between Venues, MapsIndoors integrate with external and global map providers. Our preferred provider is Google Maps.

The central components that utilize a Directions experience is the and the . But before we get to the fun part, let's examine some key concepts first.

MapsIndoors Auth is handled in two ways:

• API keys - This is how apps built on top of the SDKs are authorized by default,

• MapsIndoors Auth server - This is how the MapsIndoors CMS authorizes, as well as apps to access secured solutions.

The MapsIndoors Auth server is located at https://auth.mapsindoors.com - including SSO page and OIDC metadata. The server is an IdentityServer4 implementation - with support for OAauth 2 and OIDC protocols.

It stores all users that are managed through the MapsIndoors CMS, as well as configurations for authentication providers. Based on these users and authentication providers, it can authenticate and authorize users in order to access the MapsIndoors CMS and secured MapsIndoors solutions.

This guide covers the different aspects of user authentication and authorization in the MapsIndoors JavaScript SDK.

Usually, access to the services behind the MapsIndoors SDK is restricted with API keys. However, as an additional layer of security and control, access can be restricted to users of a specific tenant. A MapsIndoors dataset can only be subject to user authentication and authorization if integration with an identity provider exists. Current examples of such identity providers are Google and Microsoft. These providers and more can be added and integrated to your MapsIndoors project by request.

We recommend using a library such as AppAuth to handle verification and response to get a token to use in the MapsIndoors SDK.

To utilize an OAuth2 login flow for your MapsIndoors project, you will need to provide some details to the OAuth2 client, like the issuer url, client id, scopes and possibly a preferred identity provider if there is more than one option. These details are available as arguments in the MapsIndoors.onAuthRequired callback.

You are required to provide a redirect_url. The authorization server will redirect the user back to the application using this URL after successful authorization.

Note that the redirect link must be known to MapsIndoors and white-listed for your identity provider integration. You must inform us about all the links that you need for your application, both for development and production use so they can be white-listed. How to apply the authentication details is varying from each OAuth2 client, but you can see below how they are applied in a login flow using the

The above login flow is executed by the SDK if authentication is needed.

The SDK will then make sure that all requests for data are performed using this access token.

For a full example, please .

Note that the access token obtained from a MapsIndoors Single Sign-on flow cannot be used as access token for the Booking Service. Single Sign-on access tokens are issued by MapsIndoors and not the underlying tenant. You need to login directly on your Booking tenant to get an access token that can be used for working with the Booking Service as an authenticated user.

Show a Map with MapsIndoors​

Initialize MapsIndoors

We start by initializing MapsIndoors. MapsIndoors is used to get and store all references to MapsIndoors-specific data. This includes access to all MapsIndoors-specific geodata.

Place the following initialization code in the onCreate method in the MapsActivity that displays the Google map. You should also assign the mapFragment view to a local variable, as we will use this later to initialize inside the onCreate, after it has been created:

If you do not have your own key, you can use this demo MapsIndoors API key: 02c329e6777d431a88480a09.

Initialize MapsControl

We now want to add all the data we get by initializing MapsIndoors to our map. This is done by initializing onto the map. is used as a layer between the map provider and MapsIndoors.

Start by creating an initMapControl method which is used to initiate the and assign it to mMap:

In your onMapReady callback function, assign the mMap variable with the GoogleMap you get from the callback and call the initMapControl method with the mMapView you assigned in the onCreate to set up a Google map with MapsIndoors Venues, Buildings and Locations. For Mapbox you can simple call initMapControl inside your onCreate:\

Expected result:

See the full example of MapsActivity here:

The Mapbox examples can be found here:

To implement a custom floor selector, we expect you to already have completed the Getting Started Tutorial.

This guide will walk you through the process of implementing a custom floor selector using the MapsIndoors JavaScript SDK. The custom floor selector provides a more flexible and visually appealing way to switch between floors in your MapsIndoors-enabled application.

Prerequisites

Before you begin, make sure you have completed the getting started tutorial for the MapsIndoors JavaScript SDK. You should have a basic MapsIndoors map set up in your project.

Implementation

Step 1: Create the CustomFloorSelector Class

First, we'll create a CustomFloorSelector class that will handle the creation and management of our custom floor selector.

Step 2: Implement Floor Management Methods

Add methods to handle showing, hiding, and updating the floor selector:

Step 3: Implement Floor Button Creation and Updating

Add methods to create and update the floor buttons:

Step 4: Initialize MapsIndoors and CustomFloorSelector

Now, let's initialize MapsIndoors and our custom floor selector:

Step 5: Set Up Event Listeners

Finally, set up event listeners to update the floor selector when necessary:

Customization

You can customize the appearance of the floor selector by modifying the CSS styles in the createSelectorElement and updateFloorButtons methods. Adjust colors, fonts, sizes, and positioning to match your application's design.

Some larger organisations may have not just multiple Venues, but also multiple Solutions in the MapsIndoors system. Therefore, it is naturally important to be able to switch between them.

At it's core, this is done simply by switching out the API key and reloading the system. However, there are a few more steps that can be done to ensure smooth transition between Solutions.

Starting a Solution​

To initialize MapsIndoors, do the following:

Google Maps

Mapbox

Switching Solutions

You switch Solutions by changing the active API key using setAPIKey().

We recommend creating your own function to call in the future for this purpose, like the example here with switchSolution():

Google maps

Mapbox

The MapsIndoors Template is a downloadable starting point for you to integrate basic usage of MapsIndoors, containing search and directions functionalities, into your existing app. If you just want to get started with a simple solution with no customisation, this should fulfil your needs. Going through this guide will also teach you some principles on how MapsIndoors interacts with an app, and is a natural next step after the "Getting Started" guides.

If you need more customisation you can implementing your own solution using the documentation found on this site, or modify this code as needed.

MapsIndoors Template is provided as is, and can be integrated into your existing app. If you need further features, or want to customize existing ones, you're free to modify this one to your needs. However, MapsPeople offers no support or responsibility for changes made.

Prerequisites

Before you get started, you need to get the API keys needed. This process is the same for both platforms.

Get Your Google Maps API key

First, you need to , just like you did in the guide (Please note: You are going to need a Google Billing Account for this step, so go ahead and if you haven't already). When the project is created, the following APIs and the specific SDK you plan to use must be enabled from the .

• Google Maps Distance Matrix API

• Google Maps Directions API

• Google Places API Web Service

• Maps SDK for Android/iOS

When the above 3 APIs and the relevant SDK are enabled, you can retrieve the API key from the . On the Credentials page, click Create credentials > API key.

Get Your MapsIndoors API key

If you are not a customer yet, you can use this demo MapsIndoors API key {{sdk.tutorialAPIKey}} to follow this guide, or you can to get your building drawings processed and hosted by us to receive a unique API key. For the purpose of this guide, both methods will work.

Integrating the App

First, download or clone the pre-made project from GitHub: .

• Open the project you just downloaded, and copy the classes located in java/com/mapspeople/mapsindoorstemplate into your own App

• Add the Maven repository () to your project's build.gradle file

• Add the following dependencies from build.gradle:

• For the next step, this project uses for image handling in your application. If you are not using Glide, either import it, or if you use a different image library, you need to change some lines of code in the app. What you need to change them to, depends on the library you use. The lines are:

• Copy the layout and drawables from the res folder into your app

• Copy the String values from res/values into your app

• Copy the google_maps_api.xml file to your project and insert a valid Google Maps API key -

• Change the places where the navigation graph is used, if you are not using navigation. Alternatively, create a navigation action for MapsFragment. If so, change the navigation controller call on line: 74 inside MapsFragment.kt under the TODO

• Check the FirstFragment.kt class on how to apply User Roles to the map fragment

The Final Result

Summary

Congratulations! You now have a functioning map in your own app, with the ability to both search for Locations and generate directions! If you want more advanced features, check out , or modify the existing code from this tutorial to suit your needs!

Ready to add indoor navigation to your app with MapsIndoors SDK?

This guide will show you how to implement directions, render routes, and interact with them in your application.

Design

• Would you like to show textual directions in a UI?

  • What will your user interface look like?

You begin by creating an initial application. Throughout this tutorial, you will modify and extend that starter application to create a simple application which covers the basic features of this guide.

Set Up Your Environment

This guide explains how to start using a MapsIndoors map in your Android application using the MapsIndoors Android SDK v4.

We recommend using Android Studio for using this tutorial. Read how to set it up here:

If you do not have a Android device, you can .

The class MPDirectionsService is used to request routes from one point to another. The minimum required input to receive a route is an origin and a destination.

This example shows how to setup and execute a query for a Route:

The route can be customized via the directionsRenderer. An example could be the color of the rendered path and the background color of the rendered line. This can be set like this: