This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
Creating an ADA-Compliant app with Mapping SDK 3.0
The Mapping SDK 3.0 is written to allow developers total control over their UI so they can create the best possible experience for their users. Most of the work necessary to make an app accessible for visually impaired users is not specific to this SDK, and information regarding best practices can be found here: Developing Accessible apps
We have created an ADA Sample App demonstrating how the Mapping SDK can be used in a way that is useful to visually impaired individuals. Some of the recommended implementation details used in the sample app are:
- Saving Floor and POI data to a SQL database after the first call to addBuilding, allowing for faster data loading on subsequent app launches and making information available in areas of poor internet connectivity.
- Setting a LocationProviderFactory on the PhunwareMapManager before calling addBuilding, so turn-by-turn navigation functionality is available.
- Implementing Navigator.OnManeuverChangedListener in a navigation list view to update and read out maneuvers as the users moves along a route
How would a visually-impaired user navigate the app?
After moving past the onboarding screen, the user is initially brought to the directory list of all POIs in the building (On first app load this list is initially blank, then populates as soon as data is downloaded from the network).
Users can switch to the “Around Me” tab to explore what is near their current location (once acquired) or navigate through the Directory list to hear details about the building’s POIs. If they are looking for something specific they can use the search and filter functions on the directory to more easily find the intended POI.
Activating a POI from either the Around Me or Directory list will open a new view with details about that point. If we are able to determine the user’s current location, a “Get Directions” button will be activated on this screen.
Activating the “Get Directions” button will bring up a route preview screen. Navigating from the top down, Talkback will read out a description of the route (start and end points, distance, floor changes), let the user know about the two preview tabs, and notify them of the “start navigation” button. If they choose to continue scrolling through the page they can hear all the route steps listed out.
Activating the “Start navigation” button opens the navigation view, with the listview tab active. The list of route steps is initially covered by a blocker view which tells the user which direction they should face before they start moving. Once they are oriented correctly, route steps will be read off as they approach each one. Long steps (over 20 ft) will have reminders read out at 20 foot intervals so the user knows when to turn and what direction. Straight maneuvers will also have warnings at 50 foot intervals telling the user how much longer to continue straight. When the user reaches their destination they will hear “You have arrived” and navigation will stop. If the SDK detects that the user has gone off route they will be automatically rerouted to their destination.
UI Elements developers may wish to reuse
Automatic Re-routing
Navigator.OnManeuverChangedListener has a callback method onRouteSnapFailed() that will be called on all registered listeners any time a user’s location is too far away from the route to implement route snapping behavior
In our ADA sample app we have implemented a threshold count to avoid unnecessary rerouting. Once we have had 5 snap failures in a row, we cancel navigation, recalculate a route to the destination from the user’s new current location, and restart navigating with the new route.
Navigation Overlay View
The NavigationOverlayView is a custom ViewPager implementation that displays route step details on top of the map in navigation mode
The view is added to the same view hierarchy as the PhunwareMap and visibility is toggled based on whether the user is in navigation mode.
Custom UI when Talkback is turned on
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
Getting Started (Android)
This guide is a quick start to adding a Phunware Map to an Android app. Android Studio is the recommended development environment for building an app with the Phunware Mapping SDK.
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
(v3.0.0-3.1.0 of Location SDK-Android)
Integrating a Location Provider
This guide provides instructions for integrating Location SDK for routing. It is only applicable for users of the Android Location SDK v 3.0.0-3.1.0.
*If you are using a more recent version of the Android Location SDK, view the Location SDK-Managed Provider Integration Guide.
*If you are using an earlier version of the Location SDK for Android contact Phunware Support (support@phunware.com).
In order to show the user's current location, you must add a Location Provider, which updates location information.
Phunware's location providers:
Provider | Settings/Keys | Compile Statement | Description |
---|---|---|---|
BLE |
| com.phunware.location:provider-senion:3.0.0 | Senion Lab BLE (bluetooth low energy) location provider |
CMX - Hyperlocation (MSE) |
| com.phunware.location:provider-cmx:3.0.0 | Cisco Hyperlocation (wifi) location provider |
GPS | com.phunware.location:provider-gps:3.0.0 | GPS location provider |
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
Integrating a Managed Provider
Step 1 - Add the Phunware Maven remote repository. Insert this block into allprojects
-> repositories
:
allprojects { repositories { maven { url "https://nexus.phunware.com/content/groups/public/" } } }
Step 2 - Add Phunware key resources to strings.xml for App Id, Access Key, Signature Key
Navigate to portal, find your app, and add your access key and signature key to setup your application.
<string name="app_Id">APPID</string> <string name="access_Key">ACCESSKEY</string> <string name="sig_Key">SIGKEY</string>
Step 3 - Add Phunware keys for App Id, Access Key, and Signature Key to Manifest
<meta-data android:name="com.phunware.APPLICATION_ID" android:value="@string/app_id"/> <meta-data android:name="com.phunware.ACCESS_KEY" android:value="@string/access_key"/> <meta-data android:name="com.phunware.SIGNATURE_KEY" android:value="@string/signature_key"/> <meta-data android:name="com.phunware.ENCRYPTION_KEY" android:value="@string/encrypt_key"/>
Note that encryption key may not be provided in portal under your app's settings. If it isn't, you may leave it empty.
Step 4 - Add managed provider as a compile dependency.
apply plugin: 'com.android.application' android { ... } dependencies { ... compile 'com.phunware.mapping:mapping:3.1.2' compile 'com.phunware.location:provider-managed:3.1.1' ... }
Step 5 - Set the Location Provider on the PhunwareMapManager
@Override public void onPhunwareMapReady(final PhunwareMap phunwareMap) { mapManager.setPhunwareMap(phunwareMap); this.phunwareMap = phunwareMap; mapManager.addBuilding(buildingId, venueGuid, new Callback<Building>() { @Override public void onSuccess(Building building) { if (building == null) { Toast.makeText(MainActivity.this, "No building", Toast.LENGTH_LONG) .show(); return; } // ManagedProvider must be set after the map is loaded ManagedProviderFactory.ManagedProviderFactoryBuilder builder = new ManagedProviderFactory.ManagedProviderFactoryBuilder(); builder.application(getApplication()) .context(new WeakReference<Context>(getApplication())) .venueId(String.valueOf(buildingId))); ManagedProviderFactory factory = builder.build(); PwManagedLocationProvider provider = (PwManagedLocationProvider) factory .createLocationProvider(); mapManager.setLocationProvider(provider, building); ...
It's important to note that Managed Provider must be built and set on my MapManager after the the map is ready and the building has been loaded.
There are a few values that will be needed to build a ManagedProvider, they are as follows:
- application: reference to the users application
- context: Context of the application
- buildingId: Id of the venue/building you currently have loaded
Step 6 - Enable Location Updates
@Override public void onPhunwareMapReady(final PhunwareMap phunwareMap) { ... mapManager.addBuilding(buildingId, venueGuid, new Callback<Building>() { @Override public void onSuccess(Building building) { ... // enable my location (blue dot) after setting the location provider mapManager.setMyLocationEnabled(true); } } }
Enable location updates after we have the map and building as well as after setting the provider
Step 7 - Manage Location Updates when in the Background
@Override protected void onPause() { super.onPause(); // If you have permission to access location and you don't have a building then proceed if (canAccessLocation() && building == null) { if (mapFragment != null) { mapFragment.getPhunwareMapAsync(this); } } if (mapManager != null) { mapManager.setMyLocationEnabled(false); } } @Override protected void onResume() { super.onResume(); if (mapManager != null) { mapManager.setMyLocationEnabled(true); } }
In order to ensure that we handle lifecycles correctly we must stop requesting location updates when we background, and begin requesting them when we are in the foreground.
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
Using a MapView in a Custom Layout
MapView is a subclass of the Google Maps MapView class. It can be used to place a map in any Android View.
Users of the MapView class must forward all the activity lifecycle methods to the corresponding methods in the MapView class. Examples of these methods include onCreate(), onDestroy(), onResume() and onPause().
This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.
Getting POI info from a Map Marker
The Mapping SDK associates a PointOptions object with its associated Google map marker object.
Android Mapping SDK Installation - Getting Started
This guide is a quick start to adding a Phunware Map to an Android app. Android Studio is the recommended development environment for building an app with the Phunware Mapping SDK.
Integrating a Managed Provider
Managed Providers offer a combination of signal location providers. This combination results in higher accuracy rates for location in dynamic way finding.
Phunware Managed Providers:
Provider | Settings/Keys | Description |
---|---|---|
Cisco Beacon Point |
| Cisco vBLE (virtual bluetooth low energy) location provider |
Mist |
| Mist vBLE (virtual bluetooth low energy) location provider |