Welcome to Phunware SDKs
Welcome to Phunware's SDK Documents. On this page you will find instructions on how to on-board Phunware's SDKs for Mobile Engagement and Wayfinding for both iOS and Android development environments. After you have completed the on-boarding process, Follow the links to additional SDK documentation and the SDK repos.
How Do Phunware SDKs Work?
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 a weapons array, and you may 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 offer you the building blocks for adding mapping/routing and mobile engagement functionalities to your apps, 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.
What Do Phunware SDKs Do?
Phunware Core SDK
Phunware’s Core SDK is required and integrated into all Phunware modules to provide security; login functionality; Org, User, and Role Management, Application keys, Content Management functionality, and Analytics.
Because Core is fully integrated, you will not need to import this SDK separately or complete any additional steps to add this SDK.
Included in Phunware’s Core SDK are:
User and Role Management
Content Management Module
- SSL used for all transmission
- Building Bundles are encrypted with AES-256
Android SDK 4.0.3+ (API level 15) or above
Android Support Library v4 24.0+
General On-boarding Steps for ALL Android SDKs
Step 1: Add the Phunware Maven remote repository
Insert this block into allprojects -> repositories: Add the following to your
Step 2: Add Needed Permissions
In the Android manifest, the following permissions are needed:
NOTE: BLE and Android SDK version 4.3 (API 18) or above are required if Bluetooth is actually is going to be used. If your users only are going to use Bluetooth for positioning, you should change the android:required attribute to true (this will filter out non-BLE devices at Google Play). Observe that the WAKE_LOCK permission can be removed, but background navigation performance might become worse.
Step 3 - Retrieve App ID, Access Key and Signature Key from MaaS Portal
Add your app to Mass Portal.
The App UUID is required if you are using Phunware's App Builder to create your apps.
Step 4: Add Phunware key resources to strings.xml for App Id, Access Key, Signature Key
Add the keys obtained in step 4 to strings.xml.
Step 5: Add Phunware keys for App Id, Access Key, and Signature Key to Manifest
Add the keys obtained in step 4 to Manifest.
On-boarding Steps for Android Mapping/Location SDKs
Step 1: Add the Mapping SDK as a dependency in your app's build.gradle file
These two lines includes all dependencies necessary to use the Phunware Mapping and Location SDKs.
The Core SDK (and all of its parts) is automatically integrated with the Mapping SKD.
Step 3: Add your Google Maps Api Key to AndroidManifest.xml
Create a string resource that contains your Google Maps API Key.
If you need help getting a Google Maps API Key, please find instructions here: Get a Google Maps API key
On-boarding Steps for Android Engagement SDK
Step 1: Setup GCM Service in MaaS
If you are planning on sending Alerts and Notifications (Broadcast Campaigns), you have obtained Android and iOS keys needed to push notifications from your app.
Navigate to Phunware's MaaS portal to find your App.
After you have obtained your keys:
Step 2: Add the Mobile Engagement SDK as a dependency in your app's
The Core SDK is automatically imported with the Mobile Engagement SDK.
Step 3: (Optional) Add beacon support if you are using beacons
If you would like to take advantage of the Mobile Engagement SDK's beacon support, simply add the
With properly configured beacons in your environments, no other code changes are required to take advantage of beacon-based messaging.
Step 4: Add Location and Storage permissions to Manifest
This allows you to utilize location-based messages and beacon messaging.
NOTE: Background location notifications currently cannot work with runtime permissions required for apps targeting Android SDK level 23 and higher, so your targetSdkVersion in your build.gradle file must be 22 or lower.
Step 5: Configure the Mobile Engagement SDK with your environment
You should only initialize the Mobile Engagement SDK once, after you initialize PwCoreSession. Once it's complete, you can access the Location, Message and Attribute managers directly.
Once initialization is complete, users will be automatically notified with your custom broadcast messages. If you have location and storage permissions they will also be able to receive messages for location events, like entering a retail store.
Step 6: Designate an Activity to launch from notifications
Notifications can be customized by extending the
This launches your activity from a notification with message and promo information.
Step 7: Show Messages
NOTE: Calls to the MessageManager are asynchronous, and may require loading data from the network.
Step 8: Customizing Notifications
This service allows app developers to customize notifications. It must be implemented initially even if the user would like to just use standard out of the box notifications.
Step 9: Enable Push Notifications
- iOS 9.0 or greater
- Xcode 8 or greater
General On-boarding Steps for ALL iOS SDKs
Step 1: Initialize Cocoapods and add SDK(s) to podfile
a. 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.
b. In the Podfile file that is generated, modify the text in Xcode or your preferred text editor. Add the line "pod 'PWMapKit'" or pod 'PWEngagment'" after the "target" line and before the "end" line. Save the file.
c. Enter "pod update" in Terminal while in the directory that contains the Podfile.
d. Use the .xcworkspace file that was generated by the pod install from now on.
e. 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.
f. (For Mobile Engagement) Navigate to Build Phases inside your Xcode Projects and click on Link Binary With Libraries add following frameworks:
Step 2: Get App Keys from MaaS Portal
Step 3: Add Core call in AppDelegate
In your application's AppDelegate, add the following:
Step 4: Set Required background modes values.
NSLocationAlwaysAndWhenInUseUsageDescription: (This is the message you want to display on the prompted alert when the user grants the app permission to use the location service.)
On-boarding Steps for iOS Mapping/Location SDKs
Step 1: Setup the map view
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.
The example shows how to instantiate a PWMapView and load a building from the sample application, where "mapView" is a PWMapView property of calling class.
Step 2: Register the Location Provider (for Blue Dot implementations)
The PWMapView can display a user location on the map if a location provider is registered with the PWMapView.
The location providers are in the PWLocation framework, and each different provider requires different steps to set up.
(See Readme at https://github.com/phunware/maas-location-ios-sdk to view setup examples of all different provider options).
Once the location provider is initialized, the call may be used to register the provider with the PWMapView.
Step 3: Calculate and show a route
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.
Step 4: Update current route
As a user traverses a route, PWMapKit will post notifications to tell the developer when the next routing instruction is reached.
On-boarding Steps for iOS Engagement SDK
Step 1: Add p12 Push Notification Certificate to App in MaaS Portal
A. In your Apple Developer's Console get your p12 Certificate. You will download this certificate to MaaS Portal to enable Broadcast Campaigns.
B. Once it's created, download the push production certificate and add it to Keychain Access. Then, from Keychain Access, export both the certificate and key.
(Right click to view the Export option) as a .p12 and set a password.
C. Log in to Maas portal and navigate to the app created for your application and update the following.
Click Apps to go to your application list.
Either Click NEW or find the App you want to send push notifications for and click Edit in the Action menu
Complete the Marketing Automation section as follows:
p12 Certificate: Upload the certificate you downloaded to your local drive
Password: The password you setup for the push certificate.
Environment: Select Production environment for production apps.
Step 2: Beacon and Geofence Registration
As of PWEngagement, the application developer needs to implement the following delegate in launch options. This registers for the remote notifications and notifies user when app is launched from a local notification (Geofence/ Beacon).
Step 3: Remote Notification Handling
Apple has these primary methods for handling remote notifications. You will need to implement these in your application delegate, forwarding the results to PWEngagement:
Step 4: Fetching/Updating Profile Attributes
PWMEAttributeManager customizes notifications to users' preferences. The PWMEAttributeManager is the central point for fetching and updating attributes associated with the device or user. You use an instance of this class to fetch and update profile and user attributes.
Step 5: Listening for and Receiving Notifications
The application can listen to the following to be notified of Message Read/Modified notifications:
The application can be notified of Geofence events like entry/exits. Add/Remove and Modify Geofence notifications by subscribing to the following keys.
Deep Linking (Option)
The Message object has metadata property which may consist of multiple key-value pairs that allow for deep link to different sections of the application (Ex: Launch Image, Initial screen, app launch behavior etc.)
By default a notification launches the App and goes to the HOME page. Metadata deep linking can direct the notification to open elsewhere in the app or to web URL.
Promotions Handling (Option)