Modo Juntos

Artigo
12/18/2024

Este artigo descreve como implementar o Modo conferência do Microsoft Teams com os SDKs de Chamada dos Serviços de Comunicação do Azure. O Modo conferência aprimora reuniões e chamadas virtuais, dando a elas uma sensação mais pessoal. Ao criar uma exibição unificada que coloca todos em uma tela de fundo compartilhada, os participantes podem se conectar perfeitamente e colaborar efetivamente.

Importante

A funcionalidade descrita neste artigo está atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Suporte

As tabelas a seguir definem o suporte ao Modo Juntos nos Serviços de Comunicação do Azure.

Identidades e tipos de chamadas

A tabela a seguir mostra o suporte para tipos de chamada e identidade.

Identidades	Reunião do Teams	Sala	Chamada 1:1	Chamada em grupo	Chamada de interoperabilidade do Teams 1:1	Chamada de interoperabilidade de Grupo do Teams
Usuário dos Serviços de Comunicação	✔️			✔️		✔️
Usuário do Microsoft 365	✔️			✔️		✔️

Operações

A tabela a seguir mostra o suporte para APIs individuais no SDK de Chamada em relação aos tipos de identidade individuais.

Operações	Usuário dos Serviços de Comunicação	Usuário do Microsoft 365
Iniciar o fluxo do Modo conferência		✔️ [1]
Obter fluxo de Modo Juntos	✔️	✔️
Obter o tamanho da cena	✔️	✔️
Obter mapa de assentos	✔️	✔️
Alterar cena
Alterar atribuição de assento

[1] Iniciar o Modo Juntos só pode ser feito por um usuário do Microsoft 365 com a função de organizador, co-organizador ou apresentador.

SDKs

A tabela a seguir mostra o suporte para o recurso de Modo Juntos em SDKs individuais dos Serviços de Comunicação do Azure.

Plataformas	Web	Interface do usuário da Web	iOS	Interface do usuário do iOS	Android	Interface do usuário do Android	Windows
Tem suporte	✔️

Instalar o SDK

Use o comando npm install para instalar o SDK Comum e de Chamada dos Serviços de Comunicação do Azure para JavaScript:

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

Inicializar objetos necessários

Uma instância CallClient é necessária para a maioria das operações de chamada. Ao criar uma instância de CallClient, você pode configurá-la com opções personalizadas, como uma instância de Logger.

Com a instância de CallClient, você pode criar uma instância de CallAgent chamando o createCallAgent. Esse método retorna de modo assíncrono um objeto de instância CallAgent.

O método createCallAgent usa CommunicationTokenCredential como um argumento. Ele aceita um token de acesso do usuário.

Você pode usar o método getDeviceManager na instância CallClient para acessar o 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()

Como gerenciar melhor a conectividade do SDK com a infraestrutura da Microsoft

A instância Call Agent ajuda você a gerenciar chamadas (para ingressar ou iniciar chamadas). Para trabalhar, o SDK de chamada precisa se conectar à infraestrutura da Microsoft para receber notificações de chamadas de entrada e coordenar outros detalhes da chamada. O seu Call Agent tem dois estados possíveis:

Conectado: um valor connectionStatue Call Agent de Connected significa que o SDK do cliente está conectado e capaz de receber notificações da infraestrutura da Microsoft.

Desconectado: um valor connectionStatue Call Agent de Disconnected declara que há um problema que está impedindo o SDK de se conectar corretamente. Call Agent deve ser recriado.

invalidToken: se um token tiver expirado ou for inválido, a instância Call Agent se desconecta com este erro.
connectionIssue: se houver um problema com o cliente se conectando à infraestrutura da Microsoft, depois de muitas tentativas Call Agent expõe o erro connectionIssue.

Você pode verificar se o local Call Agent está conectado à infraestrutura da Microsoft inspecionando o valor atual da propriedade connectionState. Durante uma chamada ativa, você pode ouvir o evento connectionStateChanged para determinar se Call Agent muda do estado Conectado para 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 o Modo conferência

O Modo Juntos é um recurso estendido da API Call principal. Primeiro, você precisa importar recursos de chamada do SDK de Chamada:

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

Em seguida, você pode obter o objeto da API do Modo conferência da instância de chamada:

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

Receber eventos quando o fluxo do Modo Juntos for iniciado ou atualizado

Você pode assinar o evento togetherModeStreamsUpdated para receber notificações quando o Modo Juntos for iniciado ou atualizado. O evento contém informações sobre como renderizar o fluxo de vídeo adicionado.

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

Obter fluxo de Modo Juntos

Você pode acessar fluxos do Modo Juntos por meio da propriedade togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Propriedades do fluxo de modo Juntos	Descrição
`id`	Número exclusivo usado para identificar o fluxo.
`mediaStreamType`	Retorna o tipo de fluxo de modo Juntos. O valor de `mediaStreamType` é sempre `video`.
`isReceiving`	Retorna um valor booliano que indica se os pacotes de vídeo são recebidos.
`size`	Retorna o modo Juntos `StreamSize` com informações sobre a largura e a altura do fluxo em pixels.

Iniciar o Modo Juntos para todos os participantes

Os usuários do Microsoft 365 com organizador de funções, co-organizador ou apresentador podem iniciar o Modo Juntos para todos na reunião. Quando o Modo conferência é iniciado, todos os assinantes do evento togetherModeStreamsUpdated recebem uma notificação que permite que os participantes renderizem o Modo conferência.

togetherModeFeature.start();

Encerrar o Modo Juntos

O Modo conferência será encerrado automaticamente para todos os participantes se nenhum fluxo de vídeo for detectado de qualquer participante durante um minuto. Não há nenhuma API para terminar o Modo Juntos.

Obter coordenadas de participantes no Modo Juntos

A propriedade togetherModeSeatingMap fornece coordenadas para participantes individuais no fluxo. Os desenvolvedores podem usar essas coordenadas para sobrepor informações do participante, como nome de exibição ou recursos visuais, como destaque, mão levantada e reações no fluxo.

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

Gerenciar o tamanho da cena

A propriedade sceneSize especifica as dimensões (largura e altura) do contêiner HTML que abriga o fluxo de vídeo togetherMode. As posições de assento dos participantes são calculadas com base nas dimensões do tamanho da cena. Se o tamanho da cena não for fornecido, o cálculo usará como padrão uma largura de 1.280 pixels e uma altura 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 )}`)

Receber eventos quando a cena ou os assentos forem atualizados

Observação

Somente usuários do Microsoft 365 com organizador de funções, co-organizador ou apresentador podem alterar a cena ou a atribuição de participantes no Modo conferência. Essas alterações só podem ser feitas no Cliente do Teams.

Se houver uma alteração de cena ou alteração de assento, os eventos togetherModeSceneUpdated ou togetherModeSeatingUpdated serão gerados respectivamente, fornecendo um cálculo atualizado das posições de assento do 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);

Solução de problemas

Código	Subcódigo	Categoria de resultado	Motivo	Resolução
403	46303	ExpectedError	A função do participante não tem as permissões necessárias para chamar a API de início `togetherMode`.	Somente usuários do Microsoft 365 com a função de organizador, co-organizador ou apresentador podem iniciar o Modo conferência. Você pode verificar a função de um usuário por meio da propriedade `role` na instância da classe `Call`.
403	46304	ExpectedError	O Modo Juntos foi iniciado em um cenário de chamada sem suporte.	Verifique se o Modo Juntos é iniciado apenas em cenários de chamada em grupo ou de reunião.
403	46306	ExpectedError	API `start` de Modo Juntos chamada por um usuário dos Serviços de Comunicação do Azure.	Somente usuários do Microsoft 365 com a função de organizador, co-organizador ou apresentador podem iniciar o Modo conferência.

Compartilhar via