Mobile Push Notifications

  • Updated: Mar 31, 2017
  • Starting Guide

The Realtime Mobile Push Notifications are a great way to keep your mobile users engaged and informed about your app. It'll allow you to send notifications about content and other updates to users when they are offline. You can use the Mobile Push Notifications feature for both iOS and Android apps. For the iOS apps we’ll use the Apple Notification Service (APNS) and for Android apps we’ll use Firebase Cloud Messaging.

We’ve encapsulated this feature into our pub/sub messaging system in order to make the developer’s life easier: the general idea is that when you subscribe a channel using the iOS or Android SDK (stating that you want to receive push notifications), the published messages will be delivered to your users by one of three possible ways:

1- The Realtime Cloud Messaging socket if the app is running and the user is connected to a Realtime Messaging server;
2- The Apple Notification Service if the user is using the iOS version of your app and if the app was not running at the moment the message was published (the user is offline);
3- The Firebase Cloud Messaging if the user is using the Android version of your app and if the app was not running at the moment the message was published (the user is offline).

When the user is connected to a Realtime Server it’s business as usual, messages are delivered in real-time. If the user is offline (the app is not running or the device has no network) messages are delivered as push notifications and as soon as the user selects them they will be handled in your app just as if they were received through the Realtime connection. As simple as that!

An important warning

But beware, if the user doesn’t accept receiving push notifications from your app or if he doesn’t select the received notification or even if he deletes the notification, the messages will not be delivered to your app and will in fact be lost. So use this feature carefully and if possible use it only to notify the user that there’s a data update in the app and make sure that when he opens the app (even if not through selecting the notification) he’ll get the updated data that triggered the notification. The Realtime Cloud Storage backend-as-a-service can be very useful in this scenario, since your app’s data will be persisted in a database and retrieved when the user opens the app, thus guaranteeing that he always gets the most recent data.

The activation process

To use the Mobile Push Notifications for both iOS and Android devices you’ll have to go through the following steps:

1- Provision your app at the APNS - Apple Notification Service platform (we’ll cover this at the next chapters);
2- Provision your app at the FCM - Firebase Cloud Messaging (we’ll cover this at the next chapters);
3- Register at and get your free developers license;
4- Using the account website enter your APNS certificate + private key and your FCM API Key;
5- Develop your iOS and Android apps using the Realtime Cloud Messaging SDKs

Automatic Notifications vs Custom Notifications

The Realtime Cloud Messaging servers implement an automatic publish feature where all messages are automatically pushed as notifications to all the devices (users) subscribing the message channel. When this happen the notification alert text is set to the default string you entered at the Realtime Accounts Console (we’ll cover this in the next chapter).

We call this feature Automatic Notifications. To use them you just need to subscribe the Realtime channel using the subscribeWithNotifications method (see the iOS and Android SDK reference documentation for more details).

However in some situations you’ll want to have full control over the notification text and body payload (e.g. to include a badge for iOS users or to send some custom data). To achieve that you’ll need to use the Custom Notifications feature. In fact you just need to make a simple REST API POST as shown in the following CURL example (replace INSERT_YOUR_APP_KEY and INSERT_YOUR_PRIVATE_KEY with your Realtime keys):

curl -X POST  -d '{
    "applicationKey": "YOUR_REALTIME_APPKEY",
    "channel" : "NewArticles",
    "message" : "We have new articles for you",
    "payload" : "{
        \"sound\" : \"default\",
        \"badge\" : \"2\",
        \"custom-property\" : \"value\",
        \"another-property\" : \"other-value\"

Now in PHP using cURL:


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "",
    "content-type: application/json"
      "applicationKey": "YOUR_REALTIME_APPKEY",
      "privateKey": "YOUR_REALTIME_PRIVATEKEY",
      "channel" : "NewArticles",
      "message" : "We have new articles for you",
      "payload" : "{
          \\"sound\\" : \\"default\\",
          \\"badge\\" : \\"2\\",
          \\"custom-property\\" : \\"value\\"

$response = curl_exec($curl);
$err = curl_error($curl);


if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;

In the previous examples the devices subscribing channel NewArticles would receive a notification with We have new articles for you as the alert text. Also the iOS devices would show a badge at the app icon with the number 2 (indicating that 2 new articles are available at the app) and play the default sound.

The devices would also receive the two extra properties: custom-property and another-property. This is very useful to send an entity id so the app can redirect the user to the entity associated with the push message (e.g. redirecting the user to the chat room in a chat app). Consider using base64 for the payload custom properties to avoid issues with enconding.

You can also use the publishbatch endpoint to send the same message to several channels using a single request. The list of channels should be passed as an array of strings in the channels request property. All the remaining request parameters work exactly as the single channel publish endpoint.

Notification size limits

Due to the fact that APNS imposes payload limits to the push notifications, the limit to the message size was set to 1024 bytes.
If the message is longer than that a “Message too long” will be sent as the message payload (note: the alert text, the data the user sees at the UI will remain untouched).

Sending a notification for a single user

The Realtime Push Notifications are based on the pub/sub pattern just like normal Realtime messages. This means you can broadcast a notification to several users, those who are subscribing the channel where you published the notification.

However sometimes you’ll need to send a notification for a single user. To do that make users subscribe their own channel using some unique user data like the user id, username or email (e.g. notification_[USER_ID]).

Then, when you need to send a notification for a given user just publish an automatic notification (using the normal send() method of any Realtime SDK) or a custom notification (using the REST API described earlier) to the user “private” channel (e.g. notification_12345).


We have already mentioned the publish and publishbatch API endpoints, but there's a couple more that might be useful.

List subscribed channels

Retrieves the channels currently subscribed using push notifications.

curl -X POST -d '{
   "applicationKey": "YOUR_REALTIME_APPKEY",
}' ""

Get devices subscribing a channel

Retrieves the list of device tokens subscribing a given channel with push notifications.

curl -X POST -d '{
   "applicationKey": "YOUR_REALTIME_APPKEY",

Check if channel is subscribed

Checks if the given channel is currently subscribed using push notifications.

curl -X POST -d '{
   "applicationKey": "YOUR_REALTIME_APPKEY",

In this API the words topic and channel are interchangeable, they mean the same.

The detailed reference of all Mobile Push API endpoints can be found in section 4. of the Realtime RESTful Services API Reference Guide.

Back to Cluster in India - Next: Mobile Push Provisioning for APNS

If you find this interesting please share: