Getting Started
The following sections introduce you to the Cisco Spaces WayFinding SDK API resources and provide instructions to make your first project.
The Cisco Spaces WayFinding SDK lets developers add indoor navigation and wayfinding features to iOS and Android apps. It uses Cisco Spaces location services to give users accurate turn-by-turn directions inside large buildings. Users can quickly find meeting rooms, desks, amenities, and other important locations.
This SDK is part of the Cisco Spaces ecosystem. The platform connects people, devices, and spaces. It delivers smart workspace solutions such as asset tracking, occupancy analytics, and environmental monitoring.
This SDK enables mobile applications to use best-in-class map and user location data such as:
- Get the user’s location indoors using BLE.
- Display maps showing points of interest and the user’s location.
- Search for points of interest.
- Provide wayfinding to any point of interest or other mapped location.
Prerequisites
These are the prerequisites:
- A Cisco Spaces WayFinding API key
- Cisco Spaces WayFinding SDK download link
| Operating System | Download options |
|---|---|
| iOS | SpacesWayFindingSDK.xcframework SpacesWayFindingApp.xcframework Mapbox.xcframework (Maplibre library) |
| Android | SpacesWayFindingSDK.aar SpacesWayFindingApp.aar |
iOS Required Permissions
| Key | Type | Value |
|---|---|---|
| Privacy - Bluetooth Peripheral Usage Description | String | Bluetooth permission is required to check the status of Bluetooth Services if it is enabled or not on the device and for iBeacon |
| Application requires iPhone environment | Boolean | YES |
| Privacy - Location Always Usage Description | String | Turn-by-turn navigation and location-based notifications require location services to be enabled |
| Privacy - Location Always and When In Use Usage Description | String | Turn-by-turn navigation and location-based notifications require location services to be enabled |
| Privacy - Bluetooth Always Usage Description | String | Bluetooth permission is required to remind you to turn your Bluetooth on |
| Privacy - Location When In Use Usage Description | String | Turn-by-turn navigation and location-based notifications require location services to be enabled |
| Privacy - Motion Usage Description | String | Motion data required to enhance WayFinding experience across multiple levels |
- Minimum version
| Operating System | Version |
|---|---|
| iOS | iOS 16.0 or later |
| Android | JDK 17 or later, Android 8.0(SDK version 26) or later |
Android sample build.gradle
In build.gradle, add these libraries for Android SDK:
- org.maplibre.gl:android-sdk
- org.maplibre.gl:android-plugin-localization-v9
- org.maplibre.gl:android-plugin-markerview-v9
implementation (fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar", "*.jar"))))
implementation ("com.google.android.gms:play-services-location:21.0.1")
implementation ("org.maplibre.gl:android-sdk:11.7.1")
implementation ("org.maplibre.gl:android-plugin-localization-v9:3.0.2")
implementation ("org.maplibre.gl:android-plugin-markerview-v9:3.0.2")
implementation ("com.github.bumptech.glide:glide:4.16.0")
implementation ("androidx.cardview:cardview:1.0.0")
implementation ("androidx.lifecycle:lifecycle-extensions:2.2.0")
Download sample project
To download the sample project, contact Cisco Spaces team.
Start SDK
Before you display a map, start listening to the user's location, or perform any other action, you first need to start the SDK and ensure that the SDK is in running state.
1. Initialization
- Create an instance SpacesWayFinding as spacesWayFinding.
- To initialize the SDK, app initiates a call spacesWayFinding.getAllBuildings(), followed by spacesWayFinding.selectBuilding().
2. Get all buildings
- Obtain a Cisco Spaces WayFinding API key in advance.
- Provide the API key along with the region (io, eu, sg, event) as parameters when calling the method. This call returns a list of building location IDs and names.
iOS (Swift)
/// initialize Spaces WayFinding
let spacesWayFinding = SpacesWayFinding(
apiKey: String,
region: SpacesWayFindingRegion
)
spacesWayFinding.getAllBuildings(buildings, error in
/// Custom Logic
)
Android (Kotlin)
val spacesWayFinding = SpacesWayFinding(
apiKey: String,
region: SpacesWayFindingRegion
)
spacesWayFinding.getAllBuildings{ spacesBuildings, error ->
/// Custom Logic
}
3. Select building
- Initialize SDK and get all buildings.
- Select a building.
- App state returns as running after the building is selected successfully.
iOS (Swift)
/// Initialize SpacesWayFindingParams
let params = SpacesWayFindingParams(building: building)
params.mode = .debug
params.loggerLevel = .error
spacesWayFinding.selectBuilding(params: params) { [weak self] (state) in
/// Your Custom logic based on SDK start
}
Android (Kotlin)
/// Initialize SpacesWayFindingParams
val params = SpacesWayFindingParams(buildingCredential)
params.loggerLevel = .error
spacesWayFinding.selectBuilding(applicationContext, params) { state ->
/// Your Custom logic based on SDK start
}
Ensure the API key and region are valid before initializing. Handle errors if the building location ID is invalid or selection fails.
4. Render MapWidget
To render the building map, instantiate and present the MapWidget class (iOS, Android) to the application view. For more information, see MapWidgetFragment Class and MapWidgetViewController Class in SDK Reference.