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 10 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 "https://nexus.phunware.com/content/groups/public/"
       	}
    }
}

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

apply plugin: 'com.android.application'

android {
	...
}

dependencies {
	...
    compile 'com.phunware.messaging:messaging:3.0.0'
    ...
}

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.0'
  compile 'com.phunware.messaging:beacon-location-manager:3.0.0'
  ...
}

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 and add your access key and signature key from the GCM setup to your application.
Gcm setup can be done here: https://developers.google.com/cloud-messaging/android/client 

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 SenderId to App build.gradle

In order to verify that we are receiving GCM notifications from the correct sender you must modify the build.gradle of your app to overwrite the SDK's GCMSenderId resValue

build.gradle
defaultConfig {
    resValue 'string', 'GCMSenderId', '\"YOURSENDERIDHERE\"'
}

Step 6 - Add Phunware keys for App Id, Access Key, Signature Key and Encryption 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, Signature Key and Encryption 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 {

  @Override
  public void onCreate() {
    super.onCreate();
	//initialize PwCoreSession
	PwCoreSession.getInstance().registerKeys(this);
	
	//initialize LocationMessaging
    new LocationMessaging.Builder(this)
			.appId(/*your app ID from the MaaS portal, as a long*/)
			.environment(LocationMessaging.Environment.PROD)
        	.build();
	
	//start location manager to receive location based events
	LocationMessaging.locationManager().start();
  }

} 

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

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

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);
    LocationMessaging.analytics().trackCampaignAppLaunched(intentMessage.campaignId(),
            intentMessage.campaignType());

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

    		@Override
    		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 {
 
  @Override
  public void onActivityCreated(@Nullable Bundle savedInstanceState) {
    super.onActivityCreated(savedInstanceState);

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

      @Override
      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.

  • No labels