Keep Agora Calls Alive In Background & Closed Flutter Apps

Hey guys! Ever been in a super important Agora call in your Flutter app, and then, poof – the audio cuts out the second you background or close the app? Annoying, right? You're not alone! Many Flutter developers face this issue, and the good news is, there are solutions! This guide dives deep into keeping your Agora calls alive and kicking, even when your app is chilling in the background or completely closed. We'll cover the core problems, explore the how-to, and make sure those calls keep running smoothly.

The Problem: Agora Calls and Flutter's Lifecycle

Okay, so what's the deal? Why does the audio drop when the app goes into the background or is closed? It all boils down to how Flutter and the operating systems (iOS and Android) handle app lifecycles and background processes. When your Flutter app isn't actively in the foreground, the operating system can be pretty aggressive about conserving resources, which means it might suspend or even terminate background tasks – like your ongoing Agora audio stream. This is especially true if your app isn't explicitly designed to handle background operations.

Here’s a breakdown of the common issues:

• App Lifecycle: Flutter apps have different states: active (foreground), inactive, paused, and resumed. When an app enters the background (inactive or paused), the OS starts optimizing resources. If not handled correctly, this can disrupt the Agora connection.
• Resource Management: Both iOS and Android have mechanisms to manage system resources. Background apps are often given lower priority, leading to potential termination if they consume too much power or memory.
• Lack of Background Services: Without proper configuration, your Flutter app may not be able to run background services, which are critical for maintaining continuous audio streams. The OS might kill the process when you background or close the app.
• Notification Absence: The lack of an “ongoing call” notification is also a problem. Users need a clear indication that a call is still active, especially when the app isn’t visible. Without a notification, they might assume the call has ended.

Essentially, the default behavior of Flutter apps, when not specifically configured, is to pause or terminate background processes. Agora, like many real-time communication SDKs, needs to keep the audio stream active and manage the connection, even when the app isn't in the foreground. So, without proper implementation, the call will disconnect.

Solution Breakdown: Keeping the Call Alive

So, how do we fix it? The key is to implement strategies that allow your Flutter app to continue running essential tasks, like the Agora audio stream, even in the background. Here's a comprehensive breakdown of the key steps:

1. Background Service Initialization (Android)

Android requires you to explicitly declare background services. This ensures that the OS knows that your app needs to continue operating even when the user isn’t actively interacting with it. You can achieve this using plugins like flutter_background_service. This approach is crucial because it allows your app to bypass the operating system's default behavior, which might otherwise shut down the audio stream when the app goes into the background or is closed. This means your users can continue participating in calls without interruptions.

• Installation: Add the flutter_background_service and flutter_local_notifications packages to your pubspec.yaml file and run flutter pub get.

  dependencies:
    flutter_background_service: ^4.0.0
    flutter_local_notifications: ^14.0.0
  

• Service Configuration: Set up the background service. This usually involves creating a service that runs in the background and handles the Agora SDK's audio streaming.

  import 'dart:ui';
  import 'package:flutter_background_service/flutter_background_service.dart';
  import 'package:flutter_local_notifications/flutter_local_notifications.dart';
  
  Future<void> initializeService() async {
    final service = FlutterBackgroundService();
    await service.configure( 
      androidConfiguration: AndroidConfiguration(
        onStart: onStart,
        autoStart: true,
        isForegroundMode: true,
      ),
      iosConfiguration: IosConfiguration(
        onForeground: onStart,
        onBackground: onIosBackground,
        isPersistent: true,
      ),
    );
  }
  
  @pragma('vm:entry-point')
  void onStart(ServiceInstance service) async {
    DartPluginRegistrant.ensureInitialized();
    // For Android, set up foreground notification
    var flutterLocalNotificationsPlugin = FlutterLocalNotificationsPlugin();
    const AndroidNotificationDetails androidPlatformChannelSpecifics = AndroidNotificationDetails(
      'your_channel_id', 
      'your_channel_name', 
      importance: Importance.max, 
      priority: Priority.high, 
      ongoing: true, // Make it ongoing
    );
    const NotificationDetails platformChannelSpecifics = NotificationDetails(android: androidPlatformChannelSpecifics);
    
    service.on('stopService').listen((event) {
      service.stopSelf();
    });
  
    service.on('updateNotification').listen((event) async {
      await flutterLocalNotificationsPlugin.show(0, 'Ongoing Call', 'Call in progress...', platformChannelSpecifics);
    });
  
    await flutterLocalNotificationsPlugin.show(0, 'Ongoing Call', 'Call in progress...', platformChannelSpecifics);
  }
  
  @pragma('vm:entry-point')
  Future<bool> onIosBackground(ServiceInstance service) async {
    WidgetsFlutterBinding.ensureInitialized();
    return true;
  }
  

• Starting the Service: Start the background service when the app enters the background or when the user initiates a call.

  await initializeService();
  FlutterBackgroundService().startService();
  

2. Foreground Notifications

To provide users with a clear indication that a call is still active, you absolutely need to display a persistent notification. This notification should show details such as call status. This ensures that users always know that their call is ongoing, even when the app is in the background or closed. This can be achieved using the flutter_local_notifications plugin, as shown in the example code above. It's a crucial part of the user experience, ensuring the user doesn't wonder if they are still connected and is kept informed.

• Persistent Notification: Create a notification that displays information about the ongoing call (e.g., call duration, participant names).
• Updating the Notification: Update the notification with relevant information to reflect the current status of the call.
• Integration: Integrate the notification with the background service.

3. iOS Configuration

For iOS, you will need to add the UIBackgroundModes key to your Info.plist. This tells iOS that your app requires background audio capabilities, helping to keep the Agora call active. The Info.plist file is a crucial part of your iOS app, and modifying it correctly is essential for ensuring your app works correctly on Apple devices. It is very important.

• Edit Info.plist: Open your iOS project's Info.plist file. You can find this inside your ios/Runner/ directory. If you are not familiar with the Info.plist file, it is where you provide important information to the iOS operating system.

• Add UIBackgroundModes Key: Add the UIBackgroundModes key to your Info.plist file. If the key already exists, then skip this step. This is done by adding the following code inside the <dict> tag:

  <key>UIBackgroundModes</key>
  <array>
    <string>audio</string>
  </array>
  

• Explanation: By including audio in the UIBackgroundModes array, you signal to iOS that your application needs to continue audio processing even when it's in the background. Without this, iOS will likely terminate the audio stream when your app transitions to the background.

4. Agora SDK Integration

Properly integrating the Agora SDK is crucial for managing the audio stream and connection status. Make sure the Agora SDK is initialized correctly and that you are handling the connection events such as onUserOffline and onJoinChannelSuccess to monitor the call's status. For this, it is necessary to:

• SDK Initialization: Initialize the Agora SDK and join the channel when the app starts or when the user initiates a call.
• Event Handling: Implement the necessary event handlers to manage the audio stream and connection status.
• Error Handling: Implement error handling to gracefully handle any disruptions to the audio stream or connection, such as network issues.

5. Handling App Lifecycle Events

Flutter provides lifecycle events you can use to manage the Agora connection based on the app's state. When the app is backgrounded, you'll need to prepare the system for the background tasks. When the app is foregrounded again, you might need to re-establish the connection. The code samples for each platform will provide a clearer understanding, but the main thing is that it is very important to use the lifecycle events in your app.

• WidgetsBindingObserver: Use WidgetsBindingObserver to monitor app lifecycle changes.
• Lifecycle Events: Implement the didChangeAppLifecycleState method to handle changes in the app's state.
• Connection Management: Within didChangeAppLifecycleState, handle Agora connection appropriately.

6. Testing and Debugging

Thorough testing is absolutely essential to ensure that your background call functionality works as expected. This involves testing on various devices, iOS and Android versions, and network conditions to identify and fix any potential problems. This helps ensure that the app behaves correctly in all scenarios.

• Testing on Real Devices: Test your app on both iOS and Android devices.
• Network Conditions: Simulate various network conditions to test the app's resilience.
• Debugging Tools: Use debugging tools to monitor the app's behavior and identify any potential issues.

Example Code Snippets

Here's a simplified example of how you can implement these features. Remember that the code needs to be adapted to fit your specific Agora setup and app design. I will show a complete example for Android and iOS.

// Android - MainActivity.kt
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugins.GeneratedPluginRegistrant

class MainActivity: FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        GeneratedPluginRegistrant.registerWith(flutterEngine)
    }
}

// iOS - AppDelegate.swift
import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

// Flutter Code Example: Lifecycle Observer and Background Service
import 'package:flutter/material.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_background_service/flutter_background_service.dart';
import 'package:agora_rtc_engine/agora_rtc_engine.dart';

class AgoraCallScreen extends StatefulWidget {
  @override
  _AgoraCallScreenState createState() => _AgoraCallScreenState();
}

class _AgoraCallScreenState extends State<AgoraCallScreen> with WidgetsBindingObserver {
  late RtcEngine _engine;
  String _channelName = 'your_channel_name';
  String _appId = 'your_app_id';
  String _token = 'your_token'; // Or null if you're not using tokens
  bool _isCallActive = false;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _initializeAgora();
  }

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

  Future<void> _initializeAgora() async {
    _engine = createAgoraRtcEngine();
    await _engine.initialize(const RtcEngineContext(appId: _appId));
    _engine.registerEventHandler(RtcEngineEventHandler(
      onJoinChannelSuccess: (connection, elapsed) {
        setState(() {
          _isCallActive = true;
        });
        print('joinChannelSuccess ${connection.channelId}');
      },
      onUserOffline: (connection, remoteUid, reason) {
        print('userOffline ${remoteUid}');
      },
    ));
  }

  Future<void> _joinChannel() async {
    await _engine.joinChannel(token: _token, channelId: _channelName, uid: 0, options: null);
  }

  Future<void> _leaveChannel() async {
    await _engine.leaveChannel();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);

    if (state == AppLifecycleState.paused) {
      // App is in the background
      _startBackgroundService();
    } else if (state == AppLifecycleState.resumed) {
      // App is back in the foreground
      _stopBackgroundService();
    }
  }

  Future<void> _startBackgroundService() async {
    await initializeService();
    FlutterBackgroundService().startService();
  }

  Future<void> _stopBackgroundService() async {
    FlutterBackgroundService().invoke('stopService');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Agora Call')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(
              onPressed: _isCallActive ? _leaveChannel : _joinChannel,
              child: Text(_isCallActive ? 'Leave Call' : 'Join Call'),
            ),
          ],
        ),
      ),
    );
  }
}

Remember to replace 'your_channel_name', 'your_app_id', and 'your_token' with your actual Agora credentials. Also, ensure you have set up the Android background service and the iOS Info.plist configuration as described earlier.

Best Practices and Tips

• Test Thoroughly: Test on various devices, especially the older ones and newer ones, and operating system versions, to guarantee compatibility.
• Handle Network Issues: Implement robust error handling to deal with network interruptions, and reconnect the call automatically if possible.
• Battery Optimization: Be mindful of battery usage. The flutter_background_service package offers options to control how the service behaves in the background to minimize battery drain.
• User Experience: Design the notification to be clear and not intrusive, providing essential call information.

Conclusion: Keeping the Conversation Going

By implementing these strategies, you can keep your Agora calls alive and working when your Flutter app is in the background or closed. Remember that handling the background state is a critical step in providing a seamless user experience, allowing users to continue their audio calls without interruption, and keeping them connected no matter what state their app is in. Good luck, and happy coding!