Режим объединения

Статья
08/16/2024

В этой статье описывается, как реализовать microsoft Teams Together Mode с помощью Службы коммуникации Azure вызовов пакетов SDK. В режиме совместной работы вы можете улучшить виртуальные собрания и звонки, что делает их более личными. Создавая единое представление, которое помещает всех пользователей в общий фон, участники могут эффективно подключаться и работать совместно.

Внимание

Функции, описанные в этой статье, в настоящее время находятся в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания. Ее не следует использовать для производственных рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Дополнительные сведения см. в статье Дополнительные условия использования Предварительных версий Microsoft Azure.

Поддержка

В следующих таблицах определяется поддержка режима объединения в Службы коммуникации Azure.

Удостоверения и типы вызовов

В следующей таблице показана поддержка типов вызовов и удостоверений.

Удостоверения	Собрание Teams	Комната	Вызов 1:1	Групповой вызов	Вызов взаимодействия Teams 1:1	Вызов взаимодействия с Группами Teams
Пользователь служб коммуникации	✔️			✔️		✔️
Пользователь Microsoft 365	✔️			✔️		✔️

Операции

В следующей таблице показана поддержка отдельных API в пакете SDK для вызова отдельных типов удостоверений.

Операции	Пользователь служб коммуникации	Пользователь Microsoft 365
Запуск потока в режиме объединения		✔️ [1]
Объединение потока в режиме объединения	✔️	✔️
Получение размера сцены	✔️	✔️
Получение карты мест	✔️	✔️
Изменение сцены
Изменение назначения места

[1] Режим запуска вместе может вызываться только пользователем Microsoft 365 с ролью организатора, соорганизатора или докладчика.

Пакеты SDK

В следующей таблице показана поддержка функции "Режим объединения" в отдельных пакетах SDK для Службы коммуникации Azure.

Платформы	Интернет	Веб-интерфейс	iOS	Пользовательский интерфейс iOS	Android	Пользовательский интерфейс Android	Windows
Поддерживается	✔️

Установка пакета SDK

npm install Используйте команду для установки пакета SDK Службы коммуникации Azure Common and Calling SDK для JavaScript:

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

Инициализация обязательных объектов

Экземпляр CallClient требуется для большинства операций вызова. При создании нового CallClient экземпляра его можно настроить с помощью пользовательских параметров, таких как Logger экземпляр.

С помощью экземпляра CallClient можно создать CallAgent экземпляр, вызвав его createCallAgent. Этот метод асинхронно возвращает объект экземпляра CallAgent.

Метод createCallAgent использует CommunicationTokenCredential в качестве аргумента. Он принимает маркер доступа пользователя.

Можно применить метод getDeviceManager для экземпляра CallClient, чтобы получить доступ к 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 к инфраструктуре Майкрософт

Экземпляр Call Agent помогает управлять вызовами (для присоединения или запуска вызовов). Для работы пакета SDK для вызова необходимо подключиться к инфраструктуре Майкрософт для получения уведомлений о входящих звонках и координации других сведений о вызове. У вас Call Agent есть два возможных состояния:

Подключено — Call Agent значение Connected connectionStatue означает, что клиентский пакет SDK подключен и способен получать уведомления из инфраструктуры Майкрософт.

Отключено — Call Agent значение connectionStatue состояний Disconnected возникает проблема, которая препятствует правильному подключению пакета SDK. Call Agent необходимо повторно создать.

invalidToken: если срок действия маркера истек или является недопустимым Call Agent экземпляром, отключается с этой ошибкой.
connectionIssue: если возникла проблема с клиентом, подключающимся к инфраструктуре Майкрософт, после многих повторных попыток Call Agent возникает connectionIssue ошибка.

Вы можете проверить, подключен ли локальный сервер Call Agent к инфраструктуре Майкрософт, проверив текущее значение connectionState свойства. Во время активного вызова можно прослушивать connectionStateChanged событие, чтобы определить, изменяются ли Call Agent изменения из подключенного к отключенном состоянию.

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

Реализация режима объединения

Режим объединения — это расширенная функция основного Call API. Сначала необходимо импортировать функции вызова из пакета SDK для вызовов:

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

Затем можно получить объект API "Режим объединения" из экземпляра вызова:

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

Получение событий при запуске или обновлении потока в режиме объединения

Вы можете подписаться на событие togetherModeStreamsUpdated , чтобы получать уведомления при запуске или обновлении режима объединения. Событие содержит сведения о отрисовке добавленного видеопотока.

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

Объединение потока в режиме объединения

Вы можете получить доступ к потокам в режиме объединения через свойство togetherModeStream.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Свойства потока в режиме объединения	Description
`id`	Уникальный номер, используемый для идентификации потока.
`mediaStreamType`	Возвращает тип потока в режиме объединения. Значение `mediaStreamType` всегда `video`равно.
`isReceiving`	Возвращает логическое значение, указывающее, получены ли видеопакеты.
`size`	Возвращает режим `StreamSize` "Вместе" со сведениями о ширине и высоте потока в пикселях.

Запуск режима "Вместе" для всех участников

Пользователи Microsoft 365 с организатором ролей, соорганизатором или выступающим могут запускать режим "Вместе" для всех участников собрания. При запуске режима объединения все подписчики togetherModeStreamsUpdated на событие получают уведомление, которое позволяет участникам отображать режим "Вместе".

togetherModeFeature.start();

Режим завершения объединения

Режим объединения автоматически завершается для всех участников, если видеопоток не обнаруживается от любого участника в течение одной минуты. Нет API для завершения режима объединения.

Получение координат участников в режиме объединения

togetherModeSeatingMap Свойство предоставляет координаты для отдельных участников потока. Разработчики могут использовать эти координаты для наложения сведений о участниках, таких как отображаемое имя или визуальные функции, такие как внимания, поднятая рука и реакции на поток.

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

Управление размером сцены

Свойство sceneSize задает измерения (ширину и высоту) контейнера HTML, в котором размещается togetherMode видеопоток. Места сидения участников вычисляются на основе измерений размера сцены. Если размер сцены не указан, вычисление по умолчанию равно ширине 1280 пикселей и высоте 720 пикселей.

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

Получение событий при обновлении сцены или мест

Примечание.

Только пользователи Microsoft 365 с организатором ролей, соорганизатором или выступающим могут изменять сцену или назначение участников в режиме объединения. Эти изменения можно вносить только из клиента Teams.

При изменении сцены или изменении места на togetherModeSceneUpdated togetherModeSeatingUpdated месте, возникают или события соответственно, обеспечивая обновленный расчет мест места для места для участников.

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

Устранение неполадок

Код	Дополнительный код	Категория результатов	Причина	Разрешение
403	46303	ExpectedError	Роль участника не имеет необходимых разрешений для вызова начального `togetherMode` API.	Только пользователи Microsoft 365 с организатором ролей, соорганизатором или выступающим могут запускать режим "Вместе". Роль пользователя можно проверить с помощью `role` свойства в экземпляре `Call` класса.
403	46304	ExpectedError	Режим совместной работы запущен в неподдерживаемом сценарии вызова.	Убедитесь, что режим "Вместе" запущен только в сценариях группового вызова или собрания.
403	46306	ExpectedError	API режима `start` объединения, вызываемый пользователем Службы коммуникации Azure.	Только пользователи Microsoft 365 с организатором ролей, соорганизатором или выступающим могут запускать режим "Вместе".

Поделиться через