Android - Java/Kotlin

Overview

Follow this step-by-step tutorial to implement the Watch Together video chat sample application.

While the client-side application will take care of most of the functionality, in order to make this sample application work, you will need to get an access token from the Cluster Authentication Server (CAS).

Requirements

To complete this guide successfully the following prerequisites are required:

Authentication

An Access Token is needed in order to allow a client to connect to a Session.

Note: It is important that the client application does not request an Access Token directly from the backend. By doing that you risk exposing the API_TOKEN and API_SECRET.

  • To learn how to acquire an Access Token please look at the Cluster Authentication Server (CAS) reference

  • To simplify the tutorial, in the section below you can see an example of getting an Access Token

Acquiring an Access Token

curl -iL --request GET --url https://YOUR_CAS_URL/stream/token/v2/ --header 'auth-api-key: API_KEY' --header 'auth-api-secret: API_SECRET'

TheAccess Tokenis a JWT token - more about JWT you can read - here.

A successful response will look like that:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...."
}

You can get your API_KEY and API_SECRET in your private area, here.

Note: Every Streaming Token corresponds to one specific Session only. To allow two different clients to connect to the same Session, the clients need to use the same Access Token.

Going to production

To go to production you will need to implement your own authentication server. Using the server the Access Token will be shared to your various clients (Web, Android, and iOS). With this valid Access Token you will be able to use the service.

For that you will need:

  • API_KEY, and API_SECRET - can be retrieved in your private area once you login

  • Your own working authentication server - Authentication overview

Creating a new project

  • Open Android Studio and select New Project from the File menu

  • Select Empty Activity and click next

  • Choose Java or Kotlin as your programming language for the project

  • Configure your project's location, application, and package names

  • Set minimum SDK version of the application to 23 or higher

Adding Watch Together Android SDK library to the project

  • Create (if it does not exist) in the project libs directory under the app folder

  • Take the downloaded file wtsdk_v....aar and put it into the libs folder

  • Edit application's build.gradle file (in the app folder) with SDK

dependencies {	
    implementation files('libs/wtsdk_v....aar')	
}

If you are using android.enableJetifier=true to automatically convert third-party libraries to use AndroidX, please add this line android.jetifier.blacklist=wsdk_v2.0.4.aar to your gradle.properties file.

If this line is not there the WT library will not compile

# AndroidX package structure to make it clearer which packages are bundled with the
# Android operating system, and which are packaged with your app"s APK
# https://developer.android.com/topic/libraries/support-library/androidx-rn
android.useAndroidX=true

# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true
android.jetifier.blacklist=sdk-release.aar

Adding dependencies

  • Modify the build.gradle file (in the app folder) with SDK dependencies, once modified it should look as follows:

android {
...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version'
    ...

	//Watch Together SDK library
    implementation files('libs/wtsdk_v....aar')	
}

  • Sync and Rebuild the project

    • If the Sync and Rebuild was executed successfully, the Watch Together classes and functions should be available in the project

Granting access to camera and microphone

Using the device Audio and Video requires permissions to be granted from the user and some code that will allow the application to work well under different scenarios.

  • Add the following permissions to the AndroidManifest.xml file under the app/src/main folder in the project above the application tag.

<uses-feature android:name = "android.hardware.camera" />
<uses-feature android:name = "android.hardware.camera.autofocus" />
<uses-feature
    android:glEsVersion = "0x00020000"
    android:required = "true" />
<uses-permission android:name = "android.permission.CAMERA" />
<uses-permission android:name = "android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name = "android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name = "android.permission.RECORD_AUDIO" />
<uses-permission android:name = "android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name = "android.permission.INTERNET" />

The permissions should be validated before every connect of a client to a session.

Sample application UI

The sample application has a UI element that needs to be handled to allow the proper presentation of the streams and stream properties.

  • Use a view container in the application’s resource layout file to display videos. The sample application demonstrates how to manage videos with RecyclerView container

  • For rendering videos, the SDK provides the VideoRenderer class for use in the application’s layout

    <?xml version="1.0" encoding="utf-8"?>
<android.support.constraint.ConstraintLayout
...

<com.wt.sdk.VideoRenderer
    android:id="@+id/video_renderer"
    android:layout_width="120dp"
    android:layout_height="160dp" />

  • Initialize Session object with SessionBuilder class

// Host class of Session object should implement or have interface SessionListener
mSession = new Session.SessionBuilder(this)           // this - SessionListener object   
                    .setReconnectListener(this)       // this - ReconnectListener object
                    .setConnectionListener(this)      // this - ConnectionListener object
                    .build(this);                     // this - Android context
                    
mSession.setDisplayName(mDisplayName);                // optional 
mSession.setEnableStats(isEnableStats);               // isEnableStats - enable stats received

  • Start camera preview - can be called without the Session’s url and the Access Token

mSession.startCameraPreview();

  • Connecting to the Session using the Session object requires a Session’s URL and a valid Streaming Token to be available before connecting. The connect() function establishes a connection to the Session with the audio and video tracks inside MediaStream object

// String parameter sessionId should be passed in the function connect.
mSession.connect(mToken);               // mToken - authorization token

  • It is possible connect as different types of participants:

    • FULL_PARTICIPANT - publishes Audio and Video to the session and Subscribes to all other participants Audio and Video in the Session

    • VIEWER - Subscribes to all other participants Audio and Video in the Session

    • AV_BROADCASTER - Publishes Audio and Video to the Session

    • A_BROADCASTER - Publishes only Audio to the Session

  • In the case you would like to connect as a Viewer do the following:

// String parameter sessionId should be passed in the function connectAsViewer.
mSession.connect(mToken, mParticipantType);  // mParticipantType - participant's connection type

Managing Session logic

To manage the session's logic we provided several callbacks that will allow you to customize the interactions as you need.

  • The SessionListener interface, which the MainActivity implements, will allow you to control the flow of logic of the Session you are managing

public class MainActivity extends AppCompatActivity implements SessionListener {
   ...
   
    @Override
    public void onConnected(@NonNull List<? extends Participant> list) {
        // client has been connected to the session with the unique sessionId and participants already in the Session
    }

    @Override
    public void onDisconnected() { 
        // client has been disconnected from the session. All connections will be closed.
        // clear ui and data  
        finish() // Close MainActivity page      
    }
    
    @Override
    public void onError(SessionError error) {
        // You can implement error handling here. Check API rferences for possible errors.
    }
    
    @Override
    public void onLocalParticipantJoined(@Nullable Participant participant) {
        // Camera preview started, local stream created, update UI  
        if (mParticipantAdapter != null) {
            mParticipantAdapter.addLocalParticipant(participant);
        }
    }

    @Override
    public void onRemoteParticipantJoined(@Nullable Participant participant) {
        // remote participant joined to the session, update ui.
        // create addParticipant method in the ParticipantsAdapter as in the sample code
        if (mParticipantAdapter != null) {
            mParticipantAdapter.addRemoteParticipant(participant);
        }
    }

    @Override
    public void onUpdateParticipant(@Nullable String participantId, @Nullable Participant participant) {
        // participant update the session, update ui
        if (mParticipantAdapter != null) {
            mParticipantAdapter.updateParticipant(participantId, participant);
        }
    }

    @Override
    public void onRemoteParticipantLeft(@Nullable String participantId) {
        // remote participant left the session, update ui
        if (mParticipantAdapter != null) {
            mParticipantAdapter.removeParticipant(participantId);
        }
    }

    @Override
    public void onParticipantMediaStateChanged(@Nullable String participantId, MediaType mediaType,
        MediaState mediaState) {
        // Method is triggered when remote participant disabled/enabled (mediastate) it's audio/video (mediaType).
        // On UI it can be reflected with this callback
        if (mParticipantAdapter != null) {
            mParticipantAdapter.updateParticipantMedia(participantId, mediaType, mediaState);
        }
    }

    @Override
    public void onMessageReceived(@Nullable String participantId, @Nullable String message) {
        // The method is receiving messages from remote participants into the current room
        Toast.makeText(this, "participant=$participant, message=$message", Toast.LENGTH_LONG).show()
    }
   
    @Override
    protected void onPause() {
        // Disconnect from the session
        mSession.disconnect();
    }

    @Override
    public void onBackPressed() {
        // Disconnect from the session
        mSession.disconnect();
    }
    
    @Override
    protected void onDestroy() {
        // Clear participants and publishers
        mParticipantAdapter.clearParticipants();
        super.onDestroy();
    }
}

Managing Reconnection logic

To manage the reconnect session's logic we provide several callbacks and will allow you to customize the interactions you need.

  • The SessionReconnectListener interface, which the MainActivity implements in the sample application, will allow you to control the flow of logic of the Reconnect you are managing

public class MainActivity extends AppCompatActivity implements SessionReconnectListener {
   ...
    
    @Override
    public void onParticipantReconnecting(final String participantId) {
        // callback which triggers when remote participant loses network 
        // participantId - participant's identificator for updating
        mParticipantAdapter.progressConnection(participantId, true);
    }

    @Override
    public void onParticipantReconnected(String participantId, String oldParticipantId) { 
        // callback with triggers when remote participant network resumes
        // oldParticipantId -  identificator old participant for updating
        // participantId - participant's identificator for updating
        mParticipantAdapter.progressConnection(oldParticipantId, false);     
    }
}

Managing Connection states logic

To manage the connection states session's logic we provided several callbacks and will allow you to customize the interactions you need.

  • The SessionConnectionListener interface, which the MainActivity implements in the sample application, will allow you to control the flow of logic of the Connection states you are managing

public class MainActivity extends AppCompatActivity implements SessionConnectionListener {
    ...
    
    @Override
    public void onLocalConnectionLost() {
        // callback with triggers when local participant connection lost
    }
    
    @Override
    public void onLocalConnectionResumed() {
        // callback with triggers when local participant connection resumed
    }
    
    @Override
    public void onRemoteConnectionLost(String participantId) {
        // callback with triggers when remote participant connection lost
        // participantId - identificator that participant by id losing connection
        if (mParticipantAdapter != null) {
            mParticipantAdapter.remoteParticipantConnectionLost(participantId);
        }
    }
}

Enable/Disable Audio or Video

  • Bind the Participant view to the Participant data in the ParticipantsAdapter class

    @Override
    public void onBindViewHolder(@NonNull final ViewHolder viewHolder, final int position) {
        final Participant participant = mParticipants.get(viewHolder.getAdapterPosition());
        if (participant != null) {
            participant.setRenderer(viewHolder.videoRenderer);
            participant.enableStats();
            participant.setParticipantStatsListener(new OnParticipantStatsListener() {
                @Override
                public void onStats(@Nullable JSONObject jsonStats,
                    @NotNull Participant participant) {
                    // The callback with json data about connection quality for audio and video
                    try {
                        if (jsonStats != null) {
                            jsonStats.get("audioAvg")          // 0 - 4.5 value
                            jsonStats.get("audioQosMos")       // Value of quality {BAD, GOOD, EXCELLENT}
                            jsonStats.get("videoAvg")          // 0 - 4.5 value
                            jsonStats.get("videoQosMos")       // Value of quality {BAD, GOOD, EXCELLENT}
                        }
                    } catch (JSONException e) {
                        e.printStackTrace();
                    }
                }
            });
            viewHolder.mic.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(final View v) {
                    if (participant.isAudioEnabled()) {
                        participant.disableAudio();
                    } else {
                        participant.enableAudio();
                    }
                    notifyItemChanged(position, participant);
                }
            });
            viewHolder.cam.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(final View v) {
                    if (participant.isVideoEnabled()) {
                        participant.disableVideo();
                    } else {
                        participant.enableVideo();
                    }
                    notifyItemChanged(position, participant);
                }
            });
            // Update microphone and camera UI icons according to Participant's Audio and Video track state
            viewHolder.connectionState.setVisibility(participant.isConnectionLost() ? View.VISIBLE : View.GONE);
            viewHolder.layoutProgress.setVisibility(participant.isProgressReconnection() ? View.VISIBLE : View.GONE);
            viewHolder.mic.setBackgroundResource(participant.isAudioEnabled() ? R.drawable.ic_mic_on : R.drawable.ic_mic_off);
            viewHolder.cam.setBackgroundResource(participant.isVideoEnabled() ? R.drawable.ic_video_on : R.drawable.ic_video_off);

            viewHolder.name.setText(participant.getName());
      }
}

Switching camera

During streaming, you can switch from front to back camera by a simple call to the Session’s function switchCamera

Running the application

Once coding is finished, you should be able to run the application in the Android Studio emulator.

You can view the complete Watch Together sample application here

Release notes

  • The Android SDK’s support Android 6.0 version and higher

Next steps

Support

Need technical support? contact us at Support@sceenic.co.

PreviousAndroidNextiOS

Last updated

Was this helpful?