QuickBlox Documentation

QuickBlox provides powerful Chat API and SDK to add real-time messaging and video calls to your web and mobile apps. Learn how to integrate QuickBlox across multiple platforms.

Push Notifications

Use this page to learn how to send push notifications to users when they are offline.

🚧

This is our documentation for beta version of QuickBlox React Native SDK. Please contact our Customer Support Team to provide your feedback, suggestions, and requests to improve this page.

Push Notifications provide a way to deliver some information to a user while they are not using your app actively. The following use cases can be covered by push notifications:

  • Offline messages. Send a chat message when a recipient is offline. In this case, a push notification will be sent automatically if the user is offline.
  • Offline calls. Make a video/audio call with offline opponents. In this case, a push notification will be sent manually.
  • Requests to contact list. Send requests to add a user to the contact list. In this case, a push notification will be sent manually).
  • User tags. Send notifications to specific user groups defined by tags.

Learn more information from the Push Notifications section of our Key Concepts page.

Before you begin

  1. Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.
  2. Register a QuickBlox account. This is a matter of a few minutes and you will be able to use this account to build your apps.
  3. Configure QuickBlox SDK for your app. Check out our Setup page for more details.
  4. Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.

Configuration

To start working with push notifications, you need to install react-native-push-notification library. Follow the setup steps in the README file. After that, follow the platform-specific steps on this page.

iOS

Step1. Create APNS certificate and upload it to the Dashboard.

Each iOS application that uses Apple Push Notifications must have an APNS certificate. Upload the APNS certificate to QuickBlox Dashboard => Push Notifications => Settings => Apple Push Notification Service (APNS). To learn how to create APNS certificates and upload them to Dashboard, refer to our guide.

Step2. Open your project in Xcode and enable Push Notifications capabilities.

  1. Open Xcode and choose your project file.
  2. Choose the Signing & Capabilities tab.
  3. Add a Push Notifications and Background Modes capabilities. To see these sections, you should be logged in to Xcode with your Apple ID that is enrolled in the Apple developer program.
  4. Turn on a Push Notifications capability.
  5. Turn on a Background modes capability. This section requires you to add specific app permissions.
  6. Select a Remote notifications checkbox if you want to receive push notifications when the app goes to background mode.
  7. Select a Voice over IP checkbox if you want your app to receive incoming Voice-over-IP (VoIP) push notifications and use them to display the system call interface to the user when the app is in the background mode.

Android

Step 1. Configure Firebase project and get API key and Sender ID.

First, you should create a Firebase account if you don't have it. Then you should configure your Firebase project. To learn how to configure a Firebase project and get API key and Sender ID, refer to our guide .

Step 2. Add Firebase to your project.

  1. Prepare app dependencies. As part of enabling Firebase services in your Android application, you need to add the google-services plugin to your project android/build.gradle file.
dependencies {
  classpath 'com.google.gms:google-services:4.3.3'
  //...
}

Add Firebase dependency and include gms plugin in the bottom of your module android/app/build.gradle.

implementation "com.google.firebase:firebase-analytics:17.3.0"
//...
apply plugin: 'com.google.gms.google-services'

🚧

Make sure that apply plugin: 'com.google.gms.google-services' is at the end of the file to avoid compilation errors.

  1. Put your google-services.json file for your package into android/app/ folder.

Initialize react-native-push-notification lib

Initialize the react-native-push-notification lib using the code snippet below.

import PushNotificationIOS from "@react-native-community/push-notification-ios";
var PushNotification = require("react-native-push-notification");

// Must be outside of any component LifeCycle (such as `componentDidMount`).
PushNotification.configure({
  // (optional) Called when Token is generated (iOS and Android)
  onRegister: function (token) {
    console.log("TOKEN:", token);
  },

  // (required) Called when a remote is received or opened, or local notification is opened
  onNotification: function (notification) {
    console.log("NOTIFICATION:", notification);

    // process the notification

    // (required) Called when a remote is received or opened, or local notification is opened
    notification.finish(PushNotificationIOS.FetchResult.NoData);
  },

  // (optional) Called when Registered Action is pressed and invokeApp is false, if true onNotification will be called (Android)
  onAction: function (notification) {
    console.log("ACTION:", notification.action);
    console.log("NOTIFICATION:", notification);

    // process the action
  },

  // (optional) Called when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. (iOS)
  onRegistrationError: function (err) {
    console.error(err.message, err);
  },

  // IOS ONLY (optional): default: all - Permissions to register.
  permissions: {
    alert: true,
    badge: true,
    sound: true,
  },

  // Should the initial notification be popped automatically
  // default: true
  popInitialNotification: true,

  /**
   * (optional) default: true
   * - Specified if permissions (ios) and token (android and ios) will requested or not,
   * - if not, you must call PushNotificationsHandler.requestPermissions() later
   * - if you are not using remote notification or do not have Firebase installed, use this:
   *     requestPermissions: Platform.OS === 'ios'
   */
  requestPermissions: true,
});

Subscribe to push notifications

Subscribe to FCM or APNs service. Once the device is subscribed, the service delivers a notification to it.

For VoIP push notifications, specify push_channel: apns_voip channel.

import { Platform } from 'react-native'

//...
onRegister: function(token) {
  // token obtained from APNS or FCM
  const config = Platform.OS === 'ios' ? {
    deviceToken: token,
    // to receive incoming call notification on iOS device(s) APNS_VOIP should be used
    pushChannel: QB.subscriptions.PUSH_CHANNEL.APNS_VOIP
  } : {
    deviceToken: token.token
  }

  QB.subscriptions
    .create(config)
    .then((subscriptions) => { /* subscription(s) created successfully */ })
    .catch(e => { /* handle error */ })
}
//...

Parameters

Required

Description

deviceToken

yes

Token received from FCM/APNs.

pushChannel

no

Channel for receiving push notifications.

Send push notifications

You can initiate sending a push notification to a user(s) on any event in your application. To do so, you need to set push notification parameters, push recipients, notification type, sender ID, and type of the notification event.

For VoIP push notifications, you need to set the ios_voip: 1 parameter.

const event = {
  notificationType: QB.events.NOTIFICATION_TYPE.PUSH,
  payload: {
    ios_voip: 1, // to send VoIP push notification (https://docs.quickblox.com/reference/push-notifications#push-notification-formats)
    message: "Your push notification message",
    // key: value
  },
  recipientsIds: [51,46], // users' IDs to deliver notification
  senderId: 45, // ID of the user who created the event
  type: QB.events.NOTIFICATION_EVENT_TYPE.ONE_SHOT,
};

QB.events
  .create(event)
  .then(function (data) {
    /* notification event(s) created successfully */
  })
  .catch(function (e) {
    /* handle error */
  });

Parameter

Required

Description

notificationType

yes

Type of notifications:

  • push - send push notification.
  • email - send email.

payload

yes

Push notification payload. Can contain a message (string) property and many other key-value pairs (string-string). Refer here for more details.

recipientsIds

no

Users' IDs to deliver notification.

senderId

yes

ID of the user who created the event.

type

yes

Types of the notification event.

  • one_shot - a one-time event (valid only if the date is not specified).
  • fixed_date - a one-time event that occurs at a specified date (valid only if the date is specified).
  • period_date - is a reusable event that occurs within a given period from the initial date (valid only if the period is specified).

name

no

The name of the event. Service information. Only for your own usage.

pushType

no

Channel for delivering notification. Used only if the notificationType is push, ignored in other cases.
If pushType is not present, the notification will be delivered to all possible devices/platforms for specified users.

date

no

The date when the event will be sent on. The date is required if the event type is fixed_date or period_date.
If the type is fixed_date, the date can not be in the past.

endDate

no

The date when the event is completed.
Must be not less than the date value.

period

no

The period of the event in seconds.
The period is required if event's type is period_date.

recipientsTagsAny

no

Recipients (users) must have at least one tag that is specified in the list.

recipientsTagsAll

no

Recipients (users) must have all tags specified in the list.

recipientsTagsExclude

no

Recipients (users) must not have tags specified in the list.

Receive push notifications

When any notification is opened or received the onNotification callback is called passing an object with the notification data.

// (required) Called when a remote is received or opened, or local notification is opened
onNotification: function (notification) {
  console.log("NOTIFICATION:", notification);

  // process the notification

  // (required) Called when a remote is received or opened, or local notification is opened
  notification.finish(PushNotificationIOS.FetchResult.NoData);
},

Let’s review the notification object below:

{
    foreground: false, // BOOLEAN: If the notification was received in foreground or not
    userInteraction: false, // BOOLEAN: If the notification was opened by the user from the notification area or not
    message: 'My Notification Message', // STRING: The notification message
    data: {}, // OBJECT: The push data
}

Unsubscribe from push notifications

You can unsubscribe from receiving push notification by passing a subscription ID.

QB.subscriptions
  .remove({ id: "your subscription Id" })
  .then(() => {
    /* removed successfully */
  })
  .catch(function (e) {
    /* handle error */
  });

CallKit and VoIP push notifications

If you need to display a native calling interface for incoming and outgoing calls, you should use CallKit on iOS. It lets you integrate your calling services with other call-related apps on the system. Use Apple CallKit guide to learn how to integrate a CallKit functionality.

For iOS, together with the CallKit, you also need to integrate VoIP push notifications.

QuickBlox supports iOS VoIP push notifications via the same API described above:

  1. For VoIP pushes, you need to generate a separated VoIP device token. See how to get it here.
  2. When the token is retrieved, you need to subscribe to VoIP push notifications by passing a push_channel: apns_voip in the subscription request.
  3. To send a VoIP push notification, use ios_voip: 1 parameter in a push payload of the create event request.

Updated 2 months ago


What's Next

Custom Objects

Push Notifications


Use this page to learn how to send push notifications to users when they are offline.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.