Configure and activate devices

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

Configure devices

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, as well as on the Ably platform.

Install and set up your Ably SDK

Use the following code to install and set up your Ably SDK:

// Add the Ably SDK into your build.gradle dependencies and ensure there's a reference to Maven in the repositories section:

dependencies {
  // io.ably.pubsub:device requires Android API level 24 (minSdk 24) or later
  implementation 'io.ably.pubsub:device:2.0.0'
  implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.1.0'
}

repositories {
  mavenCentral()
}

Activate devices

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

Activate directly

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. The following steps describe the direct activation process:

1. Authenticate the Ably client.
2. Generate a unique identifier for the device and saves it locally.
3. Activate 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. Register the device with Ably, providing its unique identifier (deviceId), platform details, and push recipient information.
5. Store 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:

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

import { ReactNativePush } from '@ably/pubsub-device/react-native-push';
import AsyncStorage from '@react-native-async-storage/async-storage';
import messaging from '@react-native-firebase/messaging';

const Push = ReactNativePush.create({
  storage: AsyncStorage,
  requestToken: async () => ({ transportType: 'fcm', token: await messaging().getToken() }),
});

const pubsubDeviceClient = getPubSubRealtimeClient({ plugins: { Push } });
await pubsubDeviceClient.push.activate();

Update the token when the platform rotates it

The push platform can rotate the device's token at any time. On React Native your application receives the rotation, so forward the new token to Ably with push.updateToken() to keep the device registration deliverable:

messaging().onTokenRefresh(async (token) => {
  await pubsubDeviceClient.push.updateToken({ transportType: 'fcm', token });
});

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.

Activate via server

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 calls push.activate() with custom registration enabled. As with direct activation, the SDK obtains a push token from the device's platform service, such as a registration token for FCM or a device token for APNs.
2. Instead of registering the device with Ably itself, the SDK asks your app to register it. Your app sends the device's details, including its deviceId and push token, to your server. Your server registers the device with Ably using the push admin API, and returns the device identity token from the registration to your app, which passes it back to the SDK.
3. Whenever the push token changes, and when the SDK rechecks an existing registration, for example when push.activate() is called on a device that is already activated, it asks your app to update the registration in the same way. Your server updates it using the push admin API, so make this update idempotent.

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

Device activation lifecycle

When the push.activate() and push.deactivate() methods are called, the SDK registers or deregisters the device with Ably in the background, or asks your app to do so if you activate via server. In addition, whenever there is an update to the push token (registration token for FCM or device token for APNs), the Ably SDK attempts to update this token on Ably's servers. Each of these operations can fail, so handle their outcomes.