Web SDK
Voximplant push notifications for web applications rely on the Firebase Cloud Messaging (FCM) platform and are implemented as "data messages". Using notifications, a client can be informed about incoming calls when an app tab is inactive or closed (in this case, the app should be started before a call arrives).
You can clone a sample application with the coding needed to handle push notifications from our GitHub repository. This tutorial explains that code and outlines additional steps that should be performed to have a working solution for push notifications in a web application.
Push notifications are available in browsers that support Push API and in pages served over HTTPS. You can check a list of supported browsers here.
Create a Firebase Project
To enable push notifications, you need to create a Firebase project first:
- Sign into Firebase using your Google account.
- In the Firebase console, click Add project, then enter a new Project name or select an existing project.
Connect Firebase to a Voximplant Application
Configure web credentials with FCM and add them to your Voximplant application:
Generate a new key pair through the Firebase console: open Settings in the Firebase console, select the Cloud Messaging tab, scroll to the Web configuration section, and click Generate Key Pair.
Open the Applications section in the Voximplant control panel, click your target application and switch to the Push Certificates tab.
Click Add Certificate, then fill and submit the form:
a. Select GOOGLE in the Platform field.
b. Copy and paste your Sender ID from the Firebase console.
c. Copy and paste your Server key from the Firebase console.
d. Click Add.
Send Push Notifications to your Web Application
To configure the Voximplant cloud to send push notifications, add a push service to the JavaScript scenario that initiates a call:
This code will make VoxEngine automatically manage timeouts so that they won't be configurable. VoxEngine will wait for a user login event for 20 seconds after a push notification is sent. If the user doesn’t log in within this time, the call is considered failed. If the user logs in or is already logged in, he/she will receive an incoming call event and have the same timeframe to answer the call.
Then, use the callUser or forwardCallToUser method in the scenario – push notifications will be sent automatically to the app so that it can wake up, connect to Voximplant, log in, and accept the call.
The following sections explain the code from our push notifications demo app. You may clone it from this repo, launch the code and play with it, or continue reading if you want a more thorough step-by-step explanation.
Receive and Display Push Notifications
To receive push notifications, you must define the Firebase messaging service worker in a file called firebase-messaging-sw.js
that is located in the root of your app domain. Or you can specify another name of the service worker with useServiceWorker.
Here is the code for your service worker file:
YOUR_SENDER_ID is a Sender ID from the Cloud Messaging Settings of the Firebase console.
Use the setBackgroundMessageHandler
method to handle push notifications when your app is in the background and to show Voximplant notifications. You can also customize the data that you want to display to users.
Open or focus your web app page when a notification is clicked:
Add Firebase to your Web Application
Add a web app manifest that specifies the gcm_sender_id
, a hard-coded value indicating that FCM is authorized to send messages to this app. If your app already has a manifest.json
configuration file, make sure to add the browser sender ID exactly as it is shown below (do not change the value):
Create an index.html
file for this demo app. Copy and paste this markup into it:
Add the core Firebase and Firebase Messaging SDKs to your project by adding the script
tag to the bottom of the body
tag in your index.html
:
In a real-world app, you may also add them by using a packet manager:
yarn add @firebase/app
yarn add @firebase/messaging
Add the Voximplant Web SDK after the Firebase scripts:
Add a main.js
file to your push notifications demo app and link it to your index.html file
:
Switch to the General tab in Settings of the Firebase console, scroll to Your apps, and add a new web app – Firebase will provide you with your web app's Firebase configuration. Copy and paste a firebaseConfig
variable into the main.js
file before you use any Firebase services:
Initialize Firebase:
Handle Push Notifications in your Web Application
Now, let’s add some logic that deals with messages from a service worker to main.js
. We’ll use a demo app to outline all necessary steps, but it’s up to you to implement them into your real-world app with all error checks and other necessities.
After initializing Firebase, get the Firebase Messaging and Voximplant SDKs instances:
Add variables to check if you can process a call from a push notification and to store a call in case you need to wait for the user to log in:
Add a handler for a message event from a service worker:
The Web SDK handlePushNotification method notifies the Voximplant cloud that a push notification was successfully received and that a user is ready to answer a call.
Before processing any calls or messages from push notifications, you have to do the following:
- Initialize Web SDK.
- Connect to the Voximplant cloud.
- Log into the Voximplant cloud:
This order is crucial. Don’t worry about the logIntoVoxCloud
, handleLoginError
and runApp
functions for now. We’ll get to them later in this tutorial.
Logging and auto logging into the Voximplant cloud
To log your user in automatically when a push notification arrives, you need to use stored credentials. Storing the password is not secure, so use the loginWithToken method that employs the "token" approach. Token passed as a second parameter is accessToken which is returned after the first login via the login method. That means you can use push notifications only after the first user login. Store all LoginTokens in localStorage.
If login is not successful, proceed with the response error. This may occur because accessToken has expired (701 error code). If so, try to use refreshToken instead. If that has also expired, use the basic login via password.
Enabling push notifications for a user
Most of the interactions with the Voximplant cloud are available only after login, including enabling and processing push notifications so we’ll place this logic in the runApp
function.
Check and receive an incoming call if it’s an automatic login after receiving a push notification:
After each successful login to the Voximplant cloud, the application should add your FCM key credential to allow it to send message requests to different push services. You will need your public key generated previously in the Firebase console.
And you should get a push notification token from Firebase and pass it to the Voximplant Cloud using the registerForPushNotifications method.
Finally, let’s handle incoming calls by subscribing to the IncomingCall event.