Интеграция Agora SDK для видеозвонков в мобильном приложении

В видеозвонках на мобильных платформах главные проблемы — lifecycle и управление токенами. Без правильной настройки получаете утечки ресурсов, обрывы сессий и перерасход лицензий. Наш опыт более 30 проектов с Agora SDK позволил сформулировать рабочий подход.

Почему Agora SDK — лучший выбор для видеозвонков?

Agora SDK — managed-сервис real-time видео и аудио, который берёт на себя WebRTC под капотом, собственную транспортную сеть SD-RTN, адаптивный битрейт и кодеки. В сравнении с raw WebRTC: Agora ускоряет разработку видеозвонков в 12 раз (с 3 месяцев до 1 недели), но требует грамотного токен-менеджмента. Правильная интеграция даёт сокращение расходов на инфраструктуру до 40% за счёт использования SD-RTN.

Как правильно настроить токены и избежать ошибок?

Agora работает по модели App ID + Token. App ID — публичный идентификатор из консоли. Token — короткоживущий JWT, который ваш бэкенд генерирует через Agora Token Builder и передаёт клиенту при входе в канал. Самые частые ошибки в продакшене: tokenExpired (109) и invalidToken (110). Token имеет ограниченный TTL (от 24 часов до 1 часа). Реализуем обработку через tokenPrivilegeWillExpire делегатный метод — получаем новый токен с бэкенда и вызываем renewToken() без разрыва соединения.

Типичная ошибка: токен генерируется с UID 0 на бэкенде, но клиент после joinChannel получает конкретный UID от Agora — и при следующем renewToken передаёт токен под неправильный UID. Решение: сохраняем UID из didJoinChannel и используем его при запросе нового токена.

Инициализация движка

Инициализируйте движок один раз при старте приложения:

let config = AgoraRtcEngineConfig()
config.appId = "YOUR_APP_ID"
agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)

val config = RtcEngineConfig()
config.mContext = context
config.mAppId = "YOUR_APP_ID"
config.mEventHandler = handler
rtcEngine = RtcEngine.create(config)

Не создавайте движок заново под каждый звонок. sharedEngine — синглтон, повторный вызов с тем же App ID возвращает существующий экземпляр. На Android RtcEngine.create() каждый раз создаёт новый экземпляр; предыдущий нужно уничтожить через RtcEngine.destroy(). Иначе утечка нативных ресурсов проявляется через 3–5 звонков. Используйте LifecycleObserver для автоматического уничтожения движка при завершении активности.

Подключение к каналу и обработка видео

let option = AgoraRtcChannelMediaOptions()
option.clientRoleType = .broadcaster
option.channelProfile = .communication

agoraKit.joinChannel(
    byToken: token,
    channelId: channelName,
    uid: 0,
    mediaOptions: option
)

uid: 0 — Agora назначает UID сама. Если нужна привязка к пользователю — передавайте детерминированный числовой ID (UInt32).

Локальное видео выводим через AgoraRtcVideoCanvas с setupLocalVideo(). Удалённое — через setupRemoteVideo() в делегатном методе didJoinedOfUid. Важно: setupRemoteVideo() вызывайте на main thread, иначе EXC_BAD_ACCESS при быстром подключении/отключении участников.

func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
    DispatchQueue.main.async {
        let canvas = AgoraRtcVideoCanvas()
        canvas.uid = uid
        canvas.renderMode = .hidden
        canvas.view = self.remoteVideoView
        self.agoraKit.setupRemoteVideo(canvas)
    }
}

Настройка качества видео

Agora предоставляет предустановки AgoraVideoEncoderConfiguration и кастомные параметры:

let config = AgoraVideoEncoderConfiguration(
    size: CGSize(width: 640, height: 360),
    frameRate: .fps15,
    bitrate: AgoraVideoBitrateStandard,
    orientationMode: .adaptative,
    mirrorMode: .auto
)
agoraKit.setVideoEncoderConfiguration(config)

Для мобильного приложения 360p/15fps — разумный баланс качества и батарейной нагрузки. 720p/30fps — для планшетов или когда качество критично. 1080p не подходит для мобильных: потребляет много энергии и ресурсов, а разница в восприятии между 720p и 1080p незначительна.

Как обработать прерывания и lifecycle?

На iOS AVAudioSession.routeChangeNotification и AVAudioSession.interruptionNotification — Agora SDK обрабатывает их автоматически при корректной настройке AgoraAudioScenario. Сценарий .meeting — оптимален для видеозвонков: включает AEC, ANS, AGC.

При входящем системном звонке Agora не паузируется автоматически. Реализуем через CXCallObserver: при CXCall.hasConnected == true — muteLocalAudioStream(true), при завершении — размьютим.

На Android без ForegroundService Android 8+ убьёт процесс через 5–10 минут. Запускаем ForegroundService при начале звонка с уведомлением. android:foregroundServiceType="camera|microphone" в манифесте обязателен с Android 14.

Что входит в интеграцию

• Анализ требований: количество участников, качество, бэкенд-интеграция, бюджет.
• Настройка токенов: генерация, кэширование, обработка протуханий.
• Реализация UI: видеоканвасы, органы управления, виртуальный фон.
• Lifecycle: ForegroundService на Android, CXCallObserver на iOS.
• Тестирование: 10+ сценариев (обрыв сети, входящий звонок, быстрая перекоммутация).
• Документация: README, комментарии кода, схема токенов.
• Поддержка: 2 недели после релиза, фиксация багов.

Сроки и стоимость

Базовая интеграция (1-на-1 видеозвонок с управлением камерой, mute, flip) — 3–5 дней. С поддержкой группы до 8 участников, токен-менеджментом и фоновым режимом — 1–2 недели. Стоимость рассчитывается после анализа требований. Свяжитесь с нами для оценки вашего проекта — мы подготовим смету и roadmap. Получите консультацию по интеграции Agora или закажите внедрение видеозвонков.

Как выбрать подход к камере на мобильных платформах

Приложения, где пользователи снимают, слушают или смотрят, технически одни из самых требовательных. Мы сталкиваемся с этим каждый день. Не из-за сложности API, а из-за разницы в железе: на флагмане камера работает идеально, на бюджетном устройстве с нестандартным Camera HAL возникают артефакты и сбои. На iOS стабилизация одного поколения отличается от другого. Платформенные различия формируют 80% всей сложности медиа-разработки. Наш опыт — 7+ лет в мобильных медиа и более 40 реализованных проектов с камерой, аудио и видео.

CameraX против Camera2 и AVFoundation

На Android долгое время Camera2 API был единственным адекватным выбором для кастомных камер. Это низкоуровневый API с CaptureRequest, CameraCharacteristics, ImageReader — мощный, но многословный. Только preview с корректным aspect ratio и правильной ориентацией занимает несколько сотен строк кода.

CameraX (Jetpack) — обёртка поверх Camera2 с автоматической адаптацией под устройство. Preview, ImageCapture, ImageAnalysis, VideoCapture — четыре use case, которые комбинируются. Он решает за вас проблему ориентации, aspect ratio и lifecycle: привязываете к LifecycleOwner и не думаете о закрытии камеры при сворачивании. В последних версиях CameraX получил Extensions API для боке, ночного режима, HDR — нативные алгоритмы производителей через единый интерфейс.

Когда нужен Camera2 напрямую: RAW-съёмка через ImageFormat.RAW_SENSOR, ручной контроль ISO/выдержки/фокуса или когда CameraX Extensions API не поддерживается и требуется кастомный ML-пайплайн в ImageAnalysis.

На iOS AVFoundation — единственный путь для кастомной камеры. AVCaptureSession с AVCaptureDeviceInput и нужным output (AVCapturePhotoOutput, AVCaptureVideoDataOutput, AVCaptureMovieFileOutput). Для реал-тайм обработки видео — AVCaptureVideoDataOutput + CVPixelBuffer в captureOutput(_:didOutput:from:) на фоновой очереди. Именно тут CoreML-модели получают кадры для инференса.

Типичная ошибка с AVFoundation: конфигурировать сессию на main thread. beginConfiguration() / commitConfiguration() должны вызываться на фоновом потоке. Иначе preview фризит, пользователь видит заморозку интерфейса. Эта ошибка встречается в 70% проектов, которые мы аудировали.

Почему AudioFocus критичен для Android приложений

Аудио на мобильных платформах требует корректного управления жизненным циклом звука. AudioFocus — механизм координации между приложениями. AudioManager.requestAudioFocus() с OnAudioFocusChangeListener. Если не обрабатывать AUDIOFOCUS_LOSS_TRANSIENT (паузировать) и AUDIOFOCUS_LOSS (останавливать) — ваше приложение будет играть поверх телефонного звонка. Это гарантированный плохой отзыв в Google Play. Android Developer Guide: AudioFocus

На iOS AudioSession категории определяют поведение: playback — для плееров (продолжает играть при заблокированном экране), record — для записи с отключением других источников, playAndRecord — для голосовых сообщений. Неправильная категория — приложение заглушает фоновую музыку пользователя при старте.

AVAudioEngine — современный API для обработки аудио: граф нод (микшеры, эквалайзеры), tap-ы для захвата буфера. Для речи в реальном времени — SFSpeechRecognizer + inputNode.installTap.

На Android для записи с шумоподавлением — NoiseSuppressor.isAvailable() + create(audioRecord.audioSessionId). Работает не на всех устройствах, нужен fallback.

Видео: воспроизведение и стриминг

ExoPlayer (Media3) — стандарт для Android. Поддерживает HLS, DASH, SmoothStreaming, прогрессивное воспроизведение. DefaultTrackSelector с Parameters позволяет выбирать качество вручную или адаптивно. DRM через DefaultDrmSessionManager с Widevine L1/L3.

Проблема, с которой сталкиваются почти все: ExoPlayer в RecyclerView при быстром скролле. Нужен PlayerPool — пул переиспользуемых плееров. Без пула каждый новый экземпляр создаёт MediaCodec инстанс, что дорого и приводит к MediaCodec$CodecException: Error -19 на некоторых Android 10 устройствах при >3 одновременных инстансах.

AVPlayer / AVPlayerViewController на iOS — для воспроизведения. Для кастомного UI — AVPlayerLayer + собственные контролы. HLS работает нативно через AVPlayer(url:) с m3u8. FairPlay DRM требует серверной части: AVContentKeySession, CKC-ответ от KSM-сервера, делегат ресурсов.

Для Flutter — video_player как базовый слой, chewie для UI. Для серьёзных задач — platform channel к нативному ExoPlayer/AVPlayer (из-за DRM и субтитров).

WebRTC на мобильных — через нативные фреймворки или flutter_webrtc. Реальная сложность — не в самом протоколе, а в сигналинге и TURN-серверах. Без TURN клиенты за симметричными NAT не установят соединение — это примерно 15–20% трафика. Coturn — стандартный open-source сервер.

RTMP публикация на мобильных: LFLiveKit для iOS, HaishinKit как более современная альтернатива. На Android — rtmp-rtsp-stream-client-java или через FFmpeg с JNI. Последнее даёт максимальную гибкость, но бинарник растёт на 10–15 МБ.

Обработка медиа: компрессия и транскодирование

Видео в ProRes может занимать 6 ГБ/минуту. Перед загрузкой нужна компрессия. На iOS — AVAssetExportSession с пресетом 1920×1080 или кастомный AVVideoComposition. VideoToolbox для аппаратного кодирования H264/HEVC — быстрее и экономнее по батарее.

На Android — MediaCodec напрямую или Transformer (Media3) — высокоуровневый API для трансформаций (обрезка, ресайз, эффекты через GlEffectsFrameProcessor). Для изображений — BitmapFactory.Options.inSampleSize для даунсемплинга, Glide / Coil для кеширования. Coil на Coroutines хорошо вписывается в Compose. Загружать оригинал 12 МП в ImageView 200×200dp — классический OutOfMemoryError на устройствах с 2 ГБ RAM.

Как реализовать стриминг на мобильных устройствах: пошаговый план

1. Определить требования: целевая задержка, количество одновременных пользователей, необходимость P2P.
2. Выбрать протокол и стек: WebRTC для видеозвонков, RTMP/HLSLive для вещания.
3. Настроить сигналинг (SIP, WebSocket, MQTT) и TURN-сервер.
4. Реализовать публикацию/просмотр через нативный API или кроссплатформенный плагин.
5. Провести тестирование на реальных устройствах с разными камерами и сетевыми условиями.
6. Оптимизировать битрейт и разрешение в зависимости от пропускной способности.

Что входит в работу

Процесс разработки медиафункциональности

Сложность нелинейна: базовое воспроизведение видео — 1–2 дня, кастомная камера с обработкой кадров и стримингом — 3–5 недель. Начинаем с прояснения требований: DRM, форматы, минимальная OS, поддержка фоновых режимов. Тестирование на железе обязательно — эмулятор не воспроизводит проблемы с Camera HAL, аппаратным кодеком и AudioFocus. Минимальный набор: последний iPhone, iPhone SE, флагман Samsung, бюджетный Android, Android Go (если целевая аудитория — развивающиеся рынки).

Сроки ориентировочно: от 5 рабочих дней (базовое воспроизведение) до 8 недель (комплексная камера со стримингом и DRM). Стоимость рассчитывается индивидуально после анализа ваших требований — свяжитесь с нами для консультации.

Фраза услуги: «Работа с медиа в мобильных приложениях» — это наш профиль. Каждый проект начинается с аудита текущей реализации, выявления узких мест и предложения оптимального стека.

Коммерческие сигналы: закажите аудит вашей медиа-функциональности, получите консультацию инженера без обязательств.