SDK Android

Le SDK Android de l'API Video de Vonage vous permet d'utiliser des sessions vidéo alimentées par l'API Video de Vonage dans les applications que vous créez pour les appareils Android.

Des SDK clients sont également disponibles pour le web, iOS, Windows, macOS, Linux et React Native. Tous les SDK clients peuvent interagir les uns avec les autres. Vous pouvez en apprendre davantage sur les principes de base des clients, serveurs, sessions et autres de Vonage Video sur le site Web de Vonage Video. Les bases de Video API page.

Remarques importantes

  • Le SDK Android 2.35.1+ prend en charge Android 17 (niveau d'API 37). Aucune nouvelle autorisation n'est requise pour cette mise à jour.
  • Le SDK Android 2.30.0+ prend en charge les appareils dont la taille de page est de 4 Ko et de 16 Ko.
  • Le SDK Android 2.29.1+ nécessite une autorisation. ACCESS_NETWORK_STATE et sur Android, le niveau API 35+ nécessite également une autorisation REQUEST_IGNORE_BATTERY_OPTIMIZATIONS. Consultez la liste complète des autorisations.
  • Le SDK Android 2.28.0+ requiert un niveau d'API Android minimum de 24.
  • Le SDK Android 2.24.3+, 2.25.4+ et 2.26.0+ requiert un niveau d'API Android minimum de 23.
  • Le SDK Android 2.24.0 et les versions ultérieures ne prennent plus en charge les architectures x86 32 bits.
  • Les applications ciblant le niveau d'API 31 et plus nécessitent désormais une autorisation READ_PHONE_STATE. Consultez la liste complète des autorisations.

Interopérabilité

Les applications développées à l'aide du SDK Video Android 2.35.1 peuvent interagir avec les applications Vonage Video développées à l'aide de la version 2.33 ou supérieure des Client SDK Video :

  • OpenTok.js (Web)
  • SDK Android
  • SDK iOS
  • SDK Windows
  • SDK macOS
  • SDK Linux
  • SDK React Native

Installation

Une version Maven est disponible à l'adresse suivante https://search.maven.org/artifact/com.vonage/client-sdk-video. L'identifiant de l'artefact est "client-sdk-video".

Modifiez votre application pour télécharger le SDK Android à partir de https://search.maven.org/artifact/com.vonage/client-sdk-video. Par exemple :

  1. Modifiez le fichier build.gradle de votre projet et ajoutez l'extrait de code suivant au fichier allprojects/repositories section : mavenCentral()
  2. Modifiez le fichier build.gradle de l'application et ajoutez l'extrait de code suivant au fichier dependencies section : implementation 'com.vonage:client-sdk-video:2.35.1'
  3. Assurez-vous que le fichier build.gradle de l'application contient l'extrait de code suivant android (à partir d'Android Studio 4.1, cet extrait est présent lors de la création d'un nouveau projet).

Pour les versions du SDK Android supérieures à 2.28.1 :

compileOptions {
      sourceCompatibility JavaVersion.VERSION_17
      targetCompatibility JavaVersion.VERSION_17
}

Pour les versions du SDK Android comprises entre 2.22.0 et 2.28.1 :

compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
}

Configuration requise

Pour une diffusion vidéo fiable, veillez à ce que votre appareil Android réponde aux spécifications recommandées :

  • PROCESSEUR : Processeur double cœur récent ; ARM64 (ARMv8) quadricœur ou supérieur à 2,0 GHz+ (par exemple, Qualcomm Snapdragon série 600+, Samsung Exynos série 7 ou supérieure, Google Tensor (appareils Pixel)).
  • GPU : Série Adreno 500+ (Qualcomm), Mali-G71+ (ARM) ; pour l'encodage/décodage vidéo accéléré au niveau matériel.
  • MÉMOIRE VIVE : Au moins 6 Go de RAM pour les appels de groupe et le multitâche.
  • Écran : 5"+ pour une meilleure expérience utilisateur.
  • Capacité de la batterie : 3000+ mAh pour des appels vidéo prolongés.
  • Réseau : Connectivité internet fiable ; fonctionne sur Wi-Fi ou cellulaire.

Ces recommandations garantissent une lecture stable, une utilisation réduite de l'unité centrale et des performances fluides lors de la diffusion de vidéos.

Exemples d'appareils par catégorie : Samsung Galaxy A12, Moto G Play et Nokia G10 sont d'entrée de gamme ; Google Pixel 6a, Samsung Galaxy A52/A53 et OnePlus Nord sont de milieu de gamme ; et Samsung Galaxy S23/S24, Google Pixel 8 Pro et OnePlus 11 sont de haut de gamme.

Apprendre à construire

La meilleure façon d'apprendre à utiliser le SDK Android est de suivre le Tutoriel de base sur le chat vidéo.

Une fois que vous maîtrisez les bases, vous pouvez obtenir des informations plus détaillées et découvrir comment personnaliser votre application à l'aide de la guides destinés aux développeurs. Pour étudier des classes et des méthodes spécifiques de l'API, voir la page Référence de l'API du SDK Android de Vonage Video.

Exigences du développeur et du client

Le SDK Android prend en charge un flux audio-vidéo publié, un flux audio-vidéo souscrit et jusqu'à cinq flux audio supplémentaires souscrits simultanément.

Pour connecter plus de deux clients dans une session à l'aide du Client SDK Android, créez une session qui utilise le routeur média vidéo de Vonage (une session dont le mode média est réglé sur routé). Voir Le routeur vidéo multimédia de Vonage et les modes médias.

Le SDK est compatible avec les réseaux Wi-Fi et 4G LTE à haut débit.

Le SDK Android est pris en charge sur armeabi-v7a, arm64-v8aet x86_64 architectures.

Le SDK prend en charge les dispositifs de taille de page de 4 Ko et 16 Ko à partir de la version 2.30.0. Cela permet de garantir la fonctionnalité, d'améliorer la compatibilité et d'éviter les pannes. Pour plus d'informations, voir cette documentation Android sur les tailles des pages.

Le SDK Android fonctionne avec tout appareil Android 7.0+ (Nougat, niveau API 24) doté d'une caméra (pour la publication de vidéos) et d'une prise en charge adéquate du processeur et de la mémoire.

Permissions

Le SDK Android utilise les autorisations suivantes :

  • android.permission.ACCESS_NETWORK_STATE -- Le SDK Android de Vonage Video nécessite cette autorisation à partir de la version 2.29.1.
  • android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS -- Le SDK Android Video de Vonage nécessite cette autorisation à partir de la version 2.29.1 dans le niveau API 35 et supérieur.
  • android.permission.BLUETOOTH_CONNECT -- Vous devez l'activer pour les niveaux d'API 31 et supérieurs. Si vous souhaitez utiliser le périphérique Bluetooth avec le SDK Android DefaultAudioDevice ciblant le niveau API 31 et supérieur, veuillez demander des autorisations d'exécution dans l'application ou activer manuellement l'autorisation ("Nearby devices/Bluetooth") dans les paramètres de l'application.
  • android.permission.READ_PHONE_STATE -- Le SDK Android Video de Vonage demande cette permission au niveau API 22 et inférieur, et 31 et supérieur.
  • android.permission.CAMERA -- Si votre application n'utilise pas le capteur vidéo par défaut et n'accède pas à la caméra, vous pouvez supprimer cette autorisation.
  • android.permission.INTERNET -- requis.
  • android.permission.RECORD_AUDIO -- Si votre application n'utilise pas le périphérique audio par défaut et n'accède pas au microphone, vous pouvez supprimer cette autorisation.
  • android.permission.MODIFY_AUDIO_SETTINGS -- Si votre application n'utilise pas le périphérique audio par défaut et n'accède pas au microphone, vous pouvez supprimer cette autorisation.
  • android.permission.BLUETOOTH -- Le périphérique audio par défaut prend en charge l'audio Bluetooth. Si votre application n'utilise pas le périphérique audio par défaut et n'utilise pas Bluetooth, vous pouvez supprimer cette permission.
  • android.permission.BROADCAST_STICKY -- Nous avons déterminé que cette permission n'est pas utilisée par le SDK Android, et nous la supprimerons dans une prochaine version.
  • android.permission.ACCESS_LOCAL_NETWORK -- Ce n'est pas obligatoire. Android 17 (API 37) a introduit cette autorisation afin de contrôler l'accès aux API de découverte du réseau local de haut niveau. Le SDK Android de Vonage Video utilise des sockets UDP/TCP brutes pour la négociation ICE WebRTC, qui ne sont pas soumises à cette autorisation. Les connexions P2P et les candidats ICE du réseau local fonctionnent correctement sur Android 17 sans cette autorisation.

Vous n'avez pas besoin de les ajouter au manifeste de votre application. Le SDK Android les ajoute automatiquement. Toutefois, à partir du niveau 21 de l'API, certaines autorisations nécessitent que vous demandiez à l'utilisateur de le faire.

Votre application peut supprimer toutes les autorisations qui ne seront pas nécessaires. Voir ce poste et cette documentation Android. Par exemple, ceci supprime le android.permission.CAMERA autorisation :

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

Règles ProGuard

La configuration recommandée de ProGuard est la suivante :

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

Lorsque vous utilisez Android Studio 3.4 ou le plugin Android Gradle 3.4.0+, la réduction, l'obscurcissement et l'optimisation sont, par défaut, automatiquement activés. Il n'est pas recommandé de réduire et d'obscurcir le SDK Android de Vonage Video.. La configuration ci-dessus oblige à conserver le code source de Vonage Video Android SDK, sans empêcher la réduction du reste de l'application. Préservez les noms des paquets de Vonage Video Android SDK avec le drapeau -keeppackagenames. Par défaut, le compilateur effectue automatiquement une série d'optimisations. Il n'est pas recommandé d'appliquer d'autres optimisations, mais il est possible d'en activer de supplémentaires, ce qui peut nécessiter d'inclure des règles ProGuard supplémentaires afin d'éviter des problèmes d'exécution, en ajoutant ce qui suit dans le fichier `gradle.properties` du projet :

android.enableR8.fullMode=true

Il n'est pas recommandé de minimiser le SDK Android de Vonage Video. La réduction et l'obscurcissement du SDK Android de Vonage Video avec l'optimisation précédente généreront des avertissements. Ceux-ci doivent être désactivés.

# 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

Voir cette documentation Android pour mieux comprendre les règles générales de ProGuard et ses fonctionnalités.

Services de premier plan

Les services d'avant-plan dans Android sont essentiels pour maintenir l'accès aux capacités de la caméra et du microphone même lorsque votre application est en arrière-plan. Pour les applications de chat vidéo, cela signifie que vous pouvez continuer à capturer de la vidéo et de l'audio tout en étant multitâches. À partir d'Android 14 (niveau API 34), vous devez déclarer un type de service approprié pour chaque service d'avant-plan dans le manifeste de votre application - par exemple, en déclarant le type de service "camera" avec l'élément correspondant FOREGROUND_SERVICE_CAMERA . En outre, vous devez demander les autorisations d'exécution nécessaires, telles que l'autorisation CAMERA, qui est soumise à des restrictions en cours d'utilisation. Cette configuration garantit que votre application dispose des privilèges requis pour exploiter les fonctionnalités de l'appareil photo et du microphone en arrière-plan, conformément aux dernières exigences et aux meilleures pratiques d'Android.

Qu'est-ce qu'un service d'information préalable ?

Les services d'avant-plan vous permettent d'effectuer de manière asynchrone des opérations perceptibles par l'utilisateur. Les services d'avant-plan affichent une notification dans la barre d'état, afin de signaler aux utilisateurs que votre application exécute une tâche en avant-plan et consomme des ressources système.

Voici quelques exemples de cas d'utilisation des services d'avant-plan :

  • Continuez à capturer et à envoyer des données audio à vos homologues, même lorsque l'utilisateur ouvre une autre application.
  • Permettre à un utilisateur de partager son écran lorsqu'il passe d'une application à l'autre.
  • Permettre aux utilisateurs d'éteindre leur écran tout en écoutant un appel vidéo.

Types de services exogènes

Android 10 a introduit la android:foregroundServiceType dans l'attribut <service> élément. L'idée est de spécifier explicitement le type de travail effectué par le service.

Android 14 rend obligatoire la spécification du type de service d'avant-plan. Cette mesure vise à garantir l'utilisation correcte des services d'avant-plan et la cohérence entre les différents fabricants d'appareils.

Les types actuellement pris en charge sont les suivants :

  • caméra (requis dans Android 11) - lors de l'accès à l'appareil photo depuis l'arrière-plan, comme les applications d'appel vidéo.
  • appareil connecté - lors de l'interaction avec un appareil externe, tel qu'un appareil de fitness Bluetooth
  • dataSync - lors du chargement ou du téléchargement de données, sera obsolète et des alternatives telles que DownloadManager, BackupManager, ou WorkManager devraient être utilisées à la place.
  • la santé (nouveau dans Android 14) - pour les applications de fitness telles que les traqueurs d'exercice.
  • emplacement (obligatoire dans Android 10) - lorsque l'emplacement est requis, par exemple pour la navigation
  • mediaPlayback - lors de la poursuite de la lecture d'un fichier audio ou vidéo en arrière-plan, comme Spotify ou Netflix
  • médiaProjection - lors de la projection de contenu sur des appareils ou des écrans externes
  • microphone (requis dans Android 11) - lors de l'accès au microphone en arrière-plan, par exemple pour les applications d'appel.
  • appel téléphonique - lors de la poursuite d'un appel en cours
  • messagerie à distance (nouveau dans Android 14) - lors du transfert de messages texte d'un appareil à l'autre
  • service court — lorsqu’il est nécessaire de mener à bien rapidement une tâche critique qui ne peut être interrompue et qui ne peut s’exécuter que pendant environ 3 minutes
  • utilisation spéciale — lorsque les autres types ne correspondent pas à votre cas d'utilisation
  • systèmeExempté - réservé aux applications système

Déclarer le type de service d'avant-plan

La première étape de la prise en charge d'Android 14 consiste à mettre à jour votre déclaration de service dans le fichier AndroidManifest et à spécifier le type de service d'avant-plan correct.

Si votre service nécessite plusieurs types, vous pouvez les combiner en utilisant l'opérateur | comme suit :

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

Si vous essayez de démarrer un service en avant-plan sans déclarer son type dans le manifeste, le système émettra un MissingForegroundServiceTypeException lors de l'appel startForeground().

Demander l'autorisation d'un service d'avant-plan spécifique

À partir d'Android 9 (API 28), les applications devaient demander SERVICE_DE_PREMIER_PLAN dans le manifeste de l'application, qui a été accordée automatiquement par le système.

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

À partir d'Android 14 (API 34), les applications doivent en outre demander des autorisations spécifiques en fonction du type de service au premier plan. Ainsi, si votre service continue d'accéder au microphone depuis l'arrière-plan, vous devrez spécifier PREMIER_SERVICE_MICROPHONE. L'autorisation est automatiquement accordée par le système.

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

Si votre service nécessite plusieurs types, vous devez déclarer cette autorisation pour chaque type.

Si vous oubliez de déclarer l'une de ces deux autorisations, vous recevrez un Exception de sécurité avec la raison exacte.

Sur Android 13 (API 33) et plus, déclarez également POST_NOTIFICATIONS et la demander à l'exécution si vous avez besoin que la notification de service en avant-plan apparaisse de manière fiable. Cet exemple inclut ce flux.

Lancer un service d'avant-plan

De votre Activity ou autre ContextPour cela, démarrez le service avec AndroidX afin que l'API correcte soit utilisée sur toutes les versions prises en charge (ce qui correspond à MainActivity dans ce projet) :

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() appels startForegroundService() sur API 26+ et startService() sur les anciennes API.

L'extrait de code lance un service. Cependant, le service n'est pas encore exécuté au premier plan. À l'intérieur du service lui-même, vous devez appeler startForeground() rapidement. Avec AndroidX, préférez ServiceCompat.startForeground() afin de pouvoir passer un foregroundServiceType qui correspond à votre manifeste (voir MyForegroundService dans ce projet) :

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
    },
)

Créer un NotificationChannel (Android 8.0+) avant de créer la notification, et de cliquer sur ForegroundServiceStartNotAllowedException sur l'API 31+ si l'application n'est pas autorisée à démarrer un service au premier plan à partir de l'état actuel.

Remarque : Si vous passez un type de service d'avant-plan à startForeground / ServiceCompat.startForeground que vous n'avez pas déclarée dans le manifeste, le système lance IllegalArgumentException.

Fournissez les détails de votre cas d'utilisation sur Google Play Console

Après avoir téléchargé la nouvelle version de l'application qui cible Android 14 et utilise un type de service d'avant-plan dans la Google Play Console, vous verrez apparaître dans votre console une invite à fournir des détails supplémentaires sur votre utilisation.

Google souhaitant s'assurer que les applications utilisent les services de premier plan de manière appropriée, vous devrez soumettre une nouvelle déclaration sur la page Contenu de l'application (Règles -> Contenu de l'application).

Pour chaque type de service de premier plan que vous déclarez, vous devrez procéder comme suit :

  • Décrivez la fonctionnalité de l'application qui utilise ce type de service d'avant-plan.
  • Décrire l'impact sur l'utilisateur si la tâche est reportée ou interrompue par le système.
  • Incluez un lien vers une vidéo démontrant chaque fonctionnalité de service d'avant-plan. La vidéo doit montrer les étapes que l'utilisateur doit suivre dans votre application pour déclencher la fonctionnalité.
  • Choisissez votre cas d'utilisation spécifique pour chaque type de service en avant-plan. Vous pouvez choisir parmi une liste prédéfinie de cas d'utilisation énumérés ici ou les saisir manuellement.

Exemple d'application pour les services au premier plan

Voir le Chat vidéo de base avec les services de terrain dans l'échantillon vonage-video-android-sdk-samples repo.

Plus d'informations dans le site Android Aperçu des services exogènes documentation.

Intégration du ConnectionService Android

Utiliser la fonction Service de connexion pour créer une application VoIP qui utilise les capacités audio-vidéo du SDK Android. Pour créer une application VoIP de base :

  • Enregistrer le android.telecom.ConnectionService dans le fichier 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>
  • Créer une classe qui étend la classe android.telecom.ConnectionService classe. Mettre en œuvre les méthodes de la classe ConnectionService y compris onCreateIncomingConnection(), onCreateOutgoingConnection, onCreateIncomingConnectionFailed()et onCreateOutgoingConnectionFailed().
  • Créer une classe qui étend la classe android.telecom.Connection classe. Mettre en œuvre les méthodes de la classe Connection y compris onAnswer() et onDisconnect. Dans la mise en œuvre de la onAnswer() vous pouvez vous connecter à une session Vonage Video, publier un flux dans la session et permettre au code de s'abonner aux flux créés dans la session. Dans la mise en œuvre de la méthode onDisconnect() vous pouvez vous déconnecter de la session (et cesser de publier des flux et de vous y abonner).
  • Vous pouvez utiliser un service comme Google Firebase pour mettre en place des notifications push pour l'application. Vous pouvez configurer des notifications pour savoir quand votre application est en arrière-plan ou fermée. Ainsi, votre application peut recevoir un appel VoIP alors qu'elle est fermée.

Lors de l'utilisation de ConnectionService, utiliser le AudioDeviceManager.getAudioFocusManager() et mettre en œuvre les méthodes de la méthode AudioFocusManager pour déléguer le contrôle du focus audio à votre application. Ces instances sont définies dans le SDK 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();
}

Lors de la délégation du focus audio à l'application, le SDK arrête son routage audio automatique. Au lieu de cela, cette logique de routage est gérée par ConnectionServicequi signale à l'application les appareils audio disponibles par l'intermédiaire de l'interface utilisateur de la connexion. CallEndpoint et CallAudioState API. Votre application doit prendre en charge l'énumération des périphériques audio et la logique de sélection.

Cette délégation assure un routage audio correct et une coordination avec le système Android Telecom.

Voir le exemple d'application VOIP dans le vonage-video-android-sdk-samples . Il montre comment mettre en œuvre le ConnectionService pour créer une application VoIP qui utilise le SDK Android.

Échantillons de code

Pour obtenir un exemple de code, visitez notre site repo vonage-video-android-sdk-samples sur GitHub.

Documentation et informations complémentaires

Vous trouverez une documentation détaillée de chaque méthode Android dans la section guide de référence.

Pour une liste des nouvelles fonctionnalités et des problèmes connus, voir la page notes de mise à jour.