Mode Ensemble

Cet article explique comment implémenter le mode Ensemble de Microsoft Teams avec les Kits de développement logiciel (SDK) Appel Azure Communication Services. Le mode Ensemble améliore les réunions virtuelles et les appels en leur apportant une touche plus personnelle. Grâce à une vue unifiée qui place tout le monde dans un arrière-plan partagé, les participants peuvent se connecter en toute transparence et collaborer efficacement.

Support

Les tableaux suivants définissent la prise en charge du mode Ensemble dans Azure Communication Services.

Identités et types d’appels

Le tableau suivant présente la prise en charge des types d’appels et d’identités.

Opérations

Le tableau suivant indique la prise en charge des différentes API du kit SDK Calling pour les types d’identités individuels.

[1] Démarrer le mode Ensemble ne peut être appelé que par un utilisateur Microsoft 365 avec le rôle d’organisateur, de co-organisateur ou de présentateur.

SDK

Le tableau suivant indique la prise en charge du mode Ensemble dans les différents kits SDK Azure Communication Services.

Installer le SDK

Utilisez la commande npm install pour installer le SDK Azure Communication Services Common et le SDK Azure Communication Services Calling pour JavaScript :

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

Initialiser les objets nécessaires

Une instance CallClient est requise pour la plupart des opérations d’appel. Lorsque vous créez une instance CallClient, vous pouvez la configurer avec des options personnalisées comme une instance Logger.

Avec l’instance CallClient, vous pouvez créer une instance CallAgent en appelant createCallAgent. Cette méthode renvoie un objet d’instance CallAgent de manière asynchrone.

La méthode createCallAgent utilise CommunicationTokenCredential comme argument. Elle accepte un jeton d’accès utilisateur.

Vous pouvez utiliser la méthode getDeviceManager sur l’instance CallClient pour accéder à deviceManager.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Comment gérer au mieux la connectivité du SDK à l’infrastructure Microsoft

L’instance Call Agent vous aide à gérer les appels (pour rejoindre ou démarrer des appels). Pour fonctionner, votre SDK d’appel doit se connecter à l’infrastructure Microsoft pour recevoir des notifications d’appels entrants et coordonner d’autres détails de l’appel. Votre Call Agent a deux états possibles :

Connecté : un Call Agent dont la valeur connectionStatue est égale à Connected signifie que le SDK client est connecté et capable de recevoir des notifications de l’infrastructure Microsoft.

Déconnecté : un Call Agent dont la valeur connectionStatue est égale à Disconnected indique qu’un problème empêche le SDK de se connecter correctement. Call Agent doit être recréé.

• invalidToken : si un jeton a expiré ou n’est pas valide, l’instance Call Agent se déconnecte avec cette erreur.
• connectionIssue : en cas de problème de connexion du client à l’infrastructure Microsoft, après plusieurs tentatives, Call Agent lève l’erreur connectionIssue.

Vous pouvez vérifier si votre Call Agent local est connecté à l’infrastructure Microsoft en inspectant la valeur actuelle de la propriété connectionState. Pendant un appel actif, vous pouvez écouter l’événement connectionStateChanged pour déterminer si Call Agent passe de l’état Connecté à l’état Déconnecté.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Implémenter le mode Ensemble

Le mode Ensemble est une fonctionnalité étendue de l’API Call principale. Vous devez d’abord importer les fonctionnalités d’appel à partir du Kit de développement logiciel (SDK) Appel :

import { Features} from "@azure/communication-calling";

Vous pouvez ensuite récupérer l’objet d’API du mode Ensemble à partir de l’instance d’appel :

const togetherModeFeature = call.feature(Features.TogetherMode);

Recevoir des événements lorsque le flux de mode Ensemble démarre ou est mis à jour

Vous pouvez vous abonner à l’événement togetherModeStreamsUpdated pour recevoir des notifications en cas de démarrage ou de mise à jour du mode Ensemble. L’événement contient des informations sur le rendu du flux vidéo ajouté.

// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] }
togetherModeFeature.on('togetherModeStreamsUpdated', (event) => {
    event.added.forEach(async stream => {
        // stream can be rendered as a remote video stream
    });
});

Obtenir un flux de mode Ensemble

Vous pouvez accéder aux flux de mode Ensemble via la propriété togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Démarrer le mode Ensemble pour tous les participants

Les utilisateurs de Microsoft 365 disposant du rôle d’organisateur, de co-organisateur ou de présentateur peuvent démarrer le mode Ensemble pour tous les participants à la réunion. Lorsque le mode Ensemble démarre, tous les abonnés à l’événement togetherModeStreamsUpdated reçoivent une notification qui permet aux participants d’afficher le mode Ensemble.

togetherModeFeature.start();

Mettre fin au mode Ensemble

Le mode Ensemble se termine automatiquement pour tous les participants si aucun flux vidéo n’est détecté d’aucun participant pendant une durée d’une minute. Il n’existe aucune API pour mettre fin au mode Ensemble.

Obtenir les coordonnées des participants en mode Ensemble

La propriété togetherModeSeatingMap fournit les coordonnées des différents participants dans le flux. Les développeurs peuvent utiliser ces coordonnées pour superposer des informations sur les participants telles que le nom d’affichage ou des fonctionnalités visuelles telles que les projecteurs, les mains levées et les réactions sur le flux.

// returns Map<string, TogetherModeSeatingPosition>
// where the  key is the participant ID
// and value of type TogetherModeSeatingPosition is the position relative to the sceneSize
// TogetherModeSeatingPosition {
//   top: number;
//   left: number;
//   width: number;
//   height: number;
// }
const seatingMap = togetherModeFeature.togetherModeSeatingMap;

Gérer la taille de la scène

La propriété sceneSize spécifie les dimensions (largeur et hauteur) du conteneur HTML qui héberge le flux vidéo togetherMode. Les positions assises des participants sont calculées en fonction des dimensions de la taille de la scène. Si la taille de la scène n’est pas fournie, le calcul est défini par défaut sur une largeur de 1280 pixels et une hauteur de 720 pixels.

const togetherModeContainerSize = { width: 500, height: 500 };

// To set the scene size
togetherModeFeature.sceneSize = togetherModeContainerSize;

// To get the scene size
console.log(`Current scene has the following size: ${JSON.stringify(togetherModeFeature.sceneSize )}`)

Recevoir des événements en cas de mise à jour de la scène ou des sièges

En cas de changement de scène ou de siège, les événements togetherModeSceneUpdated ou togetherModeSeatingUpdated sont respectivement déclenchés, fournissant un calcul mis à jour des positions des sièges des participants.

const seatUpdate = (participantSeatingMap) => {
    participantSeatingMap.forEach((participantID, seatingCoordinates) => {
        console.log(`User with ID: ${participantID} has new coordinates ${JSON.stringify(seatingCoordinates)} `)
    })
}

togetherModeFeature.on('togetherModeSceneUpdated', seatUpdate);
togetherModeFeature.on('togetherModeSeatingUpdated', seatUpdate);

Dépannage

Étapes suivantes

• Découvrir comment gérer les appels
• Découvrir comment gérer la vidéo
• Découvrez comment enregistrer les appels
• Découvrir comment transcrire les appels