Režim společně

Článek
12/18/2024

Tento článek popisuje, jak implementovat microsoft Teams společně s voláním sad SDK služby Azure Communication Services. Režim společně vylepšuje virtuální schůzky a hovory, aby se cítily osobnější. Vytvořením sjednoceného zobrazení, které umístí všechny do sdíleného pozadí, se účastníci můžou bezproblémově spojit a efektivně spolupracovat.

Důležité

Funkce popsané v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Technická podpora

Následující tabulky definují podporu režimu Společně ve službách Azure Communication Services.

Identity a typy volání

Následující tabulka uvádí podporu pro typy volání a identit.

Identity	Schůzka v Teams	Místnost	1:1 hovor	Skupinový hovor	1:1 Zprostředkovatele spolupráce v Teams	Skupinový interopový hovor v Teams
Uživatel komunikačních služeb	✔️			✔️		✔️
Uživatel Microsoftu 365	✔️			✔️		✔️

Operace

Následující tabulka uvádí podporu jednotlivých rozhraní API při volání sady SDK k jednotlivým typům identit.

Operace	Uživatel komunikačních služeb	Uživatel Microsoftu 365
Spuštění streamu v režimu společně		✔️ [1]
Seskupit stream režimu	✔️	✔️
Získání velikosti scény	✔️	✔️
Získat mapu posezení	✔️	✔️
Změna scény
Změna přiřazení sedadla

[1] Režim Spustit společně může volat jenom uživatel Microsoftu 365 s rolí organizátora, spoluorganizátora nebo prezentujícího.

Sady SDK

Následující tabulka uvádí podporu funkce Režimu společně v jednotlivých sadách SDK služby Azure Communication Services.

Platformy	Web	Webové uživatelské rozhraní	iOS	Uživatelské rozhraní iOS	Android	Uživatelské rozhraní Androidu	Windows
Je podporováno.	✔️

Nainstalujte sadu SDK .

npm install Pomocí příkazu nainstalujte sadu AZURE Communication Services Common and Calling SDK pro JavaScript:

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

Inicializace požadovaných objektů

Pro CallClient většinu operací volání se vyžaduje instance. Když vytvoříte novou CallClient instanci, můžete ji nakonfigurovat s vlastními možnostmi, jako je Logger instance.

CallClient S instancí můžete vytvořit CallAgent instanci voláním createCallAgent. Tato metoda asynchronně vrátí CallAgent objekt instance.

Metoda createCallAgent se používá CommunicationTokenCredential jako argument. Přijímá přístupový token uživatele.

K přístupu deviceManagermůžete použít metodu getDeviceManager v CallClient instanci .

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

Jak nejlépe spravovat připojení sady SDK k infrastruktuře Microsoftu

Tato Call Agent instance vám pomůže spravovat hovory (pro připojení nebo zahájení hovorů). Aby bylo možné pracovat s vaší sadou SDK volání, musí se připojit k infrastruktuře Microsoftu, aby bylo možné dostávat oznámení o příchozích hovorech a koordinovat další podrobnosti volání. Máte Call Agent dva možné stavy:

Připojeno – Call Agent Hodnota connectionStatue znamená, Connected že klientská sada SDK je připojená a dokáže přijímat oznámení z infrastruktury Microsoftu.

Odpojeno – Call Agent Hodnota Disconnected connectionStatue stavů existuje problém, který brání sadě SDK, aby se správně připojil. Call Agent by se mělo znovu vytvořit.

invalidToken: Pokud vypršela platnost tokenu nebo je neplatná Call Agent instance, odpojí se s touto chybou.
connectionIssue: Pokud došlo k problému s klientem, který se připojuje k infrascture Microsoftu, po mnoha opakovaných pokusech Call AgentconnectionIssue se zobrazí chyba.

Zkontrolujte, jestli je vaše místní Call Agent infrastruktura připojená k infrastruktuře Microsoftu, a to kontrolou aktuální hodnoty connectionState vlastnosti. Během aktivního volání můžete naslouchat connectionStateChanged události a zjistit, jestli Call Agent se změny ze stavu Připojeno k Odpojeno .

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

Implementace režimu společně

Režim společně je rozšířená funkce základního Call rozhraní API. Nejdřív je potřeba importovat funkce volání ze sady SDK pro volání:

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

Pak můžete objekt rozhraní API režimu Společně získat z instance volání:

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

Příjem událostí při spuštění nebo aktualizaci datového proudu v režimu Společně

Můžete se přihlásit k odběru události togetherModeStreamsUpdated , abyste dostávali oznámení při spuštění nebo aktualizaci režimu společně. Událost obsahuje informace o vykreslení přidaného streamu videa.

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

Seskupit stream režimu

K datovým proudům Režimu Společně můžete přistupovat prostřednictvím vlastnosti togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Vlastnosti streamu v režimu společně	Popis
`id`	Jedinečné číslo použité k identifikaci datového proudu.
`mediaStreamType`	Vrátí typ datového proudu Režim společně. Hodnota `mediaStreamType` je vždy `video`.
`isReceiving`	Vrátí logickou hodnotu označující, jestli jsou přijímány pakety videa.
`size`	Vrátí režim `StreamSize` spolu s informacemi o šířce a výšce datového proudu v pixelech.

Spustit režim společně pro všechny účastníky

Uživatelé Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo prezentujícím můžou zahájit režim Společně pro všechny účastníky schůzky. Když se spustí režim Společně, všichni togetherModeStreamsUpdated odběratelé události obdrží oznámení, které účastníkům umožní vykreslit režim společně.

togetherModeFeature.start();

Ukončit režim společně

Režim společně se automaticky ukončí pro všechny účastníky, pokud se od žádného účastníka nezjistí žádný datový proud po dobu jedné minuty. Neexistuje žádné rozhraní API pro ukončení režimu společně.

Získání souřadnic účastníků v režimu společně

Vlastnost togetherModeSeatingMap poskytuje souřadnice pro jednotlivé účastníky v datovém proudu. Vývojáři můžou tyto souřadnice použít k překrytí informací o účastníkech, jako jsou zobrazované jméno nebo vizuální funkce, jako jsou spotlight, ruka zvednutá a reakce na streamu.

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

Spravovat velikost scény

Vlastnost sceneSize určuje rozměry (šířku a výšku) kontejneru HTML, který je součástí streamu togetherMode videa. Pozice sezení účastníků se počítají na základě rozměrů velikosti scény. Pokud není zadána velikost scény, ve výchozím nastavení se výpočet nastaví na šířku 1 280 pixelů a výšku 720 pixelů.

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

Příjem událostí při aktualizaci scény nebo sezení

Poznámka:

Scénu nebo přiřazení účastníků v režimu společně můžou změnit jenom uživatelé Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo prezentujícím. Tyto změny je možné provést pouze z klienta Teams.

Pokud dojde ke změně scény nebo změně sezení, togetherModeSceneUpdated jsou vyvolány události nebo togetherModeSeatingUpdated události, které poskytují aktualizovaný výpočet pozice účastníků sezení.

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

Řešení problému

Kód	Podkód	Kategorie výsledků	Důvod	Rozlišení
403	46303	ExpectedError	Role účastníka nemá potřebná oprávnění k volání počátečního `togetherMode` rozhraní API.	Režim Společně můžou spustit jenom uživatelé Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo prezentujícím. Roli uživatele můžete zkontrolovat prostřednictvím `role` vlastnosti instance `Call` třídy.
403	46304	ExpectedError	Režim společně byl spuštěn v nepodporovaném scénáři volání.	Zajistěte, aby se režim Společně spustil pouze ve scénářích skupinového hovoru nebo schůzky.
403	46306	ExpectedError	Rozhraní API režimu `start` společně volal uživatel služby Azure Communication Services.	Režim Společně můžou spustit jenom uživatelé Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo prezentujícím.

Sdílet prostřednictvím