Publish and receive push notifications

Publishing sends push notifications to all specified devices either directly or via channels. This process is facilitated by Ably’s realtime messaging infrastructure, which ensures that messages and notifications are delivered instantaneously.

Push Notifications in Ably

Publish push notifications directly or via channels:

Publish directly
  • Description: Messages are sent directly to specified devices without the need for channel subscriptions.
Publish via channels
  • Description: Messages are sent to multiple devices through specified channels.
  • Requirement: Devices must be subscribed to these channels to receive notifications.

Ably adapts message fields for seamless compatibility with each push notification platform:

Ably field
The message field in Ably.
FCM Field
Field mapping in Firebase Cloud Messaging.
APNs

Field mapping in Apple Push Notification service.

The following table shows how the mapping works:

Ably field FCM APNs
notification.title notification.title aps.alert.title
notification.body notification.body aps.alert.body
notification.icon notification.icon Discarded
notification.sound notification.sound aps.alert.sound
notification.collapseKey collapse_key aps.thread-id
data data Merged into root object

The following examples show how Ably transforms each field:

{ // General notification structure "notification": { "collapseKey": "chat" } } // Equivalent raw format for FCM { "collapse_key": "chat" } // Equivalent raw format for APNs { "aps.thread-id": "chat" }
Copied!

You can also override generic values for a field or add specific fields not supported in the general structure. The following is an example of overriding the title for iOS and setting a specific background color for Android:

// Example payload structure with specific customizations for APNs and FCM { "notification": { "title": "Hello from Ably!", "body": "Example push notification from Ably." }, "data": { "foo": "bar", "baz": "qux" }, "apns": { "aps": { "alert": { "title": "Hello to iOS from Ably!" } } }, "fcm": { "notification": { "color": "#d3d3d3" } } }
Copied!

To enable background notifications on iOS, you must include specific headers in the notification. You can specify these headers by adding an apns-headers object, which should contain all the desired APNs headers, as part of the apns object. The following example shows how a background notification would appear:

{ "data": { "foo": "bar", "baz": "qux" }, "apns": { "aps": { "content-available": 1, }, "apns-headers": { "apns-push-type": "background", "apns-priority": "5" } } }
Copied!

Direct publishing sends push notifications directly to individual devices via the Ably SDK, bypassing the intermediary of channels. This approach delivers personalized or precise notifications customized for individual users. Direct publishing proves beneficial during the transition phase to Ably’s platform and when the objective is to engage existing push notification devices.

Notifications are targeted explicitly towards devices identified by:

For applications requiring direct targeting of individual devices, using the deviceId allows for precise control over where each push notification is sent. This approach is ideal when notifications are intended for a specific device, such as alerting users about actions required on a particular device or sending device-specific updates.

A deviceId is set during the device activation process.

The following example publishes a push notification using the deviceId:

Select...
var recipient = { deviceId: 'xxxxxxxxxxx' }; var data = { notification: { title: 'Hello from Ably!', body: 'Example push notification from Ably.' } }; rest.push.admin.publish(recipient, data);
Copied!

When you need to deliver push notifications to specific users rather than a single device, you can use the clientId to target all devices associated with a particular user. This process is particularly useful for applications where users may have multiple devices, and you want to ensure that all devices receive the notifications seamlessly.

A clientId is set during the device activation process.

The following example publishes a push notification using the clientId:

Select...
var recipient = { clientId: 'bob' }; var notification = { notification: { title: 'Hello from Ably!', body: 'Example push notification from Ably.' } }; rest.push.admin.publish(recipient, notification);
Copied!

Direct publishing using recipient attributes allows for a highly tailored approach to sending notifications based on specific criteria such as device tokens or transport types. This method is particularly effective when engaging users across different platforms or devices with customized messages.

Recipient attributes are set during the device activation process.

The following example publishes a push notification using the recipient attributes:

Select...
var recipient = { transportType: 'apns', deviceToken: 'xxxxxxxxxx' }; var notification = { notification: { title: 'Hello from Ably!', body: 'Example push notification from Ably.' } }; rest.push.admin.publish(recipient, notification);
Copied!

Publishing via channels is modeled on Ably’s channel infrastructure, facilitating the delivery of push notifications across a network of subscribed devices. This process publishes messages through predefined channels, which devices must subscribe to in order to receive updates. This process ensures registered devices in the specified channels recieve the correct push notifications. Publishing via channels is particularly useful for publishing notifications to multiple groups with varying privileges.

It’s important to distinguish — subscribing to push notifications differs from subscribing to ordinary messages, as it requires a specific action to receive updates.

Subscribe to Ably channels only if you are publishing push notifications via channels process. You can subscribe using either deviceId or clientId. For the client to register with Ably automatically, it must be authenticated and possess the necessary push-subscribe capability.

The following example shows how to subscribe for push notifications using deviceId by calling the push.subscribeDevice() method:

Select...
realtime.channels.get("pushenabled:foo").push.subscribeDevice(context); // or realtime.channels.get("pushenabled:foo").push.subscribeDeviceAsync(context, new CompletionListener() { @Override public void onSuccess() {} @Override public void onError(ErrorInfo errorInfo) { // Handle error. } });
Copied!

The following example shows how to subscribe for push notifications using clientId by calling the push.subscribeClient() method:

Select...
realtime.channels.get("pushenabled:foo").push.subscribeClient(); // or realtime.channels.get("pushenabled:foo").push.subscribeClientAsync(new CompletionListener() { @Override public void onSuccess() {} @Override public void onError(ErrorInfo errorInfo) { // Handle error. } });
Copied!

Publishing via channels mirrors the process of sending standard messages to subscribers in realtime via Ably’s pub/sub channels. When a message is sent on an Ably channel, it’s immediately published to all channel subscribers.

Note that the device will receive a push notification published on a channel only if:

  • The published message includes the extra push notification payload.
  • You explicitly configure a channel rule to enable push notifications on that channel.
  • The device subscribes to the channel.
  • The push notification payload is compatible with the device.

Add push notifications as special payloads in a standard Ably message’s extras field. Ensure this field includes a push attribute object specifying the push payload details:

Select...
var extras = { push: { notification: { title: 'Hello from Ably!', body: 'Example push notification from Ably.' }, data: { foo: 'bar', baz: 'qux' } } }; const channel = rest.channels.get('pushenabled:foo'); await channel.publish({ name: 'example', data: 'data', extras: extras });
Copied!
Push notification payload structure
v2.0