Configure and activate devices

To push notifications with Ably, you must first configure the device using its platform-specific notification service (APNs for iOS or FCM for Android) and integrate it with Ably’s infrastructure. You can then activate the push notifications service, either directly or via a server.

Configuration is the first step in setting up push notifications with Ably. This step requires setting up the necessary infrastructure on the device’s operating system or platform, such as iOS with APNs or Android with FCM, as well as on the Ably platform.

Push Notifications in Ably

  • Go to the Firebase Console.
  • Click add project and follow the steps to create and manage service account keys.
  • Download your Service account key file containing your Privacy Enhanced Mail (PEM) cert and PEM private key.
  • In your Ably dashboard, navigate to the notifications tab under your app settings.
  • Go to push notifications setup, click configure push.
  • Add your PEM cert and PEM private key.
  • Go to the Apple Developer Program.
  • Use the Apple Developer portal to create a push notification service certificate for your app.
  • Export the certificate as a .p12 file.
  • In your Ably dashboard, navigate to the notifications tab under your app settings.
  • Go to push notifications setup, click configure push.
  • Add your .p12 file.

The following steps guide you through the Ably SDK integration process:

Select...
// Define the custom action for push notifications public class AblyPushNotificationService extends FirebaseMessagingService { // This method is overridden to handle any messages received while the app is in the foreground or background. @Override public void onMessageReceived(@NonNull RemoteMessage message) { // Process the incoming message here } //This method is overridden to handle token refresh, ensuring that Ably is always updated with the latest token. @Override public void onNewToken(@NonNull String token) { super.onNewToken(s); // Update Ably's server with the new token ActivationContext.getActivationContext(this).onNewRegistrationToken(RegistrationToken.Type.FCM, s); } }
Copied!

To receive push notifications using Ably, each device must first register with the platform-specific push notification service — APNs and FCM. Ably’s SDK facilitates this registration process and provides a unified API to manage it across different platforms.

Push Notifications in Ably

Activating a device for push notifications is typically done directly on the device itself. Use the push.activate() method to activate push notifications from a device. This process handles the following steps:

  1. Authenticates the Ably client.
  2. Generates a unique identifier for the device and saves it locally.
  3. Activates push notifications for the device with the underlying OS, obtaining a unique identifier like a registration token for FCM or a device token for APNs.
  4. Registers the device with Ably, providing its unique identifier (deviceId), platform details, and push recipient information.
  5. Stores the device’s identity token from Ably’s response locally for authentication in subsequent updates.

Note that once activated, the device remains registered even after the application is closed until the push.deactivate() method is called. Calling activate again has no effect if the device is already activated.

The following diagram demonstrates the direct activation process:

push notifications in Ably

The following example initializes an instance of the Ably Realtime service and then activates the push notifications feature for that instance:

Select...
AblyRealtime ably = getAblyRealtime(); ably.setAndroidContext(context); ably.push.activate();
Copied!

Test your push notification activation

  • Use the Ably dashboard or API to send a test push notification to a registered device.
  • Ensure your application correctly receives and handles the push notification.

In specific scenarios, especially where strict control over device capabilities is essential, managing the activation of devices for push notifications through the server is useful. This approach separates the registration with the device’s platform-specific push notification service, which still happens on the device. Meanwhile, your server manages the device registration with Ably. This setup provides a centralized and efficient process for controlling devices.

The following steps explain the server assisted activation process:

  1. The device initiates the activation process by registering with its respective platform service (APNs or FCM) to obtain a unique device identifier, such as a registration token or device token.
  2. Instead of registering itself with Ably, the device sends its platform-specific identifier to your server. Your server then uses this identifier to register the device with Ably using Ably’s Push Admin API.
  3. The server stores and manages the device tokens. It is responsible for updating these tokens in Ably’s system whenever they change, which can be triggered by the device sending a new token to the server following the platform service’s renewal.

The following diagram demonstrates the process for activating devices from a server:

push notifications in Ably

Activate Android device via server

Your application must interact with the Ably SDK to configure server-side registration for push notifications, utilizing the LocalBroadcastManager for communication.

Ensure that the useCustomRegisterer parameter is set to true when calling push.activate() or push.deactivate().

Select...
ably.push.activate(context, true); ably.push.deactivate(context, true);
Copied!

Upon activation or deactivation, the Ably SDK broadcasts signals indicating whether to register or deregister the device from your server. It uses io.ably.broadcast.PUSH_REGISTER_DEVICE for registration and io.ably.broadcast.PUSH_DEREGISTER_DEVICE for deregistration. To handle these broadcasts, implement a listener in your app’s AndroidManifest.xml and respond by sending back PUSH_DEVICE_REGISTERED or PUSH_DEVICE_DEREGISTERED as appropriate.

The following examples set up the server-side activation:

<receiver android:name=".MyAblyBroadcastReceiver"> <intent-filter> <action android:name="io.ably.broadcast.PUSH_REGISTER_DEVICE" /> <action android:name="io.ably.broadcast.PUSH_DEREGISTER_DEVICE" /> <intent-filter> <receiver>
Copied!
Select...
public class MyAblyBroadcastReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { AblyRealtime ably = getAblyRealtime(); String action = intent.getAction(); if (action.equals("io.ably.broadcast.PUSH_REGISTER_DEVICE")) { DeviceDetails device = ably.device(context); boolean isNew = intent.getBooleanExtra("isNew", false); Intent response = new Intent("io.ably.broadcast.PUSH_DEVICE_REGISTERED"); try { String deviceIdentityToken = registerThroughYourServer(device, isNew); response.putExtra("deviceIdentityToken", deviceIdentityToken); } catch(AblyException e) { IntentUtils.addErrorInfo(intent, e.errorInfo); } LocalBroadcastManager.getInstance(context.getApplicationContext()).sendBroadcast(intent); } else if (action.equals("io.ably.broadcast.PUSH_DEREGISTER_DEVICE")) { DeviceDetails device = ably.device(context); Intent response = new Intent("io.ably.broadcast.PUSH_DEVICE_DEREGISTERED"); try { deregisterThroughYourServer(device.id); } catch(AblyException e) { IntentUtils.addErrorInfo(intent, e.errorInfo); } LocalBroadcastManager.getInstance(context.getApplicationContext()).sendBroadcast(intent); } } }
Copied!

Activate iOS device via server

When setting up server-side registration for push notifications on iOS, your application must interact with the Ably SDK to handle device registration and deregistration securely and effectively. Implement the following optional methods from ARTPushRegistererDelegate in your UIApplicationDelegate to customize the registration process:

Select...
func ablyPushCustomRegister(_ error: ARTErrorInfo?, deviceDetails: ARTDeviceDetails, callback: @escaping (ARTDeviceIdentityTokenDetails?, ARTErrorInfo?) -> Void) { if let e = error { // Log or handle the error as needed callback(nil, e) return } // Your server-side logic to register the device self.registerThroughYourServer(deviceDetails: deviceDetails, callback: callback) } func ablypushCustomDeregister(_ error: ARTErrorInfo?, deviceId: String, callback: @escaping (ARTErrorInfo?) -> Void) { if let e = error { // Log or handle the error as needed callback(nil, e) return } // Your server-side logic to deregister the device self.unregisterThroughYourServer(deviceId: deviceId, callback: callback) }
Copied!

Test your push notification activation

  • Use the Ably dashboard or API to send a test push notification to a registered device.
  • Ensure your application correctly receives and handles the push notification.

When the push.activate() and push.deactivate() methods are called, the device registers with FCM or APNs. In addition, whenever there is an update to the push token (either the APNs device token or the FCM registration token), the Ably SDK attempts to update this token on Ably’s servers.

Android
  • To activate implement io.ably.broadcast.PUSH_ACTIVATE in a broadcast intent.
  • To deactivate implement io.ably.broadcast.PUSH_DEACTIVATE in a broadcast intent.
  • To update implement io.ably.broadcast.PUSH_UPDATE_FAILED in a broadcast intent.
Swift
  • To activate implement func didActivateAblyPush(_ error: ARTErrorInfo?)
  • To deactivate implement func didDeactivateAblyPush(_ error: ARTErrorInfo?)
  • To update implement func didAblyPushRegistrationFail(_ error: ARTErrorInfo?)
ObjC
  • To activate implement (void)didActivateAblyPush:(nullable ARTErrorInfo *)error;
  • To deactivate implement (void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error;
  • To update implement (void)didAblyPushRegistrationFail:(nullable ARTErrorInfo *)error;=:ionFail:(nullable ARTErrorInfo *)error;

The following is an example of how to listen for a push activation event:

Select...
LocalBroadcastManager.getInstance(context.getApplicationContext()).registerReceiver(new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { ErrorInfo error = IntentUtils.getErrorInfo(intent); if (error != null) { // Handle error return; } // Subscribe to channels / listen for push etc. } }, new IntentFilter("io.ably.broadcast.PUSH_ACTIVATE")); ably.push.activate(context);
Copied!
Configure devices
v2.0