Setup

Follow the instructions below to ensure that QuickBlox Android SDK runs smoothly with your app.

Before you begin

Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.

Get application credentials

QuickBlox application includes everything that brings messaging right into your application - chat, video calling, users, push notifications, etc. To create a QuickBlox application, follow the steps below:

Register a new account following this link. Type in your email and password to sign in. You can also sign in with your Google or Github accounts.
Create the app clicking New app button.
Configure the app. Type in the information about your organization into corresponding fields and click Add button.
Go to Dashboard => YOUR_APP => Overview section and copy your Application ID, Authorization Key, Authorization Secret, and Account Key .

Requirements

The minimum requirements for QuickBlox Android SDK are:

Android 5.0 (API 21).
Android Studio.
Gradle 4.6.
Gradle plugin 2.5.1.

Install QuickBlox SDK into your app

To connect QuickBlox SDK to your app, import QuickBlox SDK dependencies via build.gradle file.
Include reference to SDK repository in your project-level build.gradle file at the root directory. Specify the URL of QuickBlox repository where the files are stored. Following this URL, gradle finds SDK artifacts.

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://github.com/QuickBlox/quickblox-android-sdk-releases/raw/master/"
        }
    }
}

When the artifacts are found in QuickBlox repository, they get imported to particular SDK modules in build.gradle project file. Add the following code lines to app-level build.gradle file.

dependencies {
    implementation "com.quickblox:quickblox-android-sdk-messages:3.9.2"
    implementation "com.quickblox:quickblox-android-sdk-chat:3.9.2"
    implementation "com.quickblox:quickblox-android-sdk-content:3.9.2"
    implementation "com.quickblox:quickblox-android-sdk-videochat-webrtc:3.9.2"
    implementation "com.quickblox:quickblox-android-sdk-conference:3.9.2"
    implementation "com.quickblox:quickblox-android-sdk-customobjects:3.9.2"
}

Parameters	Description
messages	Push Notifications module enables working with push notifications and alerts to users.
chat	Chat module allows creating dialogs and sending messages into these dialogs.
content	Content module enables file storage and creating chat attachments for your app.
webrtc	Video Calling module adds video and audio calling features to your app.
conference	Video Conference allows setting up a video conference between 10-12 people in your app.
customobjects	Custom Objects module provides flexibility to define any data structure you need for your app.

Add permissions

The video chat module requires a camera, microphone, and internet permissions. You should add permissions to receive push notifications to run foreground service as well. Make sure you add relevant permissions to your app manifest.

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="com.quickblox.sample.messages.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

To use a hardware camera with autofocus, you can add the following features to your app manifest.

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

The Chat app requires adding some specific permissions to access internet, storage, vibrate permissions, etc. Add the following permissions to your app manifest.

<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="com.quickblox.sample.chat.kotlin.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Initialize QuickBlox SDK

Initialize the framework with your application credentials. Pass Application ID, Authorization Key, Authorization Secret, and Account Key to the init() method.

🚧
Pay attention
You must initialize SDK before calling any methods through the SDK, except for the init() method. If you attempt to call a method without connecting, the error is returned.

static final String APPLICATION_ID = "41";
static final String AUTH_KEY = "lkjdueksu7392kj";
static final String AUTH_SECRET = "iiohfdija792hj";
static final String ACCOUNT_KEY = "sdjfnksnlk2bk1k34kb";

QBSettings.getInstance().init(getApplicationContext(), APPLICATION_ID, AUTH_KEY, AUTH_SECRET);
QBSettings.getInstance().setAccountKey(ACCOUNT_KEY);

private const val APPLICATION_ID = "41"
private const val AUTH_KEY = "lkjdueksu7392kj"
private const val AUTH_SECRET = "iiohfdija792hj"
private const val ACCOUNT_KEY = "sdjfnksnlk2bk1k34kb"

QBSettings.getInstance().init(applicationContext, APPLICATION_ID, AUTH_KEY, AUTH_SECRET)
QBSettings.getInstance().accountKey = ACCOUNT_KEY

Parameters	Description
APPLICATION_ID	Application identifier.
AUTH_KEY	Authentication key.
AUTH_SECRET	Authentication secret.
ACCOUNT_KEY	Account key. Required to get actual Chat and API endpoints for the right server.

Initialize with existing token

You can initialize the SDK with an existing QuickBlox token. It can be interesting in cases when you build a big system and you have the server side which generates QuickBlox tokens.

String token = "3Fjs1su8ery463gjd8hf";
QBSessionManager.getInstance().createActiveSession(token, tokenExpirationDate);

val token = "3Fjs1su8ery463gjd8hf"
QBSessionManager.getInstance().createActiveSession(token, tokenExpirationDate)

Custom endpoints

To connect QuickBlox SDK to the custom server, you should pass API_DOMAIN and CHAT_DOMAIN endpoints to the setEndpoints() method.

private static final String API_DOMAIN = "https://apicustomdomain.quickblox.com";
private static final String CHAT_DOMAIN = "chatcustomdomain.quickblox.com";
 
QBSettings.getInstance().setEndpoints(API_DOMAIN, CHAT_DOMAIN), ServiceZone.PRODUCTION);
QBSettings.getInstance().setZone(ServiceZone.PRODUCTION);

private const val API_DOMAIN = "https://apicustomdomain.quickblox.com"
private const val CHAT_DOMAIN = "chatcustomdomain.quickblox.com"

QBSettings.getInstance().setEndpoints(API_DOMAIN, CHAT_DOMAIN, ServiceZone.PRODUCTION)
QBSettings.getInstance().zone = ServiceZone.PRODUCTION

Parameters	Description
API_DOMAIN	API endpoint.
CHAT_DOMAIN	Chat endpoint.
ServiceZone.PRODUCTION	Connection service zone. The area where push notifications and messages can work.

📘
For Basic, Startup, and Growth plan users
- Make sure to set ACCOUNT_KEY to get all correct endpoints.
- Make sure to leave API_DOMAIN and CHAT_DOMAIN fields empty to provide a smooth migration between servers.

📘
For Enterprise plan users
- Contact our sales team to get API_DOMAIN and CHAT_DOMAIN.
- Configure API_DOMAIN and CHAT_DOMAIN after initialization. If you have your own API and Chat servers you should set these endpoints manually.

Enable logging

Logging functionality allows you to keep track of all events and activities while running your app. As a result, you can monitor the operation of the SDK and improve the debug efficiency. There are 3 logging use cases:

REST API logging is used to monitor REST API calls.
Chat logging is used to monitor chat issues.
WebRTC logging is used to gather issues with video.

REST API logging

Enable REST API calls debug console output using the code snippet below.

QBSettings.getInstance().setLogLevel(LogLevel.DEBUG);

QBSettings.getInstance().logLevel = LogLevel.DEBUG

Log levels	Description
LogLevel.NOTHING	Write nothing. Turn off logs.
LogLevel.DEBUG	Enable logs (default value).

Chat logging

Use the method below to enable a detailed XMPP logging in the console output. true is enabled, false is disabled. Default: false.

QBChatService.setDebugEnabled(true);

QBChatService.setDebugEnabled(true)

WebRTC logging

To enable WebRTC logging, use the setDebugEnabled() method. true is enabled, false is disabled. Default: true.

QBRTCConfig.setDebugEnabled(true);

QBRTCConfig.setDebugEnabled(true)

Autoreconnect to Chat

QuickBlox Chat runs over XMPP protocol. To receive messages in a real-time mode, the application should be connected to the Chat over XMPP protocol. To enable autoreconnection to Chat, call the setReconnectionAllowed() method and pass true.

QBChatService.getInstance().setReconnectionAllowed(true)

QBChatService.getInstance().isReconnectionAllowed = true

📘
Note
By default, autoreconnection functionality is enabled. Set autoreconnection before calling the QBChatService.getInstance().login() method so it could be applied in a current chat.

Message carbons

Message carbons functionality allows for multi-device support. Thus, all user messages get copied to all their devices so they could keep up with the current state of the conversation. For example, a User A has phone running conversations and desktop running conversations. User B has desktop running conversations. When User B sends a message to User A, the message shows on both the desktop and phone of User A.

Enable message carbons

try {
   QBChatService.getInstance().enableCarbons();
} catch (XMPPException e) {
   e.printStackTrace();
} catch (SmackException e) {
   e.printStackTrace();
}

try {
   QBChatService.getInstance().enableCarbons()
} catch (e: XMPPException) {
   e.printStackTrace()
} catch (e: SmackException) {
   e.printStackTrace()
}

Disable message carbons

try {
   QBChatService.getInstance().disableCarbons();
} catch (XMPPException e) {
   e.printStackTrace();
} catch (SmackException e) {
   e.printStackTrace();
}

try {
   QBChatService.getInstance().disableCarbons()
} catch (e: XMPPException) {
   e.printStackTrace()
} catch (e: SmackException) {
   e.printStackTrace()
}

📘
Note
By default, message carbons functionality is disabled.

📘
Note
Since message carbons functionality works over XMPP connection, make sure to enable it after the QBChatService.getInstance().login() method is called.

Stream management

Stream management has two important features Stanza Acknowledgements and Stream Resumption:

Stanza Acknowledgements is the ability to know if a stanza or series of stanzas has been received by one's peer. In other words, a reply is requested on every sent message. If the reply is received, the message is considered as delivered.
Stream Resumption is the ability to quickly resume a stream that has been terminated. So once a connection is re-established, Stream Resumption is executed. By matching the sequence numbers assigned to each Stanza Acknowledgement a server and client can verify which messages are missing and request to resend missing messages.

QBChatService.getInstance().setUseStreamManagement(true);

QBChatService.getInstance().setUseStreamManagement(true)

📘
Note
By default, stream management functionality is disabled.

📘
Note
You should enable Stream Management before you do the login() because the Stream Management is initialized while Chat login is performed.
The Stream Management defines an extension for active management of a stream between a client and server, including features for stanza acknowledgments.

Configure media settings

You can use QBRTCMediaConfig class instance to configure a various list of media settings like video/audio codecs, bitrate, fps, etc.

QBRTCMediaConfig.setAudioCodec(QBRTCMediaConfig.AudioCodec.ISAC);
QBRTCMediaConfig.setAudioCodec(QBRTCMediaConfig.AudioCodec.OPUS);

QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.H264);
QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.VP8);
QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.VP9);

QBRTCMediaConfig.setAudioStartBitrate(audioStartBitrate);

QBRTCMediaConfig.setVideoStartBitrate(videoStartBitrate);

QBRTCMediaConfig.setVideoWidth(videoWidth);
QBRTCMediaConfig.setVideoHeight(videoHeight);

// Enable Hardware Acceleration if device supports it
QBRTCMediaConfig.setVideoHWAcceleration(true);

// Set frames-per-second in transmitting video stream
QBRTCMediaConfig.setVideoFps(videoFPS);

// Enable built-in AEC if device supports it
QBRTCMediaConfig.setUseBuildInAEC(true);

// Enable OpenSL ES audio if device supports it
QBRTCMediaConfig.setUseOpenSLES(true);

QBRTCMediaConfig.setAudioProcessingEnabled(true);

QBRTCMediaConfig.setAudioCodec(QBRTCMediaConfig.AudioCodec.ISAC)
QBRTCMediaConfig.setAudioCodec(QBRTCMediaConfig.AudioCodec.OPUS)

QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.H264)
QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.VP8)
QBRTCMediaConfig.setVideoCodec(QBRTCMediaConfig.VideoCodec.VP9)

QBRTCMediaConfig.setAudioStartBitrate(audioStartBitrate)

QBRTCMediaConfig.setVideoStartBitrate(videoStartBitrate)

QBRTCMediaConfig.setVideoWidth(videoWidth)
QBRTCMediaConfig.setVideoHeight(videoHeight)

// Enable Hardware Acceleration if device supports it
QBRTCMediaConfig.setVideoHWAcceleration(true)

// Set frames-per-second in transmitting video stream
QBRTCMediaConfig.setVideoFps(videoFPS)

// Enable built-in AEC if device supports it
QBRTCMediaConfig.setUseBuildInAEC(true)

// Enable OpenSL ES audio if device supports it
QBRTCMediaConfig.setUseOpenSLES(true)

QBRTCMediaConfig.setAudioProcessingEnabled(true)

📘
Note
Make sure to setup media settings before initiating a call.

Synchronous and Asynchronous performers

You can use different performers perform() or performAsync(). Please note that the QBUsers.getUser() method is used there as an example. You can use these performers in all cases where performers are available. In a synchronous way, you should handle QBResponseException.

try {
    QBUsers.getUser(qbUser.getId()).perform();
} catch (QBResponseException e) {
      // handling exception
}

try {
    QBUsers.getUser(qbUser.id).perform()
} catch (e: QBResponseException) {
      // handling exception
}

In an asynchronous way, you can make further logic according to the server response.

QBUsers.getUser(qbUser.getId()).performAsync(new QBEntityCallback<QBUser>() {
    @Override
    public void onSuccess(QBUser qbUser, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});

QBUsers.getUser(qbUser.id).performAsync(object : QBEntityCallback<QBUser> {
    override fun onSuccess(qbUser: QBUser?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

Custom ICE servers

You can customize a list of ICE servers. By default, WebRTC module will use internal ICE servers that are usually enough, but you can always set your own. WebRTC engine will choose the TURN relay with the lowest round-trip time. Thus, setting multiple TURN servers allows your application to scale-up in terms of bandwidth and number of users.

// Set custom ICE servers up. Use it in case you want set YOUR OWN servers instead of defaults

List<PeerConnection.IceServer> iceServerList = new LinkedList<>();

iceServerList.add(new PeerConnection.IceServer("stun:stun.randomserver.example","", ""));
iceServerList.add(new PeerConnection.IceServer("stun:stun.randomserver.example","stun_login", "hdccn97ba2d56d72i426eb9875bya7yte8"));
iceServerList.add(new PeerConnection.IceServer("turn:turn.randomserver.example:6789?transport=udp","turn_login", "78kkb67m2f45h1e27ub9886gt70109"));
iceServerList.add(new PeerConnection.IceServer("turn:turn.randomserver.example:6789?transport=tcp","turn_login", "78kkb67m2f45h1e27ub9886gt70109"))
        
QBRTCConfig.setIceServerList(iceServerList);

// Set custom ICE servers up. Use it in case you want set YOUR OWN servers instead of defaults

val iceServerList = LinkedList<PeerConnection.IceServer>()

iceServerList.add(PeerConnection.IceServer("stun:stun.randomserver.example", "", ""))
iceServerList.add(PeerConnection.IceServer("stun:turn.randomserver.example", "stun_login", "hdccn97ba2d56d72i426eb9875bya7yte8"))
iceServerList.add(PeerConnection.IceServer("turn:turn.randomserver.example:6789?transport=udp", "turn_login", "78kkb67m2f45h1e27ub9886gt70109"))
iceServerList.add(PeerConnection.IceServer("turn:turn.randomserver.example:6789?transport=tcp", "turn_login", "78kkb67m2f45h1e27ub9886gt70109"))

QBRTCConfig.setIceServerList(iceServerList)

QuickBlox Docs

QuickBlox Documentation

Before you begin

Get application credentials

Requirements

Install QuickBlox SDK into your app

Add permissions

Initialize QuickBlox SDK

🚧
Pay attention

Initialize with existing token

Custom endpoints

📘
For Basic, Startup, and Growth plan users

📘
For Enterprise plan users

Enable logging

Autoreconnect to Chat

📘
Note

Message carbons

📘
Note

📘
Note

Stream management

📘
Note

📘
Note

Configure media settings

📘
Note

Synchronous and Asynchronous performers

Custom ICE servers

What's Next

Setup

Suggested Edits are limited on API Reference Pages

Before you begin

Get application credentials

Requirements

Install QuickBlox SDK into your app

Add permissions

Initialize QuickBlox SDK

🚧Pay attention

Initialize with existing token

Custom endpoints

📘For Basic, Startup, and Growth plan users

📘For Enterprise plan users

Enable logging

Autoreconnect to Chat

📘Note

Message carbons

📘Note

📘Note

Stream management

📘Note

📘Note

Configure media settings

📘Note

Synchronous and Asynchronous performers

Custom ICE servers

What's Next

🚧
Pay attention

📘
For Basic, Startup, and Growth plan users

📘
For Enterprise plan users

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note