Push notifications
Push notifications notify user devices or browsers regardless of whether an application is open and running. They deliver information, such as app updates, social media alerts, or promotional offers, directly to the user’s screen. Ably sends push notifications to devices using Firebase Cloud Messaging or Apple Push Notification Service, and to browsers using Web Push. Push notifications don’t require a device or browser to stay connected to Ably. Instead, a device’s or browser’s operating system or web browser maintains its own battery-efficient transport to receive notifications.
You can publish push notifications to user devices or browsers directly or via channels.
Publishing directly sends push notifications to specific devices or browsers identified by unique identifiers, such as a deviceId
or a clientId
. This approach is akin to sending a personal message or alerts directly to an individual user’s device or browser, bypassing the need for channel subscriptions. It excels in targeted and personalized communications, such as alerts specific to a user’s actions, account notifications, or customized updates.
Publishing via channels uses a Pub/Sub model. Messages are sent to channels to which multiple devices or browsers can subscribe. When a message is published to a channel, all devices or browsers subscribed to that channel receive the notification. This approach is particularly powerful for simultaneously publishing messages to multiple users.
Push notification process
Integrating push notifications into your application includes a few essential configuration steps.
The following diagram demonstrates the push notification process:
Configure
Configuring push notifications sets your device’s or browser’s push notification service to operate with the Ably platform. This process includes inputting the necessary credentials into your Ably dashboard.
Activate
Activate devices or browsers for push notifications directly or via a server:
- Activating directly enables devices or browsers to receive push notifications. This process involves obtaining a device or browser unique identifier, which serves as a push recipient. Direct activation is typically used when the application can directly handle device or browser registration without intermediaries, providing a straightforward approach to activation.
- Activating via server delegates the activation process to your server rather than handling it directly on devices or browsers. This approach is often preferred to minimize the capabilities assigned to untrusted devices or browsers, enhancing security and control. By managing device or browser registrations server-side, you can also centralize activation logistics and handle sensitive operations away from the client.
Publish
Publish push notifications using Ably via channels or directly:
- Publishing directly allows for the delivery of push notifications straight to individual devices or browsers. This process is beneficial for targeting a specific device or browser using a unique
deviceId
,clientId
, orrecipient
. Direct publishing is akin to sending a personal, targeted message to a user’s device or browser.
- Publishing via channels operates similarly to Ably’s Pub/Sub messaging model, broadcasting notifications to all channel subscribers. This process leverages Ably channels to distribute push notifications efficiently to all devices or browsers subscribed to those channels. It is ideal for scenarios where the same information, such as alerts or updates, needs to be sent to multiple users.
Subscribe
If you publish via channels, devices or browsers must subscribe to those channels to receive notifications. This process offers flexibility in managing and delivering notifications. Subscriptions can be made using the deviceId
or clientId
:
- The
deviceId
process subscribes devices or browsers directly to a channel using its uniquedeviceId
, assigned by Ably, for push notifications upon device activation.
- The
clientId
process subscribes all devices or browsers tied to a particularclientId
to a channel in one action, for example the same user’s laptop and mobile phone. This approach is useful for subscribing multiple devices or browsers simultaneously.
Push admin API
Ably’s push admin API is a set of functionalities designed for backend servers to manage push notification tasks. It handles registering devices or browsers for push notifications, managing subscriptions to specific channels, and sending push notifications directly to devices, browsers or users identified by a client identifier. It can be used with both the realtime and REST interfaces of an Ably SDK.
Using the push Admin API requires explicit capabilities within a client’s credentials:
- Access using the
push-admin
capabilities grants full API access, enabling the management of registrations and subscriptions for all devices or browsers.
- Access using the
push-subscribe
capabilities designates a client as a push target device or browser. It can only manage its own registration and subscriptions, not those of other devices or browsers.
Each push target device or browser is associated with a unique deviceId
and authentication credentials. Authentication can be achieved in two ways when using the push Admin API:
- By utilizing an Ably token containing the device’s or browser’s
deviceId
.
- By employing a standard Ably key or Token, with a
deviceIdentityToken
, a credential generated during registration to assert the device’s or browser’s identity, included in the request header.
The service credential management is handled by the Ably SDK, removing the need for the client application to manage device credentials unless accessing the push admin API directly via HTTP.
Error handling
Metachannels, such as [meta]log:push
, publish events and errors that aren’t otherwise available to clients. It’s important to note that client-returned errors will not be published to this channel.
The following example subscribes to the [meta]log:push
channel:
const channel = realtime.channels.get('[meta]log:push');
channel.subscribe(msg => console.log(msg));
CopyCopied!