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.

1. 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.

2. 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.

3. For iOS apps, you must also come up with a bundle ID for your application to uniquely identify it.

4. 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.

5. 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 JavaScript 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 JavaScript 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.

Under the hood

Method signature

These methods take the following parameters:

• registerForPush() - lets you register a device on a single channel

  channel.registerForPush(): Promise<void>

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

  chat.registerPushChannels(channels: string[]): Promise<void>

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	string[]	Yes	n/a	List of channels where you want your device to receive push notifications for sent messages.

Output

Type	Description
Promise<void>	Method returns no output data.

Basic usage

• registerForPush()

  Receive push notifications for messages sent on the support channel.

  // reference the "channel" object
  const channel = await chat.getChannel("support")
  // register this channel for push notifications
  const registeredChannel = channel.registerForPush()

• registerPushChannels()

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

  const registeredChannel = await chat.registerPushChannels([
      "support",
      "inicident-management"
  ])

List all push channels

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

Under the hood

Method signature

This method has the following signature:

chat.getPushChannels(): Promise<string[]>

Input

This method doesn't take any parameters.

Output

Type	Description
Promise<string[]>	Returned list of all channels registered to receive push notifications on a given device.

Basic usage

List all registered channels.

const allRegisteredChannels = await chat.getPushChannels()

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.

Under the hood

Method signature

These methods take the following parameters:

• unregisterFromPush() - lets you unregister a device from a single channel

  channel.unregisterFromPush(): Promise<void>

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

  chat.unregisterPushChannels(channels: string[]): Promise<void>

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	string[]	Yes	n/a	List of channels where you want your device to unregister from receiving push notifications for sent messages.

Output

Type	Description
Promise<void>	Method returns no output data.

Basic usage

• unregisterFromPush()

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

  // reference the "channel" object
  const channel = await chat.getChannel("support")
  // unregister this channel from push notifications
  channel.unregisterFromPush()

• unregisterPushChannels()

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

  await chat.unregisterPushChannels([
      "support",
      "inicident-management"
  ])

Unregister all push channels

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

Under the hood

Method signature

This method has the following signature:

chat.unregisterAllPushChannels(): Promise<void>

Input

This method doesn't take any parameters.

Output

Type	Description
Promise<void>	Method returns no output data.

Basic usage

Disable push notifications on all registered channels.

await chat.unregisterAllPushChannels()