Modus Samen

Artikel
12/18/2024

In dit artikel wordt beschreven hoe u de Microsoft Teams-modus samen kunt implementeren met Azure Communication Services-aanroepende SDK's. De modus Samen verbetert virtuele vergaderingen en gesprekken, waardoor ze zich persoonlijker voelen. Door een uniforme weergave te maken die iedereen op een gedeelde achtergrond plaatst, kunnen deelnemers naadloos verbinding maken en effectief samenwerken.

Belangrijk

De functionaliteit die in dit artikel wordt beschreven, is momenteel beschikbaar als openbare preview. Deze preview-versie wordt geleverd zonder een service level agreement en we raden deze niet aan voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

Ondersteuning

In de volgende tabellen wordt ondersteuning gedefinieerd voor de modus Together in Azure Communication Services.

Identiteiten en oproeptypen

In de volgende tabel ziet u ondersteuning voor oproep- en identiteitstypen.

Identiteiten	Teams-vergadering	Ruimte	1:1 oproep	Groepsgesprek	1:1 Teams-interopgesprek	Gesprek tussen Teams groeperen
Communication Services-gebruiker	✔️			✔️		✔️
Microsoft 365-gebruiker	✔️			✔️		✔️

Operations

In de volgende tabel ziet u ondersteuning voor afzonderlijke API's in het aanroepen van SDK voor afzonderlijke identiteitstypen.

Operations	Communication Services-gebruiker	Microsoft 365-gebruiker
Stroom voor de modus Samen starten		✔️ [1]
Stroom voor de modus Samenbrengen	✔️	✔️
Grootte van scène ophalen	✔️	✔️
Zitkaart ophalen	✔️	✔️
Scène wijzigen
Stoeltoewijzing wijzigen

[1] Start Together Mode kan alleen worden aangeroepen door een Microsoft 365-gebruiker met de rol van organisator, mede-organisator of presentator.

SDK's

In de volgende tabel ziet u ondersteuning voor de functie Together Mode in afzonderlijke Azure Communication Services SDK's.

Platformen	Web	Webgebruikersinterface	iOS	iOS-gebruikersinterface	Android	Android-gebruikersinterface	Windows
Wordt ondersteund	✔️

Installeer de SDK

Gebruik de npm install opdracht om de Common and Calling SDK voor Azure Communication Services voor JavaScript te installeren:

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

Vereiste objecten initialiseren

Een CallClient exemplaar is vereist voor de meeste aanroepbewerkingen. Wanneer u een nieuw CallClient exemplaar maakt, kunt u deze configureren met aangepaste opties, zoals een Logger exemplaar.

Met het CallClient exemplaar kunt u een CallAgent exemplaar maken door het createCallAgentaan te roepen. Deze methode retourneert asynchroon een CallAgent exemplaarobject.

De createCallAgent methode gebruikt CommunicationTokenCredential als argument. Het accepteert een toegangstoken van een gebruiker.

U kunt de getDeviceManager methode op het CallClient exemplaar gebruiken om toegang te krijgen tot 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()

Sdk-connectiviteit met Microsoft-infrastructuur het beste beheren

Het Call Agent exemplaar helpt u bij het beheren van gesprekken (om aanroepen deel te nemen of te starten). Als u wilt werken met uw aanroepende SDK, moet u verbinding maken met de Microsoft-infrastructuur om meldingen van binnenkomende oproepen te ontvangen en andere gespreksgegevens te coördineren. Uw Call Agent heeft twee mogelijke statussen:

Verbonden : een Call Agent connectionStatue-waarde van Connected het middel dat de client-SDK is verbonden en meldingen van de Microsoft-infrastructuur kan ontvangen.

Verbinding verbroken - Een Call Agent connectionStatue-waarde van Disconnected statussen is er een probleem dat verhindert dat de SDK verbinding maakt. Call Agent moet opnieuw worden gemaakt.

invalidToken: Als een token is verlopen of een ongeldig exemplaar Call Agent wordt verbroken met deze fout.
connectionIssue: Als er een probleem is met de client die verbinding maakt met Microsoft infrascture, wordt de connectionIssue fout na veel nieuwe pogingen Call Agent weergegeven.

U kunt controleren of uw lokale Call Agent verbinding heeft met de Microsoft-infrastructuur door de huidige waarde van connectionState de eigenschap te controleren. Tijdens een actieve oproep kunt u naar de connectionStateChanged gebeurtenis luisteren om te bepalen of Call Agent de status Verbonden naar Verbroken is gewijzigd.

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

Samen implementeren-modus

De modus Together is een uitgebreide functie van de kern-API Call . U moet eerst aanroepende functies importeren uit de Calling SDK:

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

Vervolgens kunt u het API-object Together Mode ophalen uit het aanroepexemplaren:

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

Gebeurtenissen ontvangen wanneer de stream Samen modus wordt gestart of bijgewerkt

U kunt zich abonneren op de gebeurtenis togetherModeStreamsUpdated om meldingen te ontvangen wanneer de modus Samen wordt gestart of bijgewerkt. De gebeurtenis bevat informatie over het weergeven van de toegevoegde videostream.

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

Stroom voor de modus Samenbrengen

U hebt toegang tot samenmodusstreams via de eigenschap togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Eigenschappen van stream samen in modus	Beschrijving
`id`	Uniek nummer dat wordt gebruikt om de stream te identificeren.
`mediaStreamType`	Retourneert het stroomtype Samenmodus. De waarde van `mediaStreamType` is altijd `video`.
`isReceiving`	Retourneert een Booleaanse waarde die aangeeft of videopakketten worden ontvangen.
`size`	Retourneert de modus `StreamSize` Samen met informatie over de breedte en hoogte van de stroom in pixels.

De modus Samen starten voor alle deelnemers

Microsoft 365-gebruikers met rolorganisator, medeorganisator of presentator kunnen de modus Samen starten voor iedereen in de vergadering. Wanneer de modus Samen starten, ontvangen alle abonnees van de togetherModeStreamsUpdated gebeurtenis een melding waarmee deelnemers de modus Samen kunnen weergeven.

togetherModeFeature.start();

Modus Samen beëindigen

De modus Samen wordt automatisch beëindigd voor alle deelnemers als er gedurende één minuut geen videostream van een deelnemer wordt gedetecteerd. Er is geen API om de modus Samen te beëindigen.

Coördinaten van deelnemers ophalen in de modus Samen

De eigenschap togetherModeSeatingMap biedt coördinaten voor afzonderlijke deelnemers in de stream. Ontwikkelaars kunnen deze coördinaten gebruiken om informatie van deelnemers over te leggen, zoals weergavenaam of visuele functies zoals spotlight, hand opgevoed en reacties op de stream.

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

Grootte van scène beheren

De sceneSize eigenschap specificeert de afmetingen (breedte en hoogte) van de HTML-container die de togetherMode videostream bevat. De zitplaatsen van deelnemers worden berekend op basis van de afmetingen van de scènegrootte. Als er geen scènegrootte is opgegeven, wordt de berekening standaard ingesteld op een breedte van 1.280 pixels en een hoogte van 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 )}`)

Gebeurtenissen ontvangen wanneer scène- of zitplaatsenupdates worden bijgewerkt

Notitie

Alleen Microsoft 365-gebruikers met rolorganisator, medeorganisator of presentator kunnen scènes of toewijzingen van deelnemers wijzigen in de modus Samen. Deze wijzigingen kunnen alleen worden aangebracht vanuit de Teams-client.

Als er sprake is van een wijziging in de scène of het wijzigen van de zitplaatsen, worden de togetherModeSceneUpdated of togetherModeSeatingUpdated gebeurtenissen respectievelijk gegenereerd, waardoor een bijgewerkte berekening van de positie van de deelnemers wordt geboden.

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

Probleemoplossing

Code	Subcode	Resultaatcategorie	Reden	Oplossing
403	46303	ExpectedError	De rol van de deelnemer heeft niet de benodigde machtigingen om de `togetherMode` start-API aan te roepen.	Alleen Microsoft 365-gebruikers met rolorganisator, mede-organisator of presentator kunnen de modus Samen starten. U kunt de rol van een gebruiker controleren via `role` de eigenschap voor het exemplaar van `Call` de klasse.
403	46304	ExpectedError	De modus Samen is gestart in een niet-ondersteund belscenario.	Zorg ervoor dat de modus Samen alleen wordt gestart in groepsgesprekken of vergaderscenario's.
403	46306	ExpectedError	Modus-API `start` die wordt aangeroepen door een Azure Communication Services-gebruiker.	Alleen Microsoft 365-gebruikers met rolorganisator, mede-organisator of presentator kunnen de modus Samen starten.

Delen via