迁移指南

声网 SDK v4.0.0 是一个新的 SDK 版本，可帮助用户将实时音视频功能集成到 App 中。在大规模的实时互动场景下，你可以用它实现更好的实时互动效果，详见产品概述。

本文介绍如何将 SDK 从 v3.x（指 v3.7.0.3 以及之前版本）升级至 v4.0.0。

迁移步骤

本节介绍将 SDK 从 v3.x 升级至 v4.0.0 的主要步骤。

1. 集成 SDK

在 v4.0.0 中，当你成功下载声网 Unity SDK 后可以看到一个 .unitypackage 的资源包，你可以直接在 Unity 编辑器中将其导入至你的项目中。成功导入后，你项目的 Assets 路径下会出现 Agora-RTC-Plugin 目录。

参考创建项目，将 v4.0.0 SDK 集成到你的项目中。

2. 更新 App 代码

v4.0.0 SDK 对部分功能的实现方式进行了优化或修改，从而导致与 v3.x 不兼容。为了继续使用 App 中已有的声网功能，请根据变更介绍更新 App 中的代码。

变更介绍

本节以 v3.x 为基础，按如下分类介绍 v4.0.0 相对于 v3.x 的主要变更，你需要结合实际业务场景更新 App 代码：

• 中断性变更：介绍影响较大的 API 兼容性变更，修改相关实现代码的预期耗时较多。
• 行为变更：介绍对 SDK 默认行为和 API 行为的合理优化造成的变更，无需修改相关实现代码或修改代码的预期耗时较少。
• 功能差距：介绍在 v3.x 中支持、但在 v4.0.0 中不支持的功能，这些功能会在后续版本中增加。
• 已删除 API：介绍在 v3.x 中支持、但在 v4.0.0 中删除了的 API，这些 API 大部分在 v4.0.0 中有替代方案，修改相关实现代码的预期耗时较少。
• 命名和数据类型变更：介绍主要 API 的命名和数据类型变更，你可以借助 IDE 的报错提示更新相关实现代码，预期耗时较少。

中断性变更

从 v3.x 升级至 v4.0.0 后，实现部分功能的 API 存在差异。本节介绍这些 API 的兼容性变更及 App 代码的更新逻辑。

多频道

在 v3.x 中，SDK 提供 AgoraChannel 类和 Channel 相关 delegate 实现多频道控制，支持订阅多个频道的音视频流，但只能选择一个频道发布一组音视频流。

在 v4.0.0 中：

• SDK 支持同时采集或同时发布多组音视频流。例如，同时发布多路摄像头采集或者屏幕共享的视频流。
• SDK 提供 IRtcEngineEx 类实现多频道功能：调用 JoinChannel 加入首个频道后，多次调用 JoinChannelEx 加入多个频道，通过不同的用户 ID (localUid) 和 ChannelMediaOptions 设置发布指定的流到不同的频道。
• 新增了 RtcConnection 二元组表示 JoinChannel 建立的连接，一个连接由频道名 (channelId) 和 localUid 确定。你可以通过 RtcConnection 控制不同连接的发布和订阅。所有带 connection 参数（对应 RtcConnection 类）的 API 命名中都增加了 Ex 以区分，并统一放在 IRtcEngineEx 类中，用于多流的扩展。

通过设置 ChannelMediaOptions，v4.0.0 支持一个 IRtcEngine 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如：

• 同时发布多路摄像头采集的视频流或者多路屏幕共享流
• 同时发布单路媒体播放器的视频流、屏幕共享流和摄像头采集的视频流
• 同时发布单路麦克风采集、自采集的音频流和媒体播放器的音频流

结合多频道能力，你还可以体验如下功能：

• 将多组音视频流通过不同的 localUid 发布到远端
• 将多路音频流混音后通过一个 localUid 发布到远端
• 将多路视频流合图后通过一个 localUid 发布到远端

v3.x 的 AgoraChannel 和 IRtcEngine 在功能上有部分重复、不够正交，因此在 v4.0.0 中隐藏了 AgoraChannel 类和 Channel 相关 delegate。你可以参考示例项目，用 JoinChannel 和 ChannelMediaOptions 替代 AgoraChannel，预计迁移成本在一天以内。如果你需要继续使用 AgoraChannel 和 Channel 相关 delegate，请联系技术支持，声网会根据反馈情况决定是否在后续版本中保持兼容。

媒体流发布控制

在 v4.0.0 中，将更多频道相关的设置都汇聚进了 ChannelMediaOptions，包括不同音视频流的发布、自动订阅、用户角色切换、Token 更新、默认大小流选项等。你可以在加入频道时通过 JoinChannel 或 JoinChannelEx 明确媒体流发布和订阅行为，也可以在加入频道后通过 UpdateChannelMediaOptions 动态更新频道中的媒体选项，例如切换视频源。

警告码

在 v3.x 中，SDK 通过 OnWarning 回调报告警告码。

为方便用户定位和排查问题，v4.0.0 通过 API 返回值或不同状态回调来报告问题和原因。例如：

• OnConnectionStateChanged：报告网络连接状态。
• OnLocalAudioStateChanged：报告本地音频状态。
• OnLocalVideoStateChanged：报告本地视频状态。
• OnRemoteAudioStateChanged：报告远端音频状态。
• OnRemoteVideoStateChanged：报告远端视频状态。

因此，v4.0.0 删除了 OnWarning 回调。

注意

除上述相对于 v3.x 的中断性变更以外，v4.0.0 对于 v4.0.0 Beta 也存在极少数中断性变更。例如在 v4.0.0 中，将 ChannelMediaOptions 中的 publishAudioTrack 替换为 publishMicrophoneTrack。 如果你在 v4.0.0 Beta 版本中使用了该功能、并且希望升级到 v4.0.0 版本，请在升级 SDK 后修改功能的实现。

行为变更

本节介绍由 v4.0.0 对 SDK 默认行为和 API 行为的合理优化造成的变更。

初始化引擎

在 v3.x 中，你可以使用 GetEngine (appId) 或 GetEngine(engineConfig) 方法获取 IRtcEngine 实例并初始化引擎。

在 v4.0.0 中，你可以使用 CreateAgoraRtcEngine 或 RtcEngine.Instance 方法来实例化 IRtcEngine，然后通过 Initialize 方法来初始化引擎，在初始化的同时你还可以通过 RtcEngineContext 来设置频道场景、音频应用场景、进行日志文件配置等。

注册回调事件

在 v3.x 中，你可以使用 C# delegate 注册的形式来注册回调事件。

在 v4.0.0 中，你依然可以使用 C# delegate 注册的形式来注册回调事件，delegate 被封装在 Agora.Rtc.RtcEngineEventHandler 中。除此之外，你还可以通过 InitEventHandler 来注册回调事件，你需要继承声网提供的事件基类并实现自己的 EventHandler 类，通过 InitEventHandler 方法将自己的 EventHandler 类实例注册给 SDK。

资源释放

如果你需要释放声网 Unity SDK 使用的所有资源：

在 v3.x 中，你需要调用 Destroy 方法来释放资源。

在 v4.0.0 中，你需要调用 Dispose 方法来释放资源。

频道场景

在 v3.x 中，默认的频道场景为 CHANNEL_PROFILE_COMMUNICATION（通信）。因为直播场景支持从一对一通话无缝切换到多人互动，所以声网自 v3.0.0 起将通信场景下内部的传输协议和弱网对抗能力改成与直播场景一致。

在 v4.0.0 中，声网也将默认的频道场景改成了 CHANNEL_PROFILE_LIVE_BROADCASTING（直播）。

默认日志文件

在 v3.x 中，有多个日志文件时，旧的文件会以 agorasdk_x.log 格式命名，例如 agorasdk_1.log。

在 v4.0.0 中, 修改命名格式为 agorasdk.x.log（例如 agorasdk.1.log）。此外，v4.0.0 新增了 agoraapi.log、agora_iris.log 记录 API 调用的日志。

快速切换频道

在 v3.x 中，你需要调用 SwitchChannel 实现快速切换频道。

在 v4.0.0 中，通过 LeaveChannel 和 JoinChannel 切换频道即可实现和 SwitchChannel 一样的切换速度，因此该版本删除了 SwitchChannel。如果你在 v3.x 中使用 SwitchChannel 切换频道，你需要在 v4.0.0 中先调用 LeaveChannel 离开当前频道，再调用 JoinChannel 加入第二个频道。

声网自研插件

v4.0.0 在 v4.0.0 Beta 的基础上新增了自动加载自研动态库功能。自该版本起，当你使用声网自研的插件时，不需要在项目中手动集成动态库，SDK 会在 IRtcEngine 初始化阶段自动加载动态库。你可以直接调用插件对应的方法即可开启该功能。

API	插件类型
EnableVirtualBackground	虚拟背景插件
SetBeautyEffectOptions SetVideoDenoiserOptions SetLowlightEnhanceOptions SetColorEnhanceOptions	视频增强插件
EnableRemoteSuperResolution	超分辨率插件
SetAudioEffectPreset SetVoiceBeautifierPreset SetVoiceConversionPreset	美声插件
EnableSpatialAudio	空间音频插件
EnableContentInspect	内容审核插件

音量提示

当你调用 EnableAudioVolumeIndication 方法并将 interval 参数设置为 > 0 时，可启用用户音量提示。在 v3.x 和 v4.0.0 中，interval 参数的定义存在差异：

• 在 v3.x 中：建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 OnAudioVolumeIndication 回调。
• 在 v4.0.0 中：该参数需要设为 200 的整数倍。如果取值低于 200，SDK 会自动调整为 200。

当启用音量提示回调后，SDK 会上报 OnAudioVolumeIndication 回调，如果本地用户将自己静音（调用了 MuteLocalAudioStream），在 v3.x 和 v4.0.0 中，SDK 的行为不一致：

• 在 v3.x 中：SDK 立即停止报告本地用户的音量提示回调。
• 在 v4.0.0 中：SDK 会继续报告本地用户的音量提示回调。此时，如果用户依旧开启了音频采集，AudioVolumeInfo 中 volume 的值表示本地音频采集信号的音量。

设备权限

• 在 v3.x 中，通过 OnLocalAudioStateChanged 中的 LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION 上报没有权限启动音频采集设备；通过 OnLocalVideoStateChanged 中的 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION 上报没有权限启动视频采集设备。

在 v4.0.0 中，统一通过 OnPermissionError 回调上报音视频采集设备的权限状态。

通话前网络测试

如果你需要开启或停止网络连接质量测试：

在 v3.x 中，你可以调用 EnableLastmileTest 开启网络质量测试，如果你想停止网络测试，需要调用 DisableLastmileTest。

在 v4.0.0 中，你可以调用 StartLastmileProbeTest 启用网络质量测试，如果你想停止网络测试，需要调用 StopLastmileProbeTest。

原始音视频数据

在 v3.x 中，你可以通过 VideoRawDataManager、AudioRawDataManager 类下的 API 来管理原始音视频数据。

在 v4.0.0 中，你可以调用 IRtcEngine 类中的 RegisterAudioFrameObserver 或 RegisterVideoFrameObserver 注册语音或视频观测器后，直接使用该类实现原始音视频数据观测；或者通过继承该类，自行实现原始音视频数据观测。

远端媒体事件触发机制

假设存在以下两种场景：

• 场景一：主播在频道外调用 MuteLocalAudioStream 或 MuteLocalVideoStream 改变本地音视频流的发布状态、然后加入频道。
• 场景二：主播在频道内调用 MuteLocalAudioStream 或 MuteLocalVideoStream 改变本地音视频流的发布状态，然后其他用户加入频道。

v3.7.0 和 v4.0.0 SDK 中存在以下行为差异：

• 在 v3.7.0 中，本地用户会收到 OnRemoteAudioStateChanged 或 OnRemoteVideoStateChanged 回调，报告远端主播的音视频流的状态变化。
• 在 v4.0.0 中，本地用户不会收到 OnRemoteAudioStateChanged 或 OnRemoteVideoStateChanged 回调，但是会收到 OnUserMuteAudio 或 OnUserMuteVideo 回调，报告远端主播的发流状态变化（即是否正在发布音视频流）。

频道媒体选项

在加入频道的同时设置频道媒体选项时，在 v3.7.0 和 v4.0.0 中，SDK 的行为存在以下差异：

• 在 v3.7.0 中，如果你将 ChannelMediaOptions 中的 publishLocalAudio 设置为 false，会停止在频道内发布本地音频流。
• 在 v4.0.0 中，如果你将 ChannelMediaOptions 中的 publishMicrophoneTrack 设置为 false，除了停止在频道内发布本地音频流以外，还会停止本地麦克风采集。

视频信息改变事件 (iOS)

如果在采集视频时调整视频采集设备为横屏或竖屏，在 v3.7.0 和 v4.0.0 中，SDK 上报的视频信息改变事件存在以下差异：

• 在 v3.7.0 中，OnVideoSizeChanged 回调中的 rotation 参数会显示当前设备的旋转信息。
• 在 v4.0.0 中，OnVideoSizeChanged 回调中的 rotation 参数始终为 0。

功能差距

本节介绍在 v3.x 中支持、但在 v4.0.0 中不支持或行为不一致的功能，这些功能会在后续版本中支持或改为一致。

音频应用场景

v4.0.0 重构了音频应用场景，可以替代大部分 v3.x 的音频应用场景。下表展示了两个版本中音频应用场景的对应关系：

v3.x	v4.0.0
AUDIO_SCENARIO_DEFAULT	AUDIO_SCENARIO_DEFAULT
AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT	AUDIO_SCENARIO_CHATROOM
AUDIO_SCENARIO_EDUCATION	AUDIO_SCENARIO_DEFAULT
AUDIO_SCENARIO_GAME_STREAMING	AUDIO_SCENARIO_GAME_STREAMING
AUDIO_SCENARIO_SHOWROOM	AUDIO_SCENARIO_DEFAULT
AUDIO_SCENARIO_CHATROOM_GAMING	AUDIO_SCENARIO_CHATROOM
AUDIO_SCENARIO_IOT	AUDIO_SCENARIO_DEFAULT
AUDIO_SCENARIO_MEETING	AUDIO_SCENARIO_MEETING

不支持功能

相比于 v3.x，某些功能在 v4.0.0 中不支持或仅支持部分。本节展示尚未支持的 API，这些 API 会在后续版本中支持。

远端视频流回退：

• SetRemoteUserPriority

屏幕共享：

• OnScreenCaptureInfoUpdated

已删除 API

v4.0.0 中，删除了已废弃或不推荐使用的 类和 API。已删除 API 的替代方案或删除原因展示如下：

• VideoRawDataManager：使用 IVideoFrameObserver 类下的相关 API 替代。

• AudioRawDataManager：使用 IAudioFrameObserver 类下的相关 API 替代。

• PacketObserver：在 v3.x 中很少使用。

• EnableFilpTextureApply：推荐自行实现。

• SetGameFps：推荐自行实现。

• VirtualBackgroundSourceEnabled：使用 EnableVirtualBackground 的返回值替代。

• OnUserSuperResolutionEnabled：使用 OnRemoteVideoStats 回调的 superResolutionType 成员替代。

• SetExternalAudioSourceVolume：使用 AdjustCustomAudioPublishVolume 替代。

• GetAudioFileInfo 和 OnRequestAudioFileInfo：使用 GetDuration 替代。

• OnAudioDeviceTestVolumeIndication：由 OnAudioVolumeIndication 替代。

• SetLocalPublishFallbackOption 和 OnLocalPublishFallbackToAudioOnly：在 v3.x 中很少使用。

• RENDER_MODE_TYPE 中的 RENDER_MODE_FILL(4)：该模式可能造成图片过度拉伸，不推荐使用。

• AUDIO_MIXING_REASON_TYPE 中的以下枚举：在 v3.x 中应用场景很少。

  • AUDIO_MIXING_REASON_STARTED_BY_USER
  • AUDIO_MIXING_REASON_START_NEW_LOOP
  • AUDIO_MIXING_REASON_PAUSED_BY_USER
  • AUDIO_MIXING_REASON_RESUMED_BY_USER

• OnAudioMixingFinished: 使用 OnAudioMixingStateChanged 替代。

• EnableDeepLearningDenoise：AI 降噪将在后续版本改由 SDK 控制，不通过 API 实现。

• TakeSnapshot 和 OnSnapshotTaken 中的 channel 参数：冗余参数。

• SetDefaultMuteAllRemoteVideoStreams：由 ChannelMediaOptions 中的 autoSubscribeVideo 替代。

• SetDefaultMuteAllRemoteAudioStreams：由 ChannelMediaOptions 中的 autoSubscribeAudio 替代。

• LOCAL_VIDEO_STREAM_ERROR 中的 LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED：该枚举在 v3.x 已废弃。

• StartAudioMixing 中的 replace 参数：由 ChannelMediaOptions 中的 publishMicrophoneTrack 替代。

命名和数据类型变更

v4.0.0 的命名和数据类型变更会在你编译项目时引入 IDE 的报错提示，你需要根据提示更新 App 代码。

相较于 v3.x，v4.0.0 中主要的命名变更如下：

命名空间变更

• namespace agora_gaming_rtc 变更为 namespace Agora.Rtc

类名变更

• AudioPlaybackDeviceManager 和 AudioRecorderDeviceManager 合并为 IAudioDeviceManager
• VideoDeviceManager 变更为 IVideoDeviceManager
• MediaRecorder 变更为 IMediaRecorder
• MetadataObserver 变更为 IMetadataObserver
• AgoraCallback 变更为 IRtcEngineEventHandler

API 及参数名变更

• AdjustLoopbackRecordingSignalVolume 变更为 AdjustLoopbackSignalVolume
• OnFirstLocalAudioFrame 变更为 OnFirstLocalAudioFramePublished
• LogConfig 中的 fileSize 成员变更为 fileSizeInKB
• JoinChannel[2/2] 中的 options 参数变更为 mediaOptions
• EnableAudioVolumeIndication 中的 report_vad 参数变更为 reportVad