Mobile Push Notifications

Mobile Push Notifications are a great way to notify online and offline users about appointments, updates, previews of conversations, special offers, and more.

Required configuration

To enable push notifications in your chat app:

Configure your app's keyset in Admin Portal by enabling MOBILE PUSH NOTIFICATIONS for your app's keyset in the Admin Portal and providing required details under the APPLE PUSH CREDENTIALS or FIREBASE CLOUD MESSAGING section.
While initializing the Chat SDK, configure your chat app to send/receive push notifications.

How to set up push notifications

In general, you can configure your chat app to receive notifications on iOS or Android devices about messages sent from a particular client (whether a mobile device, web browser, or server). You do so by communicating either with the Apple Push Notification service (APNs), for Apple devices, or Google's Firebase Cloud Messaging (FCM, formerly known as GCM), for Android devices.

Setting up mobile push notifications for your app built with PubNub is a few-step process. This process is already documented but may differ slightly depending on the SDK you built your app with. Let's go briefly through it together.

Start by setting up a server-to-server communication as you want the PubNub server to communicate with the push notifications' provider server (APNs or FCM).

Assuming you already have a PubNub account on our Admin Portal, you must enable MOBILE PUSH NOTIFICATIONS on your app's keyset. Additionally, depending on whether you want to send push notifications from your app to iOS or Android devices, provide the required details under the APPLE PUSH CREDENTIALS or FIREBASE CLOUD MESSAGING section. You'll need such details as APNs Authentication Token (in the form of a *.p8 file) or Firebase Server Key from the chosen provider's account.
You must enable client communication by registering your app (client) with the service provider.

Request the provider to register your app on their service to issue a device token. The device token is a unique identifier assigned by Apple and Google to a specific device when it registers for push notifications. The device token is essential for push notifications to function correctly because it allows the push notification service to identify and reach the specific devices that have opted to receive notifications for your app. When you want to send a push notification to a particular user or device, you use this device token to target the intended recipient, and the push notification service delivers notifications directly to that device.

For iOS, when you install and open the app for the first time, the app requests push notification permissions, and if granted, the device token is generated. For Android, when you install the app and grant permission for push notifications, the FCM service generates a unique registration token for the device.

For details on how to get a device token for the APNs and FCM services, refer to the official Apple and Google docs.
For iOS apps, you must also come up with a bundle ID for your application to uniquely identify it.
Register the device token with selected channels on the PubNub network. Publishing messages on those channels triggers push notifications on the device.

You can change the registration at any time during the application lifecycle by adding additional channels or removing previously registered channels. This allows you to handle a variety of channel-specific messages and dynamically change each channel's targeted device lists in real time.
Finally, you have to attach a specific payload to every message that needs to be sent as a notification - push notification providers require a message to include a payload structure that differs per provider.

What's improved in Chat SDK

If you create a chat app with Chat SDK, you can count on a few simplifications in the above process.

Simple configuration process

You decide if you want your app to send/receive push notifications once during the Chat SDK initialization. You must pass them as configuration options when calling the init() method. Note that there are separate options for receiving and sending push notifications.

Easy methods for (un)registering channels

Chat SDK offers a few simple methods for registering selected channels for push notifications, listing all registered channels, and unregistering selected or all channels.

These methods are wrappers on the existing Kotlin SDK methods with a twist - by passing all required configuration options once during Chat SDK configuration, you don't have to pass these options each time when calling the helper methods (unlike in the Kotlin SDK).

Automatic payload creation

When you configure your app to send push notifications using the sendPushes option, you no longer have to think about adding push notification payload to every message because Chat SDK does this work for you.

Once you enable and properly configure your app for push notifications during initialization, Chat SDK passes the default payload structure to the registered channels in every message.

See this example:

{
  "fcm": {
    "notification": {
      // message author - either the name or ID (if the name is missing)  
      "title": "John Doe",
      // content of the message
      "text": "Hello, this is a test notification!"
    }
  },
  "apns": {
    "configurations": [
      {
        "targets": [
          {
            // for example, "com.apple.iMovie"
show all 28 lines

Register selected push channels

Use the registerForPush() and registerPushChannels() methods to decide on which channel or channels a previously registered device will receive push notifications about new messages.

The difference between these methods is that you call these methods on different objects (Channel and Chat) and can choose one or many channels where you want users to receive push notifications.

Method signature

These methods take the following parameters:

registerForPush() - lets you register a device on a single channel
```
channel.registerForPush(): PNFuture<PNPushAddChannelResult>
```

registerPushChannels() - lets you register a device on multiple channels at once

chat.registerPushChannels(channels: List<String>): PNFuture<PNPushAddChannelResult>

Input

As the registerForPush() method is invoked on the Channel object, it doesn't need to take any parameters. The channel the method is invoked on is the one registered.

The registerPushChannels() method takes the following parameters:

Parameter	Type	Required	Default	Description
`channels`	`List<String>`	Yes	n/a	List of channels where you want your device to receive push notifications for sent messages.

Output

Type	Description
`PNFuture<PNPushAddChannelResult>`	Method returns no output data.

Basic usage

registerForPush()

Receive push notifications for messages sent on the support channel.

// register the "support" channel for push notifications
chat.getChannel("support").async { result ->
    result.onSuccess { channel ->
        // register this channel for push notifications
        channel.registerForPush().async { pushResult ->
            pushResult.onSuccess { pushAddChannelResult: PNPushAddChannelResult ->
                println("Successfully registered the 'support' channel for push notifications.")
            }.onFailure { throwable ->
                println("Failed to register the 'support' channel for push notifications.")
                throwable.printStackTrace()
            }
        }
    }.onFailure { throwable ->
        println("Failed to retrieve the 'support' channel.")
        throwable.printStackTrace()
show all 17 lines

registerPushChannels()

Receive push notifications for messages sent on the support and inicident-management channels.

// list of channels you want to register for push notifications
val channelsToRegister = listOf("support", "incident-management")

// register the list of channels for push notifications
chat.registerPushChannels(channelsToRegister).async { pushResult ->
    pushResult.onSuccess { pushAddChannelResult: PNPushAddChannelResult ->
        println("Successfully registered channels for push notifications: $channelsToRegister")
    }.onFailure { throwable ->
        println("Failed to register channels for push notifications: $channelsToRegister")
        throwable.printStackTrace()
    }
}

List all push channels

Use the getPushChannels() method to request for all channels where your registered device receives push notifications.

Method signature

This method has the following signature:

chat.getPushChannels(): PNFuture<List<String>>

Input

This method doesn't take any parameters.

Output

Type	Description
`PNFuture<List<String>>`	Returned list of all channels registered to receive push notifications on a given device.

Basic usage

List all registered channels.

chat.getPushChannels().async { result ->
    result.onSuccess { channels ->
        println("Push notifications are registered for the following channels:")
        channels.forEach { channel ->
            println(channel)
        }
    }.onFailure { throwable ->
        println("Failed to retrieve push notification registered channels.")
        throwable.printStackTrace()
    }
}

Unregister selected push channels

Use the unregisterFromPush() and unregisterPushChannels() methods to decide for which channel or channels a registered device will no longer receive push notifications about new messages.

The difference between these methods is that you call these methods on different objects (Channel and Chat) and can choose either one or many channels where you want users to stop receiving push notifications.

Method signature

These methods take the following parameters:

unregisterFromPush() - lets you unregister a device from a single channel
```
channel.unregisterFromPush(): PNFuture<PNPushRemoveChannelResult>
```

unregisterPushChannels() - lets you unregister a device from multiple channels at once

chat.unregisterPushChannels(channels: List<String>): PNFuture<PNPushRemoveChannelResult>

Input

As the unregisterFromPush() method is invoked on the Channel object, it doesn't need to take any parameters. The channel the method is invoked on is the one unregistered.

The unregisterPushChannels() method takes the following parameters:

Parameter	Type	Required	Default	Description
`channels`	`List<String>`	Yes	n/a	List of channels where you want your device to unregister from receiving push notifications for sent messages.

Output

Type	Description
`PNFuture<PNPushRemoveChannelResult>`	Method returns no output data.

Basic usage

unregisterFromPush()

Stop receiving push notifications for messages sent on the support channel.

// Unregister the "support" channel for push notifications
chat.getChannel("support").async { result ->
    result.onSuccess { channel ->
        // Unregister this channel from push notifications
        channel.unregisterFromPush().async { pushResult ->
            pushResult.onSuccess { pushRemoveChannelResult: PNPushRemoveChannelResult ->
                println("Successfully unregistered the 'support' channel from push notifications.")
            }.onFailure { throwable ->
                println("Failed to unregister the 'support' channel from push notifications.")
                throwable.printStackTrace()
            }
        }
    }.onFailure { throwable ->
        println("Failed to retrieve the 'support' channel.")
        throwable.printStackTrace()
show all 17 lines

unregisterPushChannels()

Stop receiving push notifications for messages sent on the support and inicident-management channels.

// list of channels you want to unregister for push notifications
val channelsToUnregister = listOf("support", "incident-management")

// unregister the list of channels for push notifications
chat.unregisterPushChannels(channelsToUnregister).async { pushResult ->
    pushResult.onSuccess { pushRemoveChannelResult: PNPushRemoveChannelResult ->
        println("Successfully unregistered channels from push notifications: $channelsToUnregister")
    }.onFailure { throwable ->
        println("Failed to unregister channels from push notifications: $channelsToUnregister")
        throwable.printStackTrace()
    }
}

Unregister all push channels

Disable push notifications for a device on all registered channels using the unregisterAllPushChannels() method.

Method signature

This method has the following signature:

chat.unregisterAllPushChannels(): PNFuture<Unit>

Input

This method doesn't take any parameters.

Output

Type	Description
`PNFuture<Unit>`	Method returns no output data.

Basic usage

Disable push notifications on all registered channels.

// unregister all channels for push notifications
chat.unregisterAllPushChannels().async { pushResult ->
    pushResult.onSuccess { 
        println("Successfully unregistered all channels from push notifications")
    }.onFailure { throwable ->
        println("Failed to unregister all channels from push notifications")
        throwable.printStackTrace()
    }
}

Required configuration

How to set up push notifications​

What's improved in Chat SDK​

Simple configuration process​

Easy methods for (un)registering channels​

Automatic payload creation​

Register selected push channels​

Method signature​

Input​

Output​

Basic usage​

List all push channels​

Method signature​

Input​

Output​

Basic usage​

Unregister selected push channels​

Method signature​

Input​

Output​

Basic usage​

Unregister all push channels​

Method signature​

Input​

Output​

Basic usage​

How to set up push notifications

What's improved in Chat SDK

Simple configuration process

Easy methods for (un)registering channels

Automatic payload creation

Register selected push channels

Method signature

Input

Output

Basic usage

List all push channels

Method signature

Input

Output

Basic usage

Unregister selected push channels

Method signature

Input

Output

Basic usage

Unregister all push channels

Method signature

Input

Output

Basic usage