Skip to content
Branch: master
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
android @ e21a5bb Update push submodules Aug 22, 2016
images The push submodule will become a folder instead Mar 26, 2015
ios @ 1d20930 Update submodule Dec 15, 2016
README.md Update push repo URLs Jan 10, 2017

README.md

Liferay Mobile SDK logo

Liferay Push

About

The Liferay Push framework is comprised of 3 main components:

This document describes how to install and configure the Liferay Push Notifications Portlet. This portlet is necessary to enable Liferay Push. It's responsible for making the bridge between mobile apps, your Liferay Portal instance, and the iOS and Android push notification services. Once you install this portlet, mobile users can register their devices with your portal instance. The Push Notifications Portlet also provides an API that developers can leverage to send push notifications from their plugins.

For example, if you've developed your own blogs portlet and a corresponding mobile app, you can use Liferay Push to notify users on their mobile devices whenever a new blog post is made. Instead of having to poll the server every few seconds, your mobile app can just wait for announcements. In other words, you can use Liferay Push so that the server only communicates with your mobile app when there's something to communicate. This is one of the main benefits of using push notifications.

In addition to the Liferay Push Notifications Portlet, Liferay Push also has client libraries for Android and iOS. To see how your mobile app can leverage the Liferay Push framework, see the client library documentation for Android and iOS.

Setup

You first need to download and install the Liferay Push Notifications Portlet from the Liferay Marketplace. Once installed, you can find the portlet in the Configuration section of the Control Panel. Click Push Notifications to access it:

Click Push Notifications under the Configuration section of the Control Panel.

Before you can send push notifcations to your users' mobile devices, you need to configure the portlet. The next section walks you through the configuration steps for sending push notifications to Android and iOS devices.

Configuration

The portlet's Configuration tab is where you specify the settings for sending push notifications from your portal. Note that there are separate settings for Android and iOS. This is because Android and iOS use different push notification services. Note that if you don't need to send notifications to both platforms, you only need to set the properties for the platform you're sending them to.

Configuration tab

You don't have to use this UI to configure the portlet. You can also manually set the properties in the portlet's portlet(-ext).properties file, which is located in the /push-notifications-portlet/WEB-INF/classes folder. However, each time you make changes to this file you need to restart your portal for them to take effect. You should also note that any changes made through the UI take precedence over those set manually in portlet.properties.

Next, you'll learn how to configure the portlet for sending push notifications to Android and iOS devices.

Android

Push notifications sent to Android devices use the Google Cloud Messaging service (GCM). The Liferay Push Notifications Portlet has two settings for configuring your portal to use GCM:

API Key: The API key to use when communicating with the GCM servers. More specifically, the API key is used to authorize the portlet to send notifications to your mobile app. Note that your app must also be configured with a GCM sender ID that is linked to this API key. Without this linkage, your app can't be registered with your server and sending push notifications isn't possible. For more information on how to obtain the API key, see Google's documentation. Be sure that your API key remain secret. If others know it, then they can also send push notifications to your app!

Retries: When sending a notification fails, this is the number of times to retry sending that notification.

Next, the portlet's configuration for sending push notifications to iOS devices is presented. If you don't need to send push notfications to iOS devices, you can skip this and proceed to the section on testing your configuration.

iOS

Push notfications to iOS devices use the Apple Push Notification service (APNs). For more information on how this service works, see Apple's documentation. The Liferay Push Notifications Portlet has two settings for configuring your portal to use APNs:

Certificate Path: The path to the .p12 certificate file that authorizes the portlet to send notifications to APNs. To generate this certificate, carefully follow the steps described here or here. After generating the .p12 file, store it on your server. The Certificate Path property points to this file on your server.

Certificate Password: The password you used during the creation of the certificate.

Sandbox: While your app is still in development, you should enable this option. It will use APNs sandbox servers to send notifications, instead of their production servers.

Great! Now that you've configured the Liferay Push Notifications Portlet to send push notifications, you're ready to test it out.

Testing Your Configuration

Click the Test tab of the portlet to access the screen for sending a test notification via push. However, be careful not to send a test notification from a production Liferay instance. Doing so sends a message to all devices registered with your portal! Type your message into the Message text box and press Send.

Send a test notification using push.

A success or failure message appears to let you know if your test was successful. You should also check your console log for any exceptions. Super! Now you know how to install, configure, and test the Liferay Push Notifications Portlet. Next, you'll learn how to leverage the API to send push notifications from your own plugins.

Using Liferay Push in Your Plugins

Once you've successfully configured the Liferay Push Notifications Portlet to send push notifications, you can use the Push Notifications API in your own plugin. You first need add the push-notifications-portlet as a dependency to your plugin inside docroot/WEB-INF/liferay-plugin-package.properties. This is shown here:

required-deployment-contexts=\
    push-notifications-portlet

Now you're ready to send the notification! You can do so with the following code:

PushNotificationsDeviceLocalServiceUtil.sendPushNotification(toUserId, notificationJSONObject);

When this code runs, the portlet first finds all devices registered to the user indicated by toUserId. The notificationJSONObject is then sent to each device. If you want to send the same notification to all users, use the version of this method that has no toUserId.

You can’t perform that action at this time.