Sammansättningsläge

2025-04-21

I den här artikeln beskrivs hur du implementerar Microsoft Teams Together Mode med Azure Communication Services Calling SDK:er. Tillsammansläget förbättrar virtuella möten och samtal, vilket gör att de upplevs som mer personliga. Genom att skapa en enhetlig vy som placerar alla i en delad bakgrund kan deltagarna ansluta sömlöst och samarbeta effektivt.

Viktigt!

Den här funktionen i Azure Communication Services är för närvarande i förhandsversion. Funktioner i förhandsversionen är offentligt tillgängliga och kan användas av alla nya och befintliga Microsoft-kunder.

Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller så kan funktionerna vara begränsade.

Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Stöd

Följande tabeller definierar stöd för sammanlänkningsläge i Azure Communication Services.

Identiteter och anropstyper

I följande tabell visas stöd för samtals- och identitetstyper.

Identiteter	Teams-möte	Rum	1:1 samtal	Gruppsamtal	1:1 Teams interoperabilitetssamtal	Grupp Teams-interoperabilitetssamtal
Communication Services-användare	✔️			✔️		✔️
Microsoft 365-användare	✔️			✔️		✔️

Verksamhet

I följande tabell visas stöd för enskilda API:er i Anropa SDK till enskilda identitetstyper.

Verksamhet	Communication Services-användare	Microsoft 365-användare
Starta Together-läge-strömmen		✔️ [1]
Get Together Mode-ström	✔️	✔️
Hämta scenstorlek	✔️	✔️
Hämta sittplatskarta	✔️	✔️
Ändra scen
Ändra platstilldelning

[1] Start Together Mode kan bara anropas av en Microsoft 365-användare med rollen som organisatör, medorganisatör eller presentatör.

SDK:er

I följande tabell visas stöd för funktionen Tillsammansläge i enskilda Azure Communication Services-SDK:er.

Plattformar	Webb	Webbgränssnitt	Ios	iOS-användargränssnitt	Android	Android-användargränssnitt	Windows
Är stödd	✔️

Installera SDK:n

npm install Använd kommandot för att installera Azure Communication Services Common och Calling SDK för JavaScript:

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

Initiera nödvändiga objekt

En CallClient instans krävs för de flesta anropsåtgärder. När du skapar en ny CallClient instans kan du konfigurera den med anpassade alternativ som en Logger instans.

Med instansen CallClient kan du skapa en CallAgent instans genom att anropa createCallAgent. Den här metoden returnerar asynkront ett CallAgent instansobjekt.

Metoden createCallAgent använder CommunicationTokenCredential som argument. Den accepterar en användaråtkomsttoken.

Du kan använda getDeviceManager metoden på instansen CallClient för att få åtkomst deviceManagertill .

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

Hantera SDK-anslutning till Microsoft-infrastruktur

Instansen Call Agent hjälper dig att hantera anrop (för att ansluta eller starta samtal). För att kunna arbeta måste din anropande SDK ansluta till Microsofts infrastruktur för att få meddelanden om inkommande samtal och samordna annan samtalsinformation. Din Call Agent har två möjliga tillstånd:

Ansluten – Ett Call Agent connectionStatue-värde Connected innebär att klient-SDK:t är anslutet och kan ta emot meddelanden från Microsofts infrastruktur.

Frånkopplad – Ett Call Agent connectionsStatus-värde för Disconnected indikerar att det finns ett problem som förhindrar att SDK:n ansluter korrekt. Call Agent bör återskapas.

invalidToken: Om en token är utgången eller en ogiltig instans kopplas bort med det här felet.
connectionIssue: Om det finns ett problem med att klienten ansluter till Microsoft-infrastrukturen, efter många återförsök exponerar Call AgentconnectionIssue-felet.

Du kan kontrollera om din lokala Call Agent är ansluten till Microsofts infrastruktur genom att granska det aktuella värdet för connectionState egenskapen. Under ett aktivt anrop kan du lyssna på connectionStateChanged händelsen för att avgöra om Call Agent det ändras från Anslutet till frånkopplat tillstånd.

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

Aktivera tillsammansläge

Tillsammansläge är en utvidgad funktion i kärn-API:et Call. Först måste du importera samtalsfunktioner från Calling SDK.

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

Sedan kan du hämta API-objektet för tillsammansläge från anropsinstansen:

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

Ta emot händelser när Together Mode-strömmen startar eller uppdateras

Du kan prenumerera på händelsen togetherModeStreamsUpdated för att ta emot meddelanden när läget Tillsammans startar eller uppdateras. Händelsen innehåller information om hur du återger den tillagda videoströmmen.

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

Get Together Mode-ström

Du kan komma åt strömmar i Together-läge via egenskapen togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Together Mode-strömegenskaper	beskrivning
`id`	Unikt nummer som används för att identifiera strömmen.
`mediaStreamType`	Returnerar strömtypen för "Together Mode". Värdet `mediaStreamType` för är alltid `video`.
`isReceiving`	Returnerar ett booleskt värde som anger om videopaket tas emot.
`size`	Returnerar Together Mode `StreamSize` med information om strömmens bredd och höjd i bildpunkter.

Starta tillsammans-läge för alla deltagare

Microsoft 365-användare med rollorganisatör, medorganisatör eller presentatör kan starta tillsammansläge för alla i mötet. När läget Tillsammans startar får alla prenumeranter till togetherModeStreamsUpdated-händelsen ett meddelande som gör det möjligt för deltagarna att visa läget Tillsammans.

togetherModeFeature.start();

Avsluta tillsammans-läge

Samlingsläge avslutas automatiskt för alla deltagare om ingen videoström upptäcks från någon deltagare under en minut. Det finns inget API för att avsluta tillsammansläge.

Hämta koordinater för deltagare i tillsammansläge

Egenskapen togetherModeSeatingMap innehåller koordinater för enskilda deltagare i strömmen. Utvecklare kan använda dessa koordinater för att lägga över deltagarinformation, till exempel visningsnamn eller visuella funktioner som spotlight, upplyft hand och reaktioner på strömmen.

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

Hantera scenstorlek

Egenskapen sceneSize anger dimensionerna (bredd och höjd) för HTML-containern som rymmer togetherMode videoströmmen. Deltagarnas placeringar beräknas baserat på scenstorlekens dimensioner. Om scenstorleken inte anges är beräkningen som standard en bredd på 1 280 bildpunkter och en höjd på 720 bildpunkter.

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

Ta emot händelser vid uppdateringar av scen eller sittplatser

Kommentar

Endast Microsoft 365-användare med rollorganisatör, medorganisatör eller presentatör kan ändra scen eller tilldelning av deltagare i tillsammansläge. Dessa ändringar kan bara göras från Teams-klienten.

Om det sker en scenändring eller en platsändring utlöses togetherModeSceneUpdated eller togetherModeSeatingUpdated-händelser, vilket ger en uppdaterad beräkning av deltagarnas sittpositioner.

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

Felsökning

Kod	Underkod	Resultatkategori	Orsak	Beslut
403	46303	FörväntatFel	Deltagarens roll har inte de behörigheter som krävs för att anropa start-API:et `togetherMode` .	Endast Microsoft 365-användare med rollorganisatör, medorganisatör eller presentatör kan starta tillsammansläge. Du kan kontrollera rollen för en användare via `role` egenskapen på instansen av `Call` klassen.
403	46304	FörväntatFel	Tillsammans-läget startade i ett samtalsscenario som inte stöds.	Se till att läget Tillsammans endast startas i gruppsamtal eller mötesscenarier.
403	46306	FörväntatFel	Tillsammansläge-API `start` anropas av en användare av Azure Communication Services.	Endast Microsoft 365-användare med rollorganisatör, medorganisatör eller presentatör kan starta tillsammansläge.