Skip to main content
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
  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

Quick setup overview

Regardless of platform, the setup process follows these steps:
1
Configure push service credentials
2
Add your push notification service credentials to your Ably app:
3
  • Go to your Ably dashboard
  • Select your app
  • Navigate to the Notifications tab
  • Select your platform (APNs, FCM, or Web Push)
  • Enter your credentials
  • Click Save
  • 4
    Install the Ably SDK
    5
    Install the Ably SDK for your platform:
    6
    JavaScript (Web)
    npm install ably
    
    iOS
    // Add to Podfile
    pod 'Ably'
    
    Android
    // Add to build.gradle
    implementation 'io.ably:ably-android:1.2.0'
    
    7
    Activate device for push
    8
    Register your device to receive push notifications:
    9
    JavaScript
    const realtime = new Ably.Realtime({
      key: 'YOUR_API_KEY',
      clientId: 'user-123'
    });
    
    // Activate device for push
    await realtime.push.activate();
    
    iOS
    import Ably
    
    let realtime = ARTRealtime(key: "YOUR_API_KEY")
    realtime.clientId = "user-123"
    
    // Request permission and activate
    realtime.push.activate()
    
    Android
    import io.ably.lib.realtime.AblyRealtime
    
    val realtime = AblyRealtime("YOUR_API_KEY")
    realtime.setAndroidContext(applicationContext)
    
    // Activate device for push
    realtime.push.activate()
    
    10
    Subscribe to a channel
    11
    Subscribe your device to receive push notifications from a channel:
    12
    JavaScript
    // Subscribe to push notifications on a channel
    await realtime.push.admin.channelSubscriptions.save({
      channel: 'notifications',
      clientId: 'user-123'
    });
    
    iOS
    // 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")
        }
    }
    
    Android
    // 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")
        }
    }
    
    13
    Publish a push notification
    14
    Send a push notification to all subscribed devices:
    15
    Server-side
    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'
          }
        }
      }
    });
    
    Server-side
    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'
                }
            }
        }
    )
    

    Platform-specific guides

    For detailed setup instructions for each platform:

    iOS (APNs)

    1. Create APNs certificates
    2. Configure your Xcode project
    3. Request push permissions
    4. Handle push notifications
    See the complete APNs setup guide.

    Android (FCM)

    1. Create a Firebase project
    2. Add FCM to your app
    3. Configure Ably with FCM credentials
    4. Handle push notifications
    See the complete FCM setup guide.

    Web Push

    1. Generate VAPID keys
    2. Configure service worker
    3. Request notification permission
    4. Handle push notifications
    See the complete Web Push setup guide.

    Testing push notifications

    Use the Ably dashboard to test push notifications:
    1. Go to your app in the dashboard
    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

    Publish to all devices subscribed to a channel:

    Direct publishing

    Publish to specific devices or clients:

    Common notification formats

    Basic notification

    With action buttons (iOS)

    With custom data

    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

    Build docs developers (and LLMs) love