Skip to content
Liferay Push Client for Android
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
docs/images
gradle/wrapper
library
.gitignore
.travis.yml
README.md
build.gradle
gradlew
gradlew.bat
settings.gradle

README.md

Liferay Mobile SDK logo

Liferay Push for Android

Build Status Coverage Status

Setup

Add the library as a dependency to your project's build.gradle file:

dependencies {
	compile 'com.liferay.mobile:liferay-push:1.2.0'
}

Breaking changes in version 1.2.0

Since version 1.2.0 you have to add a new property when declaring the PushService:

<service android:name=".PushService"
	android:permission="android.permission.BIND_JOB_SERVICE" /> <!--You have to add this-->

Use

Registering a device

To receive push notifications, your app must register itself to the portal first. On the portal side, each device is tied to a user. Each user can have multiple registered devices. A device is represented by a device token string. Google calls this the registrationId.

To register a device, we need a SENDER_ID, the id of our project in firebase. Read Firebase's documentation to learn how to get the SENDER_ID.

The SENDER_ID is available, after creating a firebase project, in the Cloud Messaging tab under the project settings:

After obtaining the SENDER_ID it's easy to register a device with Liferay Push for Android, you just have to call to the following method:

import com.liferay.mobile.push.Push;

Session session = new SessionImpl("http://localhost:8080", new BasicAuthentication("test@liferay.com", "test"));

Push.with(session).register(this, SENDER_ID);

If you want to use Liferay 7.x you should manually specify the version with a call like this:

push.withPortalVersion(70)

Since all operations are asynchronous, you can set callbacks to check if the registration succeeded or an error occurred on the server side:

Push.with(session)
	.onSuccess(new Push.OnSuccess() {

		@Override
		public void onSuccess(JSONObject jsonObject) {
			System.out.println("Device was registered!");
			registrationId = jsonObject.getString("token");
		}

	})
	.onFailure(new Push.OnFailure() {

		@Override
		public void onFailure(Exception e) {
			System.out.println("Some error occurred!");
		}

	})
	.register(this, SENDER_ID);

The onSuccess and onFailure callbacks are optional, but it's good practice to implement both. By doing so, your app can persist the registrationId device token or tell the user that an error occurred.

Liferay Push for Android is calling the GCM server, retrieving the results and storing your registrationId in the Liferay Portal instance for later use.

Don't forget to add in your app the Internet permission if you haven't done it already:

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

And, if you are using Liferay 7, you will have to add permissions to be able to register the device in the portal:

All set! If everything went well, you should see a new device registered under the Push Notifications menu in Configuration. Next step is Receiving push notifications

Using the registrationId directly without registering against Liferay Portal

If you obtain the token manually, you can register the device to the portal by calling the following method:

Push.with(session).register(registrationId);

Now each time the portal wants to send a push notification to the user test@liferay.com, it looks up all registered devices for the user (including the one just registered) and sends the push notification for each registrationId found.

You should note that the Push class is a wrapper for the Mobile SDK generated services. Internally, it calls the Mobile SDK's PushNotificationsDeviceService class. While you can still use PushNotificationsDeviceService directly, using the wrapper class is easier.

Receiving push notifications

Once your device is registered, you have to configure both the server and the client to be able to receive push messages.

To send notifications from Liferay you should configure the API_KEY inside System Settings, Other and Android Push Notifications Sender. To obtain the API_KEY you should, again, access your firebase project settings and under Cloud Messaging, use the Legacy Server Key.

Then you have to configure your project to be able to listen for notifications:

  • You should implement a BroadcastReceiver instance in your app. Android's developer documentation shows you how to do this. Specifically, you should:

    • Register a <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> in your AndroidManifest.xml file.

    • Register a WAKE_LOCK permission and Internet if you had not used those permissions before:

       <uses-permission android:name="android.permission.INTERNET" />
       <uses-permission android:name="android.permission.WAKE_LOCK" />
    • Add a BroadcastReceiver and a IntentService to your project:

       <receiver
           android:name=".PushReceiver"
           android:permission="com.google.android.c2dm.permission.SEND">
           <intent-filter>
               <action android:name="com.google.android.c2dm.intent.RECEIVE" />
               <category android:name="com.liferay.mobile.push" />
           </intent-filter>
       </receiver>
      
      <service android:name=".PushService" 
      		android:permission="android.permission.BIND_JOB_SERVICE"/>
    • The code implementing those classes is really simple:

       public class PushReceiver extends PushNotificationsReceiver {
           @Override
           public String getServiceClassName() {
               return PushService.class.getName();
           }
       }
       
       public class PushService extends PushNotificationsService {
       	 @Override
           public void onPushNotification(JSONObject jsonObject) {
               super.onPushNotification(jsonObject);
               
               // Your own code to deal with the push notification
           }
       }
  • If you want to execute an action or show a notification only if the application is active, you could register a callback:

Push.with(session).onPushNotification(new Push.OnPushNotification() {

	@Override
	public void onPushNotification(JSONObject jsonObject) {
	}

});

This method only works if you have already registered against Liferay Portal using the previous instructions.

Sending push notifications

There are many ways to send push notifications from Liferay Portal. See the Liferay Push documentation for more details. Alternatively, you can send push notifications from your Android app. Just make sure the user has the proper permissions in the portal to send push notifications.

JSONObject notification = new JSONObject();
notification.put("message", "Hello!");

Push.with(session).send(toUserId, notification);

In this code, the push notification is sent to the user specified by toUserId. Upon receiving the notification, the portal looks up all the user's registered devices (both Android and iOS devices) and sends notification as the body of the push notification.

Unregistering a device

If you want to stop receiving push notifications on a device, you can unregister it from from the portal with the following code:

Push.with(session).unregister(registrationId);

Users can only unregister devices they own.

You can’t perform that action at this time.