Delen via

Samenmodus

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

Deze functie van Azure Communication Services is momenteel beschikbaar als preview-versie. Functies in preview zijn openbaar beschikbaar en kunnen worden gebruikt door alle nieuwe en bestaande Microsoft-klanten.

Deze preview-versie wordt geleverd zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of mogelijkheden zijn mogelijk 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 Kamer 1:1 oproep Groepsgesprek één-op-één Teams-interoperabiliteitsgesprek Interop-oproep voor groepsteams
Communication Services-gebruiker ✔️ ✔️ ✔️
Microsoft 365-gebruiker ✔️ ✔️ ✔️

Bedrijfsactiviteiten

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

Bedrijfsactiviteiten Communication Services-gebruiker Microsoft 365-gebruiker
Samen-modusstream starten ✔️ [1]
Streaming voor de samenwerkingsmodus ✔️ ✔️
Scènegrootte 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 Het web Web-UI Ios iOS-gebruikersinterface Androïde Android-gebruikersinterface Ramen
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 beheren

Het Call Agent exemplaar helpt u bij het beheren van gesprekken (om oproepen aan 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 connectionStatus-waarde van Connected betekent dat de client-SDK is verbonden en meldingen van de Microsoft-infrastructuur kan ontvangen.

Verbinding verbroken - Een connectionStatus-waarde van Call Agent geeft aan dat er een probleem is dat voorkomt dat de SDK correct verbinding maakt. Call Agent moet opnieuw worden gemaakt.

  • invalidToken: Als een token is verlopen of ongeldig is Call Agent verbreekt de verbinding met deze fout.
  • connectionIssue: als er een probleem is met de client die verbinding maakt met de Microsoft-infrastructuur, wordt na veel nieuwe pogingen Call Agent de fout connectionIssue 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 verandert van de status Verbonden naar Verbroken.

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 Together Mode API-object ophalen uit de belinstantie.

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

Gebeurtenissen ontvangen wanneer de Samen-modus stream 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
    });
});

Streaming voor de samenwerkingsmodus

U hebt toegang tot Samenwerkingsmodus-streams via de eigenschap togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;
Eigenschappen van Together-modusstream Beschrijving
id Uniek nummer dat wordt gebruikt om de stream te identificeren.
mediaStreamType Retourneert het Together Mode streamtype. De waarde van mediaStreamType is altijd video.
isReceiving Retourneert een Booleaanse waarde die aangeeft of videopakketten worden ontvangen.
size Retourneert de modus SamenStreamSize 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 start, ontvangen alle abonnees van de togetherModeStreamsUpdated gebeurtenis een melding die deelnemers in staat stelt de modus Samen weer te geven.

togetherModeFeature.start();

Samenmodus 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, zoals weergavenaam, of visuele functies zoals spotlight, hand opsteken en reacties op de stream te plaatsen.

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

Meldingen ontvangen wanneer scène- of zitplaatswijzigingen plaatsvinden

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 VerwachteFout 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 bekijken via de role eigenschap op een instantie van de Call klasse.
403 46304 VerwachteFout De Samen-modus is gestart in een niet-ondersteund belscenario. Zorg ervoor dat de modus Samen alleen wordt gestart in groepsgesprekken of vergaderscenario's.
403 46306 VerwachteFout Together Mode API start die wordt aangeroepen door een gebruiker van Azure Communication Services. Alleen Microsoft 365-gebruikers met rolorganisator, mede-organisator of presentator kunnen de modus Samen starten.

Volgende stappen