Android

Ask tech team
From QuickBlox Developers (API docs, code samples, SDK)
Jump to: navigation, search

Contents

Download Android SDK

Quickblox Android SDK, version 2.6.1

Code samples

How to run

To run samples on Android Studio go to menu File - Import Project. Select path to sample, select Use default gradle wrapper(recommended) and click OK.

Code samples

Learn how to enable Push Notifications, create a Chat room, authenticate users via Facebook, show users' locations and POIs, store and retrieve files from the cloud - these code samples are really simple so that even beginner developers can understand:

Title APIs used Description
Simple Android Chat code sample Chat, Users The Chat sample connects and socializes your users with the chat module. Features include: Peer to Peer Chat; Group chat; Location based chat; Push notification for offline users.


Simple Android WebRTC (VideoChat) code sample Chat, VideoChat The VideoChat code sample allows you to easily add video calling and audio calling features into your iOS app. Enable a video call function similar to FaceTime or Skype using this code sample as a basis.


User List Android.png Video Call Android.png Incoming Call Android.png

Simple Android Location code sample Location The Location sample connects app users with each other and their environment. Using GPS locations, map integrations and local data, end users can literally 'see' each other on the map and engage with other users


Simple Android Push Notifications code sample Messages, Users Push notifications to your user base — even when your app is not running! This sample enables you to send notifications and alerts to users at any time through an API or easy-to-use admin panel. You can filter who you send messages to through additional parameters.


Simple android Custom Objects (key value data store) code sample Сustom Objects This Custom Objects sample allows to create any server side data structure, use it as you want, create any logic and a lot of others custom features.


Simple android Users authentication code sample Users The Users sample helps you manage and retain your user base across all platforms. It includes a simple authentication process with Single Sign-On and integration across all popular platforms.


Simple android content storage and update code sample Content The Content sample allows send, stream, store, share and save content, update your app's content without having to republish.



How to: add SDK to IDE and connect to the cloud

To get the QuickBlox SDK project running you will need Android Studio and Maven installed.

The repository https://github.com/QuickBlox/quickblox-android-sdk-releases contains binary distributions of QuickBlox Android SDK and an instruction how to connect SDK to your project. Check it out.


To add the SDK to your app in Android Studio follow this steps:

Include reference to sdk repository in your build.gradle file at the app level (top level) :

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

Include dependencies to particular sdk-modules in build.gradle project file:

dependencies {
   compile "com.quickblox:quickblox-android-sdk-core:2.5.1@aar"	
   compile("com.quickblox:quickblox-android-sdk-chat:2.5.1@aar") {
        transitive=true
   }
}

Make sure you add "transitive" flag in chat module dependency to include all necessary libraries.

Starting from sdk 2.6.1 to add dependency on particular module just add:

dependencies {
   compile("com.quickblox:quickblox-android-sdk-chat:2.6.1")
}

Sdk module automatically includes transitive module dependencies.

Proguard and quickblox sdk

To configure proguard with quickblox modules refer to tutorial: https://github.com/QuickBlox/quickblox-android-sdk/blob/master/README.md#customize-proguard-in-android-studio

Getting started

Android SDK is really simple to use. In just a few minutes you can power up your mobile app with huge amount of awesome communication features & data services.

The common way to interact with QuickBlox can be presented with the following sequence of actions:

  1. Initialize framework with application credentials
  2. Create session
  3. Login with existing user or register new one
  4. Perform actions with QuickBlox communication services and any data entities (users, locations, files, custom objects, pushes etc.)

Initialize framework

static final String APP_ID = "961";
static final String AUTH_KEY = "PBZxXW3WgGZtFZv";
static final String AUTH_SECRET = "vvHjRbVFF6mmeyJ";
static final String ACCOUNT_KEY = "961";
//
QBSettings.getInstance().init(getApplicationContext(), APP_ID, AUTH_KEY, AUTH_SECRET);
QBSettings.getInstance().setAccountKey(ACCOUNT_KEY);

If you have an account on quickblox shared server (api.quickblox.com) or moved from shared server to your own, you can set Account Key. Account Key provides mechanism to automatically synchronize all the correct endpoints (API, Chat, etc) to your server. For more information refer to http://quickblox.com/developers/Overview#Endpoints

Pay attention, if you don't have an account on shared server you should set all endpoints manually. Refer to https://quickblox.com/developers/Android#Endpoints_customization


It's also possible to initialize the SDK with an existent QuickBlox token. It can be interesting in cases when you build a big system and you have a custom server side which generates QuickBlox tokens:

try {
    QBAuth.createFromExistentToken("31ed199120fb998dc472aea785a1825809ad5c04", date);
} catch (BaseServiceException e) {
    e.printStackTrace();
}

or you can save your token and expiration date in a secure storage for reuse in future if it's valid and bypass the session creation request:

String token = BaseService.getBaseService().getToken();
Date expirationDate = BaseService.getBaseService().getTokenExpirationDate();
// save to secure storage when your application goes offline or to the background
 
...
 
// recreate session on next start app
Date currentDate = new Date();
Calendar cal = Calendar.getInstance();
cal.setTime(currentDate);
cal.add(Calendar.HOUR, 2);
Date twoHoursAfter = cal.getTime();
 
if(expirationDate.before(twoHoursAfter)){
    try {
        QBAuth.createFromExistentToken(token, expirationDate);
    } catch (BaseServiceException e) {
       e.printStackTrace();
    }
}else{
    // create a session
}

A couple of words about Authentication and Authorization

To be able to use QuickBlox API you have to create a session.

There are 2 types of session:

  • Application session. It provides only READ access to data.
  • User session. It provides CRUD(Create, Read, Update, Delete) access to data.


To create an application session use this code:

QBAuth.createSession(new QBEntityCallback<QBSession>() {
    @Override
    public void onSuccess(QBSession session, Bundle params) {
        // success
    }
 
    @Override
    public void onError(QBResponseException error) {
        // errors
    }
});

With an Application session you can READ any data you need and only have to do one Create operation - User Sign Up:

// Register new user
final QBUser user = new QBUser("userlogin", "userpassword");
 
QBUsers.signUp(user, new QBEntityCallback<QBUser>() {
    @Override
    public void onSuccess(QBUser user, Bundle args) {
        // success
    }
 
    @Override
    public void onError(QBResponseException error) {
       // error
    }
});

To update an Application session to a User session you have to login to QuickBlox:

// Login
QBUsers.signIn(user, new QBEntityCallback<QBUser>() {
    @Override
    public void onSuccess(QBUser user, Bundle args) {
        // success
    }
 
    @Override
    public void onError(QBResponseException error) {
        // error
    }
});

You can create a User session in single query as well:

QBAuth.createSession(new QBUser("garrysantos", "garrysantospass"), new QBEntityCallback<QBSession>() {
    @Override
    public void onSuccess(QBSession session, Bundle params) {
        // success
    }
 
    @Override
    public void onError(QBResponseException error) {
        // errors
    }
});

A session will remain valid for 2 hours after the last request to QuickBlox was performed. To check a session's expiration date use this next snippet of code:

try {
    Date expirationDate =  BaseService.getBaseService().getTokenExpirationDate();
}catch (BaseServiceException e) {
    e.printStackTrace();
}

In order to use real time features you have to be logged in to Chat:

// initialize Chat service
QBChatService chatService = QBChatService.getInstance();
 
final QBUser user = new QBUser("indianajones", "indianapassword");
 
chatService.login(qbUser, new QBEntityCallback() {
    @Override
    public void onSuccess() {
        // success
    }
 
    @Override
    public void onError(QBResponseException error) {
        // errror
    }
});

Sync vs Async

It's possible to perform any request asynchronously and synchronously.

We do recommend to run asynchronously requests on UI thread and run synchronously on your own background thread.

For example, let's sign in a user.

Asynchronous way:

QBUser user = new QBUser();
user.setLogin("userlogin");
user.setPassword("userpassword");
 
QBUsers.signIn(user, new QBEntityCallback<QBUser>() {
    @Override
    public void onSuccess(QBUser user, Bundle params) {
 
    }
 
    @Override
    public void onError(QBResponseException error) {
 
    }
});

Synchronous way:

QBUser user = new QBUser();
user.setLogin("userlogin");
user.setPassword("userpassword");
 
QBUser userResult = null;
try {
    userResult =  QBUsers.signIn(user);
} catch (QBResponseException e) {
 
}
 
if(userResult != null){
    // success
}

If you would like to run asynchronously request on none UI thread you should create a thread and connect a handler to it:

public class MyWorkerThread extends HandlerThread {
 
    private Handler mWorkerHandler;
 
    public MyWorkerThread(String name) {
        super(name);
    }
 
    public void postTask(Runnable task){
        mWorkerHandler.post(task);
    }
 
    public void prepareHandler(){
        mWorkerHandler = new Handler(getLooper());
    }
}
 
...
 
MyWorkerThread mWorkerThread = new MyWorkerThread("myWorkerThread");
 
Runnable task = new Runnable() {
    @Override
    public void run() {
 
        QBUser user = new QBUser();
        user.setLogin("userlogin");
        user.setPassword("userpassword");
 
        QBUsers.signIn(user, new QBEntityCallback<QBUser>() {
            @Override
            public void onSuccess(QBUser user, Bundle params) {
 
            }
 
            @Override
            public void onError(QBResponseException error) {
 
            }
        });
    }
};
 
 
mWorkerThread.start();
mWorkerThread.prepareHandler();
mWorkerThread.postTask(task);
 
...
// mWorkerThread.quit();

More info you can find here.

Endpoints customization

You may need to configure custom endpoints to point your application to a custom backend. Here is how to do via QBSettings:

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

Read on: Android SDK documentation (Javadoc)

Full reference on classes and interfaces used in QuickBlox Android SDK:
Quickblox Android SDK framework documentation

Framework changelog

v2.6.1 — July 22, 2016

  • WebRTC calls functionality:
    • Improved WebRTC calls performance and simplified interface.
    • added calling all callbacks on UI main thread.
    • added features - settings fps, changing frame resolution during call, switching between hardware/software AEC, ability to disable audio processing: AEC, noise suppression etc, ability to enable/disable using OpenSL ES for audio playback.
    • added QBRTCSurfaceView to render video frames with ability to use and overlapping multiple views on a screen layout.
    • small bug fixes.
  • Chat functionality:
    • Added ability to enable/disable TLS mechanism in chat via QBChatService.ConfigurationBuilder.
    • Added ability to set custom SSL context in chat via QBChatService.ConfigurationBuilder.
  • Content functionality:
    • Fixed SignatureDoesNotMatch exception while uploading file
    • Adopt file upload method to work with different files storages.
  • Others:
    • Reworked building sdk modules and setup sdk dependencies to your project via gradle.


v2.6 — June 14, 2016

  • WebRTC calls functionality:
    • Added ability to retrieve peer connection statistics during call. Added QBRTCStatsReportCallback to QBRTCSession class.
  • Chat functionality:
    • Updated equals & hashcode methods in QBDialog model to be able to store and search it in Collections.
    • Added QBMessageUpdateBuilder to simplify updating message.
    • Added QBDialogRequestBuilder to simplify updating dialog.
    • Added QBMessageGetBuilder to simplify requesting messages by filters.
    • Added chat API requests: force deletion dialog, force deletion message, delete many dialogs in single query, update chat message.
    • Added returning joinFailed callback when user is trying to join none existent room.
    • Add ability to manage chat socket settings – keep alive, socket timeout, default socket factory. Added ConfigurationBuilder class to QBChatService class.
    • Fixed carbon for system messages.
  • Custom objects functionality:
    • Added request for aggregation functions - QBCustomObjects.getAggregationObjects().
  • Content module functionality:
    • Fixed invoking onProgressUpdate method for QBProgressCallback on thread in which request to upload/download file was started. If request is started from android UIThread, QBProgressCallback will be called on UIThread although request itself will be running in background thread.
    • Fixed passing correct progress to QBProgressCallback in downloading requests.
  • Core module:
    • Fixed NPE while parsing request's url with malformed filters.


v2.5.2 — April 15, 2016

  • WebRTC calls functionality:
    • Improved WebRTC calls stability.
    • Fixed major bugs and crashes.
    • hangUp and reject methods now send parameter "userInfo" to opponent in appropriately callbacks onReceiveHangUpFromUser and onCallRejectByUser.
    • QBRTCSession doesn't manage audio settings anymore. Added AppRTCAudioManager class to manage audio settings manually. Refer to http://quickblox.com/developers/Sample-webrtc-android#Manage_Audio_settings
    • Reworked video calls. Now If you creates video call but device doesn't have camera at all or hasn't requested "CAMERA" permission, device just will not send video track to opponent, but can receive video track from opponent.
  • Chat functionality:
    • Added automatically send presence feature to keep connection active. Refer to method startAutoSendPresence and stopAutoSendPresence in QBChatService.
    • fixed issue with wrong order of received messages
    • Added query to Retrieve total unread messages count for dialogs: QBChatService.getTotalUnreadMessagesCount
    • added the updated_at field into 'toString' for QBDialog class
    • Fixed "NPE" in asynchronous join method with null callback in group chat.
    • Fixed "OutOfBoundsException" when retrieving "Location" custom data from QBDialog
    • Fixed issue with setting chat resource according to device unique id. It can be useful if you login under the same account on different devices.
  • Others:
    • Fixed QBUsers.updateUser query. To delete tags from user put empty StringifyArrayList to QBUser.setTags method. If you put null then tags won't be changed.


v2.5.1 — March 3, 2016

  • Fixed NullPointerException issue in video-chat module on "accept" event in QBRTCSession class in some unusual cases.


v2.5 — Feb 5, 2016

  • Automatic endpoints retrieval. This is for smooth migration between plans.
  • Updated the way SDK is initialized:
QBSettings.getInstance().init(getApplicationContext(), APP_ID, AUTH_KEY, AUTH_SECRET);
QBSettings.getInstance().setAccountKey(ACCOUNT_KEY);
  • Updated the way the SDK is pointed to custom server:
QBSettings.getInstance().setEndpoints(API_DOMAIN, CHAT_DOMAIN), ServiceZone.PRODUCTION);
QBSettings.getInstance().setZone(ServiceZone.PRODUCTION);
  • Chat initialisation simplification, Methods QBChatService.isInitialized() and QBChatService.init(context) are deprecated now.
  • Updated the error callback:

QBEntityCallback.onError(List<String> errors) -> QBEntityCallback.onError(QBResponseException exception)

  • All 3rd party libs are integrated now into SDK.
  • Chat Stream Management (XEP-0198), 'sent' status in chat, added QBMessageSentListener interface.
  • Removed deprecated methods of 1.x API. 'Result' class is removed.
  • Maven/AAR distribution support
  • Renamed QBMessages to QBPushNotifications
  • Simplified push subscription API.

Deprecated QBPushNotifications.subscribeToPushNotificationsTask(registrationID, deviceId, QBEnvironment.DEVELOPMENT) and replaced with QBPushNotifications.createSubscription(subscription)

  • Content: access to public/private urls:

QBFile.publicUrl, QBFile.publicUrlForID, QBFile.privateUrl, QBFile.publicUrlForID

  • fixed QBRequestUpdateBuilder 'pullAll' and added 'pushAll' operators
  • renamed all setters and getters to the correct meaning in QBLimitedRequestBuilder
  • QBEntityCallback cleanup, QBEntityCallbackImpl is deprecated
  • Migrate to 'HttpURLConnection' instead of 'Apache Client' library.
  • Added method to get dialogs' count: QBChatService.getChatDialogsCount()
  • TransferProtocol enum is removed.
  • Twitter digits integration
  • fixed QBChatMessage.dateSent field cross platform issue
  • added an ability to send Apple specific pushes
  • QBChatMessage: put senderID to readIds and deliveredIds
  • access to total_entries in request chat dialogs response
  • added QBDialogCustomData class to work with chat dialog's custom data
  • Fixed an issue with org.apache.http.conn.HttpHostConnectException exception when using REST API and don't have an active Internet connection.
  • Removed Places API.


v2.4 — Nov 27, 2015


v2.3.3 — Nov 5, 2015

  • Updated the url formation logic in QBFile.getPublicUrl method.


v2.3.2 — Oct 26, 2015

  • Features:
    • System Notifications API.
    • Ability to set 'QBChatMessage.senderId'. Useful to send 'read' statuses in a case you don't have the origin 'QBChatMessage' object.
  • Bug fixes:
    • Fixed the 'NullPointerException' in 'QBJsonErrorParser'
    • Fixed a crash when trying to delete one custom object via 'QBCustomObjects.deleteObjects'
    • Fixed an issue with embedded arrays in CustomObjects fields.
    • Fixed an issue where it wasn't possible to exchange messages between Android SDK and desktop XMPP clients like Adium or Psi
    • Fixed an issue with QBRTCClient 'rejectCall' method where a parameter 'userInfo' was never used.
    • Fixed an issue with context in 'QBRTCClient'
    • Content: don't print a file to log when download it.
    • Content: fixed the OutOfMemory issue with big files upload.
    • Content: fixed an issue with 'QBProgressCallback' when it was producing the same progress value many times.
    • Updated 'QBFile.lastReadAccessTime' field's type to 'Date'.
    • Updated 'QBFile.getPublicUrl' method output to new format.
  • Other:
    • QBFile: removed useless properties 'referencesCount' and 'lifeTime'


v2.3.1 — Sep 14, 2015

  • Fixed an issue with camera with WebRTC video calling (r9806)
  • QBGroupChat now throws IllegalStateException if a user isn't connected to chat
  • Added a getter QBChatMessage.isDelayed to detect if the message was sent to user when he was offline.


v2.3 — Sep 6, 2015

  • WebRTC video calling:
    • Fixed the NullPointerException issue
    • Set the default values of QBRTCConfig.dialingTimeInterval to 5 and QBRTCConfig.answerTimeInterval to 60
    • Updated webrtc lib to r9813
  • Chat
    • Added the 'mobile optimisations' - a way to save the battery life while be in inactive state.
    • Added the ping manager
    • Added the deliveredIds field to QBChatMessage model
    • Reviewed the delivered/read statuses management, added QBMessageStatusListener and QBMessageStatusesManager classes.
    • Added 'is typing' listener for group chat
    • Added the getDialogId to QBPrivateChat and QBGroupChat models
  • Content
    • Fixed the file upload issue on some Android devices



v2.2.6 — Jul 13, 2015

  • WebRTC - the background calls lifecycle is simplified. From this point it is unnecessary to implement RTCSignallingMessageProcessorCallback interface to process calls in background. More over it will be removed from public access in next SDK version. Also from this SDK version you mustn’t call prepareToProcessCalls(Context context) method in Activity, now you can call this method together with other RTCClient set up methods in any Android component.


v2.2.5 — Jun 19, 2015

  • Updated WebRTC SDK (r9417) + bug fixes.


v2.2.4 — Jun 7, 2015

  • Fixed an issue with download file request with progress callback.


v2.2.3 — May 8, 2015

  • Fixed an issue with WebRTC where it wasn't possible to start new call after previous call.


v2.2.2 — April 24, 2015

  • Fixed a crash while uploading file on QuickBlox server when devices looses Internet connection.
  • Fixed an unexpected signature issue when create a session with special characters in a user's login or password.
  • Fixed an issue with QBChatMessage.isMarkable() where it returned always false.
  • Method QBChatService.getInstance().getPrivacyListsManager().setPrivacyList now throws IllegalArgumentException where QBPrivacyList instance is null or QBPrivacyList.items is null or QBPrivacyList.items.size is 0


v2.2.1 — April 3, 2015

  • Group chat blocks
  • Fixed the NPE issue when use an old way to create group chat rooms


v2.2 — March 30, 2015

  • Updated WebRTC API for Video calling


v2.1.1 — March 17, 2015

  • Added all filter to QBRequestGetBuilder
  • QBUsers.getUsers now returns a param Consts.TOTAL_PAGES in a response bundle
  • Fixed an issue with exception in QBParticipantListener interface
  • Fixed an issue with NullPointerException in QBGroupChat class
  • Added an ability to set fileId as -1 to QBUser to clear it


v2.1 — January 19, 2015

  • Features:
    • Added QBParticipantListener that will be notified of any new Presence packets sent to the group chat.
    • Added QBMessageListenerImpl - an implementation of QBMessageListener.
    • API to remove multiple chat messages in a single query
    • API to create a chat message via REST
    • New filters in QBRequestGetBuilder: outputInclude, outputExclude, near
    • Added a method getRecipientId to QBDialog class.
    • Added a method getSession to QBAuth to get an info about current session.
    • New filters in QBRequestUpdateBuilder: addToSet, updateArrayValue.
    • Added put<type> methods to QBCustomObject class.
    • Added a method setId to QBChatMessage to set the custom Id.
    • Upload/Download files progress callbacks for Content and CustomObjects modules.
    • API to create the geodata with the location-push
    • Updated core of the XMPP library
    • Removed classes QBMessage and QBChatHistoryMessage. Now QBChatMessage must be used anywhere.
  • Fixes:
    • Don't add extraParams to the chat message if there are no any extra parameters or attachments added to chat message.
    • deleteDialog method in QBGroupChatManager and QBPrivateChatManager classes is marked as none static.
    • Issue with chat logout where it wasn't possible to login with another user without doing QBChatService.getInstance().destroy();


Previous releases

v2.0 — October 31, 2014

  • New generic callbacks
  • Result entity is deprecated
  • Synchronous requests
  • New Chat API
  • API to remove chat dialog
  • Added an ability to track 'user is typing' status in chat
  • Added an ability to track 'delivered' status in chat
  • Added an ability to track 'read' status in chat
  • Added an ability to init SDK with existent QuickBlox token
  • Set the chat message packet ID to MongoDB ObjectID
  • Message Carbons (XEP-0280)


v1.2.4 — August 12, 2014

  • Fixed an issue with filter location in geo rect request
  • Fixed an issue with get users with phone numbers request
  • Fixed some crashes in video chat


v1.2.3 — June 26, 2014


v1.2.2 — May 23, 2014

  • Content: translated File public url to new format


v1.2.1 — May 19, 2014

  • Fixed an issue with getting users with fullname with spaces
  • Fixed an issue with uploading content file with spaces in name
  • Fixed parser crash on HTC devices with Android 2.3
  • Set XMPP room name in QBChatService.getInstance().createRoom method


v1.2 — April 25, 2014

  • Chat
    • Renamed SessionListener to SessionCallback
    • Added ConnectionListener
  • General
    • Reduced amount of methods in jar file
    • bug fixes


v1.1 — January 14, 2014

  • Chat
    • Roster(contact list) API
    • Added methods to add/remove users to chat room


v1.0.2 — January 9, 2014

  • Errors handling fixes


v1.0.1 — December 30, 2013

  • Chat
    • Chat API wrapper
  • CustomObjects
    • Permissions API
    • Files API
    • Added ‘output’, ‘or’, ‘ctn’ operators
    • Multi creation of records
    • Multi update of records
    • Multi delete of records
  • Content
    • Ability to update blob’s file
  • General
    • Ability to set custom endpoints for API server, Chat server, TURN server, Content bucket name
    • Access to token expiration date


v0.8.2 — December 9, 2013

  • Improved the stability


v0.8.1 — April 29, 2013

  • Added method QBUsers.getUsersByPhoneNumbers - retrieve users by phone numbers
  • Improved the stability


v0.8 — March 14, 2013

  • Added method QBUsers.getUsersByLogins - retrieve users by logins
  • Added method QBUsers.getUsersByEmails - retrieve users by emails
  • Improved the stability


v0.7 — January 16, 2013
  • All APIs are covered
  • Renamed QBAuth.authorizeApp method to QBAuth.createSession