Zusammen-Modus

Artikel
12/18/2024

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.

Wichtig

Die in diesem Artikel beschriebenen Funktionen befinden sich derzeit in der öffentlichen Vorschauphase. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und ist nicht für Produktionsworkloads vorgesehen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Unterstützung

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

Identitäten und Anruftypen

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

Identities	Teams-Besprechung	Raum	1:1-Anruf	Gruppenanruf	1:1 Teams-Interoperabilitätsanruf	Gruppenteams-Interoperabilitätsanruf
Communication Services-Benutzer	✔️			✔️		✔️
Microsoft 365-Benutzer	✔️			✔️		✔️

Vorgänge

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

Vorgänge	Communication Services-Benutzer	Microsoft 365-Benutzer
Starten des Streams im Zusammen-Modus		✔️ [1]
Abrufen des Streams im Zusammen-Modus	✔️	✔️
Abrufen der Szenengröße	✔️	✔️
Abrufen der Platzierungsübersicht	✔️	✔️
Ändern der Szene
Ändern der Platzzuweisung

[1] „Starten des Zusammen-Modus“ kann nur von einem Microsoft 365-Benutzer mit der Rolle „Organisator“, „Mitorganisator“ oder „Referent“ aufgerufen werden.

SDKs

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

Plattformen	Web	Web-Benutzeroberfläche	iOS	iOS-Benutzeroberfläche	Android	Android-Benutzeroberfläche	Windows
Unterstützt	✔️

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 den Agent für die Anruferstellung (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()

Optimale Verwaltung der Konnektivität zwischen SDK und 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 Connected für Call Agent bedeutet, dass das Client-SDK verbunden ist und Benachrichtigungen von der Microsoft-Infrastruktur empfangen kann.

Disconnected (Getrennt) – Der connectionState-Wert Disconnected für Call Agent 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, wird die Call Agent-Instanz mit diesem Fehler getrennt.
connectionIssue: Wenn ein Problem mit der Verbindung zwischen dem Client und der Microsoft-Infrastruktur auftritt, gibt Call Agent nach mehreren Versuchen den connectionIssue-Fehler zurück.

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

Implementieren des Zusammen-Modus

Der Zusammen-Modus ist ein erweitertes Feature der Call-Core-API. Sie müssen zunächst aufrufende Features aus dem aufrufenden 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);

Empfangen von Ereignissen, wenn der Stream im Zusammen-Modus 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 Zusammen-Modus zugreifen.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Eigenschaften von Streams im Zusammen-Modus	Beschreibung
`id`	Eindeutige Nummer, die zum Identifizieren des Streams verwendet wird
`mediaStreamType`	Gibt den Streamtyp „Zusammen-Modus“ zurück. Der Wert von `mediaStreamType` ist immer `video`.
`isReceiving`	Gibt einen booleschen Wert zurück, der anzeigt, ob Videopakete empfangen werden.
`size`	Gibt die `StreamSize` des Zusammen-Modus mit Informationen zur Breite und Höhe des Streams in Pixeln zurück.

Starten des 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 Teilnehmer 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 Teilnehmern 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

Hinweis

Nur Microsoft 365-Benutzer mit den Rollen „Organisator“, „Mitorganisator“ oder „Referent“ können die Szene oder die Teilnehmerzuweisung im Zusammen-Modus ändern. Diese Änderungen können nur über den Teams-Client vorgenommen 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

Code	Subcode	Ergebniskategorie	Ursache	Lösung
403	46303	ExpectedError	Die Rolle „Teilnehmer“ verfügt nicht über die erforderlichen Berechtigungen, um die `togetherMode`-Start-API aufzurufen.	Nur Microsoft 365-Benutzer mit den Rollen „Organisator“, „Mitorganisator“ oder „Referent“ können den Zusammen-Modus starten. Sie können die Rolle eines Benutzers über die `role`-Eigenschaft der Instanz der `Call`-Klasse überprüfen.
403	46304	ExpectedError	Der Zusammen-Modus wurde in einem nicht unterstützten Anrufszenario gestartet.	Stellen Sie sicher, dass der Zusammen-Modus nur in Gruppenanrufs- oder Besprechungsszenarios gestartet wird.
403	46306	ExpectedError	Die `start`-API des Zusammen-Modus, die von einem Azure Communication Services-Benutzer aufgerufen wird	Nur Microsoft 365-Benutzer mit den Rollen „Organisator“, „Mitorganisator“ oder „Referent“ können den Zusammen-Modus starten.

Freigeben über