Modalità Insieme

Articolo
12/18/2024

Questo articolo descrive come implementare la modalità Insieme di Microsoft Teams con Servizi di comunicazione di Azure SDK per chiamate. La modalità Together migliora le riunioni virtuali e le chiamate, rendendole più personali. Creando una visualizzazione unificata che inserisce tutti gli utenti in uno sfondo condiviso, i partecipanti possono connettersi in modo trasparente e collaborare in modo efficace.

Importante

Attualmente la funzionalità descritta in questo articolo è disponibile in anteprima pubblica. Questa versione di anteprima viene fornita senza contratto di servizio, pertanto se ne sconsiglia l’uso per i carichi di lavoro in ambienti di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Supporto tecnico

Le tabelle seguenti definiscono il supporto per la modalità Together in Servizi di comunicazione di Azure.

Identità e tipi di chiamata

Nella tabella seguente viene illustrato il supporto per i tipi di chiamata e identità.

Identità	Riunione di Teams	Club	1:1 Chiamata	Chiamata di gruppo	Chiamata di interoperabilità di Teams 1:1	Chiamata di interoperabilità di Teams di gruppo
Utente di Servizi di comunicazione	✔️			✔️		✔️
Utente di Microsoft 365	✔️			✔️		✔️

Operazioni

La tabella seguente illustra il supporto per le singole API in Calling SDK per singoli tipi di identità.

Operazioni	Utente di Servizi di comunicazione	Utente di Microsoft 365
Avvia flusso in modalità together		✔️ [1]
Flusso Get Together Mode	✔️	✔️
Ottenere le dimensioni della scena	✔️	✔️
Ottenere la mappa dei posti a sedere	✔️	✔️
Cambia scena
Cambia assegnazione posto

[1] La modalità Start Together può essere chiamata solo da un utente di Microsoft 365 con il ruolo di organizzatore, co-organizzatore o relatore.

SDK

La tabella seguente illustra il supporto per la funzionalità Together Mode in singoli SDK Servizi di comunicazione di Azure.

Piattaforme	Web	Interfaccia utente Web	iOS	Interfaccia utente iOS	Android	Interfaccia utente Android	Finestre
Supportato	✔️

Installazione dell'SDK

Usare il comando npm install per installare SDK comuni e di chiamata di Servizi di comunicazione di Azure per JavaScript:

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

Inizializzare gli oggetti necessari

Per la maggior parte delle operazioni di chiamata è necessaria un'istanza di CallClient. Quando si crea una nuova istanza di CallClient, è possibile configurarla con opzioni personalizzate come un'istanza di Logger.

Con l'istanza di CallClient è possibile creare un'istanza di CallAgent chiamando il createCallAgent. Questo metodo restituisce in modo asincrono un oggetto istanza CallAgent.

Il metodo createCallAgent usa CommunicationTokenCredential come argomento. Accetta un token di accesso utente.

È possibile usare il metodo getDeviceManager nell'istanza di CallClient per accedere 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()

Come gestire al meglio la connettività dell'SDK all'infrastruttura Microsoft

L'istanza Call Agent consente di gestire le chiamate (per partecipare o avviare le chiamate). Per lavorare con l'SDK per chiamate, è necessario connettersi all'infrastruttura Microsoft per ricevere notifiche delle chiamate in arrivo e coordinare altri dettagli delle chiamate. Call Agent ha due possibili stati:

Connesso : un valore connectionStatue Call Agent di Connected indica che l'SDK client è connesso e in grado di ricevere notifiche dall'infrastruttura Microsoft.

Disconnesso : un valore connectionStatue Call Agent di Disconnected indica un problema che impedisce all'SDK di connettersi correttamente. Call Agent deve essere ricreato.

invalidToken: se un token è scaduto o non è valido l'istanza Call Agent si disconnette con questo errore.
connectionIssue: se si verifica un problema con il client che si connette a Microsoft infrascture, dopo molti tentativi Call Agent espone l'errore connectionIssue.

È possibile verificare se l'infrastruttura locale Call Agent è connessa all'infrastruttura Microsoft controllando il valore corrente della proprietà connectionState. Durante una chiamata attiva è possibile restare in ascolto dell'evento connectionStateChanged per determinare se Call Agent cambia dallo stato Connesso a Disconnesso.

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

Implementare la modalità insieme

Together Mode è una funzionalità estesa dell'API principale Call . È prima necessario importare le funzionalità chiamante da Calling SDK:

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

È quindi possibile ottenere l'oggetto API Together Mode dall'istanza di chiamata:

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

Ricevere eventi all'avvio o all'aggiornamento del flusso in modalità together

Puoi sottoscrivere l'evento togetherModeStreamsUpdated per ricevere notifiche all'avvio o agli aggiornamenti della modalità Insieme. L'evento contiene informazioni sul rendering del flusso video aggiunto.

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

Flusso Get Together Mode

È possibile accedere ai flussi in modalità together tramite la proprietà togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Proprietà del flusso in modalità together	Descrizione
`id`	Numero univoco usato per identificare il flusso.
`mediaStreamType`	Restituisce il tipo di flusso Together Mode. Il valore di `mediaStreamType` è sempre `video`.
`isReceiving`	Restituisce un valore booleano che indica se vengono ricevuti pacchetti video.
`size`	Restituisce la modalità `StreamSize` Together con informazioni sulla larghezza e l'altezza del flusso in pixel.

Avvia modalità together per tutti i partecipanti

Gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o relatore possono avviare la modalità Insieme per tutti gli utenti della riunione. All'avvio della modalità Together, tutti i sottoscrittori dell'evento togetherModeStreamsUpdated ricevono una notifica che consente ai partecipanti di eseguire il rendering della modalità Insieme.

togetherModeFeature.start();

Modalità End Together

La modalità Together termina automaticamente per tutti i partecipanti se non viene rilevato alcun flusso video da qualsiasi partecipante per una durata di un minuto. Non esiste alcuna API per terminare la modalità Together.

Ottenere le coordinate dei partecipanti in modalità Together

La proprietà togetherModeSeatingMap fornisce coordinate per i singoli partecipanti nel flusso. Gli sviluppatori possono usare queste coordinate per sovrapporre informazioni sui partecipanti, ad esempio il nome visualizzato o le funzionalità visive, ad esempio contenuti in evidenza, alzati a mano e reazioni sul flusso.

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

Gestire le dimensioni della scena

La sceneSize proprietà specifica le dimensioni (larghezza e altezza) del contenitore HTML che ospita il togetherMode flusso video. Le posizioni dei partecipanti vengono calcolate in base alle dimensioni della scena. Se le dimensioni della scena non vengono specificate, il calcolo usa per impostazione predefinita una larghezza di 1.280 pixel e un'altezza di 720 pixel.

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

Ricevere eventi quando la scena o i posti a sedere vengono aggiornati

Nota

Solo gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o relatore possono modificare la scena o l'assegnazione di partecipanti in modalità Insieme. Queste modifiche possono essere apportate solo dal client di Teams.

Se si verifica un cambiamento di scena o un cambio di posti a sedere, gli togetherModeSceneUpdated eventi o togetherModeSeatingUpdated vengono generati rispettivamente, fornendo un calcolo aggiornato delle posizioni dei posti a sedere dei partecipanti.

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

Risoluzione dei problemi

Codice	Codice secondario	Categoria dei risultati	Motivo	Risoluzione
403	46303	ExpectedError	Il ruolo del partecipante non dispone delle autorizzazioni necessarie per chiamare l'API `togetherMode` di avvio.	Solo gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o relatore possono avviare la modalità Insieme. È possibile controllare il ruolo di un utente tramite `role` proprietà nell'istanza della `Call` classe .
403	46304	ExpectedError	La modalità Together è stata avviata in uno scenario di chiamata non supportato.	Assicurarsi che la modalità Together sia avviata solo in scenari di chiamata di gruppo o riunione.
403	46306	ExpectedError	API Modalità `start` insieme chiamata da un utente Servizi di comunicazione di Azure.	Solo gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o relatore possono avviare la modalità Insieme.

Condividi tramite