本文介绍如何使用 Agora Unity SDK 快速实现语音通话。

快速跑通 Demo

如果你是第一次使用声网的服务,我们推荐观看下面的视频,了解关于声网服务的基本信息以及如何快速跑通 demo。

点击参与视频教程问卷调查,帮助我们改进体验。

视频中展示的 UI 可能有部分调整更新,请以当前最新版为准。

示例项目

Agora 在 Github 上提供开源的实时语音通话示例项目 Hello-Unity3D-Agora。在实现相关功能前,你可以下载并查看源代码。

前提条件

  • Unity 2017 或以上版本

  • 操作系统与编译器要求:

    开发平台 操作系统版本 编译器版本
    Android Android 4.1 或以上 Android Studio 2.0 或以上
    iOS iOS 8.0 或以上 Xcode 8.0 或以上
    macOS macOS 10.0 或以上 Xcode 8.0 或以上
    Windows Windows XP SP3 或以上 Visual Studio 2013 或以上
  • 有效的 Agora 账户App ID

如果你的网络环境部署了防火墙,请根据应用企业防火墙限制打开相关端口。

准备开发环境

本节介绍如何创建项目,将 Agora Unity SDK 集成进你的项目中。

创建 Unity 项目

参考以下步骤或 Unity 官方操作指南创建一个 Unity 项目。若已有 Unity 项目,可以直接查看集成 SDK

创建 Unity 项目
  1. 开始前确保你已安装 Unity。若未安装,点击此处下载。

  2. 打开 Unity,点击 New

  3. 依次填入以下内容后,点击 Create project

    • Project name:项目名称
    • Location:项目存储路径
    • Organization:组织名称
    • Template:项目类型。选择 3D

集成 SDK

选择如下任意一种方式将 Agora Unity SDK 集成到你的项目中。

方法一:使用 Unity Asset Store 自动集成

  1. Unity 中点击 Asset Store 栏,输入 Agora 搜索并选择 Agora Voice SDK for Unity
  2. 在 SDK 详情页中,点击页面右侧的 Download 按钮下载 SDK。
  3. 下载成功后,会出现 Import 按钮,点击查看可导入的内容。
  4. 取消勾选不需要的插件(默认勾选 SDK 包含的所有插件)。然后点击 Import

方法二:手动复制 SDK 文件

  1. 前往 SDK 下载页面,在语音通话/音频互动直播 SDK 中下载最新版的 Agora Unity SDK,然后解压。

  2. 在你的项目路径下,找到 Assets 文件夹,并在该文件夹中新建 Plugins 文件夹

  3. 将 SDK 包内 libs 路径下的如下文件,拷贝到你的项目路径下:

    开发平台 文件或文件夹 项目路径
    Android /Android/AgoraRtcEngineKit.plugin /Assets/Plugins/Android
    iOS /iOS/AgoraRtcEngineKit.framework /Assets/Plugins/iOS
    macOS /macOS/agoraSdkCWrapper.bundle /Assets/Plugins/macOS
    Windows /x86 /Assets/Plugins/x86
    Windows /x86_64 /Assets/Plugins/x86_64
    • 对于开发 Android 或 iOS 应用的用户,若需在 macOS 或 Windows 设备中使用 Unity Editor 调试,请确保放入上述 macOS 或 Windows 所需的文件或文件夹。
    • Android 平台集成时,还需要 AndroidManifest.xml 文件和 project.properties 文件来添加项目权限和项目属性,建议从示例项目中直接拷贝。
    • iOS 平台集成时,还需要如下操作:(你可以参考 BL_BuildPostProcess.cs 代码逻辑,或直接将该文件拷贝至你的项目路径下)
      • 链接系统库:
        • CoreTelephony.framework
        • libresolv.tbd
        • libiPhone-lib.a
        • CoreText.framework
        • CoreML.framework
        • Accelerate.framework
      • 申请权限:NSMicrophoneUsageDescription

实现语音通话

本节介绍如何实现语音通话。语音通话的 API 调用时序见下图:

1. 创建用户界面

根据场景需要,为你的项目创建语音通话的用户界面。若已有界面,可以直接查看获取设备权限(仅 Android 平台)初始化 IRtcEngine

在语音通话播中,Agora 推荐你添加如下 UI 元素:

  • 加入频道按钮
  • 退出频道按钮

2. 获取设备权限(仅 Android 平台)

仅 Android 平台需要设置此步骤,其他平台可以直接查看初始化 IRtcEngine

UNITY_2018_3_OR_NEWER 或以上版本中,Unity 不会主动向用户获取麦克风权限,需要用户调用 CheckPermission 方法获取权限。

#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) 
// 获取设备权限。 
CheckPermission(); 
#endif  
}

3. 初始化 IRtcEngine

在调用其他 Agora API 前,需要初始化 IRtcEngine 对象。

调用 GetEngine 方法,传入获取到的 App ID,即可初始化 IRtcEngine

如果你想退出应用或者释放 IRtcEngine 内存,需调用 Destroy 方法销毁 IRtcEngine。详见销毁 IRtcEngine

你还可以根据场景需要,在初始化时注册想要监听的回调事件,如本地用户加入频道,及解码远端用户音频首帧等。

// 填入 App ID 并初始化 IRtcEngine。 
mRtcEngine = IRtcEngine.GetEngine (appId); 
// 注册 OnJoinChannelSuccessHandler 回调。 
// 本地用户成功加入频道时,会触发该回调。
mRtcEngine.OnJoinChannelSuccessHandler = OnJoinChannelSuccessHandler; 
// 注册 OnUserJoinedHandler 回调。
// SDK 接收到第一帧远端音频并成功解码时,会触发该回调。
mRtcEngine.OnUserJoinedHandler = OnUserJoinedHandler; 
// 注册 OnUserOfflineHandler 回调。 
// 远端用户离开频道或掉线时,会触发该回调。
mRtcEngine.OnUserOfflineHandler = OnUserOfflineHandler;

4. 加入频道

初始化 IRtcEngine 后,你就可以调用 JoinChannelByKey 方法加入频道。你需要在该方法中传入如下参数:

  • channelKey:传入能标识用户角色和权限的 Token。可设为如下一个值:

    • NULL
    • 临时 Token。在安全要求一般的测试场景下,可使用临时 Token。你可以在控制台里生成一个临时 Token(服务有效期为 24 小时),详见获取临时 Token
    • 在你的服务器端生成的 Token。在安全要求高的场景下,Agora 推荐你使用此种方式生成的 Token,详见生成 Token
    若项目已启用 App 证书,请使用 Token。
  • channelName: 传入能标识频道的频道 ID。输入频道 ID 相同的用户会进入同一个频道。

  • uid: 本地用户的 ID。数据类型为整型,且频道内每个用户的 uid 必须是唯一的。若将 uid 设为 0,则 SDK 会自动分配一个 uid,并在 OnJoinChannelSuccessHandler 回调中报告。

// 加入频道。 
mRtcEngine.JoinChannelByKey(null, channel, null, 0);

5. 离开频道

根据场景需要,如结束通话或关闭 App 时,调用 LeaveChannel 离开当前通话频道。

public void leave()
    {
        Debug.Log ("calling leave");
        if (mRtcEngine == null)
            return;
        // 离开频道。
        mRtcEngine.LeaveChannel();
    }

6. 销毁 IRtcEngine

离开频道后,如果你想退出应用或者释放 IRtcEngine 内存,需调用 Destroy 方法销毁 IRtcEngine

void OnApplicationQuit()
{
    if (mRtcEngine != null)
    {
    // 销毁 IRtcEngine。
    IRtcEngine.Destroy();
    mRtcEngine = null;
    }
}

示例代码

你可以在 Hello-Unity3D-Agora 示例项目的 HelloUnity3D.cs 文件中查看完整的源码和代码逻辑。

运行项目

你可以在 Unity 中运行此项目。当成功开始语音通话时,你可以听到自己和远端用户的声音。