Diagnostic de pré-appel

Article
10/26/2023

Important

Cette fonctionnalité d’Azure Communication Services est actuellement en préversion.

Ces interfaces de programmation d’applications et kits de développement logiciel (SDK) en préversion sont fournis sans contrat au niveau du service. Nous vous recommandons de ne pas les utiliser pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’utilisation supplémentaires relatives aux préversions de Microsoft Azure.

L’API de pré-appel permet aux développeurs de valider par programmation la préparation d’un client pour rejoindre un appel Azure Communication Services. Les API de pré-appel sont accessibles via le Kit de développement logiciel (SDK) d’appel. Ils fournissent plusieurs diagnostics, notamment l’appareil, la connexion et la qualité des appels. Les API de pré-appel sont disponibles uniquement pour le web (JavaScript). Nous allons activer ces fonctionnalités à travers les plateformes à l’avenir, nous fournir des commentaires sur les plateformes sur lesquelles vous souhaitez voir les API de pré-appel.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Les versions actives LTS (Prise en charge à long terme) de Node.js sont recommandées.
Une ressource Communication Services active. Créez une ressource Communication Services.
Un jeton d’accès utilisateur pour instancier le client d’appel. Découvrez comment créer et gérer des jetons d’accès utilisateur Vous pouvez également utiliser Azure CLI et exécuter la commande suivante avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès. (Vous devez récupérer la chaîne de connexion de la ressource via le Portail Azure.)
```
az communication identity token issue --scope voip --connection-string "yourConnectionString"
```
Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Accès aux API de pré-appel

Important

Les diagnostics de pré-appel sont disponibles à partir de la version 1.9.1-beta.1 du kit de développement logiciel (SDK) d’appel. Veillez à utiliser cette version lors de l’essai des instructions suivantes.

Pour accéder à l’API de pré-appel, vous devez initialiser un callClientjeton d’accès Azure Communication Services et provisionner un jeton d’accès Azure Communication Services. Vous pouvez accéder ici à la PreCallDiagnostics fonctionnalité et à la startTest méthode.

import { CallClient, Features} from "@azure/communication-calling";
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

const callClient = new CallClient(); 
const tokenCredential = new AzureCommunicationTokenCredential("INSERT ACCESS TOKEN");
const preCallDiagnosticsResult = await callClient.feature(Features.PreCallDiagnostics).startTest(tokenCredential);

Une fois l’exécution terminée, les développeurs peuvent accéder à l’objet de résultat.

Résultats du diagnostic

L’API de pré-appel retourne un diagnostic complet de l’appareil, y compris des détails tels que les autorisations d’appareil, la disponibilité et la compatibilité, les statistiques de qualité des appels et les diagnostics in-call. Les résultats sont retournés en tant qu’objet PreCallDiagnosticsResult.


export declare type PreCallDiagnosticsResult  = {
    deviceAccess: Promise<DeviceAccess>;
    deviceEnumeration: Promise<DeviceEnumeration>;
    inCallDiagnostics: Promise<InCallDiagnostics>;
    browserSupport?: Promise<DeviceCompatibility>;
    id: string;
    callMediaStatistics?: Promise<MediaStatsCallFeature>;
};

Des objets de résultat individuels sont accessibles à l’aide de la preCallDiagnosticsResult constante. Les résultats des tests individuels doivent être retournés à mesure qu’ils sont terminés avec la plupart des résultats des tests disponibles immédiatement. Si vous utilisez le inCallDiagnostics test, les résultats peuvent prendre jusqu’à 1 minute, car le test valide la qualité de la vidéo et de l’audio.

Prise en charge des navigateurs

Vérification de compatibilité du navigateur. Vérifie la compatibilité pour Browser et OS et renvoie une valeur Supported ou NotSupported.


const browserSupport =  await preCallDiagnosticsResult.browserSupport;
  if(browserSupport) {
    console.log(browserSupport.browser)
    console.log(browserSupport.os)
  }

Si le test échoue et que le navigateur utilisé par l’utilisateur est NotSupported, le moyen le plus simple de résoudre ce problème est de demander à l’utilisateur de basculer vers un navigateur pris en charge. Reportez-vous aux navigateurs pris en charge dans notre documentation.

Remarque

Problème connu : browser support test de retour Unknown dans les cas où il doit retourner une valeur correcte.

Accès sur l’appareil

Vérification des autorisations. Vérifie si les appareils vidéo et audio sont disponibles du point de vue des autorisations. Fournit une valeur boolean pour les appareils audio et video.


  const deviceAccess =  await preCallDiagnosticsResult.deviceAccess;
  if(deviceAccess) {
    console.log(deviceAccess.audio)
    console.log(deviceAccess.video)
  }

Dans le cas où le test échoue et que les autorisations sont fausses pour l’audio et la vidéo, l’utilisateur ne doit pas continuer à rejoindre un appel. Au lieu de cela, vous devez inviter l’utilisateur à activer les autorisations. Pour ce faire, la meilleure façon est de fournir l’instruction spécifique sur la façon d’accéder à l’accès aux autorisations en fonction du système d’exploitation, de la version et du navigateur sur utilisant. Pour plus d’informations sur les autorisations, case activée nos recommandations.

Énumération de l’appareil

Disponibilité de l’appareil. Vérifie si les appareils microphone, caméra et haut-parleur sont détectés dans le système et prêts à être utilisés. Renvoie une valeur Available ou NotAvailable.


  const deviceEnumeration = await preCallDiagnosticsResult.deviceEnumeration;
  if(deviceEnumeration) {
    console.log(deviceEnumeration.microphone)
    console.log(deviceEnumeration.camera)
    console.log(deviceEnumeration.speaker)
  }

Dans le cas où les appareils ne sont pas disponibles, l’utilisateur ne doit pas continuer à rejoindre un appel. Au lieu de cela, l’utilisateur doit être invité à vérifier les connexions de l’appareil pour s’assurer que tous les casques, caméras ou haut-parleurs sont correctement connectés. Pour plus d’informations sur la gestion des appareils, case activée notre documentation

Diagnostics InCall

Effectue un appel rapide pour vérifier les métriques d’appel audio et vidéo et fournit des résultats. Inclut la connectivité (connected, booléenne), la qualité de la bande passante (bandWidth, 'Bad' | 'Average' | 'Good') et les diagnostics d’appel pour l’audio et la vidéo (diagnostics). Les diagnostics sont fournis jitter, packetLoss et rtt et les résultats sont générés à l’aide d’une qualité simple ('Bad' | 'Average' | 'Good').

Les diagnostics InCall utilisent des statistiques de qualité multimédia pour calculer les scores de qualité et diagnostiquer les problèmes. Pendant le diagnostic de pré-appel, l’ensemble complet des statistiques de qualité des médias sont disponibles pour la consommation. Ces statistiques incluent des valeurs brutes entre les métriques vidéo et audio qui peuvent être utilisées programmatiquement. Le diagnostic InCall fournit une couche pratique sur les statistiques de qualité des médias pour consommer les résultats sans avoir à traiter toutes les données brutes. Pour obtenir des instructions sur l’accès, consultez la section relative aux statistiques des médias.


  const inCallDiagnostics =  await preCallDiagnosticsResult.inCallDiagnostics;
  if(inCallDiagnostics) {    
    console.log(inCallDiagnostics.connected)
    console.log(inCallDiagnostics.bandWidth)
    console.log(inCallDiagnostics.diagnostics.audio)
    console.log(inCallDiagnostics.diagnostics.video)
  }

À cette étape, il existe plusieurs points d’échec à surveiller. Les valeurs fournies par l’API sont basées sur les valeurs de seuil requises par le service. Vous trouverez ces seuils bruts dans notre documentation sur la qualité des médias.

Si la connexion échoue, l’utilisateur doit être invité à revérifier sa connectivité réseau. Les échecs de connexion peuvent également être attribués à des conditions réseau telles que DNS, proxys ou pare-feu. Pour plus d’informations sur le paramètre réseau recommandé, case activée notre documentation.
Si la bande passante est Bad, l’utilisateur doit être invité à essayer un autre réseau ou à vérifier la disponibilité de la bande passante sur son réseau actuel. Vérifiez qu’aucune autre activité à bande passante élevée n’a lieu.

Statistiques des médias

Des statistiques granulaires sur des métriques de qualité telles que la gigue, la perte de paquets, rtt, etc. callMediaStatistics sont fournies dans le cadre de la fonctionnalité preCallDiagnosticsResult. Consultez la liste complète et la description des métriques disponibles dans l’article lié. Vous pouvez vous abonner aux statistiques des médias d’appel pour obtenir une collection complète d’entre elles. Cette statistique est les métriques brutes utilisées pour calculer les résultats de diagnostic InCall et qui peuvent être consommées de manière granulaire pour une analyse plus approfondie.


const mediaStatsCollector = callMediaStatistics.startCollector(); 

mediaStatsCollector.on('mediaStatsEmitted', (mediaStats: SDK.MediaStats) => { 
    // process the stats for the call. 
    console.log(mediaStats);
});

Tarification

Lorsque le test de diagnostic de pré-appel s’exécute, en arrière-plan, il utilise les minutes d’appel pour exécuter le diagnostic. Le test dure environ 30 secondes, utilisant jusqu’à 30 secondes d’appel facturé au tarif standard de 0,004 $ par participant par minute. Pour le cas de diagnostic de pré-appel, les frais seront facturés pour 1 participant x 30 secondes = 0,002 $.

Partager via