Android SDK for Indoor Maps

The Android SDK provides advanced rendering and navigation features, as well as deep linking ability, for indoor maps.

Concepts

Venue Map Data (VMD) provides functions for programmatic access to venue metadata about the venue, including buildings, floors, and places within. Support for rendering the map for interactive applications is provided with the combination of VMD information served from VMD endpoints (or locally for offline support), and optionally assets served by mapping providers (Google, Open Street Maps, etc) for interactions that involve context of the geo-coded location of the venue.

Venue Object Model

A Venue is a collection of buildings and outdoor floors that represent the space between buildings (parking lots, walyways, outdoor fixtures).
A Building is a collection of floors.
A Floor is a collection of units/places.
A Unit/Place is visually represented as a point or polygon that describes the shape, with a unique placeId for identification. These also have categories and other meta-data that can be used to provide visual annotations, or deep link buisiness actions.

Styling and Visualization

The SDK provides default styles and icons for rendering the venue, which can be customized by the developer. Tiles serve as the data source for rendering and visualization, with various options for performance and detail. Our reference apps reference a public style endpoint that is sufficent for development and getting started. Application teams should account for their own style assets as one of the VMD endpoints to consider during architecting your solution.

Supported platforms

VM-SDK supports Android 5.0+. NOTE: Android emulators require 5.0+ with Google APIs. Recommended Android emulator setup: Nexus 6 API 25 w/ Google APIs. Consult your map provider’s documentation for their own supported platforms.

Getting started

With the Venue Maps SDK Reference App, you’ll see how to:

Show a map using a specific map provider, and display your custom map tiles
Load the VMD file with wayfinding data
Optionally load additional custom map data for directions and naming
Allow custom styling for your map tiles
Allow custom styling for your wayfinding
Handle errors that occur

Add the VMSDK dependencies to your build.gradle file

implementation 'com.aegirmaps:vmsdk-core:2.0.5'
implementation 'com.aegirmaps:vmsdk-legacy:2.0.5'

Use the provided methods to render and navigate the venue

Install and run the reference app

Extract the Android VM-SDK zip file.
In the extracted directory, navigate to vmsdk-sampleapp and open it in Android Studio.
The reference app uses Google Maps, MapLibre Maps and MapTiler, so you will need to generate a Google Maps API Key and a MapTiler API Key.
Once you’ve generated an API Key, open app/src/main/res/values/strings.xml and update the map_tiler_key and google_maps_key.
Build and run.

Load Venue Map Data

To start with, identify the base url where your VMD assets are deployed. This can be a remote url, or a local file path. If this is a local file path, add the VMD assets to your application and refer to that folder using asset manager and creating an instance of VMDAssetFileCollection with the required parameters.

AssetManager assetManager = getApplicationContext().getAssets();
VMDFileCollection fileCollection = new VMDAssetFileCollection(assetManager, "VENUE_ID", "DEFAULT_MAP_PROVIDER", getApplicationContext().getCacheDir().getAbsolutePath());
Map.load(fileCollection, mapDelegate, callback);

If you are using assets stored on your server, you can use the VMDUrlFileCollection

new VMDUrlFileCollection(
    "REMOTE_ASSETS_FILE_URL",
    "VENUE_ID",
    cacheFolder,
    "DEAULT_MAP_PROVIDER",
    fileCollection -> {
        Map.load(fileCollection, mapDelegate, callback);
        return null;
    }
);

After you’ve initiated the loading, register your MapDelegate and wait for the didFinishLoadingMap callback to be invoked. At this point you can proceed to Display a venue map.

public void didFinishLoadingMap(
    Map vmd, 
    CustomMapInfo customMapInfo) {
    //display venue map
}

Display a venue map

VectorMapView mapView = new VectorMapView(context);
mapView.setLayoutParams(new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT));

// id of the container where the map is going to be located into
FrameLayout container = findViewById(R.id.map_container);

container.addView(this.mapView, 0);
mapView.setDelegate(mapViewDelegate);
String styleUrl = String.format(getResources().getString(R.string.maptiler_street_style), mapTilerKey);
this.mapView.onCreate(this.savedInstanceState, this, styleUrl);

You can specify more attributes to the map view before it's loaded by implementing the public void willStartLoadingMapView(MapView mapView) from the MapViewDelegate:

public void willStartLoadingMapView(MapView mapView) {
    mapView.setMinZoom(16f);
    mapView.setMaxZoom(22f);
    mapView.setMapPosition(centerPoint, bearing, zoom);
    VMMapViewLoadConfig mapViewConfig = new VMMapViewLoadConfig();
    mapViewConfig.setVenueBaseURL("https://myserver.com/[VENUE_ID]/venue_map_[VENUE_ID]", "MAP_VERSION", "DEFAULT_MAP_PROVIDER");
    mapView.setupMap(vmd, this.venueStyle,
            "VENUE_ID", activeIndoorFloors, activeOutdoorFloors,
            mapViewConfig
    );
}

After you’ve initiated the map view loading, register your MapViewDelegate and wait for the didFinishLoadingMapView callback to be invoked.

public void didFinishLoadingMapView(MapView map) {
    //Do any additional customization of the map view
}

At this point, you should have a map display of the world with your map tiles superimposed.

Note: If you are using local assets that have been added to your application, be sure to refer to the appropiate subolder for the correct location of the venue base URL.

Enable wayfinding

If you want the waypath to be rendered on your map view, you’ll have to create a VectorWalkingPathOverlay and add it to your mapview:

//Create a new overlay that will display paths and markers for directions
this.walkingPathOverlay = new VectorWalkingPathOverlay(this.mapView);
//Set the delegate so this class can override certain functionality
this.walkingPathOverlay.setDelegate(MapActivity.this);
this.walkingPathOverlay.setMap(this.vmd);

Key Methods

There are two key method to to use when wayfinding.

Finding waypath between two locations

Get the map object from your map view and find a path between a given start and end waypoint.

mapView.getMap().findWaypathBetweenWaypoints(walkingPathOverlay.getStartingWaypoint(), walkingPathOverlay.getEndingWaypoint(), options, MapActivity.this, callback);

Implement the WayfindingDelegate interface to get notified of any callbacks from the SDK for wayfinding.

/// Callback after waypath has been determined
/// - Parameter waypath: the Waypath that leads from the starting point to the ending point
public void didFinishFindingWaypath(Waypath path)

Convert a waypath to text directions

The second key method for wayinding is to take an instance of a Waypath that describes the path from a given start point to a end point and convert that into human-readable directions.

//configure any custom options here
TurnByTurnDirectionOptions options = new TurnByTurnDirectionOptions();
options.setMaxDistanceForLeg(25);
options.setMinDistanceForImportantTurns(10);
this.vmd.createTurnByTurnDirectionsForWaypath(path, this.customMapInfo, options, MapActivity.this);

Similar to implementing the WayfindingDelegate interface for getting notified when a waypath is found, you also need to do the same to receive the callback when a waypath has been converted to turn by turn directions.

public void didFinishCreatingTurnByTurnDirections(List<MapDirectionStep> turnByTurnDirections)

Load Legacy Venue Map Data

You can use the same VMDAssetFileCollection object to parse a legacy map. Note that loading a legacy map depends on whether the map_VENUEID.xml file exists or not in your map assets folder.