SDK de Android

El SDK para Android de la Video API de Vonage te permite utilizar sesiones de vídeo basadas en la Video API de Vonage en las aplicaciones que desarrolles para dispositivos Android.

Notas importantes:

  • Android SDK 2.30.0+ admite dispositivos con tamaños de página de 4 KB y 16 KB.
  • El SDK de Android 2.29.1 o superior requiere un permiso ACCESS_NETWORK_STATE y en Android API nivel 35+ también requiere permiso REQUEST_IGNORE_BATTERY_OPTIMIZATIONS. Consulte la lista completa de permisos.
  • El SDK de Android 2.28.0+ requiere un nivel mínimo de API de Android de 24.
  • Los SDK de Android 2.24.3+, 2.25.4+ y 2.26.0+ requieren un nivel mínimo de API de Android de 23.
  • El SDK de Android 2.24.0 y versiones posteriores ya no son compatibles con las arquitecturas x86 de 32 bits.
  • Las aplicaciones dirigidas al nivel de API 31 o superior ahora requieren un permiso READ_PHONE_STATE. Consulte la lista completa de permisos.

Los SDK de cliente también están disponibles para web, iOS, Windows, macOS, Linux y React Native. Todos los SDK de cliente pueden interactuar entre sí. Puedes obtener más información sobre los conceptos básicos de los clientes, servidores, sesiones y más de Vonage Video en el Conceptos básicos de la Video API página.

Ejemplos de códigos

Para ver ejemplos de código, visite nuestra página repo vonage-video-android-sdk-samples en GitHub.

Interoperabilidad

Las aplicaciones desarrolladas con el SDK de vídeo para Android 2.34.1 pueden interoperar con las aplicaciones de Vonage Video desarrolladas con la versión 2.32 o posterior de los Client SDK de vídeo:

  • OpenTok.js
  • SDK para iOS
  • SDK de Windows
  • SDK de macOS
  • SDK para Linux
  • SDK de React Native

Instalación

La versión Maven está disponible en https://search.maven.org/artifact/com.vonage/client-sdk-video. El ID del artefacto es "client-sdk-video".

Para más información, consulte Crear su propia aplicación utilizando el SDK de Android.

Requisitos del promotor y del cliente

El SDK de Android admite un flujo de audio-vídeo publicado, un flujo de audio-vídeo suscrito y hasta cinco flujos adicionales de sólo audio suscritos simultáneamente.

Para conectar más de dos clientes en una sesión usando el Android SDK, crea una sesión que use el enrutador de medios con video de Vonage (una sesión con el modo de medios configurado en enrutado). Consulta El enrutador de medios de video de Vonage y los modos de medios.

El SDK es compatible con redes Wi-Fi de alta velocidad y 4G LTE.

El SDK de Android es compatible con armeabi-v7a, armeabi64-v8ay x86_64 arquitecturas.

El SDK es compatible con dispositivos con un tamaño de página de 4 KB y de 16 KB a partir de la versión 2.30.0. Esto garantiza el correcto funcionamiento, mejora la compatibilidad y evita los fallos del sistema. Para obtener más información, consulta esta documentación de Android en tamaños de página.

El SDK de Android funciona con cualquier dispositivo con Android 7.0 o superior (Nougat, nivel de API 24) que cuente con una cámara (para publicar vídeos) y una CPU y memoria adecuadas.

Crear su propia aplicación utilizando el SDK de Android

La versión Maven está disponible en https://search.maven.org/artifact/com.vonage/client-sdk-video.

El ID del artefacto es "client-sdk-video". Modifica tu aplicación para descargar el SDK de Android desde https://search.maven.org/artifact/com.vonage/client-sdk-video. Por ejemplo:

  1. Edita el archivo build.gradle de tu proyecto y añade el siguiente fragmento de código al allprojects/repositories sección: mavenCentral()
  2. Modifique el archivo build.gradle de la aplicación y añada el siguiente fragmento de código al archivo dependencies sección: implementation 'com.vonage:client-sdk-video:2.34.0'
  3. Asegúrate de que el archivo `build.gradle` de la aplicación contenga el siguiente fragmento de código dentro de android (a partir de Android Studio 4.1 este fragmento está presente al crear un nuevo proyecto).

Para versiones del SDK de Android superiores a la 2.28.1:

compileOptions {
      sourceCompatibility JavaVersion.VERSION_17
      targetCompatibility JavaVersion.VERSION_17
}

Para las versiones del SDK de Android comprendidas entre la 2.22.0 y la 2.28.1:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
}

Requisitos del sistema

Para una transmisión de vídeo fiable, asegúrate de que tu dispositivo Android cumple estas especificaciones recomendadas:

  • CPU: Un procesador reciente de doble núcleo; ARM64 (ARMv8) Quad-core o superior a 2,0 GHz+ (por ejemplo, Qualcomm Snapdragon serie 600+, Samsung Exynos serie 7 o superior, Google Tensor (dispositivos Pixel)).
  • GPU: Adreno serie 500+ (Qualcomm), Mali-G71+ (ARM); para codificación/decodificación de vídeo acelerada por hardware.
  • RAM: Al menos 6 GB de RAM para llamadas en grupo y multitarea.
  • Pantalla: 5"+ para una mejor experiencia de usuario.
  • Capacidad de la batería: 3000+ mAh para videollamadas prolongadas.
  • Red: Conectividad fiable a Internet; funciona por Wi-Fi o móvil.

Estas recomendaciones garantizan una reproducción estable, un menor consumo de CPU y un rendimiento fluido al reproducir vídeo en streaming.

Ejemplos de dispositivos por categoría: el Samsung Galaxy A12, el Moto G Play y el Nokia G10 son de gama básica; el Google Pixel 6a, el Samsung Galaxy A52/A53 y el OnePlus Nord pertenecen a la gama media; y el Samsung Galaxy S23/S24, el Google Pixel 8 Pro y el OnePlus 11 pertenecen a la gama alta.

Permisos

El SDK de Android utiliza los siguientes permisos:

  • android.permission.ACCESS_NETWORK_STATE -- El SDK de Vonage Video para Android requiere este permiso a partir de la versión 2.29.1.
  • android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS -- El SDK de Vonage Video para Android requiere este permiso a partir de la versión 2.29.1 en el nivel de API 35 y superiores.
  • android.permission.BLUETOOTH_CONNECT -- Es necesario habilitarlo para el nivel de API 31 y superiores. Si desea utilizar el dispositivo Bluetooth con Android SDK DefaultAudioDevice orientado al nivel de API 31 y superior, solicite permisos de tiempo de ejecución en la aplicación o habilite el permiso ("Dispositivos cercanos/Bluetooth") manualmente en la configuración de la aplicación.
  • android.permission.READ_PHONE_STATE -- El SDK para Android de Vonage Video solicita este permiso en el nivel de API 22 e inferior, y 31 y superior.
  • android.permission.CAMERA -- Si tu aplicación no utiliza el capturador de vídeo predeterminado y no accede a la cámara, puedes eliminar este permiso.
  • android.permission.INTERNET -- Requerido.
  • android.permission.RECORD_AUDIO -- Si tu aplicación no utiliza el dispositivo de audio predeterminado y no accede al micrófono, puedes eliminar este permiso.
  • android.permission.MODIFY_AUDIO_SETTINGS -- Si tu aplicación no utiliza el dispositivo de audio predeterminado y no accede al micrófono, puedes eliminar este permiso.
  • android.permission.BLUETOOTH -- El dispositivo de audio predeterminado es compatible con el audio por Bluetooth. Si tu aplicación no utiliza el dispositivo de audio predeterminado ni utiliza Bluetooth, puedes eliminar este permiso.
  • android.permission.BROADCAST_STICKY -- Hemos determinado que esto no es utilizado por el SDK de Android, y vamos a eliminar este permiso de una próxima versión.

No es necesario que los añada al manifiesto de su aplicación. El SDK de Android los añade automáticamente. Sin embargo, a partir del nivel 21 de la API, algunos permisos requieren que se pregunte al usuario.

Tu aplicación puede eliminar cualquiera de estos permisos que no sean necesarios. Consulte esta entrada y esta documentación de Android. Por ejemplo, esto elimina el android.permission.CAMERA autorización:

<uses-permission android:name="android.permission.CAMERA" tools:node="remove"/>

Reglas de ProGuard para el SDK de Vonage Video para Android

La configuración recomendada de ProGuard es:

-keeppackagenames
-keep class com.opentok.** { *; }
-keep class com.vonage.** { *; }

Al utilizar Android Studio 3.4 o el complemento de Gradle para Android 3.4.0 o superior, la compresión, la ofuscación y la optimización están activadas automáticamente de forma predeterminada. No se recomienda comprimir ni ofuscar el SDK de Vonage Video para Android.. La configuración anterior obliga a conservar el código fuente del SDK de Vonage Video para Android, sin impedir que se reduzca el tamaño del resto de la aplicación. Conserva los nombres de los paquetes del SDK de Vonage Video para Android con el indicador -keeppackagenames. El compilador realiza automáticamente una serie de optimizaciones de forma predeterminada. No se recomienda aplicar ninguna otra optimización, pero es posible habilitar optimizaciones adicionales, lo que puede requerir incluir reglas adicionales de ProGuard para evitar problemas en tiempo de ejecución, añadiendo lo siguiente en el archivo gradle.properties del proyecto:

android.enableR8.fullMode=true

No se recomienda reducir el SDK de Vonage Video para Android. Reducir y ofuscando el SDK de Vonage Video para Android con la optimización anterior generará generará advertencias. Estas deben ser deshabilitadas.

# Please add these rules to your existing keep rules in order to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn org.bouncycastle.jsse.BCSSLParameters
-dontwarn org.bouncycastle.jsse.BCSSLSocket
-dontwarn org.bouncycastle.jsse.provider.BouncyCastleJsseProvider
-dontwarn org.conscrypt.Conscrypt$Version
-dontwarn org.conscrypt.Conscrypt
-dontwarn org.conscrypt.ConscryptHostnameVerifier
-dontwarn org.openjsse.javax.net.ssl.SSLParameters
-dontwarn org.openjsse.javax.net.ssl.SSLSocket
-dontwarn org.openjsse.net.ssl.OpenJSSE

Véase esta documentación de Android para comprender mejor las reglas generales de ProGuard y sus funcionalidades.

Integración de ConnectionService en Android

Utiliza Android Servicio de conexión para crear una aplicación VoIP que utilice las funciones de audio y vídeo del SDK de Android. Para crear una aplicación VoIP básica:

  • Registra el android.telecom.ConnectionService en el archivo AndroidManifest.xml.
<service android:name="com.example.package.MyConnectionService"
    android:label="@string/some_label_for_my_connection_service"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>
  • Crear una clase que extienda la clase android.telecom.ConnectionService clase. Implementar métodos de la clase ConnectionService clase, incluyendo onCreateIncomingConnection(), onCreateOutgoingConnection, onCreateIncomingConnectionFailed()y onCreateOutgoingConnectionFailed().
  • Crear una clase que extienda la clase android.telecom.Connection clase. Implementar métodos de la clase Connection clase, incluyendo onAnswer() y onDisconnect. En la aplicación de la onAnswer() puedes conectarte a una sesión de Vonage Video, publicar una transmisión en la sesión y habilitar el código para que se suscriba a las transmisiones creadas en la sesión. En la implementación del método onDisconnect() puede desconectarse de la sesión (y dejar de publicar y suscribirse a flujos).
  • Puedes utilizar servicios como Google Firebase para implementar notificaciones push para la aplicación. Puedes configurar las notificaciones para saber cuándo tu aplicación está en segundo plano o cerrada. De este modo, tu aplicación puede recibir una llamada VoIP mientras está cerrada.

Al utilizar ConnectionServiceutilice el botón AudioDeviceManager.getAudioFocusManager() y aplicar los métodos del método AudioFocusManager para delegar el control del enfoque de audio a tu aplicación. Se definen en el SDK para Android de Vonage:

private AudioDeviceManager audioDeviceManager;
private BaseAudioDevice.AudioFocusManager audioFocusManager;

public void setupAudioFocusManager(Context context) {
    audioDeviceManager = new AudioDeviceManager(context);
    audioFocusManager = audioDeviceManager.getAudioFocusManager();
    audioFocusManager.setRequestAudioFocus(false);
}

public void notifyAudioFocusIsActive() {
    audioFocusManager.audioFocusActivated();
}

public void notifyAudioFocusIsInactive() {
    audioFocusManager.audioFocusDeactivated();
}

Al delegar el foco de audio a la aplicación, el SDK detiene su enrutamiento automático de audio. En su lugar, esta lógica de enrutamiento es manejada por ConnectionServiceque notifica a la aplicación acerca de los dispositivos de audio disponibles a través de la conexión de CallEndpoint y CallAudioState API. Tu aplicación debe implementar la compatibilidad con la enumeración de dispositivos de audio y la lógica de selección.

Esta delegación garantiza el enrutamiento adecuado del audio y la coordinación con el sistema Android Telecom.

Véase el Aplicación de VOIP de ejemplo en el vonage-video-android-sdk-samples repo. Muestra cómo implementar el ConnectionService clase para crear una aplicación de VoIP que utilice el SDK de Android.

Servicios de primera línea

Los servicios en primer plano de Android son esenciales para mantener el acceso a las funciones de la cámara y el micrófono, incluso cuando la aplicación se encuentra en segundo plano. En el caso de las aplicaciones de videollamadas, esto significa que puedes seguir capturando vídeo y audio mientras realizas otras tareas simultáneamente. A partir de Android 14 (nivel de API 34), debes declarar un tipo de servicio adecuado para cada servicio en primer plano en el manifiesto de tu aplicación; por ejemplo, declarando el tipo de servicio «camera» junto con el correspondiente FOREGROUND_SERVICE_CAMERA permiso. Además, debes solicitar los permisos de ejecución necesarios, como el permiso de CÁMARA, que está sujeto a restricciones de uso. Esta configuración garantiza que tu aplicación tenga los privilegios necesarios para utilizar las funciones de cámara y micrófono en segundo plano, de acuerdo con los requisitos y las mejores prácticas más recientes de Android.

Configurar los servicios en primer plano

¿Qué es un servicio en primer plano?

Los servicios en primer plano te permiten realizar de forma asíncrona operaciones que el usuario puede percibir. Estos servicios muestran una notificación en la barra de estado para que los usuarios sepan que tu aplicación está realizando una tarea en primer plano y consumiendo recursos del sistema.

Algunos ejemplos de casos de uso que utilizan servicios en primer plano son:

  • Sigue capturando y enviando audio a los compañeros aunque el usuario abra otra aplicación.
  • Permitir que un usuario comparta su pantalla mientras cambia de una aplicación a otra.
  • Permitir a los usuarios apagar la pantalla sin dejar de escuchar una videollamada.

Tipos de servicios en primer plano

Android 10 introdujo el android:foregroundServiceType dentro del atributo <service> elemento. La idea es especificar explícitamente qué tipo de trabajo realiza el servicio.

Android 14 obliga a especificar el tipo de servicio en primer plano. Con ello se pretende garantizar el uso correcto de los servicios en primer plano y la coherencia entre fabricantes de dispositivos.

Los tipos admitidos actualmente son:

  • cámara (necesario en Android 11) - cuando se accede a la cámara desde el fondo, como las aplicaciones de videollamadas.
  • dispositivo conectado - al interactuar con un dispositivo externo, como un dispositivo de fitness Bluetooth
  • dataSync — al cargar o descargar datos, quedará obsoleto y, en su lugar, se deberán utilizar alternativas como DownloadManager, BackupManager o WorkManager
  • salud (novedad en Android 14) — para aplicaciones de fitness, como las de seguimiento de ejercicio
  • ubicación (obligatorio en Android 10) - cuando se requiere la ubicación, como la navegación.
  • mediaPlayback - al continuar la reproducción de audio o vídeo en segundo plano, como Spotify o Netflix
  • mediaProjection — al proyectar contenido en dispositivos o pantallas externos
  • micrófono (necesario en Android 11) - cuando se accede al micrófono desde un segundo plano, como en el caso de las aplicaciones de llamadas.
  • phoneCall - al continuar una llamada en curso
  • remoteMessaging (novedad en Android 14) — al transferir mensajes de texto de un dispositivo a otro
  • shortService - cuando se requiere terminar rápidamente un trabajo crítico que no puede interrumpirse, sólo puede funcionar durante unos 3 minutos
  • uso especial — cuando otros tipos no se ajustan a tu caso de uso
  • sistema exento — reservado para aplicaciones del sistema

Declarar el tipo de servicio en primer plano

El primer paso para soportar Android 14 es actualizar su declaración de servicio en el archivo AndroidManifest y especificar el tipo de servicio en primer plano correcto.

Si su servicio requiere varios tipos, puede combinarlos utilizando el operador | de la siguiente manera:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
    <service
        android:name=".MyForegroundService"
        android:foregroundServiceType="microphone|camera"
        android:exported="false">
    </service>
</manifest>

Si intenta iniciar un servicio en primer plano sin declarar su tipo en el manifiesto, el sistema lanzará un error MissingForegroundServiceTypeException al llamar startForeground().

Solicitar un permiso específico para un servicio en primer plano

A partir de Android 9 (API 28), las aplicaciones tenían que solicitar SERVICIO_EN_PRIMER_LUGAR permiso en el manifiesto de la aplicación, que el sistema concedió automáticamente.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

A partir de Android 14 (API 34), las aplicaciones deben solicitar además un permiso específico en función del tipo de servicio en primer plano. Por lo tanto, si tu servicio sigue accediendo al micrófono desde segundo plano, tendrás que especificar MICRÓFONO DE PRIMER PLANO_SERVICIO. El sistema concede automáticamente el permiso.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>

Si tu servicio requiere varios tipos, debes declarar este permiso para cada uno de ellos.

Si te olvidas de declarar cualquiera de los dos permisos, recibirás un SecurityException indicando el motivo exacto.

En Android 13 (API 33) y versiones posteriores, declara también POST_NOTIFICATIONS y solicitarlo en tiempo de ejecución si necesitas que la notificación de servicio en primer plano aparezca de forma fiable. Este ejemplo incluye ese flujo.

Iniciar un servicio en primer plano

De tu Activity u otros Contextinicie el servicio con AndroidX para que se utilice la API correcta en todas las versiones compatibles (esto coincide con MainActivity en este proyecto):

import android.Manifest
import android.content.Intent
import android.content.pm.PackageManager
import androidx.core.content.ContextCompat

fun startMyForegroundService() {
    val serviceIntent = Intent(this, MyForegroundService::class.java)
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO)
        == PackageManager.PERMISSION_GRANTED
    ) {
        ContextCompat.startForegroundService(applicationContext, serviceIntent)
    }
}

ContextCompat.startForegroundService() llamadas startForegroundService() en API 26+ y startService() en APIs más antiguas.

El fragmento de código lanza un servicio. Sin embargo, el servicio aún no se está ejecutando en primer plano. Dentro del propio servicio, debe llamar a startForeground() con prontitud. Con AndroidX, prefiera ServiceCompat.startForeground() para que puedas pasar un foregroundServiceType máscara de bits que coincida con tu manifiesto (véase MyForegroundService en este proyecto):

import android.app.Notification
import android.content.pm.ServiceInfo
import android.os.Build
import androidx.core.app.NotificationCompat
import androidx.core.app.ServiceCompat

val notification: Notification = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Audio Call in Progress")
    .setContentText("Your microphone is active while the app is in the background.")
    .setPriority(NotificationCompat.PRIORITY_HIGH)
    .setOngoing(true)
    .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
    .build()

ServiceCompat.startForeground(
    this,
    NOTIFICATION_ID,
    notification,
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
    } else {
        0
    },
)

Crear un NotificationChannel (Android 8.0+) antes de crear la notificación, y captura ForegroundServiceStartNotAllowedException en API 31+ si la aplicación no puede iniciar un servicio en primer plano desde el estado actual.

Nota: Si pasas un tipo de servicio en primer plano a startForeground / ServiceCompat.startForeground que no declaró en el manifiesto, el sistema lanza IllegalArgumentException.

Proporcione detalles de su caso de uso en Google Play Console

Después de cargar la nueva versión de la aplicación dirigida a Android 14 y que utiliza un tipo de servicio en primer plano en Google Play Console, aparecerá un mensaje en la consola para que proporcione información adicional sobre su uso.

Como Google quiere asegurarse de que las aplicaciones utilizan los servicios en primer plano de forma adecuada, tendrás que enviar una nueva declaración en la página de contenido de la aplicación (Política -> Contenido de la aplicación).

Por cada tipo de servicio en primer plano que declares, deberás hacer lo siguiente:

  • Describe la funcionalidad de la aplicación que utiliza ese tipo de servicio en primer plano.
  • Describe las consecuencias para el usuario en caso de que el sistema aplace o interrumpa la tarea.
  • Incluya un enlace a un vídeo que muestre cada función de los servicios en primer plano. El vídeo debe mostrar los pasos que el usuario debe seguir en la aplicación para activar la función.
  • Elija su caso de uso específico para cada tipo de servicio en primer plano. Puede elegir entre una lista preestablecida de casos de uso que se enumeran aquí o introducirla manualmente.

Aplicación de ejemplo

Véase el Chat de vídeo básico con servicios en primer plano muestra en el ejemplos-del-SDK-de-vídeo-de-Vonage-para-Android repo.

Más información en la sección de Android Servicios en primer plano documentación.

Más información

Puedes encontrar documentación detallada sobre cada método de Android en el guía de referencia.

Para consultar la lista de nuevas funciones y problemas conocidos, consulta el notas de la versión.