Agora Flutter 中如何适配新版Token机制将用户加入同一频道开展视频通话

新版Agora RTC强制开启Token鉴权的前提下，同一频道内所有连通用户必须满足：共用同一App ID、同一频道名、搭配对应生成的有效Token，且每个用户的uid全局唯一。

前置准备 #

• 在Agora控制台完成项目创建，开启Token鉴权，保存对应的App ID与App Certificate
• 在pubspec.yaml中添加官方agora_rtc_engine依赖，导入对应SDK的dart包

核心实现步骤 #

1. Token的生成与分发（核心要求） #

App Certificate仅用于服务端生成Token，严禁暴露在Flutter端代码中，避免鉴权凭证泄露。分两种场景处理：

• 测试阶段：可直接在Agora控制台的临时Token生成工具中，输入对应App ID、目标频道名生成临时Token，生成时可选择不绑定特定用户uid，这样所有进入该频道的测试用户都可以使用这个Token完成鉴权；该方案仅适合短周期测试，Token默认24小时过期，无法用于正式生产环境
• 生产环境：部署自有Token生成服务，基于官方提供的Token生成能力封装后端接口，入参为频道名、可选的用户uid，返回对应有效期的Token；Flutter端发起进频道请求前，先调用自有后端接口拉取对应频道的有效Token，再执行进频道操作。如果需要放开多用户同频道的接入权限，生成Token时不绑定特定uid即可；如果需要做严格的用户权限校验，可在生成Token时绑定对应用户的uid，只有该uid的用户能凭Token进入频道。

2. Flutter端RtcEngine初始化 #

初始化时选择通信场景，开启音视频采集能力，示例核心代码：

// 初始化RtcEngine
final engine = await RtcEngine.createWithContext(RtcEngineContext(appId: '你的项目App ID'));
// 配置为1v1/多人通信场景
await engine.setChannelProfile(ChannelProfile.Communication);
// 开启视频能力
await engine.enableVideo();
// 配置本地视频渲染控件，实现本地预览
await engine.setupLocalVideo(VideoCanvas(view: localVideoViewWidget, uid: 0));

3. 加入频道的参数配置 #

进频道时必须传入从后端获取的、与当前频道名匹配的有效Token，所有进同一频道的用户需保持频道名完全一致，示例核心代码：

await engine.joinChannel(
  token: '从自有后端拉取的、匹配当前频道名的有效Token',
  channelId: '所有用户共用的同个频道名称',
  uid: '当前用户的全局唯一id（若传0则由Agora自动分配uid）',
  options: const ChannelMediaOptions(
    autoSubscribeAudio: true, // 自动订阅远端音频
    autoSubscribeVideo: true, // 自动订阅远端视频
    publishCameraTrack: true, // 主动推自己的摄像头流
    publishMicrophoneTrack: true, // 主动推自己的麦克风流
  ),
);

4. 稳定连接保障逻辑 #

这是避免通话中断的关键，必须监听三个核心SDK事件做对应处理：

• 监听onTokenPrivilegeWillExpire回调：当SDK检测到Token即将过期时，触发回调重新从后端拉取对应频道的新Token，调用renewToken方法更新SDK内的凭证，避免因Token过期被踢出频道
• 监听onConnectionStateChanged回调：当连接状态变为断开、重连中等异常状态时，做对应的UI提示，重连成功后重新校验Token有效性，必要时刷新Token
• 监听远端用户事件：通过onUserJoined回调拿到远端用户的uid后，为对应uid绑定远端视频渲染控件，实现远端画面的正常展示

示例事件监听代码：

engine.registerEventHandler(
  RtcEngineEventHandler(
    // Token即将过期时自动续期
    onTokenPrivilegeWillExpire: (oldToken) async {
      final newToken = await requestNewTokenFromOwnBackend(channelName: '当前用户所在的频道名');
      await engine.renewToken(newToken);
    },
    // 连接状态变化处理
    onConnectionStateChanged: (state, reason) {
      if (state == ConnectionState.Disconnected) {
        // 触发UI展示网络断开提示
      }
    },
    // 远端用户加入时绑定视频渲染
    onUserJoined: (remoteUid, elapsed) {
      engine.setupRemoteVideo(VideoCanvas(view: getRemoteVideoWidget(remoteUid), uid: remoteUid));
    },
  ),
);

多用户同频道连通的注意事项 #

• 同一频道内所有用户的uid不能重复，若出现同uid的用户加入，后加入的用户会将前者踢出频道
• 不要在同一个物理设备上同时运行两个进同一频道的测试实例，会因为摄像头、麦克风硬件冲突导致音视频采集失败
• 弱网环境下可适当降低视频编码分辨率与帧率，配合Agora默认的弱网对抗能力，保障通话稳定性

内容的提问来源于stack exchange，提问作者Yahya