> ## 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 Setup

This guide walks you through setting up push notifications for your application. You'll learn how to configure push notification services, activate devices, and send your first push notification.

## Prerequisites

1. An [Ably account](https://ably.com/signup)
2. An Ably app with an API key
3. For mobile: Access to Firebase Console (Android) or Apple Developer Account (iOS)
4. For web: A web application with HTTPS support

## Choose your platform

<Tiles>
  {[
    {
      title: 'iOS (APNs)',
      description: 'Set up push notifications for iOS devices',
      link: '/docs/push/getting-started/apns',
    },
    {
      title: 'Android (FCM)',
      description: 'Set up push notifications for Android devices',
      link: '/docs/push/getting-started/fcm',
    },
    {
      title: 'Web Push',
      description: 'Set up push notifications for web browsers',
      link: '/docs/push/getting-started/web',
    },
    ]}
</Tiles>

## Quick setup overview

Regardless of platform, the setup process follows these steps:

<Steps>
  ### Configure push service credentials

  Add your push notification service credentials to your Ably app:

  1. Go to your [Ably dashboard](https://ably.com/accounts)
  2. Select your app
  3. Navigate to the **Notifications** tab
  4. Select your platform (APNs, FCM, or Web Push)
  5. Enter your credentials
  6. Click **Save**

  ### Install the Ably SDK

  Install the Ably SDK for your platform:

  <CodeGroup>
    ```javascript JavaScript (Web) theme={null}
    npm install ably
    ```

    ```swift iOS theme={null}
    // Add to Podfile
    pod 'Ably'
    ```

    ```kotlin Android theme={null}
    // Add to build.gradle
    implementation 'io.ably:ably-android:1.2.0'
    ```
  </CodeGroup>

  ### Activate device for push

  Register your device to receive push notifications:

  <CodeGroup>
    ```javascript JavaScript theme={null}
    const realtime = new Ably.Realtime({
      key: 'YOUR_API_KEY',
      clientId: 'user-123'
    });

    // Activate device for push
    await realtime.push.activate();
    ```

    ```swift iOS theme={null}
    import Ably

    let realtime = ARTRealtime(key: "YOUR_API_KEY")
    realtime.clientId = "user-123"

    // Request permission and activate
    realtime.push.activate()
    ```

    ```kotlin Android theme={null}
    import io.ably.lib.realtime.AblyRealtime

    val realtime = AblyRealtime("YOUR_API_KEY")
    realtime.setAndroidContext(applicationContext)

    // Activate device for push
    realtime.push.activate()
    ```
  </CodeGroup>

  ### Subscribe to a channel

  Subscribe your device to receive push notifications from a channel:

  <CodeGroup>
    ```javascript JavaScript theme={null}
    // Subscribe to push notifications on a channel
    await realtime.push.admin.channelSubscriptions.save({
      channel: 'notifications',
      clientId: 'user-123'
    });
    ```

    ```swift iOS theme={null}
    // Subscribe to push notifications
    realtime.channels.get("notifications").push.subscribeDevice { error in
        if let error = error {
            print("Failed to subscribe: \(error)")
        } else {
            print("Successfully subscribed to push")
        }
    }
    ```

    ```kotlin Android theme={null}
    // Subscribe to push notifications
    realtime.channels.get("notifications").push.subscribeDevice { error ->
        if (error != null) {
            Log.e("Push", "Failed to subscribe: ${error.message}")
        } else {
            Log.i("Push", "Successfully subscribed to push")
        }
    }
    ```
  </CodeGroup>

  ### Publish a push notification

  Send a push notification to all subscribed devices:

  <CodeGroup>
    ```javascript Server-side theme={null}
    const rest = new Ably.Rest({ key: 'YOUR_API_KEY' });
    const channel = rest.channels.get('notifications');

    await channel.publish({
      name: 'alert',
      data: 'This is a push notification',
      extras: {
        push: {
          notification: {
            title: 'New Alert',
            body: 'This is a push notification'
          }
        }
      }
    });
    ```

    ```python Server-side theme={null}
    from ably import AblyRest

    rest = AblyRest('YOUR_API_KEY')
    channel = rest.channels.get('notifications')

    await channel.publish(
        name='alert',
        data='This is a push notification',
        extras={
            'push': {
                'notification': {
                    'title': 'New Alert',
                    'body': 'This is a push notification'
                }
            }
        }
    )
    ```
  </CodeGroup>
</Steps>

## Platform-specific guides

For detailed setup instructions for each platform:

### iOS (APNs)

1. [Create APNs certificates](/docs/push/getting-started/apns#certificates)
2. [Configure your Xcode project](/docs/push/getting-started/apns#xcode)
3. [Request push permissions](/docs/push/getting-started/apns#permissions)
4. [Handle push notifications](/docs/push/getting-started/apns#handle)

See the [complete APNs setup guide](/docs/push/getting-started/apns).

### Android (FCM)

1. [Create a Firebase project](/docs/push/getting-started/fcm#firebase)
2. [Add FCM to your app](/docs/push/getting-started/fcm#setup)
3. [Configure Ably with FCM credentials](/docs/push/getting-started/fcm#configure)
4. [Handle push notifications](/docs/push/getting-started/fcm#handle)

See the [complete FCM setup guide](/docs/push/getting-started/fcm).

### Web Push

1. [Generate VAPID keys](/docs/push/getting-started/web#vapid)
2. [Configure service worker](/docs/push/getting-started/web#service-worker)
3. [Request notification permission](/docs/push/getting-started/web#permission)
4. [Handle push notifications](/docs/push/getting-started/web#handle)

See the [complete Web Push setup guide](/docs/push/getting-started/web).

## Testing push notifications

Use the Ably dashboard to test push notifications:

1. Go to your app in the [dashboard](https://ably.com/accounts)
2. Navigate to the **Dev Console** tab
3. Select a channel
4. Click **Publish message**
5. Add push notification extras
6. Click **Publish**

## Publish methods

### Via channels (recommended)

Publish to all devices subscribed to a channel:

<Code>
  ```javascript theme={null}
  await channel.publish({
    name: 'notification',
    data: 'Message content',
    extras: {
      push: {
        notification: {
          title: 'Title',
          body: 'Message content'
        }
      }
    }
  });
  ```
</Code>

### Direct publishing

Publish to specific devices or clients:

<Code>
  ```javascript theme={null}
  // Publish to specific client ID
  await rest.push.admin.publish({
    clientId: 'user-123'
  }, {
    notification: {
      title: 'Personal Alert',
      body: 'This is for you specifically'
    }
  });

  // Publish to specific device ID
  await rest.push.admin.publish({
    deviceId: 'device-abc-123'
  }, {
    notification: {
      title: 'Device Alert',
      body: 'Message for this device'
    }
  });
  ```
</Code>

## Common notification formats

### Basic notification

<Code>
  ```javascript theme={null}
  extras: {
    push: {
      notification: {
        title: 'New Message',
        body: 'You have a new message from Sarah'
      }
    }
  }
  ```
</Code>

### With action buttons (iOS)

<Code>
  ```javascript theme={null}
  extras: {
    push: {
      notification: {
        title: 'Friend Request',
        body: 'John wants to connect with you',
        category: 'FRIEND_REQUEST'
      },
      data: {
        userId: '12345'
      }
    }
  }
  ```
</Code>

### With custom data

<Code>
  ```javascript theme={null}
  extras: {
    push: {
      notification: {
        title: 'New Order',
        body: 'Order #1234 has been placed'
      },
      data: {
        orderId: '1234',
        action: 'view-order',
        deepLink: '/orders/1234'
      }
    }
  }
  ```
</Code>

## Troubleshooting

### Device not receiving notifications

1. Verify device is activated: `realtime.push.activate()`
2. Check subscription: `realtime.push.admin.channelSubscriptions.list()`
3. Verify credentials in dashboard
4. Check device permissions

### Notifications not appearing

1. Verify push extras format
2. Check notification payload size (\< 4KB for APNs, \< 4KB for FCM)
3. Monitor `[meta]log:push` channel for errors
4. Verify app is not in focus (some platforms)

### Testing in development

1. Use APNs development certificates for iOS
2. Use Firebase test messages for Android
3. Test on physical devices, not simulators
4. Check device system settings

## Next steps

* Learn about [publishing push notifications](/docs/push/publish)
* Understand [device activation](/docs/push/configure/device)
* Explore [push admin API](/docs/api/realtime-sdk/push-admin)
* Monitor [push errors](/docs/push#Error)