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
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:
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

Via channels (recommended)

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

• Learn about publishing push notifications
• Understand device activation
• Explore push admin API
• Monitor push errors