Meilleures pratiques : Kit de développement logiciel (SDK) d’appel Azure Communication Services

  • Article

Cet article fournit des informations sur les bonnes pratiques relatives aux SDK d’appel Azure Communication Services.

Bonnes pratiques relatives au SDK JavaScript web d’Azure Communication Services

Cette section fournit des informations sur les meilleures pratiques associées au Kit de développement logiciel (SDK) JavaScript pour les appels audio et vidéo Azure Communication Services.

Kit de développement logiciel (SDK) JavaScript pour les appels audio et vidéo

Brancher un microphone ou l’activer à partir du gestionnaire de périphériques lorsqu’un appel Azure Communication Services est en cours

Quand aucun microphone n’est disponible au début d’un appel, puis qu’un microphone devient disponible, l’évènement de diagnostic d’appel « noMicrophoneDevicesEnumerated » est déclenché. Dans ce cas, votre application doit appeler askDevicePermission pour obtenir le consentement de l’utilisateur pour énumération les appareils. L’utilisateur peut ensuite activer/désactiver le microphone.

Supprimer la vue du convertisseur de flux vidéo

Les applications Communication Services doivent supprimer VideoStreamRendererView, ou son instance parente VideoStreamRenderer, lorsqu’elles ne sont plus nécessaire.

Raccrocher l’appel lors d’un événement onbeforeunload

Votre application doit appeler call.hangup lorsque l'événement onbeforeunload est émis.

Gestion de plusieurs appels sur plusieurs onglets sur des appareils mobiles

Votre application ne doit pas se connecter aux appels depuis plusieurs onglets de navigateur simultanément, car cela peut entraîner un comportement non défini en raison de l’allocation de ressource pour le microphone et la caméra sur l’appareil. Les développeurs sont encouragés à toujours raccrocher un appel quand il est effectué en arrière-plan avant d’en démarrer un nouveau.

Gérer l’appel de désactivation du système d’exploitation lorsqu’un appel téléphonique entre.

Pendant un appel Azure Communication Services (pour iOS et Android), si un appel téléphonique arrive ou que l’assistant vocal est activé, le système d’exploitation désactive automatiquement le micro et la caméra de l’utilisateur. Sur Android, l’appel est automatiquement activé et la vidéo redémarre une fois l’appel téléphonique terminé. Sur iOS, une action de l’utilisateur est nécessaire pour « réactiver le son » et « redémarrer la vidéo ». Vous pouvez écouter la notification indiquant que le microphone a été coupé de manière inattendue avec l’événement de qualité microphoneMuteUnexpectedly. Notez que pour pouvoir participer à un appel de manière appropriée, vous devez utiliser le kit de développement logiciel (SDK) 1.2.3-beta.1 ou une version ultérieure.

const latestMediaDiagnostic = call.api(SDK.Features.Diagnostics).media.getLatest();
const isIosSafari = (getOS() === OSName.ios) && (getPlatformName() === BrowserName.safari);
if (isIosSafari && latestMediaDiagnostic.microphoneMuteUnexpectedly && latestMediaDiagnostic.microphoneMuteUnexpectedly.value) {
  // received a QualityEvent on iOS that the microphone was unexpectedly muted - notify user to unmute their microphone and to start their video stream
}

Votre application doit appeler call.startVideo(localVideoStream); pour démarrer un flux vidéo et utiliser this.currentCall.unmute(); pour activer le son.

Gestion des appareils

Vous pouvez utiliser le Kit de développement logiciel (SDK) Azure Communication Services pour gérer vos appareils et vos opérations multimédias.

  • Votre application ne doit pas utiliser les API de navigateur natives comme getUserMedia ou getDisplayMedia pour acquérir des flux en dehors du Kit de développement logiciel (SDK). Si vous le faites, vous devrez supprimer manuellement vos flux de médias avant d’utiliser DeviceManager ou d'autres API de gestion des appareils via le kit de développement logiciel (SDK) Communication Services.

Demander des autorisations d’appareil

Vous pouvez demander des autorisations d’appareil à l’aide du Kit de développement logiciel (SDK) :

  • Votre application doit utiliser DeviceManager.askDevicePermission pour demander l’accès à des périphériques audio et/ou vidéo.
  • Si l’utilisateur refuse l’accès, DeviceManager.askDevicePermission retourne la valeur « false » pour un type d’appareil donné (audio ou vidéo) lors des appels suivants, même après l’actualisation de la page. Dans ce scénario, votre application doit détecter que l’utilisateur a précédemment refusé l’accès et demander à l’utilisateur de réinitialiser manuellement ou d’accorder explicitement l’accès à un type d’appareil donné.

Appareil photo utilisé par un autre processus

  • Sur Windows Chrome et Windows Microsoft Edge, si vous démarrez/joignez/acceptez un appel avec la vidéo activée et que la caméra est utilisée par un autre processus que le navigateur sur lequel le kit de développement logiciel (SDK) web s’exécute, l’appel est lancé avec l’audio uniquement et pas la vidéo. Un UFD cameraStartFailed est déclenché, car la caméra n’a pas pu démarrer parce qu’elle était utilisée par un autre processus. Il en va de même pour l’activation de la vidéo durant un appel. Vous pouvez désactiver la caméra dans l’autre processus afin que ce processus la libère, puis redémarrer la vidéo à partir de l’appel pour que la vidéo s’active pour l’appel, et que les participants distants commencent à voir votre vidéo.
  • Ce n’est pas un problème dans macOS Chrome ni dans macOS Safari, car le système d’exploitation permet aux processus et aux threads de partager la caméra.
  • Sur les appareils mobiles, si un processus A demande la caméra et que celle-ci est utilisée par un processus B, le processus A accapare la caméra et le processus B cesse de l’utiliser
  • Sur iOS Safari, vous ne pouvez pas utiliser la caméra pour plusieurs clients d’appel dans le même onglet ni dans différents onglets. Quand un client d’appel utilise la caméra, il l’accapare et elle cesse d’être disponible pour tout client d’appel précédent qui l’utilisait. Le client d’appel précédent obtient un UFD cameraStoppedUnexpectedly.

Partage d’écran

La fermeture de l’application ne l’empêche pas d’être partagée

Par exemple, supposons que, à partir de Chromium, vous partagez l’application Microsoft Teams. Vous cliquez ensuite sur le bouton « X » sur l’application Teams pour la fermer. L’application Teams ne sera pas fermée et restera en cours d’exécution en arrière-plan. Vous verrez encore l’icône en bas à droite dans la barre de votre bureau. L’application Teams étant toujours en cours d’exécution, cela signifie qu’elle continue à partager l’écran et que le participant distant à l’appel peut toujours voir votre application Teams avec partage d’écran. Pour empêcher l’application de partager l’écran, vous devez cliquer avec le bouton droit sur son icône dans la barre de votre bureau, puis cliquer sur Quitter. Ou vous devez cliquer sur le bouton Arrêter le partage sur le navigateur. Ou appelez l’API Call.stopScreenSharing() du kit de développement logiciel (SDK).

Safari ne peut effectuer que le partage en plein écran

Safari permet uniquement de partager l’écran entier. Contrairement à Chromium, qui vous permet de partager l’écran en plein écran, une application de bureau spécifique ou un onglet de navigateur spécifique.

Autorisations de partage d’écran sur macOS

Pour effectuer le partage d’écran dans macOS Safari ou macOS Chrome, les autorisations d’enregistrement d’écran doivent être octroyées aux navigateurs dans le menu du système d’exploitation : « Préférences système » -> « Sécurité et confidentialité » -> « Enregistrement d’écran ».

Meilleures pratiques du kit de développement logiciel (SDK) natif Azure Communication Services

Cette section fournit des informations sur les meilleures pratiques associées au kit de développement logiciel (SDK) natif pour les appels audio et vidéo Azure Communication Services.

Plateformes prises en charge

Voici les exigences minimales de plateforme de système d’exploitation pour garantir des fonctionnalités optimales des kits de développement (SDK) d’appel natifs.

  • Prise en charge d’iOS 10.0 et versions ultérieures au moment de la génération et d’iOS 12.0 et versions ultérieures au moment de l’exécution.
  • XCode 12.0 et versions ultérieures.
  • Prise en charge de iPadOS 13.0 et versions ultérieures.

Demander des autorisations d’appareil à l’application

Pour utiliser les kits de développement logiciel (SDK) d’appel natifs pour effectuer ou recevoir des appels, il est nécessaire d’autoriser chaque plateforme à accéder aux ressources de l’appareil. En tant que développeur, vous devez inviter l’utilisateur à y accéder et vous assurer qu’elles sont activées. Le consommateur autorise ces droits d’accès. Vérifiez donc qu’ils ont été octroyés précédemment.

  • NSMicrophoneUsageDescription pour l’accès au microphone.
  • NSCameraUsageDescription pour l’accès à la caméra.

Configurer les journaux

L’implémentation de la journalisation conformément au didacticiel de récupération des fichiers journaux est plus critique que jamais. Les journaux détaillés aident à diagnostiquer les problèmes spécifiques aux modèles d’appareil ou aux versions de système d’exploitation qui répondent aux critères minimaux du kit de développement logiciel (SDK). Nous insistons sur le fait, pour les développeurs qui commencent à configurer l’API Journaux sans les journaux d’activité, que l’équipe Support Microsoft ne pourra pas aider à déboguer et résoudre les problèmes liés aux appels.

Suivre l’ID d’appel

CallID est l’ID unique d’un appel. Il identifie les événements corrélés de tous les participants et points de terminaison qui se connectent pendant un appel unique et, dans la plupart des cas, vous l’utilisez pour passer en revue les journaux d’activité et l’équipe Support Microsoft le demande pour aider à résoudre les problèmes des appels. Vous devez suivre le CallID dans la télémétrie que vous configurez dans votre application. Vous pouvez suivre les instructions du guide de résolution des problèmes pour comprendre comment le récupérer pour chaque plateforme.

S’abonner aux Diagnostics accessibles par l’utilisateur (User Facing Diagnostics/UFD) et aux statistiques de qualité des médias

  • Les Diagnostics accessibles par l’utilisateur (UFD) peuvent être utilisés pour examiner différentes propriétés d’un appel, pour déterminer ce que le problème en cours d’appel qui affecte vos clients peut être.
  • Les Statistiques de qualités des médias examinent les métriques de qualité audio, vidéo et de partage d’écran de bas niveau pour les métriques des appels entrants et sortants. Nous vous recommandons de collecter les données et de les envoyer à votre ingestion de pipeline après la fin de votre appel.

Gestion des erreurs

En cas d’erreur pendant l’appel ou l’implémentation, les méthodes retournent des objets d’erreur contenant des codes d’erreur. Il est essentiel d’utiliser ces objets d’erreur pour une gestion des erreurs appropriée et pour afficher les alertes. Les états d’appel retournent également des codes d’erreur pour permettre d’identifier la raison de l’échec de l’appel. Vous pouvez vous référer au guide de résolution des problèmes pour résoudre tout type de problème.

Gérer les flux vidéo

Veillez à supprimer le VideoStreamRendererView quand la vidéo n’est plus affichée sur l’interface utilisateur. Utilisez VideoStreamType pour déterminer le type du flux.

Gestion générale de la mémoire

Préallouer des ressources. Initialisez votre client d’appel et toutes les ressources nécessaires pendant la phase de démarrage de votre application plutôt que à la demande. Cette approche réduit la latence lors du démarrage d’un appel.

Supprimer correctement. Vérifiez que tous les objets d’appel sont correctement supprimés après utilisation pour libérer des ressources système et éviter les fuites de mémoire. Veillez à vous désabonner des évènements empêchant les fuites de mémoire.

Caméra ou microphone utilisés par un autre processus

Il est important de noter que, sur les appareils mobiles, si plusieurs processus tentent d’accéder à la caméra ou au microphone en même temps, le premier processus de demande d’accès prend le contrôle de l’appareil. Par conséquent, le deuxième processus perdra immédiatement l’accès à celui-ci.

Optimiser la taille de l’application à l’aide de la bibliothèque de l’interface utilisateur

Optimiser la taille des bibliothèques dans le développement de logiciels est crucial pour plusieurs raisons, en particulier lorsque les applications deviennent de plus en plus complexes et grandes consommatrices de ressources.

Performances de l’application : des bibliothèques plus petites réduisent la quantité de code qui doit être chargée, analysée et exécutée par une application. Cela peut améliorer considérablement le temps de démarrage et le niveau de performance global de votre application, en particulier sur les appareils disposant de ressources limitées.

Utilisation de la mémoire : en réduisant la taille de bibliothèque, vous pouvez réduire l’empreinte mémoire du runtime d’une application. Cela est important pour les appareils mobiles, pour lesquels la mémoire est souvent limitée. Une utilisation moins importante de la mémoire peut entraîner moins de blocages système et de meilleures performances multitâche.

Étapes suivantes

Pour plus d’informations, consultez les articles suivants :