The QuickBlox Developer Hub

Welcome to the QuickBlox developer hub. You'll find comprehensive guides and documentation to help you start working with QuickBlox as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Video Calling

This is our new 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.

QuickBlox Video Calling API is built on top of WebRTC. It allows adding real-time video communication features into your app similar to Skype using API easily. The communication is happening between peers representing camera devices. There are two peer types:

  • Local peer is a device running the app right now.
  • Remote peer is an opponent device.

Establishing real-time video communication between two peers involves 3 phases:

  1. Signaling. At this phase, the peers’ local IPs and ports where they can be reached (ICE candidates) are exchanged as well as their media capabilities and session control messages.
  2. Discovery. At this phase, the public IPs and ports at which endpoints can be reached are discovered by STUN/TURN server.
  3. Establishing a connection. At this phase, the data are sent directly to each party of the communication process.

Let’s have a look at the series of pre-steps required before making the first call:

  1. Create a new app in the Dashboard.
  2. Install QuickBlox React Native SDK into your app.
  3. Setup permissions.
  4. Initialize QuickBlox SDK.
  5. Authorize user.
  6. Connect to Chat.

Pay attention

In order to start using Video Calling Module, you need to connect to QuickBlox Chat first. The signaling in the QuickBox WebRTC module is implemented over the XMPP protocol using QuickBlox Chat Module. So QuickBlox Chat Module is used as a signaling transport for Video Calling API.

Initialize WebRTC module

WebRTC module allows to process calls. When a call is initiated or received, WebRTC session is created. If the module is not initialized, it will not be able to create WebRTC session and process calls consequently. To initialize WebRTC module call init() method:

QB.webrtc
 .init()
 .then(function () { /* module is ready for calls processing */ })
 .catch(function (e) { /* handle error */ })

Note

If you miss calling init() method, a Promise.reject(error) is returned: The call service is not connected.

Setup video chat layouts

Set up two video chat layouts for remote and local video tracks to be able to show the video.

  • A remote video track represents a remote peer video stream from a remote camera app. Specify userId for the remote camera app of the remote peer.
  • A local video track represents a local peer video stream from a local camera app. Specify userId for the local camera app of the local peer.

WebRTCView subscribes to QB.webrtc.EVENT_TYPE.RECEIVED_VIDEO_TRACK event under the hood so you do not need to subscribe to it manually. Thus, once the SDK receives data that a remote video track was received, it creates the event of RECEIVED_VIDEO_TRACK type with userId and sessionId properties. If userId matches with the one in properties, the video starts playing.

import WebRTCView from 'quickblox-react-native-sdk/RTCView'

...

render() {
 return (
 ...
 <WebRTCView
 sessionId={session.id}
 style={styles.video} // add styles as necessary
 userId={userId} // your user's Id for local video or occupantId for remote
 />
 )
}
Parameters
Description

sessionId

WebRTC session identifier.

style

View styles.

userId

User identifier.

Once WebRTCView is set, SDK is ready to play the video. Thus:

  • You can subscribe to QB.webrtc.EVENT_TYPE.RECEIVED_VIDEO_TRACK and then add WebRTCViews.
    or
  • You can add WebRTCViews immediately and wait for the event of RECEIVED_VIDEO_TRACK type to come in.

Manage calls

To process events such as incoming call, you should subscribe to events first and assign an event handler. The event handler processes events that have type and payload properties.

  • type is a type of the event (for example, CALL, REJECT, etc).
  • payload is event data (for example, userId).
import {
 DeviceEventEmitter,
 NativeEventEmitter,
 Platform,
} from 'react-native'
import QB from 'quickblox-react-native-sdk'

function eventHandler (event) {
 const { type, payload } = event
 ...
}

const emitter = Platform.select({
 android: DeviceEventEmitter,
 ios: new NativeEventEmitter(QB.webrtc)
})

Object.keys(QB.webrtc.EVENT_TYPE).forEach(key => {
 emitter.addListener(QB.webrtc.EVENT_TYPE[key], eventHandler)
})
Event type
Description

CALL

Incoming call.

CALL_ACCEPT

Call is accepted.

REJECT

Call is rejected.

HANG_UP

Call is ended.

RECEIVED_VIDEO_TRACK

Remote video track is received.

PEER_CONNECTION_STATE_CHANGED

Peer connection state is changed.

Note

The example above shows assigning one handler for all module events but you can assign separate handlers for each event.

Initiate a call

To call users, you should create a WebRTC session and start calling using call() method.

import QB from 'quickblox-react-native-sdk'

...

const params = {
 opponentsIds: [12345, 12346],
 type: QB.webrtc.RTC_SESSION_TYPE.VIDEO
}

QB.webrtc
 .call(params)
 .then(function (session) { /* session created */ })
 .catch(function (e) { /* handle error */ })
Parameters
Description

opponentsIds

IDs of the opponents.

type

Call type: QB.webrtc.RTC_SESSION_TYPE.VIDEO, QB.webrtc.RTC_SESSION_TYPE.AUDIO.

Note

After this, your opponents will receive an event QB.webrtc.EVENT_TYPE.CALL.

Accept a call

To accept a call request, call accept() method and pass sessionId to tell SDK which session to accept.

const userInfo = {
 // custom data can be passed using this object
 // only [string]: string type supported
}

QB.webrtc
 .accept({ sessionId, userInfo })
 .then(function (session) { /* handle session */ })
 .catch(function (e) { /* handle error */ })
Parameters
Description

sessionId

WebRTC session identifier.

userInfo

(optional) Custom user data.

Reject a call

To reject a call request, use reject() method and pass sessionId parameter to tell SDK which WebRTC session to reject.

const userInfo = {
 // custom data can be passed using this object
 // only [string]: string type supported
}

QB.webrtc
 .reject({ sessionId, userInfo })
 .then(function (session) { /* handle session */ })
 .catch(function (e) { /* handle error */ })
Parameters
Description

sessionId

WebRTC session identifier.

userInfo

(optional) Custom user data.

End a call

To end a call, use hangUp() method and pass sessionId parameter to tell SDK which WebRTC session to end.

const userInfo = {
 // custom data can be passed using this object
 // only [string]: string type supported
}

QB.webrtc
 .hangUp({ sessionId, userInfo })
 .then(function (session) { /* handle session */ })
 .catch(function (e) { /* handle error */ })
Parameters
Description

sessionId

WebRTC session identifier.

userInfo

(optional) Custom user data.

Release resource

When you don't want to receive and process video calls, for example, when a user is logged out, you have to release QB.webrtc module. Call release() method that allows to unregister QB.webrtc module from receiving any video chat events and closes existing signaling channels.

QB.webrtc
 .release()
 .then(() => { /* released successfully */ })
 .catch(e => { /* handle error */ })

Note

release() method should be called when a video track is no more valid. If you don't call this method, you will get a memory leak.

Monitor peer connection(s) state

Peer connection state can change. For example, when a user is connected to the call, SDK receives PEER_CONNECTION_STATE_CHANGED event type with payload and type properties.

  • type is the name of the event (the one you've subscribed to).
  • payload contains properties describing which peer's status changed and to what value. Event payload properties should contain userId, sessionId and status properties.

To monitor the states of your peer connections (users) you need to create an event handler for QB.webrtc.EVENT_TYPE.PEER_CONNECTION_STATE_CHANGED event type.

function peerConnectionStateHandler (event) {
 const {
 type, // name of the event (the one you've subscribed to)
 payload, // event data
 } = event
 const {
 userId, // user with Id specified
 state, // has peer connection state specified (one of QB.webrtc.RTC_PEER_CONNECTION_STATE)
 session // current session
 } = payload
 // handle as necessary

emitter.addListener(
 QB.webrtc.EVENT_TYPE.PEER_CONNECTION_STATE_CHANGED,
 peerConnectionStateHandler
);

Once the event handler is created, you can detect the following event types:

//@QB/PEER_CONNECTION_STATE_CHANGED
{
 type: EventName
 payload: {
 state: NEW
 session: interface RTCSession
 userId: number
 }
}
OUTBOUND:
// PEER_CONNECTION_STATE_CHANGED
// Event name -
//@QB/PEER_CONNECTION_STATE_CHANGED
{
 type: EventName
 payload: {
 state: CONNECTED
 session: interface RTCSession
 userId: number
 }
}
OUTBOUND:
// PEER_CONNECTION_STATE_CHANGED
// Event name -
//@QB/PEER_CONNECTION_STATE_CHANGED
{
 type: EventName
 payload: {
 state: FAILED
 session: interface RTCSession
 userId: number
 }
}
OUTBOUND:
// PEER_CONNECTION_STATE_CHANGED
// Event name -
//@QB/PEER_CONNECTION_STATE_CHANGED
{
 type: EventName
 payload: {
 state: DISCONNECTED
 session: interface RTCSession
 userId: number
 }
}
OUTBOUND:
// PEER_CONNECTION_STATE_CHANGED
// Event name -
//@QB/PEER_CONNECTION_STATE_CHANGED
{
 type: EventName
 payload: {
 state: CLOSED
 session: interface RTCSession
 userId: number
 }
}
Connection state
Description

NEW

Gathering information to establish connection.

CONNECTED

A user is connected to a WebRTC session.

FAILED

A user failed to join a WebRTC session.

DISCONNECTED

A user is disconnected from a WebRTC session.

CLOSED

A WebRTC session is closed by the user.

Updated 10 days ago


What's Next

Advanced

Video Calling


Suggested Edits are limited on API Reference Pages

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