Use this guide to quickly start a basic one-to-one voice call with the Agora SDK for Unity.
The following figure shows the workflow of a voice call implemented by the Agora SDK.
As shown in the figure, the workflow for adding Voice Call in your project is as follows:
Retrieve a token
A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.
Join a channel
Call joinChannel
to create and join a channel. App clients that pass the same channel name join the same channel.
Publish and subscribe to audio in the channel
After joining a channel, the app client automatically publishes and subscribes to audio in the channel.
For an app client to join an RTC channel, you need the following information:
We provide an open-source Hello-Unity3D-Agora sample project on GitHub that implements the basic one-to-one voice call. You can also see how to run the sample project in Add voice chat to your Unity app on Android and iOS.
Unity 2017 or later
Operating system and IDE requirements:
Target Platform | Operating system version | IDE version |
---|---|---|
Android | Android 4.1 or later | Android Studio 3.0 or later |
iOS | iOS 9.0 or later | Xcode 9.0 or later |
macOS | macOS 10.10 or later | Xcode 9.0 or later |
Windows | Windows 7 or later | Microsoft Visual Studio 2017 or later |
A valid Agora account and an App ID
In this section, we create a Unity project and integrate the SDK into the project.
Use the following steps or follow the Unity official manual to build a project from scratch. Skip to Integrate the SDK if you have already created a Unity project.
Ensure that you have downloaded and installed Unity before the following steps. If not, click here to download.
Open Unity and click New.
Fill in and select the options in the following fields, and click Create project.
Choose either of the following approaches to integrate the Agora Unity SDK into your project.
Approach 1: Automatically integrate the SDK with Unity Asset Store
Approach 2: Manually add the SDK files
Go to SDK Downloads, download the Agora SDK for Unity under Voice SDK, and extract the files from the downloaded SDK package.
Copy the Plugins
subfolder from the samples/Hello-Unity3D-Agora/Assets/AgoraEngine
directory of the downloaded SDK to the Assets
subfolder of your project.
BL_BuildPostProcess.cs
file from the samples/Hello-Unity3D-Agora/Assets/AgoraEngine/Editor
directory.This section provides instructions on using the Agora Voice SDK for Unity to implement a basic one-to-one voice call, as well as an API call sequence diagram.
Create the user interface (UI) for a voice call in your project. If you already have one UI in your project, skip to Get the device permission (Android only) or Initialize IRtcEngine.
We recommend adding the following elements to the UI:
If you build for Android, you should add in APIs to check and request the device permission. For all other platforms, this is handled by the engine, and you can skip to Initialize IRtcEngine.
Unity versions later than UNITY_2018_3_OR_NEWER do not automatically request microphone permissions from your Android device. If you are using one of these versions, call the CheckPermission
method to request access to the microphone of your Android device.
#if(UNITY_2018_3_OR_NEWER)
using UnityEngine.Android;
#endif
void Start ()
{
#if(UNITY_2018_3_OR_NEWER)
permissionList.Add(Permission.Microphone);
#endif
}
private void CheckPermission()
{
#if(UNITY_2018_3_OR_NEWER)
foreach(string permission in permissionList)
{
if (Permission.HasUserAuthorizedPermission(permission))
{
}
else
{
Permission.RequestUserPermission(permission);
}
}
#endif
}
void Update ()
{
#if(UNITY_2018_3_OR_NEWER)
// Ask for your Android device's permissions.
CheckPermission();
#endif
}
Initialize the IRtcEngine
object before calling any other Agora APIs.
Call the GetEngine
method and pass in the App ID to initialize the IRtcEngine
object.
Listen for callback events, such as when the local user joins the channel, and when the first audio frame of a remote user is decoded.
// Pass an App ID to create and initialize an IRtcEngine object.
mRtcEngine = IRtcEngine.GetEngine (appId);
// Listen for the OnJoinChannelSuccessHandler callback.
// This callback occurs when the local user successfully joins the channel.
mRtcEngine.OnJoinChannelSuccessHandler = OnJoinChannelSuccessHandler;
// Listen for the OnUserJoinedHandler callback.
// This callback occurs when the first audio frame of a remote user is received and decoded after the remote user successfully joins the channel.
mRtcEngine.OnUserJoinedHandler = OnUserJoinedHandler;
// Listen for the OnUserOfflineHandler callback.
// This callback occurs when the remote user leaves the channel or drops offline.
mRtcEngine.OnUserOfflineHandler = OnUserOfflineHandler;
After initializing the IRtcEngine
object, you can call JoinChannelByKey
to join a channel. Set the following parameters when calling this method:
channelKey
: The token for identifying the role and privileges of a user. Set it as one of the following values:
channelKey
as "".channelName
: The unique name of the channel to join. Users that input the same channel name join the same channel.
uid
: Integer. The unique ID of the local user. If you set uid
as 0, the SDK automatically assigns one user ID and returns it in the OnJoinChannelSuccessHandler
callback.
// Join a channel.
mRtcEngine.JoinChannelByKey(null, channel, null, 0);
According to your scenario, such as when the call ends and when you need to close the app, call LeaveChannel
to leave the current call.
public void leave()
{
Debug.Log ("calling leave");
if (mRtcEngine == null)
return;
// Leave the channel.
mRtcEngine.LeaveChannel();
}
After leaving the channel, if you want to exit the app or release the memory of IRtcEngine
, call Destroy
to destroy the IRtcEngine
object.
void OnApplicationQuit()
{
if (mRtcEngine != null)
{
// Destroy the IRtcEngine object.
IRtcEngine.Destroy();
mRtcEngine = null;
}
}
Run the project in Unity. You can hear the voice of both the local and remote users when you successfully start a one-to-one voice call in the app.
When using the Agora Unity SDK, you can also use the dollowing documents as a reference: