Unity(C#) 快速开始与功能指南
Unity(C#):前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障;接口名与签名在构建时取自公开 SDK 接口定义。
Unity 端是 C# 的 RtcEngine + IRtcEngineEventHandler 形状,方法名首字母大写(Initialize、JoinChannel、OnUserJoined)——与声网 Unity 对齐基准一致。
前置条件
- Unity 2022.3 LTS+(IL2CPP 与 Mono 均可)。
- 平台权限:Android 的
CAMERA/RECORD_AUDIO、iOS 的 usage description、Windows/macOS 的系统摄像头权限。 - 已拿到
appId与 Token 服务(见 控制台开通服务与获取凭证)。
安装
计划发布形态:
1) UPM:Packages/manifest.json 里加 "com.nimeet.rtc": "file:../ni-meet/sdk/unity"
2) 或导入 .unitypackage(Assets/Nimeet/Rtc)
Unity SDK 的安装与版本信息以发布包为准;本页示例按公开接口编写。获取 Token
Token 由游戏后端签发;Unity 客户端只拿字符串。不要把 App Certificate 写进客户端。 生产建议:登录时后端下发短期 Token,并在 OnTokenPrivilegeWillExpire 里向同一后端续期。
加入频道
using Nimeet.Rtc;
public class MeetingController : MonoBehaviour, IRtcEngineEventHandler
{
private IRtcEngine engine;
void Start()
{
engine = RtcEngine.CreateAgoraRtcEngine();
var context = new RtcEngineContext { appId = AppConfig.AppId, eventHandler = this };
engine.Initialize(context);
engine.SetChannelProfile(ChannelProfileType.ChannelProfileLiveBroadcasting);
engine.EnableVideo();
engine.StartPreview();
var options = new ChannelMediaOptions
{
clientRoleType = ClientRoleType.ClientRoleBroadcaster,
autoSubscribeAudio = true,
autoSubscribeVideo = true,
};
engine.JoinChannel(AppConfig.RtcToken, "weekly-sync", 10001, options);
}
public void OnJoinChannelSuccess(RtcConnection connection, int elapsed) => Debug.Log("joined");
public void OnUserJoined(RtcConnection connection, int remoteUid, int elapsed) { }
public void OnUserOffline(RtcConnection connection, int remoteUid, UserOfflineReasonType reason) { }
public void OnTokenPrivilegeWillExpire(string token) { engine.RenewToken(FetchFreshToken()); }
public void OnError(int err, string msg) => Debug.LogError($"rtc {err}: {msg}");
void OnDestroy() => RtcEngine.Destroy();
}发布与订阅
engine.MuteLocalAudioStream(true);
engine.MuteLocalVideoStream(true);
engine.EnableLocalVideo(false);
engine.UpdateChannelMediaOptions(options);屏幕共享:GetScreenCaptureSources 枚举源 → StartScreenCaptureByDisplayId / StartScreenCaptureByWindowId; Unity 里通常把共享画面渲染到 RawImage(纹理回调),而不是 VideoSurface。
事件
IRtcEngineEventHandler 接口在 C# 里显式实现:OnJoinChannelSuccess、OnUserJoined、OnUserOffline、 OnFirstRemoteVideoDecoded、OnTokenPrivilegeWillExpire、OnError、OnConnectionStateChanged。
错误处理
- 同步方法返回
int,0成功,负值为声网错误号; - 异步错误走
OnError; - 未实现能力返回
-4(ERR_NOT_SUPPORTED)。
排障
| 现象 | 原因 | 处理 |
|---|---|---|
| IL2CPP 构建后崩溃 | 原生库未打进包 | 检查 Plugins/<platform> 是否包含对应 ABI |
| 编辑器里正常、真机黑屏 | 权限未申请 | 真机首次启动时申请摄像头/麦克风 |
| 回调里操作 UI 报错 | 非主线程 | 入队后在 Update() 处理 |
| Android 上画面倒置 | 前置摄像头镜像 | 用 VideoCanvas.mirrorMode 调整 |
| 帧率低 | 编码参数过高 | 降 SetVideoEncoderConfiguration 分辨率/帧率 |
下一步
平台信息
| 项 | 值 |
|---|---|
| 平台 | Unity(C#) |
| 语言 | C# |
| SDK 包 | Nimeet.Rtc |
| 接口版本 | 4.6.2 |
| 兼容参考 | 声网 unity 端 API |
本端公开接口与声网 unity 端 API 对齐;安装与运行要求见上面前置条件。
可用性
该端 SDK:正式可用。本页代码片段使用公开 API;运行时的能力边界以实际发布的 SDK 包为准。
加入频道链路
下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载,这里展示最常用的那一个;完整重载见同端 API 参考页。
| 步骤 | 接口 | 方法 | 重载数 |
|---|---|---|---|
| 订阅远端媒体 | IBaseSpatialAudioEngine | MuteRemoteAudioStream | 1 |
| 创建实例 / 初始化 | ILocalSpatialAudioEngine | Initialize | 1 |
| 续期 Token | IMusicContentCenter | RenewToken | 1 |
| 开启视频与本地预览 | IRtcEngine | EnableVideo | 1 |
| 加入频道 | IRtcEngine | JoinChannel | 2 |
| 离开频道 | IRtcEngine | LeaveChannel | 2 |
| 频道场景 | IRtcEngine | SetChannelProfile | 1 |
| 切换角色 | IRtcEngine | SetClientRole | 2 |
| 绑定本地画面 | IRtcEngine | SetupLocalVideo | 1 |
MuteRemoteAudioStream(uid: uint, mute: bool): int
Initialize(): int
RenewToken(token: string): int
EnableVideo(): int
JoinChannel(token: string, channelId: string, info?: string, uid?: uint): int
LeaveChannel(): int
SetChannelProfile(profile: CHANNEL_PROFILE_TYPE): int
SetClientRole(role: CLIENT_ROLE_TYPE): int
SetupLocalVideo(canvas: VideoCanvas): int事件与回调
该端 SDK 没有事件回调。
错误码
| 常量 | 值 |
|---|---|
ERR_ABORTED | 20 |
ERR_ADM_GENERAL_ERROR | 1005 |
ERR_ADM_INIT_PLAYOUT | 1008 |
ERR_ADM_INIT_RECORDING | 1011 |
ERR_ADM_START_PLAYOUT | 1009 |
ERR_ADM_START_RECORDING | 1012 |
ERR_ADM_STOP_PLAYOUT | 1010 |
ERR_ADM_STOP_RECORDING | 1013 |
ERR_ALREADY_IN_USE | 19 |
ERR_BITRATE_LIMIT | 115 |
ERR_BUFFER_TOO_SMALL | 6 |
ERR_CLIENT_IS_BANNED_BY_SERVER | 123 |
ERR_CONNECTION_INTERRUPTED | 111 |
ERR_CONNECTION_LOST | 112 |
ERR_DATASTREAM_DECRYPTION_FAILED | 122 |
ERR_DECRYPTION_FAILED | 120 |
ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH | 130 |
ERR_FAILED | 1 |
ERR_INIT_NET_ENGINE | 21 |
ERR_INVALID_APP_ID | 101 |
ERR_INVALID_ARGUMENT | 2 |
ERR_INVALID_CHANNEL_NAME | 102 |
ERR_INVALID_STATE | 8 |
ERR_INVALID_TOKEN | null |
ERR_INVALID_USER_ACCOUNT | 134 |
ERR_INVALID_USER_ID | 121 |
ERR_JOIN_CHANNEL_REJECTED | 17 |
ERR_LEAVE_CHANNEL_REJECTED | 18 |
ERR_LOAD_MEDIA_ENGINE | 1001 |
ERR_NOT_INITIALIZED | 7 |
ERR_NOT_IN_CHANNEL | 113 |
ERR_NOT_READY | 3 |
ERR_NOT_SUPPORTED | 4 |
ERR_NO_PERMISSION | 9 |
ERR_NO_SERVER_RESOURCES | 103 |
ERR_OK | 0 |
ERR_PCMSEND_BUFFEROVERFLOW | 201 |
ERR_PCMSEND_FORMAT | 200 |
ERR_REFUSED | 5 |
ERR_RESOURCE_LIMITED | 22 |
ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED | 119 |
ERR_SIZE_TOO_LARGE | 114 |
ERR_STREAM_MESSAGE_TIMEOUT | 117 |
ERR_TIMEDOUT | 10 |
ERR_TOKEN_EXPIRED | 109 |
ERR_TOO_MANY_DATA_STREAMS | 116 |
ERR_VDM_CAMERA_NOT_AUTHORIZED | 1501 |
IRtcEngine | null |
平台 REST 层用 REST 错误码;SDK 层把连接/鉴权失败映射成声网错误号,映射表见 各端 SDK 错误标识。