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 Unity 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 Unity Chat SDK

If you create a chat app with the Unity 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 Unity Chat SDK initialization. You must pass them as configuration options when calling the CreateInstance() method through the PushNotifications property of PubnubChatConfig.

1

Easy methods for (un)registering channels

The Unity 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 C# SDK methods with a twist - by passing all required configuration options once during SDK configuration, you don't have to pass these options each time when calling the helper methods.

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 the SDK does this work for you.

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

See this example:

1{
2  "fcm": {
3    "notification": {
4      // message author - either the name or ID (if the name is missing)  
5      "title": "John Doe",
6      // content of the message
7      "text": "Hello, this is a test notification!"
8    }
9  },
10  "apns": {
11    "configurations": [
12      {
13        "targets": [
14          {
15            // for example, "com.apple.iMovie"
16            "topic": "com.domainname.applicationname"
17          }
18        ],
19        "title": "John Doe",
20        "text": "Hello, this is a test notification!",
21        // default iOS sound for notifications
22        "sound": "default",
23        // name of the channel on which the message was published
24        "subtitle": "Chat Room 1"
25      }
26    ]
27  }
28}

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.

RegisterForPush() and RegisterPushChannels() call Mobile Push Notifications API and the C# SDK AddPushNotificationsOnChannels() method.

Under the hood

Method signature

These methods take the following parameters:

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

  1channel.RegisterForPush(): Task<ChatOperationResult>

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

  1chat.RegisterPushChannels(List<string> channelIds): Task<ChatOperationResult>

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:

* required

Parameter	Description
channelIds * Type: List<string> Default: n/a	List of channels where you want your device to receive push notifications for sent messages.

Output

Type	Description
Task<ChatOperationResult>	A ChatOperationResult indicating the success or failure of the operation.

Sample code

1

List all push channels

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

GetPushChannels() calls Mobile Push Notifications API and the C# SDK AuditPushChannelProvisions() method.

Under the hood

Method signature

This method has the following signature:

1chat.GetPushChannels(): Task<ChatOperationResult<List<string>>>

Input

This method doesn't take any parameters.

Output

Type	Description
Task<ChatOperationResult<List<string>>>	A ChatOperationResult containing a list of all channels registered to receive push notifications on a given device.

Sample code

1

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.

UnRegisterFromPush() and UnRegisterPushChannels() call Mobile Push Notifications API and the C# SDK RemovePushNotificationsFromChannels() method.

Under the hood

Method signature

These methods take the following parameters:

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

  1channel.UnRegisterFromPush(): Task<ChatOperationResult>

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

  1chat.UnRegisterPushChannels(List<string> channelIds): Task<ChatOperationResult>

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:

* required

Parameter	Description
channelIds * Type: List<string> Default: n/a	List of channels where you want your device to unregister from receiving push notifications for sent messages.

Output

Type	Description
Task<ChatOperationResult>	A ChatOperationResult indicating the success or failure of the operation.

Sample code

1

Unregister all push channels

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

UnRegisterAllPushChannels() calls Mobile Push Notifications API and the C# SDK RemoveAllPushNotificationsFromDeviceWithPushToken() method.

Under the hood

Method signature

This method has the following signature:

1chat.UnRegisterAllPushChannels(): Task<ChatOperationResult>

Input

This method doesn't take any parameters.

Output

Type	Description
Task<ChatOperationResult>	A ChatOperationResult indicating the success or failure of the operation.

Sample code

1

Send custom push data

You can include custom data in push notification payloads when sending messages. Use the CustomPushData property of SendTextParams to pass additional key-value pairs that will be included in the push notification.

Sample code

1