Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

This guide is a quick start to adding the Phunware Messaging SDK to an Android app.  Android Studio is the recommended development environment for building an app with the Phunware Messaging SDK.

Step 1- Add the Phunware Maven remote repository. Insert this block into allprojects -> repositories:

allprojects {
    repositories {
        maven {
           	url ""

Step 2 - Add the Messaging SDK as a dependency in your app's build.gradle file:

apply plugin: ''

android {

dependencies {
    compile 'com.phunware.messaging:messaging:3.0.2'

This will automatically import the required dependency for Phunware Core

Step 3 (Optional) - Add beacon support if you are using beacons

dependencies {
  compile 'com.phunware.messaging:messaging:3.0.2'
  compile 'com.phunware.messaging:beacon-location-manager:3.0.2'

If you would like to take advantage of the Messaging SDK's beacon support, simply add the beacon-location-manager dependency.

With properly configured beacons in your environments, no other code changes are required to take advantage of beacon based messaging.

Step 4 - Add Access Key and Signature key to Portal

Navigate to portal, find your app, and add your access key and signature key to setup your application.
Gcm setup can be done here: 

Under these steps we can ignore a few things because they are already taken care of for you:

In the GCM setup, it asks you to add the play-services-gcm to your application gradle. This does not need to happen because we have already included the play-services-gcm dependency in the sdk itself.

Additionally, All the changes required to the AndroidManifest have been done at the SDK level so you do not need to add the GCM tutorial changes on behalf of the SDK.

Step 5 - Add Phunware key resources to strings.xml for App Id, Access Key, Signature Key

<string name="app_Id">APPID</string>
<string name="access_Key">ACCESSKEY</string>
<string name="sig_Key">SIGKEY</string>

Step 6 - 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" />

The App Id, Access Key, and Signature Key are found on the MaaS portal.

Step 7 - Add Location and Storage permissions to Manifest

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> 

This allows you to utilize location-based messages and beacon messaging. Note that 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 8 - Configure the Messaging SDK with your environment.

public class MyApplication extends Application {

  public void onCreate() {
	//initialize PwCoreSession
	//initialize LocationMessaging
    new LocationMessaging.Builder(this)
			.appId(/*your app ID from the MaaS portal, as a long*/)
	//start location manager to receive location based events


You should only initialize the Messaging 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

    android:name=".MessageActivity" >
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="locationmessaging/message" />

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.

if (getIntent().getAction() == Intent.ACTION_VIEW) {

    Message intentMessage = getIntent().getParcelableExtra(MessageManager.EXTRA_MESSAGE);,

    boolean hasPromo = getIntent()
            .getBooleanExtra(MessageManager.EXTRA_PROMO_HTML_FLAG, false);
    if (hasPromo) {
        long messageId = intentMessage.campaignId();
		LocationMessaging.messageManager().getMessage(messageId, new Callback<Message>() {
    		public void onSuccess(Message data) {
      		  //do something with the message

    		public void onFailed(Throwable e) {
        		Log.e(TAG, "Failed to get message for id: " + messageId, e);



Step 10 - Show Messages

public class MessageListFragment extends Fragment {
  public void onActivityCreated(@Nullable Bundle savedInstanceState) {

    LocationMessaging.messageManager().getMessages(new Callback<List<Message>>() {
      public void onSuccess(List<Message> data) {
        //do something with the Messages

      public void onFailed(Throwable e) {


Using the MessageManager you can easily show a list of available messages.  Note that calls to the MessageManager are asynchronous, and may require loading data from the network.


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

 <manifest ...>
    <service android:name=".MyNotificationEditService" android:exported="false">
        <action android:name="com.phunware.locationmessaging.EDIT_NOTIFICATION" />
public class MyNotificationEditService extends NotificationEditService {
  @Override public void editNotification(Notification notification) {
    notification.setTitle("Hi, Ryan!");
  • No labels