SDK quickstart
This page provides a step-by-step guide on seamlessly integrating the Voice SDK and effortlessly building a basic, real-time interactive app from scratch using minimal code.
Understand the tech
This section explains how you can integrate Voice Calling features into your app. Following are some basic concepts about real-time audio interaction:
- Voice SDK: An SDK developed by Agora to enable developers to add real-time audio interaction to their projects.
- Channel: A channel is used to transmit data. Users in the same channel can interact in real time.
- Host: A host can publish audio in a channel. The host can also subscribe to audio published by other hosts.
- Audience: A user assigned the audience role may subscribe to audio within the channel. However, they are not authorized to publish content.
For more information, see Core Concepts.
The following figure shows the basic workflow you implement to integrate this feature into your app.
Prerequisites
- Android Studio 4.2 or higher.
- Android SDK API Level 21 or higher.
- Two mobile devices running Android 5.0 or higher.
- A computer with Internet access. If a firewall is deployed in your network environment, refer to Connect through restricted networks with Cloud Proxy to use Agora services normally.
- A microphone
- A valid Agora account and project
-
The following information from Agora Console:
-
App ID: A unique string generated by Agora that identifies your project.
-
A temporary token: A dynamic key that authenticates a user when the client joins a channel. Note down the channel name you use to generate the token.
informationThe maximum validity period of a temporary token is 24 hours.
Please refer to Agora account management for details.
-
Set up your project
This section shows you how to set up a new Android project and integrate the Agora Voice SDK.
Create a project
-
Create a new project (Optional)
- Open Android Studio and select File > New > New Project....
- Select Phone and Tablet > Empty Activity and click Next.
- Set the project name and storage path.
- Select the language as Java, and click Finish to create the Android project.
NoteAfter you create a project, Android Studio automatically starts gradle sync. Ensure that the synchronization is successful before proceeding to the next step. -
Add network and device permissions
Open the
/app/src/main/AndroidManifest.xml
file and add the following permissions after</application>
: -
Prevent code obfuscation
Open the
/app/proguard-rules.pro
file and add the following lines to prevent the Voice SDK code from being obfuscated:
Integrate the SDK
Choose either of the following methods to integrate Voice SDK into your project.
- Maven Central
- Manual integration
-
Open the
settings.gradle
file in the project's root directory and add the Maven Central dependency, if it doesn't already exist:NoteIf your Android project uses dependencyResolutionManagement, the method of adding the Maven Central dependency may differ.
-
Open the
/app/build.gradle
file and add the Voice SDK underdependencies
. Check the latest version of the SDK from the release notes and replacex.y.z
with the specific version number.Obtain the latest version number from the release notes.
-
Download the latest version of Voice SDK from the the SDKs page and unzip it.
-
Open the unzipped file and copy the following files or subfolders to your project path.
File or folder Project path agora-rtc-sdk.jar
file/app/libs/
arm64-v8a
folder/app/src/main/jniLibs/
armeabi-v7a
folder/app/src/main/jniLibs/
x86
folder/app/src/main/jniLibs/
x86_64
folder/app/src/main/jniLibs/
high_level_api
ininclude
folder/app/src/main/jniLibs/
-
Select the file
/app/libs/agora-rtc-sdk.jar
in the left navigation bar of Android Studio project files, right-click, and select add as a library from the drop-down menu.
Create a user interface
Set up a FrameLayout
element to add a TextView
. Use the following code to generate the essential user interface. Paste the code into the /app/src/main/res/layout/activity_main.xml
file, replacing the existing content.
Sample code to create the user interface
<?xml version="1.0" encoding="UTF-8"?><RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" android:id="@+id/activity_main" android:layout_width="match_parent" android:layout_height="match_parent" tools:context=".MainActivity"> <FrameLayout android:layout_width="match_parent" android:layout_height="match_parent" android:background="@android:color/darker_gray"> <TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:layout_marginBottom="40dp" android:layout_marginLeft="16dp" android:layout_marginStart="16dp" android:layout_gravity="center_vertical|start" android:text="Welcome to the Agora Voice Call channel."/> </FrameLayout></RelativeLayout>
Implement Voice Calling
This section shows you how to implement basic real-time audio interaction in your app.
The following figure illustrates the essential steps:
A complete code sample that implements the basic process of real-time interaction is presented here for your reference. Copy the sample code into your project to quickly implement the basic functions of real-time interaction.
To use the sample code, copy the following lines into the /app/src/main/java/com/example/<projectname>/MainActivity.java
file and replace <projectname>
in package com.example.<projectname>
with the name of your project.
Complete sample code for real-time Voice Calling
import android.Manifest;import android.content.pm.PackageManager;import android.os.Bundle;import android.widget.Toast;import androidx.annotation.NonNull;import androidx.appcompat.app.AppCompatActivity;import androidx.core.app.ActivityCompat;import androidx.core.content.ContextCompat;import io.agora.rtc2.ChannelMediaOptions;import io.agora.rtc2.Constants;import io.agora.rtc2.IRtcEngineEventHandler;import io.agora.rtc2.RtcEngine;import io.agora.rtc2.RtcEngineConfig;public class MainActivity extends AppCompatActivity { // Fill in your App ID, which can be generated in the Agora console private String appId = "<Your App ID>"; // Fill in the channel name private String channelName = "<Your channel name>"; // Fill in the temporary Token generated in the Agora console private String token = "<Your Token>"; private RtcEngine mRtcEngine; private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() { @Override public void onJoinChannelSuccess(String channel, int uid, int elapsed) { super.onJoinChannelSuccess(channel, uid, elapsed); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "Join channel success", Toast.LENGTH_SHORT).show(); }); } @Override public void onUserJoined(int uid, int elapsed) { super.onUserJoined(uid, elapsed); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "User joined: " + uid, Toast.LENGTH_SHORT).show(); }); } @Override public void onUserOffline(int uid, int reason) { super.onUserOffline(uid, reason); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "User offline: " + uid, Toast.LENGTH_SHORT).show(); }); }; private void initializeAndJoinChannel() { try { // Create an RtcEngineConfig object and configure it RtcEngineConfig config = new RtcEngineConfig(); config.mContext = getBaseContext(); config.mAppId = appId; config.mEventHandler = mRtcEventHandler; // Create and initialize the RtcEngine mRtcEngine = RtcEngine.create(config); } catch (Exception e) { throw new RuntimeException("Check the error."); } // Create a ChannelMediaOptions object and configure it ChannelMediaOptions options = new ChannelMediaOptions(); // Set the user role to BROADCASTER (host) or AUDIENCE (audience) options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER; // Set the channel profile options.channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION; // Publish the audio collected by the microphone options.publishMicrophoneTrack = true; // Automatically subscribe to all audio streams options.autoSubscribeAudio = true; // Join the channel using a uid, temporary token and channel name. // Ensure that the uid is unique within the channel. // If you set the uid to 0, the engine generates a random uid. // The onJoinChannelSuccess callback is triggered upon success. mRtcEngine.joinChannel(token, channelName, 0, options); } private static final int PERMISSION_REQ_ID = 22; // Get the permissions required for experiencing real-time audio interaction private String[] getRequiredPermissions(){ // Determine the permissions required when targetSDKVersion is 31 or above if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) { return new String[]{ Manifest.permission.RECORD_AUDIO, // Record audio permission Manifest.permission.READ_PHONE_STATE, // Read phone state permission Manifest.permission.BLUETOOTH_CONNECT // Bluetooth connection permission }; } else { return new String[]{ Manifest.permission.RECORD_AUDIO, }; } } private boolean checkPermissions() { for (String permission : getRequiredPermissions()) { int permissionCheck = ContextCompat.checkSelfPermission(this, permission); if (permissionCheck != PackageManager.PERMISSION_GRANTED) { return false; } } return true; } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // If already authorized, initialize the RtcEngine and join the channel if (checkPermissions()) { initializeAndJoinChannel(); } else { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID); } } // System permission request callback @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (checkPermissions()) { initializeAndJoinChannel(); } } @Override protected void onDestroy() { super.onDestroy(); if (mRtcEngine != null) { // Leave the channel mRtcEngine.leaveChannel(); mRtcEngine = null; // Destroy the engine RtcEngine.destroy(); } }}
appId
and token
variables, replace the placeholders with the values you obtained from Agora Console. Ensure you enter the same channelName
you used when generating the temporary token.Follow the implementation steps to understand the core API calls in the sample code.
Handle permissions
This section describes how to import Android classes and obtain the camera, recording, and other permissions of Android devices.
-
Import Android classes
-
Get Android permissions
When launching the app, check that the required permissions for real-time interaction have been granted in the app.
Import Agora classes
Import the relevant Agora classes and interfaces:
Declare variables
Pass in the app ID and the temporary token obtained from Agora Console. Use the channel name you filled in when generating the temporary token. You use these values to initialize the engine and join a channel.
Initialize the engine
Call create
to initialize an RtcEngine
instance.
Before initializing the SDK, ensure that the user fully understands and agrees to the relevant privacy policy.
Join a channel and publish audio stream
Call joinChannel
to join the channel. Configure the ChannelMediaOptions
as follows:
- Set the channel profile to
BROADCASTING
(live broadcast scene) and set the user role toBROADCASTER
(host) orAUDIENCE
(audience). - Set
publishMicrophoneTrack
totrue
to publish the audio captured by the microphone. - Set
autoSubscribeAudio
totrue
to automatically subscribe to all audio streams.
Start and close the app
When a user launches your app, start real-time interaction. When a user closes the app, stop the interaction.
-
In the
onCreate
callback, check whether the app has obtained the required permissions. If the permissions have not been granted, request the required permissions from the user. If permissions have been granted, initializeRtcEngine
and join a channel.
-
When a user closes the app, or switches the app to the background, call
leaveChannel
to leave the current channel and release all session-related resources.
Test the sample code
Take the following steps to test the sample code:
-
Enable developer options on your Android test device. Turn on USB debugging, connect the Android device to your development machine through a USB cable, and check that your device appears in the Android device options.
-
In Android Studio, click Sync Project with Gradle Files to resolve project dependencies and update the configuration.
-
After synchronization is successful, click Run app. Android Studio starts compilation. After a few moments, the app is installed on your Android device.
- Launch the App, grant the recording permission.
- On a second Android device, repeat the previous steps to install and launch the app. Test the following scenarios:
- If users on both devices join the channel as hosts, they can hear each other.
- If one user joins as host and the other as audience, the audience can hear the host.
Reference
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.
Next steps
After implementing the quickstart sample, read the following documents to learn more:
- The sample code in this document uses a temporary token to join a channel. To ensure communication security in a test or production environment, best practice is to obtain a token from an authentication server. For details, see Secure authentication with tokens.
Sample project
Agora provides open source sample projects on GitHub for your reference. Download or view the JoinChannelAudio project for a more detailed example.