Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

  • Core Products

  • Add-Ons

  • Extensions Marketplace

SDK quickstart

Thanks to Agora’s intelligent and global Software Defined Real-time Network (Agora SD-RTN™), you can rely on the highest available video and audio quality.

This page shows the minimum code you need to integrate high-quality, low-latency Video Calling features into your app using Video SDK.

Understand the tech​

This section explains how you can integrate Video Calling features into your app. The following figure shows the workflow you need to integrate this feature into your app.

To start a session, implement the following steps in your app:

  • Retrieve a token: A token is a computer-generated string that authenticates a user when your app joins a channel. In this guide you retrieve your token from Agora Console. To see how to create an authentication server for development purposes, see Implement the authentication workflow. To develop your own token generator and integrate it into your production IAM system, read Token generators.

  • Join a channel: Call methods to create and join a channel; apps that pass the same channel name join the same channel.

Prerequisites​

In order to follow this procedure you must have:

  • Android Studio 4.1 or higher.
  • Android SDK API Level 24 or higher.
  • A mobile device that runs Android 4.1 or higher.

  • An Agora account and project.

  • A computer with Internet access.

    Ensure that no firewall is blocking your network communication.

Project setup​

To install the Video SDK reference app on your development device:

  1. Clone the Video SDK reference app to <samples-root> on your development environment:

    Navigate to your <samples-root> folder and run the following command:


    _1
    git clone https://github.com/AgoraIO/video-sdk-samples-android.git

  2. Open the reference app in Android Studio:

    From the File menu select Open... then navigate to <samples-root>/video-sdk-samples-android/android-reference-app and click OK. Android Studio loads the project and Gradle sync downloads the dependencies.

You are ready to implement Video Calling features using the Android reference app.

Implement a client for Video Calling​

When a user opens the app, you initialize Agora Engine. When the user taps a button, the app joins or leaves a channel. When another user joins the same channel, their video and audio is rendered in the app. This simple workflow enables you to concentrate on implementing Agora features and not UX bells and whistles.

Best practice is to separate the Video Calling workflows from your UI implementation. The Video SDK sample project implements Video Calling logic in the AgoraManager class. This class encapsulates the RTCEngine instance and core functionality as illustrated by the excerpts below:

  1. Import the Video SDK classes and interfaces:


    _2
    import io.agora.rtc2.video.VideoCanvas
    _2
    import io.agora.rtc2.*

  2. Declare variables to create an Agora Engine instance and join a channel:

  3. Configure an Agora Engine instance and set up an event handler:


    _18
    protected open fun setupAgoraEngine(): Boolean {
    _18
    try {
    _18
    // Set the engine configuration
    _18
    val config = RtcEngineConfig()
    _18
    config.mContext = mContext
    _18
    config.mAppId = appId
    _18
    // Assign an event handler to receive engine callbacks
    _18
    config.mEventHandler = iRtcEngineEventHandler
    _18
    // Create an RtcEngine instance
    _18
    agoraEngine = RtcEngine.create(config)
    _18
    // By default, the video module is disabled, call enableVideo to enable it.
    _18
    agoraEngine!!.enableVideo()
    _18
    } catch (e: Exception) {
    _18
    sendMessage(e.toString())
    _18
    return false
    _18
    }
    _18
    return true
    _18
    }

  4. Handle and respond to Agora Engine events:


    _42
    protected open val iRtcEngineEventHandler: IRtcEngineEventHandler?
    _42
    get() = object : IRtcEngineEventHandler() {
    _42
    // Listen for a remote user joining the channel.
    _42
    override fun onUserJoined(uid: Int, elapsed: Int) {
    _42
    sendMessage("Remote user joined $uid")
    _42
    // Save the uid of the remote user.
    _42
    remoteUids.add(uid)
    _42
    if (isBroadcaster && (currentProduct == ProductName.INTERACTIVE_LIVE_STREAMING
    _42
    || currentProduct == ProductName.BROADCAST_STREAMING)
    _42
    ) {
    _42
    // Remote video does not need to be rendered
    _42
    } else {
    _42
    // Set up and return a SurfaceView for the new user
    _42
    setupRemoteVideo(uid)
    _42
    }
    _42
    }
    _42
    _42
    override fun onJoinChannelSuccess(channel: String, uid: Int, elapsed: Int) {
    _42
    // Set the joined status to true.
    _42
    isJoined = true
    _42
    sendMessage("Joined Channel $channel")
    _42
    // Save the uid of the local user.
    _42
    localUid = uid
    _42
    mListener!!.onJoinChannelSuccess(channel, uid, elapsed)
    _42
    }
    _42
    _42
    override fun onUserOffline(uid: Int, reason: Int) {
    _42
    sendMessage("Remote user offline $uid $reason")
    _42
    // Update the list of remote Uids
    _42
    remoteUids.remove(uid)
    _42
    // Notify the UI
    _42
    mListener!!.onRemoteUserLeft(uid)
    _42
    }
    _42
    _42
    override fun onError(err: Int) {
    _42
    when (err) {
    _42
    ErrorCode.ERR_TOKEN_EXPIRED -> sendMessage("Your token has expired")
    _42
    ErrorCode.ERR_INVALID_TOKEN -> sendMessage("Your token is invalid")
    _42
    else -> sendMessage("Error code: $err")
    _42
    }
    _42
    }
    _42
    }

  5. Render video from a remote user in the channel:


    _15
    protected fun setupRemoteVideo(remoteUid: Int) {
    _15
    // Create a new SurfaceView
    _15
    val remoteSurfaceView = SurfaceView(mContext)
    _15
    remoteSurfaceView.setZOrderMediaOverlay(true)
    _15
    // Create a VideoCanvas using the remoteSurfaceView
    _15
    val videoCanvas = VideoCanvas(
    _15
    remoteSurfaceView,
    _15
    VideoCanvas.RENDER_MODE_FIT, remoteUid
    _15
    )
    _15
    agoraEngine!!.setupRemoteVideo(videoCanvas)
    _15
    // Set the visibility
    _15
    remoteSurfaceView.visibility = View.VISIBLE
    _15
    // Notify the UI to display the video
    _15
    mListener!!.onRemoteUserJoined(remoteUid, remoteSurfaceView)
    _15
    }

  6. Render video from the local user in the channel:


    _15
    val localVideo: SurfaceView
    _15
    get() {
    _15
    // Create a SurfaceView object for the local video
    _15
    val localSurfaceView = SurfaceView(mContext)
    _15
    localSurfaceView.visibility = View.VISIBLE
    _15
    // Call setupLocalVideo with a VideoCanvas having uid set to 0.
    _15
    agoraEngine!!.setupLocalVideo(
    _15
    VideoCanvas(
    _15
    localSurfaceView,
    _15
    VideoCanvas.RENDER_MODE_HIDDEN,
    _15
    0
    _15
    )
    _15
    )
    _15
    return localSurfaceView
    _15
    }

  7. Join a channel to start Video Calling:


    _39
    fun joinChannel(channelName: String, token: String?): Int {
    _39
    // Ensure that necessary Android permissions have been granted
    _39
    if (!checkSelfPermission()) {
    _39
    sendMessage("Permissions were not granted")
    _39
    return -1
    _39
    }
    _39
    this.channelName = channelName
    _39
    _39
    // Create an RTCEngine instance
    _39
    if (agoraEngine == null) setupAgoraEngine()
    _39
    val options = ChannelMediaOptions()
    _39
    if (currentProduct == ProductName.VIDEO_CALLING || currentProduct == ProductName.VOICE_CALLING) {
    _39
    // For a Video/Voice call, set the channel profile as COMMUNICATION.
    _39
    options.channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION
    _39
    isBroadcaster = true
    _39
    } else {
    _39
    // For Live Streaming and Broadcast streaming,
    _39
    // set the channel profile as LIVE_BROADCASTING.
    _39
    options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING
    _39
    if (currentProduct == ProductName.BROADCAST_STREAMING) {
    _39
    // Set Low latency for Broadcast streaming
    _39
    if (!isBroadcaster) options.audienceLatencyLevel =
    _39
    Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY
    _39
    }
    _39
    }
    _39
    _39
    // Set the client role as BROADCASTER or AUDIENCE according to the scenario.
    _39
    if (isBroadcaster) { // Broadcasting Host or Video-calling client
    _39
    options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
    _39
    // Start local preview.
    _39
    agoraEngine!!.startPreview()
    _39
    } else { // Audience
    _39
    options.clientRoleType = Constants.CLIENT_ROLE_AUDIENCE
    _39
    }
    _39
    _39
    // Join the channel with a token.
    _39
    agoraEngine!!.joinChannel(token, channelName, localUid, options)
    _39
    return 0
    _39
    }

  8. Leave the channel when the local user ends the call:


    _14
    fun leaveChannel() {
    _14
    if (!isJoined) {
    _14
    sendMessage("Join a channel first")
    _14
    } else {
    _14
    // To leave a channel, call the `leaveChannel` method
    _14
    agoraEngine!!.leaveChannel()
    _14
    sendMessage("You left the channel")
    _14
    _14
    // Set the `joined` status to false
    _14
    isJoined = false
    _14
    // Destroy the engine instance
    _14
    destroyAgoraEngine()
    _14
    }
    _14
    }

  9. Clean up the resources used by the app:


    _5
    protected fun destroyAgoraEngine() {
    _5
    // Release the RtcEngine instance to free up resources
    _5
    RtcEngine.destroy()
    _5
    agoraEngine = null
    _5
    }

Test your implementation​

Agora recommends you run this project on a physical mobile device, as some simulators may not support the full features of this project. To ensure that you have implemented Video Calling in your app:

  1. Generate a temporary token in Agora Console.

  2. Configure the web demo you use to connect to your app:

    In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

  1. Configure the project:

    In agora-manager/res/raw/config.json, Replace:

    • appId - with your app ID from Agora Console.
    • channelName - with the name of a channel you want to join.
    • rtcToken - with a valid temporary token for the channelName.

  2. Run the Android reference app:

    1. In Android Studio, connect a physical Android device to your development machine.

    2. Click Run to start the app.

      A moment later you see the project installed on your device. If this is the first time you run the project, you need to grant microphone and camera access to your app.

    3. From the main screen of the app, choose Video Calling from the dropdown and then select SDK Quickstart.

  3. Join a Channel:

Reference​

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

  • Downloads shows you how to install Video SDK manually.

  • To ensure communication security in a test or production environment, use a token server to generate token is recommended to ensure communication security, see Implement the authentication workflow.

Video Calling