> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ably/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Push Notifications Overview

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](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API).

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.

<Aside data-type="note">
  Push subscriptions do not count toward your connection limit since devices don't need to maintain an active connection to receive push notifications. However, publishing push notifications via channels does activate those channels.
</Aside>

## Publishing methods

You can publish push notifications to user devices or browsers in two ways:

### Direct publishing

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.

Direct publishing excels in:

* Targeted and personalized communications
* User-specific alerts and notifications
* Account notifications
* Customized updates based on user actions

### Publishing via channels

Publishing via channels uses a [Pub/Sub](/docs/messages) 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:

* Broadcasting to multiple users simultaneously
* Group notifications
* Topic-based alerts
* Real-time updates to subscribers

## Push notification process

Integrating push notifications into your application includes a few essential steps:

<Steps>
  ### Configure

  Configure your [device's](/docs/push/configure/device) or [browser's](/docs/push/configure/web) push notification service to operate with the Ably platform. This process includes inputting the necessary credentials into your Ably [dashboard](https://ably.com/accounts).

  ### Activate

  Activate devices or browsers for push notifications [directly](/docs/push/configure/device#device) or [via a server](/docs/push/configure/device#server).

  **Direct activation** enables devices or browsers to receive push notifications by obtaining a unique identifier. This is typically used when the application can directly handle device or browser registration.

  **Server activation** delegates the activation process to your server rather than handling it directly on devices or browsers. This approach enhances security by minimizing the capabilities assigned to untrusted devices.

  ### Publish

  Publish push notifications using Ably via [channels](/docs/push/publish#channel-pub) or [directly](/docs/push/publish#direct-publishing).

  ### Subscribe (for channel-based notifications)

  If publishing via channels, devices or browsers must subscribe to those channels to receive notifications. Subscriptions can be made using:

  * **deviceId**: Subscribe devices or browsers directly using their unique identifier
  * **clientId**: Subscribe all devices or browsers tied to a particular user in one action
</Steps>

## Push notification lifecycle

The following diagram shows the push notification lifecycle:

1. **Publish**: Your app or server publishes a push notification to Ably
2. **Process**: Ably processes and packages the notification
3. **Forward**: Ably forwards the packaged message to the appropriate push notification service (FCM, APNs, or Web Push)
4. **Deliver**: The push notification service delivers the notification to target devices or browsers
5. **Display**: The notification appears on the user's device or browser screen

## Supported platforms

### Mobile devices

* **iOS**: Via Apple Push Notification Service (APNs)
* **Android**: Via Firebase Cloud Messaging (FCM)

### Web browsers

* **Chrome, Firefox, Edge**: Via Web Push API
* **Safari**: Via APNs for web

## Push admin API

Ably's [push admin API](/docs/api/realtime-sdk/push-admin) is a set of functionalities designed for backend servers to manage push notification tasks:

* Register devices or browsers for push notifications
* Manage subscriptions to specific channels
* Send push notifications directly to devices, browsers, or users

### Required capabilities

Using the push Admin API requires explicit capabilities:

* **push-admin**: Full API access, enables management of registrations and subscriptions for all devices or browsers
* **push-subscribe**: Designates a client as a push target device or browser. Can only manage its own registration and subscriptions

## Error handling

Monitor push notification errors using the `[meta]log:push` metachannel:

<Code>
  ```javascript theme={null}
  const channel = realtime.channels.get('[meta]log:push');
  await channel.subscribe((msg) => {
    console.log('Push error:', msg);
  });
  ```
</Code>

<Aside data-type="note">
  Client-returned errors will not be published to this channel.
</Aside>

## Next steps

* Set up [push notifications](/docs/pubsub/push/setup)
* Learn about [publishing push notifications](/docs/push/publish)
* Configure [device activation](/docs/push/configure/device)
* Configure [web push](/docs/push/configure/web)