Dela via

Sammanst.läge

  • Artikel

I den här artikeln beskrivs hur du implementerar Microsoft Teams Together Mode med Azure Communication Services Calling SDK:er. Läget Tillsammans förbättrar virtuella möten och samtal, vilket gör att de känns 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!

Funktioner som beskrivs i den här artikeln är för närvarande i offentlig förhandsversion. 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 kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Förutsättningar

Support

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 interop-samtal Grupp teams-interop-anrop
Communication Services-användare ✔️ ✔️ ✔️
Microsoft 365-användare ✔️ ✔️ ✔️

Operations

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

Operations Communication Services-användare Microsoft 365-användare
Starta ström i läget Starta tillsammans ✔️ [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
Stöds ✔️

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

Så här hanterar du SDK-anslutning till Microsoft-infrastruktur på bästa sätt

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. Du 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 connectionStatue-värde för Disconnected tillstånd det finns ett problem som hindrar SDK:n från att ansluta korrekt. Call Agent ska återskapas.

  • invalidToken: Om en token har upphört att gälla eller om en ogiltig Call Agent instans kopplas från med det här felet.
  • connectionIssue: Om det finns ett problem med att klienten ansluter till Microsoft-infrastrukturen, efter att många återförsök Call Agent har exponerat connectionIssue 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);

Implementera tillsammansläge

Tillsammansläge är en utökad funktion i kärn-API Call :et. Du måste först importera samtalsfunktioner från anropande 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 strömmen i samhörningsläget 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 tillsammansläge via egenskapen togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;
Egenskaper för ström i sammanläge beskrivning
id Unikt nummer som används för att identifiera strömmen.
mediaStreamType Returnerar strömtypen Tillsammansläge. Värdet mediaStreamType för är alltid video.
isReceiving Returnerar ett booleskt värde som anger om videopaket tas emot.
size Returnerar tillsammansläge 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 återge tillsammansläge.

togetherModeFeature.start();

Avsluta tillsammans-läge

Läget Tillsammans avslutas automatiskt för alla deltagare om ingen videoström identifieras 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 när scen- eller sittplatser uppdateras

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 höjs evenemangen togetherModeSceneUpdated eller togetherModeSeatingUpdated händelserna, vilket ger en uppdaterad beräkning av deltagarnas placeringspositioner.

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 Åtgärd
403 46303 ExpectedError 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 ExpectedError Läget Tillsammans startade i ett scenario med samtal som inte stöds. Se till att läget Tillsammans endast startas i gruppsamtal eller mötesscenarier.
403 46306 ExpectedError Tillsammans läge start API anropas av en Azure Communication Services-användare. Endast Microsoft 365-användare med rollorganisatör, medorganisatör eller presentatör kan starta tillsammansläge.

Nästa steg