Zusammen-Modus

In diesem Artikel wird beschrieben, wie Sie den Microsoft Teams-Zusammen-Modus mit Azure Communication Services Calling-SDKs implementieren. Der Zusammen-Modus verbessert virtuelle Besprechungen und Anrufe und macht sie persönlicher. Durch die Erstellung einer einheitlichen Ansicht, die alle Personen vor einem gemeinsamen Hintergrund platziert, können die Teilnehmer nahtlos und effektiv zusammenarbeiten.

Unterstützung

In den folgenden Tabellen wird die Unterstützung für den Together-Modus in Azure Communication Services beschrieben.

Identitäten und Anruftypen

Die folgende Tabelle zeigt die Unterstützung für Anruf- und Identitätstypen.

Vorgänge

Die folgende Tabelle zeigt die Unterstützung einzelner APIs im Calling SDK für einzelne Identitätstypen.

[1] Der „Zusammen-Modus starten“ kann nur von einem Microsoft 365-Benutzer mit der Rolle „Organisator“, „Mitorganisator“ oder „Präsentator“ aufgerufen werden.

SDKs

Die folgende Tabelle zeigt die Unterstützung des Zusammen-Modus-Features in einzelnen Azure Communication Services-SDKs.

Das SDK installieren

Verwenden Sie den Befehl npm install, um die Common und Calling SDKs von Azure Communication Services für JavaScript zu installieren:

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

Initialisieren erforderlicher Objekte

Für die meisten Anrufvorgänge ist eine CallClient-Instanz erforderlich. Wenn Sie eine neue CallClient-Instanz erstellen, können Sie diese mit benutzerdefinierten Optionen wie einer Logger-Instanz konfigurieren.

Mit der CallClient-Instanz können Sie eine CallAgent-Instanz erstellen, indem Sie die createCallAgent aufrufen. Durch diese Methode wird ein CallAgent-Instanzobjekt asynchron zurückgegeben.

Die Methode createCallAgent verwendet CommunicationTokenCredential als Argument, welches ein Benutzerzugriffstoken akzeptiert.

Sie können die Methode getDeviceManager für die Instanz CallClient verwenden, um auf deviceManager zuzugreifen.

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

Verwalten der SDK-Konnektivität mit der Microsoft-Infrastruktur

Die Call Agent-Instanz unterstützt Sie bei der Verwaltung von Anrufen (Annehmen oder Starten von Anrufen). Damit Ihr Calling SDK funktioniert, muss eine Verbindung mit der Microsoft-Infrastruktur hergestellt werden, um Benachrichtigungen über eingehende Anrufe zu erhalten und andere Anrufdetails zu koordinieren. Ihre Call Agent-Instanz kann zwei Status haben:

Connected (Verbunden) – Der connectionState-Wert Call Agent für Connected bedeutet, dass das Client-SDK verbunden ist und Benachrichtigungen von der Microsoft-Infrastruktur empfangen kann.

Getrennt: Der connectionState-Wert Call Agent für Disconnected weist darauf hin, dass das SDK nicht ordnungsgemäß verbunden werden kann. Call Agent muss neu erstellt werden.

• invalidToken: Wenn ein Token abgelaufen oder ungültig ist, trennt sich die Call Agent Instanz aufgrund dieses Fehlers.
• connectionIssue: Wenn ein Problem mit dem Client bei der Verbindung zur Microsoft-Infrastruktur auftritt, zeigt Call Agent nach vielen Versuchen den connectionIssue Fehler an.

Sie können überprüfen, ob Ihre lokale Call Agent-Instanz mit der Microsoft-Infrastruktur verbunden ist, indem Sie den aktuellen Wert der connectionState-Eigenschaft prüfen. Während eines aktiven Anrufs können Sie auf das connectionStateChanged-Ereignis lauschen, um zu bestimmen, ob sich der Call Agent-Status von Connected in Disconnected ändert.

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

Zusammen-Modus implementieren

Together Mode ist eine erweiterte Funktion der Call-Core-API. Sie müssen zunächst Anruffunktionen aus dem Calling SDK importieren:

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

Anschließend können Sie das API-Objekt für den Zusammen-Modus aus der Anrufinstanz abrufen:

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

Ereignisse empfangen, wenn der Together-Modus-Stream gestartet oder aktualisiert wird.

Sie können das Ereignis togetherModeStreamsUpdated abonnieren, um Benachrichtigungen zu empfangen, wenn der Zusammen-Modus gestartet oder aktualisiert wird. Das Ereignis enthält Informationen zum Rendern des hinzugefügten Videostreams.

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

Abrufen des Streams im Zusammen-Modus

Sie können über die Eigenschaft togetherModeStream auf Streams im Together-Modus zugreifen.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Starten Sie den Zusammen-Modus für alle Teilnehmer.

Microsoft 365-Benutzer mit den Rollen „Organisator“, „Mitorganisator“ oder „Referent“ können den Zusammen-Modus für alle Teilnehmer der Besprechung starten. Wenn der Zusammen-Modus gestartet wird, erhalten alle Abonnenten des togetherModeStreamsUpdated-Ereignisses Benachrichtigungen, mit denen Teilnehmende den Zusammen-Modus rendern können.

togetherModeFeature.start();

Beenden des Zusammen-Modus

Der Zusammen-Modus wird für alle Teilnehmer automatisch beendet, wenn eine Minute lang kein Videostream von einem der Teilnehmer erkannt wird. Es gibt keine API zum Beenden des Zusammen-Modus.

Abrufen von Koordinaten von Teilnehmenden im Zusammen-Modus

Die Eigenschaft togetherModeSeatingMap stellt Koordinaten für einzelne Teilnehmer im Stream bereit. Entwickler können diese Koordinaten verwenden, um Teilnehmerinformationen wie den Anzeigenamen oder visuelle Features wie Spotlight, gehobene Hand und Reaktionen im Stream zu überlagern.

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

Verwalten der Szenengröße

Die sceneSize-Eigenschaft gibt die Abmessungen (Breite und Höhe) des HTML-Containers an, der den togetherMode-Videostream enthält. Die Sitzplätze der Teilnehmer werden basierend auf den Abmessungen der Szene berechnet. Wenn die Szenengröße nicht angegeben ist, wird standardmäßig eine Breite von 1.280 Pixeln und eine Höhe von 720 Pixeln verwendet.

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

Empfangen von Ereignissen, wenn Szenen oder Sitzplätze aktualisiert werden

Wenn sich eine Szene oder ein Platz ändert, werden die Ereignisse togetherModeSceneUpdated bzw. togetherModeSeatingUpdated ausgelöst, wobei eine aktualisierte Berechnung der Teilnehmersitzplätze bereitgestellt wird.

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

Problembehandlung

Nächste Schritte

• Informationen zum Verwalten von Anrufen
• Lernen Sie das Verwalten von Videos
• Informationen zum Aufzeichnen von Anrufen
• Lernen, wie man Anrufe transkribiert