Flutter集成Agora Video SDK锁屏后丢失视频连接问题求助

1. 申请必要的后台运行权限 #

Android 12以下系统对后台应用的资源限制更严格，需确保App获得足够权限维持网络连接：

• 在android/app/src/main/AndroidManifest.xml中添加权限：

  <!-- Android 8+前台服务权限 -->
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <!-- Android 9及以下唤醒锁权限 -->
  <uses-permission android:name="android.permission.WAKE_LOCK" />
  <!-- 忽略电池优化权限 -->
  <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
  

• 在代码中申请忽略电池优化（Android 6+适用）：

  import 'package:android_intent_plus/android_intent.dart';
  import 'package:package_info_plus/package_info_plus.dart';
  
  void requestIgnoreBatteryOptimizations() async {
    final packageName = (await PackageInfo.fromPlatform()).packageName;
    final intent = AndroidIntent(
      action: 'android.settings.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS',
      data: 'package:$packageName',
    );
    await intent.launch();
  }
  

• 视频通话期间启动前台服务，避免App被系统后台杀死。

2. 配置Agora SDK自动重连与状态监听 #

确保SDK在连接断开时自动重连，并手动处理异常场景：

• 初始化时开启自动重连：

  RtcEngineConfig config = RtcEngineConfig(appId);
  config.enableAutoReconnect = true;
  await RtcEngine.createWithConfig(config);
  

• 监听连接状态，断开时手动重新加入频道：

  _engine.setEventHandler(RtcEngineEventHandler(
    onConnectionStateChanged: (connectionState, reason) {
      if (connectionState == ConnectionStateType.disconnected || 
          connectionState == ConnectionStateType.failed) {
        // 携带原频道参数重新加入
        _engine.joinChannel(token, channelId, null, uid);
      }
    },
  ));
  

3. 监听Flutter应用生命周期，前台恢复时检查连接 #

App从锁屏状态回到前台时，主动检查连接状态，必要时重连：

class _VideoCallState extends State<VideoCall> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);
    if (state == AppLifecycleState.resumed) {
      _engine.getConnectionState().then((currentState) {
        if (currentState != ConnectionStateType.connected) {
          _engine.joinChannel(token, channelId, null, uid);
        }
      });
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }
}

4. 使用唤醒锁保持CPU活跃（Android 9及以下） #

针对Android 9及以下设备，获取唤醒锁防止CPU休眠，维持网络连接：

import 'package:flutter/services.dart';

const MethodChannel _wakelockChannel = MethodChannel('agora_wakelock');

void acquireWakeLock() async {
  await _wakelockChannel.invokeMethod('acquire');
}

void releaseWakeLock() async {
  await _wakelockChannel.invokeMethod('release');
}

对应Android原生代码（MainActivity.kt）：

class MainActivity : FlutterActivity() {
    private val CHANNEL = "agora_wakelock"
    private var wakeLock: PowerManager.WakeLock? = null

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler { call, result ->
            when (call.method) {
                "acquire" -> {
                    val powerManager = getSystemService(Context.POWER_SERVICE) as PowerManager
                    wakeLock = powerManager.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "AgoraCall::WakeLock")
                    wakeLock?.acquire()
                    result.success(null)
                }
                "release" -> {
                    wakeLock?.release()
                    result.success(null)
                }
                else -> result.notImplemented()
            }
        }
    }
}

5. 升级Agora Flutter SDK到最新版本 #

旧版本SDK可能存在Android 12以下的后台连接兼容性bug，建议升级至官方最新版agora_rtc_engine包。

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