Mobile Push Notifications API for JavaScript SDK

The Mobile Push Notifications feature connects native PubNub publishing to third-party push services. Supported services include Google Android FCM (Firebase Cloud Messaging) and Apple iOS APNs (Apple Push Notification service).

To learn more, read about Mobile Push Notifications.

Supported and recommended asynchronous patterns

PubNub supports Callbacks, Promises, and Async/Await for asynchronous JS operations. The recommended pattern is Async/Await and all sample requests in this document are based on it. This pattern returns a status only on detecting an error. To receive the error status, you must add the try...catch syntax to your code.

Add a device to a push notifications channel

Requires Mobile Push Notifications add-on

Enable Mobile Push Notifications for your key in the Admin Portal. See how to enable add-on features.

Enable mobile push notifications on a set of channels.

Method(s)

pubnub.push.addChannels({
    channels: Array<string>,
    device: string,
    pushGateway: string,
    environment: string,
    topic: string
})

* required

Parameter	Description
channels * Type: Array<string> Default: n/a	Channels to enable for push notifications.
device * Type: string Default: n/a	Device token.
pushGateway * Type: string Default: n/a	Accepted values: apns2, gcm.
environment Type: string Default: development	APNs environment. Accepted values: development, production. Required if pushGateway is apns2.
topic Type: string Default: n/a	APNs topic (bundle identifier). Required if pushGateway is apns2.

Sample code

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

Add device to channel

Response

{
    error: false,
    operation: 'PNPushNotificationEnabledChannelsOperation',
    statusCode: 200
}

List push notifications channels for a device

Requires Mobile Push Notifications add-on

Enable Mobile Push Notifications for your key in the Admin Portal. See how to enable add-on features.

Get all channels with push notifications for the specified push token.

Method(s)

pubnub.push.listChannels({
    device: string,
    pushGateway: string,
    environment: string,
    topic: string
})

* required

Parameter	Description
device * Type: string Default: n/a	Device token.
pushGateway * Type: string Default: n/a	Accepted values: apns2, gcm.
environment Type: string Default: development	APNs environment. Accepted values: development, production. Required if pushGateway is apns2.
topic Type: string Default: n/a	APNs topic (bundle identifier). Required if pushGateway is apns2.
start Type: string Default: n/a	Start channel for pagination. Use the last channel from the previous page.
count Type: number Default: n/a	Number of channels to return. Maximum 1000; default 500.

Sample code

List channels for device

Response

// Example of status
{
    error: false,
    operation: 'PNPushNotificationEnabledChannelsOperation',
    statusCode: 200
}

// Example of response
{
    channels: [ 'a', 'b' ]
}

Remove a device from push notifications channels

Requires Mobile Push Notifications add-on

Enable Mobile Push Notifications for your key in the Admin Portal. See how to enable add-on features.

Disable push notifications on selected channels.

Method(s)

pubnub.push.removeChannels({
    channels: Array<string>,
    device: string,
    pushGateway: string,
    environment: string,
    topic: string
})

* required

Parameter	Description
channels * Type: Array<string> Default: n/a	Channels to disable for push notifications.
device * Type: string Default: n/a	Device token.
pushGateway * Type: string Default: n/a	Accepted values: apns2, gcm.
environment Type: string Default: development	APNs environment. Accepted values: development, production. Required if pushGateway is apns2.
topic Type: string Default: n/a	APNs topic (bundle identifier). Required if pushGateway is apns2.

Sample code

Remove device from channel

Response

{
    error: false,
    operation: 'PNPushNotificationEnabledChannelsOperation',
    statusCode: 200
}

Remove a device from all push notifications channels

Requires Mobile Push Notifications add-on

Enable Mobile Push Notifications for your key in the Admin Portal. See how to enable add-on features.

Disable push notifications from all channels registered for the specified push token.

Method(s)

pubnub.push.deleteDevice({
    device: string,
    pushGateway: string,
    environment: string,
    topic: string
})

* required

Parameter	Description
device * Type: string Default: n/a	Device token.
pushGateway * Type: string Default: n/a	Accepted values: apns2, gcm.
environment Type: string Default: development	APNs environment. Accepted values: development, production. Required if pushGateway is apns2.
topic Type: string Default: n/a	APNs topic (bundle identifier). Required if pushGateway is apns2.

Sample code

Remove all mobile push notifications

Response

{
    error: false,
    operation: 'PNPushNotificationEnabledChannelsOperation',
    statusCode: 200
}

Push notification format configuration

Push notifications enforce specific message format requirements. Use these methods to configure your APNs and FCM mobile push notifications.

APNS2Configuration

APNS2 configuration type.

Method(s)

type APNS2Configuration = {
    collapseId?: string,
    expirationDate?: Date,
    targets: Array<APNS2Target>
}

* required

Parameter	Description
collapseId Type: string	Collapse identifier (apns-collapse-id).
expirationDate Type: Date	Expiration (apns-expiration).
targets * Type: Array< APNS2Target>	Delivery targets.

APNSNotificationPayload

APNSNotificationPayload provides APNs-only options.

Properties

Parameter	Description
configurations Type: Array< APNSNotificationConfiguration>	HTTP/2 APNs delivery configurations.
notification Type: Hash	User-visible key-value pairs.
payload Type: Hash	Platform-specific payload for additional data.
silent Type: Boolean	If true, omits alert, sound, and badge.

APNS2Target

APNS2 configuration target type.

Method(s)

type APNS2Target = {
    topic: string,
    environment?: 'development' | 'production',
    excludedDevices?: Array<string>
}

* required

Parameter	Description
topic * Type: string Default: n/a	APNs topic (bundle identifier).
environment Type: string Default: development	Accepted values: development, production.
excludedDevices * Type: Array Default: n/a	Push tokens to exclude.

FCMNotificationPayload

FCMNotificationPayload provides FCM-only options.

Properties

Parameter	Description
notification Type: Hash	User-visible key-value pairs.
data Type: Hash	Additional key-value data (stringify values). Must not include reserved keys (for example, from, message_type, keys starting with google or gcm). See the Firebase table.
silent Type: Boolean	If true, moves notification under data.
icon Type: String	Icon shown with the notification title.
tag Type: String	Identifier used to update/replace a prior notification.
payload Type: Hash	Platform-specific payload for additional data.

Cross-platform notifications payload

NotificationsPayload helps build multi-platform payloads and access platform-specific builders.

Method(s)

Parameter	Description
subtitle Type: string	Additional context for the notification.
badge Type: number	Badge count for supported platforms.
sound Type: string	Sound name or file path to play.
debugging Type: boolean	Include device delivery debug info.
apns Type: APNSNotificationPayload	APNs-specific builder.
fcm Type: FCMNotificationPayload	FCM-specific builder.

PubNub.notificationPayload(
    title: string,
    body: string
)

* required

Parameter	Description
title Type: string	Title shown in the notification.
body Type: string	Body text shown under the title.

buildPayload(
    platforms: Array<string>
)

* required

Parameter	Description
platforms * Type: Array<string>	List of platforms for which payload should be added to final dictionary. Available: apns apns2 fcm

Sample code

Create notification payload builder with pre-defined notification title and body:

let builder = PubNub.notificationPayload('Chat invitation',
                                            'You have been invited to \'quiz\' chat');

Response

Hash with data, which can be sent with publish method call and trigger remote notifications for specified platforms.

Other examples

Generate simple notification payload for FCM and APNS

Generate simple notification payload for FCM and HTTP/2-based APNs (default configuration)

Generate simple notification payload for FCM and HTTP/2-based APNs (custom configuration)

Output

{
    "pn_apns": {
        "aps": {
            "alert": {
                "body": "Chat invitation",
                "title": "You have been invited to 'quiz' chat"
            }
        },
        "pn_push": [
            {
                "collapse_id": "invitations",
                "expiration": "2019-11-28T22:06:09.163Z",
                "targets": [
                    {
                        "environment": "development",

show all 29 lines

Example above show how to create notification payload which APNS will try to redeliver few times (if devices not active) and give up after 10 seconds since moment when it has been scheduled.

Additionally this invitation notification will be grouped along with other invitation notifications (using provided collapse_id as group identifier) and shown as one in notification center.

Returns

Configured and ready to use NotificationsPayload instance.