Modo conferencia

Artículo
10/06/2024

Este artículo, explica cómo implementar el modo conferencia de Microsoft Teams con los SDK de llamadas de Azure Communication Services. El modo conferencia mejora las reuniones virtuales y las llamadas, lo que hace que se sientan más personales. Mediante la creación de una vista unificada que coloca a todos los usuarios en un fondo compartido, los participantes pueden conectarse sin problemas y colaborar de forma eficaz.

Importante

La funcionalidad descrita en este artículo se encuentra actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Soporte técnico

En las tablas siguientes se define la compatibilidad con el modo juntos en Azure Communication Services.

Identidades y tipos de llamadas

En la siguiente tabla se muestra la compatibilidad con los tipos de llamada e identidad.

Identidades	Reuniones en Teams	Sala	Llamada 1:1	Llamada grupal	Llamada de interoperabilidad de Teams individual	Llamada de interoperabilidad de Teams de grupo
Usuario de Communication Services	✔️			✔️		✔️
Usuario de Microsoft 365	✔️			✔️		✔️

Operations

En la siguiente tabla se muestra la compatibilidad con las API individuales del SDK de llamada a tipos de identidad individuales.

Operations	Usuario de Communication Services	Usuario de Microsoft 365
Iniciar secuencia del modo conferencia		✔️ [1]
Obtener transmisión del modo juntos	✔️	✔️
Obtener el tamaño de la escena	✔️	✔️
Obtener mapa de asientos	✔️	✔️
Cambiar escena
Cambio de la asignación de asientos

[1] Un usuario de Microsoft 365 solo puede llamar al modo juntos con el rol de organizador, coorganizador o moderador.

SDK

En la tabla siguiente se muestra la compatibilidad con la característica Modo juntos en SDK individuales de Azure Communication Services.

Platforms	Web	IU Web	iOS	Interfaz de usuario de iOS	Android	UI de Android	Windows
Se admite	✔️

Instalación del SDK

Use el comando npm install para instalar los SDK comunes y de llamada de Azure Communication Services para JavaScript:

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

Inicialización de los objetos necesarios

Se requiere una instancia de CallClient para la mayoría de las operaciones de llamada. Al crear una nueva instancia de CallClient, puede configurarla con opciones personalizadas, como una instancia de Logger.

Con la instancia de CallClient, puede crear una instancia de CallAgent llamando al createCallAgent. Este método devuelve un objeto de instancia CallAgent de manera asincrónica.

El método createCallAgent utiliza CommunicationTokenCredential como argumento. Acepta un token de acceso de usuario.

Puede usar el método getDeviceManager en la instancia de CallClient para acceder a 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()

Cuál es la mejor forma de administrar la conectividad del SDK en la infraestructura de Microsoft

La instancia de Call Agent le ayuda a administrar llamadas (para unirse o iniciar llamadas). Para trabajar con el SDK de llamadas, debe conectarse a la infraestructura de Microsoft para obtener notificaciones de llamadas entrantes y coordinar otros detalles de la llamada. Call Agent tiene dos posibles estados:

Conectado: un valor connectionStatue Call Agent con estado Connected significa que el SDK de cliente está conectado y es capaz de recibir notificaciones de la infraestructura de Microsoft.

Desconectado: un valor connectionStatue Call Agent con estado Disconnected indica que hay un problema que impide que el SDK se conecte correctamente. Call Agent se debe volver a crear.

invalidToken: si un token ha expirado o no es válido, la instancia de Call Agent se desconecta con este error.
connectionIssue: si hay un problema cuando el cliente se conecta a la infraestructura de Microsoft, después de muchos reintentos, Call Agent expone el error connectionIssue.

Para comprobar si el Call Agent local está conectado a la infraestructura de Microsoft, inspeccione el valor actual de la propiedad connectionState. Durante una llamada activa, puede escuchar el evento connectionStateChanged para determinar si Call Agent cambia de Conectado a Desconectado.

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);

Implementar el modo conferencia

El modo juntos es una característica extendida de la API principal de Call. En primer lugar, debe importar las características de llamada desde el SDK de llamada:

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

A continuación, puede obtener el objeto de API del modo conferencia de la instancia de llamada:

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

Recibir eventos cuando se inicia o actualiza la secuencia del modo juntos

Puede suscribirse al evento togetherModeStreamsUpdated para recibir notificaciones cuando se inicia o actualiza el modo juntos. El evento contiene información sobre cómo representar la secuencia de vídeo agregada.

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

Obtener transmisión del modo juntos

Puede acceder a secuencias en modo juntos a través de la propiedad togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Propiedades de secuencia de modo juntos	Descripción
`id`	Número único que se usa para identificar la secuencia.
`mediaStreamType`	Devuelve el tipo de secuencia Modo juntos. El valor de `mediaStreamType` siempre es `video`.
`isReceiving`	Devuelve un valor booleano que indica si se reciben paquetes de vídeo.
`size`	Devuelve el modo juntos `StreamSize` con información sobre el ancho y el alto de la secuencia en píxeles.

Iniciar el modo juntos para todos los participantes

Los usuarios de Microsoft 365 con organizador de roles, coorganizador o moderador pueden iniciar el modo Juntos para todos los usuarios de la reunión. Cuando se inicia el modo juntos, todos los suscriptores al evento togetherModeStreamsUpdated reciben notificaciones que permiten a los participantes representar el modo conferencia.

togetherModeFeature.start();

Fin del modo juntos

El modo conferencia finaliza automáticamente para todos los participantes si no se detecta ninguna secuencia de vídeo de cualquier participante durante un minuto. No hay ninguna API para finalizar el modo juntos.

Obtener coordenadas de los participantes en el modo juntos

La propiedad togetherModeSeatingMap proporciona coordenadas para los participantes individuales de la secuencia. Los desarrolladores pueden usar estas coordenadas para superponer la información del participante, como el nombre para mostrar o las características visuales, como el contenido destacado, las reacciones y las reacciones en la secuencia.

// 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;

Administrar el tamaño de la escena

La propiedad sceneSize especifica las dimensiones (ancho y alto) del contenedor HTML que alberga la secuencia de vídeo togetherMode. Las posiciones de asiento de los participantes se calculan en función de las dimensiones del tamaño de la escena. Si no se proporciona el tamaño de la escena, el cálculo tiene como valor predeterminado un ancho de 1280 píxeles y un alto de 720 píxeles.

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

Recibir eventos cuando la escena o los asientos se actualizan

Nota:

Solo los usuarios de Microsoft 365 con organizador de roles, coorganizador o moderador pueden cambiar la escena o la asignación de participantes en el modo juntos. Estos cambios solo se pueden realizar desde el cliente de Teams.

Si hay un cambio de escena o un cambio de asiento, los eventos togetherModeSceneUpdated o togetherModeSeatingUpdated se generan respectivamente, proporcionando un cálculo actualizado de las posiciones de asiento del participante.

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);

Solución de problemas

Código	SubCode	Categoría de resultado	Motivo	Solución
403	46303	ExpectedError	El rol del participante no tiene los permisos necesarios para llamar a la API de inicio de `togetherMode`.	Solo los usuarios de Microsoft 365 con organizador de roles, coorganizador o moderador pueden iniciar el modo juntos. Puede comprobar el rol de un usuario mediante la propiedad `role` en la instancia de la clase `Call`.
403	46304	ExpectedError	El modo juntos se inició en un escenario de llamada no admitido.	Asegúrese de que el modo juntos solo se inicia en escenarios de llamada grupal o reunión.
403	46306	ExpectedError	El modo juntos `start` API llamada por un usuario de Azure Communication Services.	Solo los usuarios de Microsoft 365 con organizador de roles, coorganizador o moderador pueden iniciar el modo juntos.

Compartir a través de