PWMapKit is a comprehensive indoor mapping and wayfinding SDK that allows easy integration with Phunware's indoor maps and location-based services. The primary use of the components of PWMapKit revolve around creating a map view, displaying points of interest, showing the user's location and indoor routing.
This document provides the prerequisites and start up instructions for integrating any of Phunware's module SDKS and use cases with sample code in:
- Objective C
This guide provides the most common location-based services use cases important to SDK developers. It is NOT an exhaustive list of the use cases that can be developed using the Phunware Mapping and Location SDKs.
What Do the Phunware LBS SDKs Do?
SDK stands for Software Development Kit, a tool which provides code, APIs, and libraries to enable specific functionality in an application.
Phunware's Location Based Services (LBS) module is driven by the Mapping and Location SDKs, providing application developers with a set of tools to enable the display of indoor venue maps, points of interest, and wayfinding throughout these venues.
Developers can utilize these LBS SDKs to offer app users either
- Static wayfinding, where users can interact with a map with highlighted routes and step by step directions, but do not see their actual position or movements reflected on the map
- Dynamic wayfinding, where users can interact with a map with highlighted routes and step by step directions, including a blue dot that mirrors users' their actual position and movements.
This guide provides the most common Location Based Services use cases important to SDK developers. It is NOT an exhaustive list of the use cases that can be developed using the Phunware Mapping and Location SDKs.
The APIs and data libraries provided offer a framework and expose the necessary data to offer mapping/wayfinding experiences. In addition, a sample including basic user interface code is provided, which can be used as a starting point by developers. This basic UI can be used as is or customized and enhanced to support specific app use cases and branding needs. For example, additional use cases (not included in this document) that a developer might add to an app include saving a custom POI or sharing a user's location. These types of customized behaviors are driven by the application code using the data libraries and APIs available through the SDK.
How Do I Use this Document and SDKs in General
Imagine that an app is a space ship made from legos. You could just build the whole ship out of individual pieces, but it would take a long time. Now imagine that someone else already built a similar space ship and they can give you a warp drive, engine room, a weapons array and medical bay. Suddenly your space ship got a whole lot easier to build. The spaceship you create will not be exactly like the example you received, because you might choose not to add the weapons array and want to create your own custom medical bay. You can simply choose which building blocks to use as is, which to modify to meet your own needs, and what to create from scratch. You get the idea.
The SDK use cases and snippets in this document offers you the building blocks for adding mapping functionality to your app, but you have the flexibility to use these building blocks (or not) in the ways that make sense for your application and your business needs.
Use of this software requires review and acceptance of our terms and conditions for developer use located at http://www.phunware.com/terms/.
PWCore uses the following third-party components. All components are prefixed so you won't have to worry about namespace collisions.
|AFNetworking||A delightful iOS and OS X networking framework.||MIT|
|TMCache||Fast parallel object cache for iOS and OS X.||Apache 2.0|
|SSZipArchive||Zipping and unzipping files for iOS and OS X.||MIT|
PWMapKit uses the following third-party components. All components are prefixed with
PW to avoid namespace collisions should your application also use an included component.
|SVPulsingAnnotationView||A customizable MKUserLocationView replica for your iOS app.||MIT|
|LBS MaaS Portal Configuration Guide||A guide to configuring Mapping and Location Providers in MaaS Portal. For detailed guides on integrating specific Location Provider Hardware contact Phunware Support firstname.lastname@example.org.|
|LBS MaaS Portal Training Videos||A series of training videos that walk you through basic Mapping and Location Provider configuration in MaaS Portal. These videos work as a companion to the Configuration guides.|
|iOS Mapping SDK GitHub Repo||GitHub repo for PWMapKit SDK Code|
|iOS Location SDK GitHub Repo||GitHub repo for PWLocation SDK Code|
|iOS Core Reference||Class reference guide for the Phunware PWCore SDK|
|iOS Mapping Reference||Class reference guide for the Phunware PWMapKit SDK|
|iOS Location Reference||Class reference guide for the Phunware PWLocation SDK|
- PWLocation 3.1.7 or greater (Automatically included when pod install PWMapKit)
- PWCore 3.1.1 or greater (Automatically included when pod install PWMapKit)
- iOS 9.0 or greater
- Xcode 8 or greater
- SSL used for all transmission
- Building Bundles are encrypted with AES-256
PWCore SDK - Integration
Phunware’s Core SDK is required and integrated into all Phunware modules. Included in Phunware’s Core SDK are:
User and Role Management
Content Management Module
SDK Integration NOTE <Remove later>
Mapping/Location SDK Use Cases
Static Wayfinding Use Cases
Dynamic Wayfinding (Blue Dot) Use Cases
Blue Dot Navigation Modes
Mapping SDK 3.0 (iOS)
This SDK is intended to provide both high-level easy-to-use functionality for SDK Developers, as well as lower level component access for SDK Developers desiring more control over their interface.
Can be found here
Mapping SDK 3.0 Integration Guide (iOS)
Mapping Setup and Prerequisites
iOS Managed Provider Setup
- Phunware recommends using CocoaPods to integrate the framework. Simply add
pod 'PWMapKit'to your podfile.
- Alternatively, all of the following frameworks can be added to the Vendor/Phunware directory of your project:
- Initialize Cocoapods if your project does not already use it. If your environment does not already have Cocoapods installed, enter "sudo gem install cocoapods" in Terminal. After Cocoapods is installed, navigate to your project's root directory in the Terminal. Enter "pod init" in Terminal.
- In the Podfile file that is generated, modify the text in Xcode or your preferred text editor. Add the line "pod 'PWMapKit'" after the "target" line and before the "end" line. Save the file.
- Enter "pod install" in Terminal while in the directory that contains the Podfile.
- Use the .xcworkspace file that was generated by the pod install from now on.
- In your project's Info.plist file, add a row with key: "Privacy - Location When In Use Usage Description" (Xcode should autocomplete this) and for value, add what you want your users to see when prompted for Location use by the device.
The framework comes with a ready-to-use sample application. In order to use this application you will need to update the configuration with your MaaS credentials and location provider information.
- Update your MaaS credentials and set up the building identifier in
Register Location Provider
Routing for iOS Mapping
Current Route Updates
Displaying your Map
Showing Current Location on the Map
This will display your current location on your building map if the MaaS and hardware were also configured properly. If you encounter issues, create the PWManagedLocationManager as a property and assign its delegate to your view controller rather than calling registerLocationManager on the PWMapView. The error may then be captured with the PWLocationManagerDelegate callback function "- (void)locationManager:(id<PWLocationManager>)manager failedWithError:(NSError *)error;"
Routing for iOS Mapping
Simply feed the PWRoute class method two points of interest and whether or not accessibility should be considered when calculating the route. accessibility:YES will not use access points marked as "inaccessible" in the portal, e.g. stairs between floors.
Current Route Updates
As a user traverses a route, PWMapKit will post notifications to tell the developer when the next routing instruction was reached.
Maps-ADA Sample App Developer Overview (iOS)
This document gives an architectural overview of some of the most important classes in the Maps-ADA iOS sample application.
The main view controller of the application. It holds several ways of searching through points of interest and also provides the routing experience for the user to follow once the route has been selected. Primary use of the PWMapView can be found in this class.
This category on the MapViewController configures and controls the segmented controls that sit above the map itself. It features two primary states: discovery of points of interest/routes, and routing. Segments for discovery are "Map", "Directory", and "Around Me", whereas the segments for routing are "Map" and "List".
This category on MapViewController configures the search bar that sits above the segmented controls, as well as controlling the results of the search displayed in a table view.
This NSObject controls the content displayed in the "Directory" segment.
This subclass of DirectoryController controls what is displayed and selected in the routing table view, which can be accessed via thisbutton. That button can be found in the top left of the screen when on the "Map" segment and not currently routing.
This subclass of DirectoryController controls what is displayed and selected in the "Around Me" segment's table view. Uses the PWMapViewDelegate to display points of interest within a radius around the current user location, ordered by proximity.
Shows the user a summary of the selected route and all the route steps, accessible from the Point of Interest Details view. Also has a preview of the route on a PWMapView that can't be interacted with by the user.
Displays the list of instructions for an in-progress route. This view leverages callbacks from RouteAccessibilityManager to give a non-sighted VoiceOver user instructions to traverse the route. These include orientation updates (i.e. "Turn to your 10 o'clock"), current instruction updates, and distance remaining updates.
Uses updates to orientation, location, and current instruction notifications to produce VoiceOver messages that are passed via delegate at the appropriate time. Most accessibility work for traversing a route is done within this class.
The app conforms to accessibility guidelines laid out by Apple, and leverages the existing VoiceOver features as close to their original intention as possible. Here are some areas that were specifically tailored to assist non-sighted users.
One of the selectable segments in the primary view of the application is "Around Me". This displays the nearest points of interest to the current user location in a table format rather than map view, so that a non-sighted user can easily see what's closest.
When a point of interest is selected from Directory or Around Me, the user is taken to a point of interest details view. If the user then selects "GET DIRECTIONS", they will be taken to the pre-routing view. This gives a summary of the route that might contain useful information for a non-sighted user (number of floors traversed, approximate walking distance).
Route Directions List
When a route is started, the user will have two segments available to select from: Map and List. The List view will show all the routing instructions of the current route, and also keep the accessibility labels updated as the route is traversed. In some cases, it will read out the information on a trigger from the current route progress. For example, if the user is coming up on the next instruction, VoiceOver might tell the user to "Turn to your 3 o'clock".
How would a visually impaired user navigate the app?
- On first start of the app with VoiceOver enabled, an on-boarding screen is presented that gives an overview of some VoiceOver specific features. There is an option to go to the iOS Settings app where they may disable VoiceOver, or the user may continue to the app
- When VoiceOver is enabled, the user is brought immediately to the Directory view. This view shows all the points of interest in the selected building, and the user may use the index on the right to jump to a particular letter, where the letter corresponds to the first letter of the point of interest.
- The Around Me segment may be selected to show which points of interest are closest to the user. The max range can be changed with one of the controls on the bottom, and the list is sorted by distance from the user to the point of interest (closest at top, farthest at bottom)
- There is a navigation button available where the user may manually select the start and end point of the route. If the user chooses to route through this Navigation button, the route will be started automatically and they will be taken to a "List" view of route instructions if VoiceOver is enabled.
- Selecting a point of interest from either Directory or Around Me will show the details of the selected point of interest. If the user's location is currently available, there will be a "GET DIRECTIONS" button visible near the bottom of the view that the user may select to be taken to a pre-routing view.
- The pre-routing view gives a high level overview of the route, and if VoiceOver is enabled, the individual route steps are not listed unless they select the "SHOW ALL STEPS" button. This was done so that if the user wants to start the route right away, the amount of VoiceOver swipes to get to the "START NAVIGATION" quicker than having to swipe through all the individual instructions. When "START NAVIGATION" is selected, the user is taken back to the original view where the "Map" segment is available, but they will start on the "List" segment which shows a list of Route Directions.
- If VoiceOver is enabled, the Route Directions list will give many helpful updates to the user via VoiceOver such as "Turn to your 10 o'clock".