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.
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:
Security-Login
Org Management
User and Role Management
Application Management
Content Management Module
Analytics Module
Security Protocols
- SSL used for all transmission
- Building Bundles are encrypted with AES-256
Important Links
SDK On-boarding
Android Requirements
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 Using the 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 Requirements
- 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:
| [PWCore setApplicationID:@"YOUR_APPLICATION_IDENTIFIER" accessKey:@"YOUR_ACCESS_KEY" signatureKey:@"YOUR_SIGNATURE_KEY"]; | ||||
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. Apple Push Notification services (APNs) tutorial 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)
|