EnableX Documentation - RawSwat/Documentation GitHub Wiki

How to build an Android application using EnableX video API

Table Of Contents

What is CPaaS

CPaaS (Communication Platform as a Service) is a cloud-based platform that allows developers to add real-time communications features: voice calling, video calling, and chatting to their applications without having to build backend infrastructure and interfaces.

Why CPaaS

Traditionally, we have seen RTC (real-time communication) taking place in dedicated RTC applications such as Skype and Whatsapp, as it is costly to build and operate a communication stack, manage network infrastructure, and develop and maintain the framework. The time, efforts, and resources utilized in addressing the above requirements could be directed to meet an organization’s core business needs.

How Enablex Helps

EnableX is a CpaaS provider that provides:

  • Communication solutions: EnableX offers communication solutions for video meetings (Online meetings, Training, and Technical support), virtual events (Webinars, Townhalls, and Broadcasting), and online classrooms (1-to-1 Tuitions, Online courses, and Study groups).
  • Communication APIs: EnableX provides APIs to enable your application to conduct RTC sessions hosted on the EnableX platform along with complete technical support.
  • Professional services for service providers: EnableX also offers technical consultation or custom development and associated services for those who choose to build their own RTC platform or need help in the cloud-deployment.

EnableX is constantly working on breakthrough technology to introduce new and exciting features such as AI-enabled video that is capable of analyzing facial expressions, various access-controlled features, video session streaming sessions, etc.
The customer only needs to pay as per usage for the above-mentioned services which makes it easier and pocket-friendly to enable RTC with advanced features in their applications.

How can you integrate EnableX into your application

Building an Android application with embedded RTC requires you to program two components:

  • An application server that would run as a web service and communicate with the EnableX server through EnableX server APIs.
  • A client application that would run on the client's endpoints and communicate with EnableX signaling server and media server through EnableX client APIs to facilitate RTC sessions, which are hosted on the EnableX platform.

To enable the Android application to establish an RTC session hosted on the EnableX platform, EnableX provides two sets of APIs:

1. Server API

Server APIs are RESTful APIs that you call from your application server to communicate with the EnableX server, as they provide the single entry point access to the EnableX services. Server APIs are typically used for provisioning connection, requesting a token to start a session, and generating the post-session report.

EnableX server side architecture

2. Client API

Client APIs are called from the Android SDK that runs in the Android application. Client APIs are typically used for

  • Connecting to a Room, where the room is a video-enabled virtual meeting space hosted on the EnableX platform where the RTC session takes place.
  • Publishing local stream, which enables the user to publish audio/video in the room.
  • Subscribing to a remote stream, which enables the participants to receive the media stream of other participants in the room.
  • Listening to the events occurring in the session, which could be events related to the room connection or events related to the streams within a room.
  • Playing the stream in a view handler, which is a customizable UI element, in the Mobile SDK.

Following are the steps to program your Android application using the Server APIs and Client APIs.

1.1. Program application server using EnableX server APIs

The following API host URLs are required to call Server REST APIs in each of the steps mentioned below.
Sever API Host: https://api.enablex.io/video/
Version Base URL: https://api.enablex.io/video/v1/
(The version base URL comprises of server API host URL and version number, where the version number changes after every major version release.)
Rooms Route URL: https://api.enablex.io/video/v1/rooms

1.1.1. Get API Authentication Credentials

  1. Log in to the EnableX portal.
  2. Create a project by selecting {Main Menu} Projects > Create New Project.
  3. You receive an email with access credentials: Application ID (APP_ID) and Application key (APP_KEY).
    Each API call is validated through an authentication header which uses Application ID/APP_ID as username and Application Key/APP_KEY as password.
POST https://api.enablex.io/video/v1/rooms/
Authorization: Basic XXXXXX    
Content-Type: application/json

In the above example, XXXXXX is a base64 encoded string of APP_ID:APP_KEY.

1.1.2. Create A Room
The create room request creates a database entry with a room Id on the EnableX platform. The room id is required to carry out CRUD (create, remove, update, and delete) operations on the room.

Request Example

{
  "name": "Topic or Room Title",
  "owner_ref": "xyz",
  "settings": {
    "description": "Descriptive text",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "2",
    "auto_recording": false,
    "quality": "SD"
  },
  "sip": {
    "enabled": false
  },
  "data": {
    "custom_key": ""
  }
}

To restrict the video call to one to one where you have one moderator and one participant, set "participants:1".

For more details on the Request JSON body payload(key/value pairs) see Create Room.

Response JSON

{
  "result": 0,
  "room": {
    "name": "Topic or Room Title",
    "service_id": "XXXXXXXXXXXXXXXX",
    "owner_ref": "xyz",
    "settings": {
      "description": "Descriptive text",
      "mode": "group",
      "scheduled": false,
      "scheduled_time": "2021-08-25 11:11:11",
      "adhoc": false,
      "duration": 30,
      "moderators": "1",
      "participants": "2",
      "auto_recording": false,
      "active_talker": true,
      "screen_share": true,
      "canvas": false,
      "knock": true,
      "quality": "SD",
      "billing_code": "XXXXXX",
      "abwd": true,
      "facex": false,
      "max_active_talkers": 2
    },
    "data": {
      "custom_key": ""
    },
    "configured_media_zone": "XX",
    "created": "2020-08-24T14:46:42.108Z",
    "isMediaServerAvailable": false,
    "updated": "2020-08-24T14:46:42.108Z",
    "room_id": "XXXXXXXXXXXXXXX",
    "sip": {
      "enabled": false
    }
  }
}

1.1.3. Create Token
Any user who wishes to join an RTC session hosted on the EnableX platform must request a token specifying her role as either a moderator or a participant. The token is designed to expire if the user fails to join the session within 120 minutes of token creation however a token may be created 15 minutes ahead of the scheduled start time for scheduled meeting rooms.

Request Example

{
  "name": "John Doe",
  "role": "participant",
  "user_ref": "XXXXX"
}

For more details on the Request JSON body payload(key/value pairs) See Create Token.

Response JSON

{
  "result": 0,
  "token": "string"
}

You may also utilize several other RESTful server APIs to be able to perform CRUD operations on the rooms, access call detail reports (CDR), or gain access to archived data by using the Server API.

1.2. Sample Application Server Program

For detailed instructions on configuring the server, acquiring SSL certificates, and building and running the server, see the readme file.
Here is a list of sample application server programs in various programming languages (refer to the section Application Server & Client End Point Applications).

1.3. Demo Application Server

To try out the sample applications, you can use the Demo Application server provided by EnableX. To use the demo server, configure your application to point to the demo server using your project's credentials (APP_ID and APP_KEY) and the demo server URL.

  • Use Demo Server URL: https://demo.enablex.io
  • Pass your Credentials as Custom Header to HTTP Request as:
    • x-app-id: Your Application ID
    • x-app-key: Your Application Key

2.1. Program your client endpoint/android application using EnableX Client APIs

2.1.1. Download the toolkit for Android SDK v1.8
For more information on how to incorporate the SDK in your project, see Android Toolkit.

2.1.2. Retrieve the token from the Application server (received from the server API as mentioned in step 1.1.3 above)
A sample code snippet to retrieve the Token from the JSON response received by the server:

private void onGetTokenSuccess(String response) {
        Log.e("responseToken", response);

        try {
            JSONObject jsonObject = new JSONObject(response);
            if (jsonObject.optString("result").equalsIgnoreCase("0")) {
                token = jsonObject.optString("token");
                Log.e("token", token);
                Intent intent = new Intent(DashboardActivity.this, VideoConferenceActivity.class);
                intent.putExtra("token", token);
                intent.putExtra("name", name.getText().toString());
                startActivity(intent);
            } else {
                Toast.makeText(this, jsonObject.optString("error"), Toast.LENGTH_SHORT).show();
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }

2.1.3 Connect to the “Room” with the token (received above in step 2.1.2)

  • Initialize Room
    Create a room object of EnxRoom Class by calling its Constructor.

    Parameters:
    EnxRoomObserver Instance
    EnxStreamObserver Instance

    After instantiating EnxRoom Class, you need to call EnxRoom.init() method as follows:

    Class: EnxRoom
    Method: public void init( Context context )

EnxRoom room = new EnxRoom(EnxRoomObserver-Instance,EnxStreamObserver-Instance);
room.init( activity-class-context );

  • Connect Room
    Once the room is initialized, connect to the room using EnxRoom.connect() method:

    Class: EnxRoom
    Method: public void connect(String Token, JSONObject RoomInfo, JSONObject advanceOptions)

    Parameters:

    • Token: As received from the Server in the steps above which allows access to the room.
    • RoomInfo: Optional. A JSON object with reconnection options. JSON keys are as followed.
      • allow_reconnect: Boolean. Default: True. Set true to enable the auto-reconnect feature.
      • number_of_attempts: Numeric. Default: 3. Min Value: 1, Max Value: Any (No Limit). Defines the maximum number of times the client endpoint tries to reconnect to the EnableX server.
      • timeout_interval: Numeric value in milliseconds defining the wait time before attempting to reconnect.
      • audio_only: Boolean. Set to True to allow the user to join in anonymous mode/audio-only mode.
    • Advanced Options: Optional. A JSON object with an array of elements with keys - id and enable.
      • battery_updates: Boolean. Set to True to enable the auto-battery-update feature.
      • notify-video-resolution-change: Boolean. Set to true to enable the video-resolution-change notification feature.
JSONObject roomInfo = {
	"allow_recnnect": true,
	"number_of_attempts": 3,
	"timeout_interval": 10000,
	"audio_only": true }
JSONObject advancedOptions = { [
		{	"id": " battery_updates",
    			"enable": true,
		},
		{	"id": " notify-video-resolution-change",
    			"enable": true,
		}]
}

EnxRoom room = new EnxRoom(this, this, this); // Initiates Room 

room.connect(token, roomInfo, advanceOptions); // Connects with Re-Connection & Advance Options

The following callback functions would be called based on the success/failure of connect() method.

  • onRoomConnected(): When the client endpoint is connected to the room.
  • onRoomError(): When the client endpoint fails to connect to the room.
  • onUserConnected(): Notifies all participants when a new user gets connected to the room.
  • onActiveTalkerList(): Gives a list of active talkers post onRoomConnected event. For more information, see Active Talker List.
public void onRoomConnected(EnxRoom room, JSONObject roomMetaData) {
 // Connected. 
 //Callback received with room object and Room Meta JSON
}
public void onRoomError(JSONObject roomError) {
 // Connection failed. Find error
}
public void onUserConnected(JSONObject userData) {
 // Notification to all that a new user is connected. 
 // userData json has user information
}
public void onActiveTalkerList(JSONObject userData) {
 // List of Current Active Talkers in the Room 
 // Received after onRoomConnected
}

  • Join Room
    You can alternatively use join room, which handles all the complexities of initializing, connecting, and joining a room.

    Class: EnxRtc
    Method: public EnxStream joinRoom(String Token, JSONObject publishStreamInfo)

    Parameters:

    • Token: As received through the server API call above.
    • publishStreamInfo: Optional. Holds stream initialization meta information.

    Returns: Local stream object EnxStream

    The following callback functions are called based on the success/failure of the join() method.

    • onRoomConnected(): When the client endpoint is connected to the room.
    • onRoomError(): When the client endpoint fails to connect to the room.
JSONObject publishStreamInfo = {
         video: true,
         audio: true,
         data: true,
         attributes: { name: "XX" }
}
String token = "XXX";
EnxRtc enxRtc = new EnxRtc(
                  Current-Class-Context, 
                  EnxRoomOberver-Instance, 
                  EnxStreamObserver-Instance);
EnxStream localStream = enxRtc.joinRoom(token, publishStreamInfo);

public void onRoomConnected(EnxRoom room, JSONObject roomMetaData) {
   // Connected. 
   //Callback received with room object and Room Meta JSON
}
public void onRoomError(JSONObject roomError) {
   // Connection failed. Find error
}

2.1.4. Publish stream after connecting/joining the room
Publish the local stream into the room by calling enxRoom.publish() method.

Class: EnxRoom
Method: public void publish(EnxStream localStream)

Parameters:

  • localStream: Initiated stream object

The following callback functions are called based on the success/failure of the publish() method.

  • onPublishedStream(): Informs the publisher(user) that the stream has been published.
  • onStreamAdded(): Informs the other participants in the room that a new stream has been added to the room.
public void onRoomConnected(EnxRoom enxRoom, JSONObject jsonObject) {
        //received when user connected with Enablex room
        enxRooms = enxRoom;
        if (enxRooms != null) {
            enxRooms.publish(localStream);
            enxRooms.setReconnectObserver(this);
            enxRoom.setActiveTalkerViewObserver(this);
        } }  
public void onPublishedStream(EnxStream stream) {
     // Your stream is published
}
public void onStreamAdded(EnxStream stream) {
     // To tell others that a New Stream is added to the Room
     // You may subscribe to the Stream
}

2.1.5. Subscribe to remote streams
Subscribe to the media streams of each of the participants in a room individually to be able to receive them, by utilizing the EnxRoom.subscribe() method. This method is called within onStreamAdded() which is invoked after the success of the publish() method as explained in step 2.1.4 above.

Class: EnxRoom
Method: public void subscribe(EnxStream remoteStream)

Parameters:

  • remoteStream: The stream object that needs to be subscribed.

The following callback functions are called based on the success/failure of the subscribe() method.

  • onSubscribedStream(): Informs the subscriber(participant) that the stream has been subscribed.
public void onStreamAdded(EnxStream enxStream) {
        //received when a new stream added
        if (enxStream != null) {
            enxRooms.subscribe(enxStream);
        }
    }
public void onSubscribedStream(EnxStream enxStream) {
        //received when a remote stream subscribed successfully
    }

2.1.6. Listen for session events
To enable your Android application to listen to any events occurring during the video/audio session, implement observer interfaces that have been defined in the EnableX client API as below:

public class VideoConferenceActivity extends AppCompatActivity
        implements EnxRoomObserver, EnxStreamObserver, View.OnClickListener, EnxReconnectObserver, EnxActiveTalkerViewObserver {
}

Implementing the observer interfaces provides access to various listener/callback methods waiting on a certain event as below:

public void onUserConnected(JSONObject jsonObject) {
        // received when a new remote participant joins the call
    }
public void onUserDisConnected(JSONObject jsonObject) {
        // received when a  remote participant left the call
        roomDisconnect();
    }
public void onPublishedStream(EnxStream enxStream) {
        //received when audio video published successfully to the other remote users
    }
public void onUnPublishedStream(EnxStream enxStream) {
        //received when audio video unpublished successfully to the other remote users
    }
public void onStreamAdded(EnxStream enxStream) {
        //received when a new stream added
        if (enxStream != null) {
            enxRooms.subscribe(enxStream);
        }
    }
public void onSubscribedStream(EnxStream enxStream) {
        //received when a remote stream subscribed successfully
    }

2.2 Sample Android Application with EnableX Android toolkit/SDK

See sample Android application that utilizes EnableX Android toolkit. For more information, see the README file.

How to incorporate anonymous video call or optional privacy mode feature in your application

  • To provide an audio-only call option in your application, set the audio_only key to true (audio_only = True) in the RoomInfo parameter to connect() method as mentioned in the "Connect Room" section in step 2.1.3.

  • You can also utilize EnxRoom.setAudioOnlyMode() method to be able to change to audio-only calls instead of restricting the connect() method. This method also allows you to toggle between audio-only and audio-video calls.

    Class: EnxRoom
    Method: publish void setAudioOnlyMode(boolean AudioOnly)

    Parameter: Boolean. Set to True to enable audio-only calls. Otherwise, set to False.

room.setAudioOnlyMode(true);   // Switched to Audio-Only call
room.setAudioOnlyMode(false);  // Switched back to Audio-Video call

  • To enable the user to see the other participant's video without showing her own video, implement the mute-video functionality using EnxStream.muteSelfVideo() method:

    Class: EnxStream
    Methods: public void muteSelfVideo( boolean )

    Parameters: Boolean. Set to True to mute. Otherwise, set to False to unmute.

    Callback Functions:

    • onRemoteStreamVideoMute(): Informs the other participants that the user has muted the video.
    • onRemoteStreamVideoUnMute(): Informs the other participants that the user has unmuted the video.
    • onVideoEvent(): Informs the user whether the video is muted or unmuted.
public void onVideoEvent(JSONObject jsonObject) {
//received when video mute/unmute happens
try {
       String message = jsonObject.getString("msg");
       if (message.equalsIgnoreCase("Video On")) {
           video.setImageResource(R.drawable.ic_videocam);
           isVideoMuted = false;
            } else if (message.equalsIgnoreCase("Video Off")) {
                video.setImageResource(R.drawable.ic_videocam_off);
                isVideoMuted = true;
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
public void onRemoteStreamVideoMute(JSONObject jsonObject) {
        //received when any remote stream mute video
    }
public void onRemoteStreamVideoUnMute(JSONObject jsonObject) {
        //received when any remote stream unmute audio
    }