Наблюдение за возможностями пользователя

Статья
09/27/2024

Есть ли у меня разрешение на включение видео, у меня есть разрешение на включение микрофона, у меня есть разрешение на общий доступ к экрану? Эти разрешения являются примерами возможностей участников, которые можно узнать из API возможностей. Изучение возможностей может помочь создать пользовательский интерфейс, который отображает только кнопки, связанные с действиями локального пользователя, имеют разрешения.

Необходимые компоненты

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Развернутый ресурс Служб коммуникации. Создайте ресурс Служб коммуникации.
Маркер доступа пользователя для включения клиента для вызовов. Дополнительные сведения см. в статье о создании маркеров доступа и управлении ими.
Необязательно. Выполните краткое руководство по добавлению голосовых звонков в приложение

Установка пакета 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, которая позволяет получить возможности локального участника в текущем вызове.

Эта функция позволяет зарегистрировать прослушиватель событий, прослушивать изменения возможностей.

Зарегистрируйтесь в функции возможностей:

const capabilitiesFeature = this.call.feature(Features.Capabilities);

Получение возможностей локального участника: объект capabilities имеет возможности локальных участников и имеет тип ParticipantCapabilities. Ниже перечислены свойства возможностей:

isPresent указывает, присутствует ли возможность.
причина указывает причину разрешения возможностей.

const capabilities =  capabilitiesFeature.capabilities;

Подписка на capabilitiesChanged событие:

capabilitiesFeature.on('capabilitiesChanged', (capabilitiesChangeInfo) => {
    for (const [key, value] of Object.entries(capabilitiesChangeInfo.newValue)) {
        if(key === 'turnVideoOn' && value.reason != 'FeatureNotSupported') {
             (value.isPresent) ? this.setState({ canOnVideo: true }) : this.setState({ canOnVideo: false });
             continue;
        }
        if(key === 'unmuteMic' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canUnMuteMic: true }) : this.setState({ canUnMuteMic: false });
            continue;
        }
        if(key === 'shareScreen' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canShareScreen: true }) : this.setState({ canShareScreen: false });
            continue;
        }
        if(key === 'spotlightParticipant' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canSpotlight: true }) : this.setState({ canSpotlight: false });
            continue;
        }
        if(key === 'raiseHand' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canRaiseHands: true }) : this.setState({ canRaiseHands: false });
            continue;
        }
        if(key === 'muteOthers' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canMuteOthers: true }) : this.setState({ canMuteOthers: false });
            continue;
        }
        if(key === 'reaction' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canReact: true }) : this.setState({ canReact: false });
            continue;
        }
    }
});

Доступные возможности

turnVideoOn: возможность включения видео
unmuteMic: возможность включения микрофона
shareScreen: возможность совместного использования экрана
removeParticipant: возможность удаления участника
hangUpForEveryOne: возможность повесить для всех
addCommunicationUser: возможность добавления пользователя связи
addTeamsUser: возможность добавления пользователя Teams
addPhoneNumber: возможность добавления номера телефона
manageLobby: возможность управления лобби (только бета-версия)
spotlightParticipant: возможность внимания участника (только бета-версия)
removeParticipantsSpotlight: возможность удаления внимания участника (только бета-версия)
startLiveCaptions: возможность запуска субтитров в реальном времени (только бета-версия)
stopLiveCaptions: возможность остановить динамические субтитры (только бета-версия)
raiseHand: возможность поднять руку (только бета-версия)
muteOthers: возможность обратимого отключения удаленных участников в собрании
реакция: способность реагировать на собрание (только бета-версия)
viewAttendeeNames: возможность просматривать имена участников в собрании

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

Найдите файл уровня build.gradle проекта и добавьте mavenCentral() в список репозиториев в buildscript разделе и allprojects:

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

Затем в файле уровня build.gradle модуля добавьте в раздел следующие строки dependencies :

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-calling:1.0.0'
    ...
}

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

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

Метод createCallAgent принимает CommunicationUserCredential в качестве аргумента, который инкапсулирует маркер доступа.

Чтобы получить доступ DeviceManager, сначала необходимо создать callAgent экземпляр. Затем можно использовать CallClient.getDeviceManager метод для получения DeviceManager.

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

Чтобы задать отображаемое имя для вызывающей стороны, используйте следующий альтернативный метод:

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

Эта функция позволяет зарегистрировать прослушиватель событий, прослушивать изменения возможностей.

Чтобы использовать функцию вызова возможностей для Windows, первым шагом является получение объекта API функций возможностей:

Функция получения возможностей

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.feature(Features.CAPABILITIES);

Получение возможностей локального участника

Объект capabilities имеет возможности локальных участников и имеет тип ParticipantCapability. Ниже перечислены свойства возможностей:

IsAllowed указывает, можно ли использовать возможность.
причина указывает причину разрешения возможностей.

List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();

Подписка на `capabilitiesChanged` событие


capabilitiesCallFeature.addOnCapabilitiesChangedListener(this::OnCapabilitiesChanged);

private void OnCapabilitiesChanged(CapabilitiesChangedEvent args)
{
    String event = String.format("Capabilities Event: %s", args.getReason().toString());
    Log.i("CapabilitiesInfo", event);
    for (ParticipantCapability capability : args.getChangedCapabilities())
    {
        Log.i("CapabilitiesInfo", capability.getType().toString() + " is " capability.getReason().toString());
    }
}

Доступные возможности

TurnVideoOn: возможность включения видео
UnmuteMicrophone: возможность отменить микрофон
ShareScreen: возможность совместного использования экрана
RemoveParticipant: возможность удаления участника
HangUpForEveryone: возможность повесить для всех
AddCommunicationUser: возможность добавления пользователя связи
AddTeamsUser: возможность добавления пользователя Teams
AddPhoneNumber: возможность добавления номера телефона
ManageLobby: возможность управления лоббировать
SpotlightParticipant: возможность внимания участника
RemoveParticipantSpotlight: возможность удаления внимания участника
BlurBackground: возможность размытия фона
CustomBackground: возможность применения пользовательского фона
StartLiveCaptions: возможность запуска динамических подписей
RaiseHand: способность поднять руку
Функция muteOthers: возможность обратимого отключения удаленных участников в собрании

Настройка системы

Выполните следующие действия, чтобы настроить систему.

Создание проекта Visual Studio

Для приложения универсальная платформа Windows в Visual Studio 2022 создайте проект пустого приложения (универсального приложения Windows). После ввода имени проекта вы можете выбрать любой пакет SDK для Windows позже 10.0.17763.0.

Для приложения WinUI 3 создайте проект с шаблоном "Пустое приложение" (WinUI 3 в классическом приложении) для настройки одностраничного приложения WinUI 3. Требуется пакет SDK для приложений Windows версии 1.3 или более поздней.

Установка пакета и зависимостей с помощью NuGet диспетчер пакетов

Api и библиотеки пакета SDK для вызовов общедоступны через пакет NuGet.

Чтобы найти, скачать и установить пакет NuGet пакета Sdk для вызовов:

Откройте nuGet диспетчер пакетов, выбрав инструменты>NuGet диспетчер пакетов> Manage NuGet Packages for Solution.
Выберите "Обзор" и введите Azure.Communication.Calling.WindowsClient в поле поиска.
Убедитесь, что установлен флажок "Включить предварительную версию ".
Выберите пакет Azure.Communication.Calling.WindowsClient, а затем выберите Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 или более позднюю версию.
Установите флажок, соответствующий проекту Службы коммуникации Azure на правой панели.
Выберите Установить.

Эта функция позволяет зарегистрировать прослушиватель событий, прослушивать изменения возможностей.

Функция получения возможностей

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.Features.Capabilities;

Получение возможностей локального участника

IsAllowed указывает, можно ли использовать возможность.
причина указывает причину разрешения возможностей.

var capabilities = capabilitiesCallFeature.Capabilities;

Подписка на `capabilitiesChanged` событие

capabilitiesCallFeature.CapabilitiesChanged += Call__OnCapabilitiesChangedAsync;

private async void Call__OnCapabilitiesChangedAsync(object sender, CapabilitiesChangedEventArgs args)
{
    Trace.WriteLine(args.Reason.ToString());
    foreach (var capability in args.ChangedCapabilities)
    {
        //Prints out capability kind and resolution reason in console
        Trace.WriteLine(capability.Kind.ToString() + " is " + capability.Reason.ToString());
    }
}

Доступные возможности

TurnVideoOn: возможность включения видео
UnmuteMicrophone: возможность отменить микрофон
ShareScreen: возможность совместного использования экрана
RemoveParticipant: возможность удаления участника
HangUpForEveryone: возможность повесить для всех
AddCommunicationUser: возможность добавления пользователя связи
AddTeamsUser: возможность добавления пользователя Teams
AddPhoneNumber: возможность добавления номера телефона
ManageLobby: возможность управления лоббировать
SpotlightParticipant: возможность внимания участника
RemoveParticipantSpotlight: возможность удаления внимания участника
BlurBackground: возможность размытия фона
CustomBackground: возможность применения пользовательского фона
StartLiveCaptions: возможность запуска динамических подписей
RaiseHand: способность поднять руку
Функция muteOthers: возможность обратимого отключения удаленных участников в собрании

Настройка системы

Выполните следующие действия, чтобы настроить систему.

Создайте проект Xcode

В Xcode создайте новый проект iOS и выберите шаблон Single View App (Приложение с одним представлением). В этой статье используется платформа SwiftUI, поэтому необходимо задать для языка значение Swift и задать для интерфейса значение SwiftUI.

Вы не собираетесь создавать тесты в этой статье. Снимите флажок "Включить тесты ".

Снимок экрана, на котором показано окно для создания проекта в Xcode.

Установка пакета и зависимостей с помощью CocoaPods

Создайте Podfile для приложения, как показано в следующем примере:

platform :ios, '13.0'
use_frameworks!
target 'AzureCommunicationCallingSample' do
    pod 'AzureCommunicationCalling', '~> 1.0.0'
end

Запустите pod install.
Откройте .xcworkspace с помощью Xcode.

Запрос доступа к микрофону

Чтобы получить доступ к микрофону устройства, необходимо обновить список свойств приложения с помощью NSMicrophoneUsageDescription. Задайте связанное значение строке, включенной в диалоговое окно, которое система использует для запроса доступа от пользователя.

Щелкните правой кнопкой мыши запись Info.plist дерева проекта и выберите "Открыть как>исходный код". Добавьте в раздел верхнего уровня <dict> следующие строки, а затем сохраните файл.

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

Настройка платформы приложения

Откройте файл проекта ContentView.swift . import Добавьте объявление в начало файла для импорта библиотекиAzureCommunicationCalling. Кроме того, импортируйте AVFoundation. Он необходим для запросов на разрешение звука в коде.

import AzureCommunicationCalling
import AVFoundation

Инициализация CallAgent

Чтобы создать экземпляр CallAgent из CallClient, необходимо использовать метод callClient.createCallAgent, который асинхронно возвращает объект CallAgent после его инициализации.

Чтобы создать клиент вызова, передайте CommunicationTokenCredential объект:

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

CommunicationTokenCredential Передайте созданный CallClientобъект и задайте отображаемое имя:

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

Эта функция позволяет зарегистрировать прослушиватель событий, прослушивать изменения возможностей.

Функция получения возможностей

let capabilitiesCallFeature =call.feature(Features.capabilities)

Получение возможностей локального участника

IsAllowed указывает, можно ли использовать возможность.
причина указывает причину разрешения возможностей.

var capabilities = capabilitiesCallFeature.capabilities

Подписка на `capabilitiesChanged` событие


capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()

public class CapabilitiesCallDelegate : CapabilitiesCallFeatureDelegate
{
    public func capabilitiesCallFeature(_ capabilitiesCallFeature: CapabilitiesCallFeature, didChangeCapabilities args: CapabilitiesChangedEventArgs) {
        let changedReason = args.reason
        let changedCapabilities = args.changedCapabilities
    }
}

Доступные возможности

TurnVideoOn: возможность включения видео
UnmuteMicrophone: возможность отменить микрофон
ShareScreen: возможность совместного использования экрана
RemoveParticipant: возможность удаления участника
HangUpForEveryone: возможность повесить для всех
AddCommunicationUser: возможность добавления пользователя связи
AddTeamsUser: возможность добавления пользователя Teams
AddPhoneNumber: возможность добавления номера телефона
ManageLobby: возможность управления лоббировать
SpotlightParticipant: возможность внимания участника
RemoveParticipantSpotlight: возможность удаления внимания участника
BlurBackground: возможность размытия фона
CustomBackground: возможность применения пользовательского фона
StartLiveCaptions: возможность запуска динамических подписей
RaiseHand: способность поднять руку
Функция muteOthers: возможность обратимого отключения удаленных участников в собрании

Поддерживаемые типы вызовов

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

Причины

В следующей таблице приведены дополнительные сведения о том, почему действие недоступно и содержит советы по созданию действия.

Причина	Описание	Решение
Способный	Действие разрешено.
CapabilityNotApplicableForTheCallType	Тип вызова блокирует действие.	Рассмотрите другой тип вызова, если вам потребуется это действие. Типы вызовов: 1:1, групповой звонок, вызов взаимодействия 1:1 Teams, вызов группы взаимодействия 1:1 Teams, комната и собрание.
ClientRestricted	Среда выполнения блокирует это действие.	Разблокируйте действие на устройстве, изменив операционную систему, браузеры, платформу или оборудование. В нашей документации можно найти поддерживаемую среду.
UserPolicyRestricted	Политика пользователя Microsoft 365 блокирует действие.	Включите это действие, изменив политику, назначенную организатору собрания, инициатору вызова или пользователя Microsoft 365 с помощью пакета SDK ACS. Целевой пользователь зависит от типа действия. Дополнительные сведения о политике Teams в Teams. Администратор Teams может изменять политики.
RoleRestricted	Назначенная роль блокирует действие.	Продвигайте пользователей на другую роль, чтобы сделать действие доступным.
FeatureNotSupported	Функция возможностей не поддерживается в этом типе вызова.	Сообщите нам в канале отзывов Azure, который вы хотите предоставить этой функции для этого типа вызова.
MeetingRestricted	Параметр собрания Teams блокирует действие.	Организатор собрания Teams или соорганизатор должны изменить параметр собрания, чтобы включить это действие.
Неинициализировано	Функция возможностей еще не инициализирована.	Подпишитесь на событие `capabilitiesChanged` `this.call.feature(Features.Capabilities)` , чтобы узнать, когда инициализирована возможность.
NotCapable	Тип пользователя блокирует действие.	Действие допускается только для определенного типа удостоверения. Включите это действие с помощью удостоверения Microsoft 365.
TeamsPremiumLicenseRestricted	Пользователю Microsoft 365 необходимо назначить Teams премиум лицензию.	Включите это действие, назначив Teams премиум лицензию организатору собраний Teams или пользователю Microsoft 365 с помощью пакета SDK. Целевой пользователь зависит от типа действия. Администратор Microsoft 365 может назначить необходимую лицензию.
ExplicitConsentRequired	Для разрешения действия требуется согласие.	Предоставьте согласие на запись или транскрибирование путем вызова метода `grantTeamsConsent()` в `this.call.feature(Features.Recording)` или `this.call.feature(Features.Transcription)` .

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

Наблюдение за возможностями пользователя

Необходимые компоненты

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

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

Управление подключением пакета SDK к инфраструктуре Майкрософт

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

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

Функция получения возможностей

Получение возможностей локального участника

Доступные возможности

Настройка системы

Создание проекта Visual Studio

Установка пакета и зависимостей с помощью NuGet диспетчер пакетов

Функция получения возможностей

Получение возможностей локального участника

Доступные возможности

Настройка системы

Создайте проект Xcode

Установка пакета и зависимостей с помощью CocoaPods

Запрос доступа к микрофону

Настройка платформы приложения

Инициализация CallAgent

Функция получения возможностей

Получение возможностей локального участника

Доступные возможности

Поддерживаемые типы вызовов

Причины

Следующие шаги

Обратная связь

Дополнительные ресурсы

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

Наблюдение за возможностями пользователя

Необходимые компоненты

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

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

Управление подключением пакета SDK к инфраструктуре Майкрософт

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

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

Функция получения возможностей

Получение возможностей локального участника

Подписка на capabilitiesChanged событие

Доступные возможности

Настройка системы

Создание проекта Visual Studio

Установка пакета и зависимостей с помощью NuGet диспетчер пакетов

Функция получения возможностей

Получение возможностей локального участника

Подписка на capabilitiesChanged событие

Доступные возможности

Настройка системы

Создайте проект Xcode

Установка пакета и зависимостей с помощью CocoaPods

Запрос доступа к микрофону

Настройка платформы приложения

Инициализация CallAgent

Функция получения возможностей

Получение возможностей локального участника

Подписка на capabilitiesChanged событие

Доступные возможности

Поддерживаемые типы вызовов

Причины

Следующие шаги

Обратная связь

Дополнительные ресурсы

Подписка на `capabilitiesChanged` событие

Подписка на `capabilitiesChanged` событие

Подписка на `capabilitiesChanged` событие