Push Notifications - Admin
The client libraries provide a Push Admin API that is intended to be used on a customer’s servers to perform all the management tasks relating to registering devices, managing push device subscriptions and delivering push notifications directly to devices or devices associated with a client identifier.
The push admin API is accessible via the push
attribute of the realtime or rest client. For example to publish a push notification directly to a device, you would access the publish
method as follows:
var rest = new Ably.Rest({ key: apiKey });
rest.push.admin.publish(recipient, data);
CopyCopied!
The push admin API offers three key features:
publish
for direct publishing to devices and groups of identified devicesdeviceRegistrations
for registering, updating, listing and de-registering push deviceschannelSubscriptions
for subscribing, listing and unsubscribing individual devices or groups of identified devices to push notifications published on channels
Push admin access control and device authentication
Operations using the push admin API, as with all our other APIs, require specific permissions as part of the credentials of a client. The push admin API has two modes of authorization:
- access using the
push-admin
permission. A client whose credentials contain thepush-admin
permission has full access to the push admin API, and can manage registrations and subscriptions for all devices;
- access using the
push-subscribe
permission. A client withpush-subscribe
is a push target device, and it can manage its registration and any subscription for itself; it is not able to manage push registrations or channel subscriptions for any other device. The credentials presented, as well as containing thepush-subscribe
permission, must also authenticate the device itself.
Every push target device has a deviceId
and also has device credentials, which are used as the basis for device authentication. When using the push admin API, a device can authenticate itself in two ways:
- by using an Ably token that contains its
deviceId
;
- by using a normal Ably key or Ably Token but additionally including a
deviceIdentityToken
– a credential created at registration time that is used to assert the device’s identity – in a header in the request.
Management of device credentials is performed by the client library, so unless the push admin API is being accessed directly using HTTP, the client application does not need to worry about managing device credentials.
Ably can deliver push notifications to devices using, amongst others, Apple’s Push Notification service and Google’s Firebase Cloud Messaging service. Push notifications, unlike Ably’s channel based pub/sub messaging, do not require the device to maintain a connection to Ably, as the underlying platform or OS is responsible for maintaining its own battery-efficient transport to receive push notifications. Therefore, push notifications are commonly used to display visual notifications to users or launch a background process for an app in a battery-efficient manner.
Delivering push notifications
As shown above, Ably provides two models for delivering push notifications to devices:
Direct publishing
Ably provides a REST API that allows push notifications to be delivered directly to:
- Devices identified by their unique device ID
- Devices identified by their assigned
clientId
- Devices identified by the recipient details of the push transport such as their unique
registrationToken
in the case of FCM ordeviceToken
in the case of APNS. This means is particularly useful when migrating to Ably with existing push notification target devices.
Find out more about direct push notification publishing
Channel-based broadcasting
The model for delivering push notifications to devices over channels is intentionally very similar to how messages are normally delivered using Ably’s pub/sub channel. For example, a normal message published on an Ably channel is broadcast immediately to all realtime subscribers of that channel. When broadcasting push notifications on channels, however, the process is the same with the exception that the subscribers (devices receiving push notifications) are registered in advance using our API and the message itself must contain an extra push notification payload that specifies the optional visual format and optional data payload of the push notification.
Find out more about channel-based push notification broadcasting
Activating a device and receiving notifications
Every device that will receive push notifications must register itself with the platform specific push notification service (APNs on iOS, FCM on Android). The Ably client libraries provide a consistent API for registration across all platforms, including device registration and receiving push notifications via Ably channels sent from other platforms.
Find out more about device activations and subscriptions.
Managing devices and subscriptions
Whilst the realtime client libraries provide APIs for a device to activate itself (via client.push
) and subscribe for push notifications (via channel.push
), those APIs are intentionally limited to actions pertaining to the device it is run on.
A separate and distinct push admin API is additionally provided in our client libraries specifically designed for use by your servers to facilitate managing and delivering push notifications across all of your registered devices. This API, amongst other things, includes features to manage registered devices, channel subscriptions and deliver push notifications directly. Currently the push admin API is available in our JavaScript, Ruby, Java/Android, PHP, Python, and iOS libraries. It is also available in our other libraries through the use of the request method, using the underlying API directly.
Find out more about the push admin API.
Platform support
Ably currently offers support for push notifications on the following platforms:
- Apple Push Notifications
- supported on all mobile devices running iOS and desktop devices running macOS
- Firebase Cloud Messaging
- supported on all Android and iOS devices, although we use FCM exclusively for Android message delivery
API Reference
View Realtime push notifications – admin for the associated Client Library SDK API reference.