Android SDK Integration Guide - Mobile Engagement
This guide is a quick start to adding the Phunware Mobile Engagement SDK to an Android app to power Phunware's Marketing Automation module which allows you to create and send broadcast, geofence, and beacon campaigns to your mobile app users.
Step 1: Add the Phunware Maven remote repository
Insert this block into
Step 2: Add the Mobile Engagement SDK as a dependency in your app's
This will automatically import the required dependency for Phunware Core
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: Retrieve App ID, Access Key and Signature Key from MaaS Portal
Navigate to Phunware's MaaS portal to find your App ID, Access Key and Signature key.
GCM setup (deprecated, see FCM): https://developers.google.com/cloud-messaging/android/client
Part of the GCM setup is managed through the Mobile Engagement SDK including:
- Add the play-services-gcm to your application gradle
- changes required to the AndroidManifest
Step 5: 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 6: Add Phunware keys for App Id, Access Key, and Signature Key to Manifest
Add the keys obtained in step 4 to Manifest.
Step 7: Add Location and Storage permissions to Manifest
This allows you to utilize location-based messages and beacon messaging.
Step 8: 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 9: Designate an Activity to launch from notifications
Notifications can be customized by extending the
NotificationCustomizationService. The intent which launches your activity from a notification will have extras with message and promo information.
Step 10: Show Messages
MessageManager you can easily show a list of available messages.
Step 11: 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 12: Enabling Push Notifications
New in Version 3.1.2 is the ability to use the SDK with or without push notifications as a feature. Enabling push notifications is as easy as enabling them through a simple call to the Engagement API
The Phunware Mobile Engagement SDK allows you to easily integrate location based messaging and notifications into your app.
When your app first starts up, you need to initialize the Mobile Engagement SDK using the
Engagement.Builder. This is where you provide your
AppId, Access Key, and
Signature Key from the Maas Portal. All production apps should use the production environment.
When setting up your app, you also need to register with GCM in order to receive push notifications from the Mobile Engagement backend. To do so, follow the steps that can be found in Googles official documentation at:
Note: All manfiest changes required in the setup have been done in the SDK's AndroidManfiest file.
By default, the Phunware Mobile Engagement SDK will log to the Android system log and a log file, and will not log in production environments. This is entirely configurable using the builder's
addLogger(Logger logger) method.
You can easily create your own
Logger implementation that will do whatever you'd like with log messages, or use one of the built in
This allows you to easily use or discard log messages as you see fit.
The Phunware Mobile Engagement SDK is broken up into 3 managers,
AttributeManager. Once the Engagement SDK has been initialized, these can be accessed using static accessors on the
If you ensure the Mobile Engagement SDK is initialized in your Application's
onCreate method, then you'll be able to access the managers from anywhere within your app (except ContentProviders).
LocationManager is your entry point into the Location components of the Mobile Engagement SDK. Through it you can start or stop the Location services, access current geozone state, and register for notifications when geozone state changes.
Starting and Stopping Location Services
By default, the Mobile Engagement SDK will monitor geozones and notify the server when the user enters or leaves them. App developers may want to allow users to opt out of location tracking, or user may deny the app location permissions on newer versions of Android, so it's important that app developers are able to start and stop the service.
To manage the location state, simply call
Engagement.locationManager().stop(). This setting will be persisted across app restarts and device reboots.
If your app targets API level 21 or higher, you will need to manage permissions at runtime. This means disabling the LocationManager until the user grants the
The same starting and stopping of the LocationManager can be applied if you explicitly allow the user to opt out of location services.
Access Geozone State
LocationManager can be used to get the current state of Geozones. This can allow you to use the known Geozones to populate a map of locations, or determine whether the user is currently inside a location.
All calls to get Geozone information from the
LocationManager are asynchronous, so you need to provide a
Callback and display appropriate UI.
Register for Geozone State Changes
You may want to register to be notified when the user enters or leaves geozones, or when new geozones are added or removed from the list. There are two ways to do this with the Phunware Mobile Engagement SDK, depending on whether you need to be notified when your app is in the foreground or background.
Foreground Geozone Notifications
To be notified of geozone state changes when your app is in the foreground, for instance to update a your app's view state when the user enters a location, you can add one or more
LocationListeners to the
LocationManager. This listener will be notified any time the state of Geozones changes while it is still registered.
Be sure to remove the
LocationListener when it is no longer needed to avoid leaks.
Background Geozone Notifications
It's also possible to register for notifications of Geozone events when the app isn't running. This can be useful if you want to process events with a service or add local notifications.
In order to receive background notifications of Geozone events, you simply need to register an
IntentService in your manifest that responds to at least one of the following intent filters:
IntentService will then be started and notified for any Geozone events you are interested whether your app is running or not.
The MessageManager allows you to interact directly with the LocationMessaging messages, including retrieving and modifying messages, and registering to be notified of message updates.
The Public Interface
To retrieve an instance of MessageManager, simply call `Engagement.messageManager()` after initializing the Engagement library.
Listening for Message Events
The MessageManager accepts multiple MessageListener objects which can be notified of events, like when a message is received, deleted or updated. This allows app developers to manage foreground components when message status changes, like updating an unread message count, or changing the display of messages in a list based on their status.
Receiving Background Events
All of the same events that can be consumed by a listener can also be consumed by a service so that app developers don't need to keep anything retained in memory to receive updates. By defining a non-exported service, app developers can have the app woken up when message events happen.
Setting exported to false means that the service is not accessible to any other apps on the system, reducing potential security vulnerabilities and ensuring the an app developer's app only receives messages destined for it.
The app developer can define any or all of the following actions:
By only subscribing to events that the developer cares about, we limit the amount of code that is needlessly run.
While the service implementation will be a standard Android IntentService, the SDK will provide a convenient abstract class that will take care of determining the appropriate action and also retrieving the Message from the Intent.
User notifications are entirely handled by the SDK, so you don't need to worry about when to show what notifications. There are times, however, when you may want to customize the notification message, perhaps to personalize it or make it more relevant to the user. This can be accomplished by implementing a bound service. Since the 3.2.0 release, we also provide the ability to customize the foreground notification that gets spawned in the same way that the user can customize all other notifications if the user is ranging for beacons. Additionally, in 8.0 and above, we provide a way to edit the various notification channels for each type of notification. Since we provide the message type with each channel, the user can have as many or as little channels as they like. If the user is okay with the default channels no change is needed and they can proceed with the default channel for each message type.
The AttributeManager allows you to interact directly with the Mobile Engagement attributes, including retrieving and modifying attributes, and retrieving attribute metadata.
Deep linking into the SDK can be done taking advantage of met data sent on a campaign. For example:
First, register your intent filter in the AndroidManifest.xml where you want your intents to come in:
Then, inside of the Activity that you want to receive these intents, handle the message metadata as you see fit.
Message State Transitions
Campaign messages go through several states during their lifecycle..
Initially when a message is received it is in the UNREAD state. When the user marks it as read using Engagement SDK APIs , the state changes to READ. When the message is in the read state, if another new message is received for the same campaign, the message is marked as UNREAD again.
Finally when the users deletes the message it goes to the DELETED state whereupon it is deleted from the SDK storage.
Following diagram represents the complete flow of a campaign message after it is received