Observar las funcionalidades del usuario
¿Tengo permiso para activar el vídeo, tengo permiso para activar el micrófono, ¿tengo permiso para compartir la pantalla? Estos permisos son ejemplos de funcionalidades de participantes que puede aprender de la API de funcionalidades. Conocer las funcionalidades puede ayudar a crear una interfaz de usuario que solo muestre los botones relacionados con las acciones para las que el usuario local tiene permisos.
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Un recurso de Communication Services implementado. Cree un recurso de Communication Services.
- Un token de acceso de usuario para habilitar el cliente de llamada. Para más información, consulte Inicio rápido: Creación y administración de tokens de acceso.
- Opcional: realice el inicio rápido para agregar llamadas de voz a la aplicación.
Instalación del SDK
Use el comando npm install
para instalar los SDK comunes y de llamada de Azure Communication Services para JavaScript:
npm install @azure/communication-common --save
npm install @azure/communication-calling --save
Inicialización de los objetos necesarios
Se requiere una instancia de CallClient
para la mayoría de las operaciones de llamada. Al crear una nueva instancia de CallClient
, puede configurarla con opciones personalizadas, como una instancia de Logger
.
Con la instancia de CallClient
, puede crear una instancia de CallAgent
llamando al createCallAgent
. Este método devuelve un objeto de instancia CallAgent
de manera asincrónica.
El método createCallAgent
utiliza CommunicationTokenCredential
como argumento. Acepta un token de acceso de usuario.
Puede usar el método getDeviceManager
en la instancia de CallClient
para acceder a 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()
Cuál es la mejor forma de administrar la conectividad del SDK en la infraestructura de Microsoft
La instancia de Call Agent
le ayuda a administrar llamadas (para unirse o iniciar llamadas). Para trabajar con el SDK de llamadas, debe conectarse a la infraestructura de Microsoft para obtener notificaciones de llamadas entrantes y coordinar otros detalles de la llamada. Call Agent
tiene dos posibles estados:
Conectado: un valor connectionStatue Call Agent
con estado Connected
significa que el SDK de cliente está conectado y es capaz de recibir notificaciones de la infraestructura de Microsoft.
Desconectado: un valor connectionStatue Call Agent
con estado Disconnected
indica que hay un problema que impide que el SDK se conecte correctamente. Call Agent
se debe volver a crear.
invalidToken
: si un token ha expirado o no es válido, la instancia deCall Agent
se desconecta con este error.connectionIssue
: si hay un problema cuando el cliente se conecta a la infraestructura de Microsoft, después de muchos reintentos,Call Agent
expone el errorconnectionIssue
.
Para comprobar si el Call Agent
local está conectado a la infraestructura de Microsoft, inspeccione el valor actual de la propiedad connectionState
. Durante una llamada activa, puede escuchar el evento connectionStateChanged
para determinar si Call Agent
cambia de Conectado a estado Desconectado.
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);
La característica de funcionalidades es una característica extendida de la API Call
principal y le permite obtener las funcionalidades del participante local en la llamada actual.
La característica permite registrarse para un agente de escucha de eventos con el fin de escuchar los cambios en funcionalidades.
Registrarse en la característica de funcionalidades:
const capabilitiesFeature = this.call.feature(Features.Capabilities);
Obtener las funcionalidades del participante local: el objeto de funcionalidades tiene las funcionalidades de los participantes locales y es de tipo ParticipantCapabilities
. Entre las propiedades de las funcionalidades se incluyen las siguientes:
- isPresent indica si una funcionalidad está presente.
- reason indica el motivo de resolución de la funcionalidad.
const capabilities = capabilitiesFeature.capabilities;
Suscripción al evento 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;
}
}
});
Funcionalidades expuestas
- turnVideoOn: capacidad de activar el vídeo
- unmuteMic: capacidad de activar el micrófono
- shareScreen: capacidad de compartir pantalla
- removeParticipant: capacidad de quitar un participante
- hangUpForEveryOne: capacidad de colgar para todos los usuarios
- addCommunicationUser: capacidad de agregar un usuario de comunicación
- addTeamsUser: capacidad de agregar usuarios de Teams
- addPhoneNumber: capacidad de agregar un número de teléfono
- manageLobby: capacidad de administrar la sala de espera (solo beta)
- spotlightParticipant: capacidad de destacar a un participante (solo beta)
- removeParticipantsSpotlight: capacidad de dejar de destacar a un participante (solo beta)
- startLiveCaptions: capacidad de iniciar subtítulos en directo (solo beta)
- stopLiveCaptions: capacidad de detener subtítulos en directo (solo beta)
- raiseHand: capacidad de levantar la mano (solo beta)
- muteOthers: Capacidad de silenciar a participantes remotos suaves en la reunión
- reaction: capacidad de reaccionar en la reunión (solo beta)
- viewAttendeeNames: capacidad de ver los nombres de los asistentes en la reunión
Instalación del SDK
Busque el archivo build.gradle
de nivel de proyecto y agregue mavenCentral()
a la lista de repositorios en buildscript
y allprojects
:
buildscript {
repositories {
...
mavenCentral()
...
}
}
allprojects {
repositories {
...
mavenCentral()
...
}
}
Luego, en el archivo build.gradle
de nivel de módulo, agregue las siguientes líneas a la sección dependencies
:
dependencies {
...
implementation 'com.azure.android:azure-communication-calling:1.0.0'
...
}
Inicialización de los objetos necesarios
Para crear una instancia de CallAgent
, debe llamar al método createCallAgent
en una instancia de CallClient
. Esta llamada devuelve un objeto de instancia de CallAgent
de manera asincrónica.
El método createCallAgent
toma CommunicationUserCredential
como argumento, que encapsula un token de acceso.
Para acceder a DeviceManager
, primero debe crear una instancia de callAgent
. A continuación, puede usar el método CallClient.getDeviceManager
para obtener 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();
Para establecer un nombre para mostrar para el autor de la llamada, use este método alternativo:
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();
La característica de funcionalidades es una característica extendida de la API Call
principal y le permite obtener las funcionalidades del participante local en la llamada actual.
La característica permite registrarse para un agente de escucha de eventos con el fin de escuchar los cambios en funcionalidades.
Para usar la característica de llamada Capabilities para Windows, el primer paso es obtener el objeto de API de características Capabilities:
Obtención de la característica de funcionalidades
private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.feature(Features.CAPABILITIES);
Obtención de las funcionalidades del participante local
El objeto Capabilities tiene las funcionalidades de los participantes locales y es de tipo ParticipantCapability
. Entre las propiedades de las funcionalidades se incluyen las siguientes:
- isAllowed indica si se puede usar una funcionalidad.
- reason indica el motivo de resolución de la funcionalidad.
List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();
Suscribirse al evento 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());
}
}
Funcionalidades expuestas
- TurnVideoOn: capacidad de activar el vídeo
- UnmuteMicrophone: capacidad para desactivar el micrófono
- ShareScreen: capacidad de compartir pantalla
- RemoveParticipant: capacidad de quitar un participante
- HangUpForEveryOne: capacidad de colgar para todos los usuarios
- AddCommunicationUser: capacidad de agregar un usuario de comunicación
- AddTeamsUser: capacidad de agregar usuarios de Teams
- AddPhoneNumber: capacidad de agregar un número de teléfono
- ManageLobby: capacidad de administrar la sala de espera
- SpotlightParticipant: capacidad para destacar al participante
- RemoveParticipantSpotlight: capacidad de quitar contenido destacado del participante
- BlurBackground: capacidad para desenfocar el fondo
- CustomBackground: capacidad de aplicar un fondo personalizado
- StartLiveCaptions: capacidad de iniciar subtítulos en directo
- RaiseHand: capacidad de levantar la mano
- MuteOthers: capacidad de silenciar temporalmente a participantes remotos en la reunión
Configuración del sistema
Siga estos pasos para configurar el sistema.
Creación del proyecto de Visual Studio
En el caso de una aplicación para la Plataforma universal de Windows, en Visual Studio 2022, cree un proyecto de Aplicación vacía (Universal Windows). Después de escribir el nombre del proyecto, puede elegir cualquier Windows SDK posterior a 10.0.17763.0.
En el caso de una aplicación WinUI 3, cree un nuevo proyecto con la plantilla Aplicación vacía, empaquetada (WinUI 3 en escritorio) para configurar una aplicación WinUI 3 de una sola página. Se requiere la versión 1.3 o posterior del SDK de aplicaciones de Windows.
Instalación del paquete y las dependencias mediante el Administrador de paquetes NuGet
Las API y bibliotecas de SDK de llamadas están disponibles públicamente a través de un paquete NuGet.
Para buscar, descargar e instalar el paquete NuGet del SDK de llamadas:
- Abra el Administrador de paquetes NuGet desde Herramientas>Administrador de paquetes NuGet>Administrar paquetes NuGet para la solución.
- Seleccione Explorar y, después, escriba Azure.Communication.Calling.WindowsClient en el cuadro de búsqueda.
- Asegúrese de que la casilla Incluir versión preliminar esté activada.
- Seleccione el paquete Azure.Communication.Calling.WindowsClient y, después, Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 o una versión más reciente.
- Seleccione la casilla correspondiente al proyecto de Azure Communication Services en el panel derecho.
- Seleccione Instalar.
La característica de funcionalidades es una característica extendida de la API Call
principal y le permite obtener las funcionalidades del participante local en la llamada actual.
La característica permite registrarse para un agente de escucha de eventos con el fin de escuchar los cambios en funcionalidades.
Para usar la característica de llamada Capabilities para Windows, el primer paso es obtener el objeto de API de características Capabilities:
Obtención de la característica de funcionalidades
private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.Features.Capabilities;
Obtención de las funcionalidades del participante local
El objeto Capabilities tiene las funcionalidades de los participantes locales y es de tipo ParticipantCapability
. Entre las propiedades de las funcionalidades se incluyen las siguientes:
- isAllowed indica si se puede usar una funcionalidad.
- reason indica el motivo de resolución de la funcionalidad.
var capabilities = capabilitiesCallFeature.Capabilities;
Suscribirse al evento 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());
}
}
Funcionalidades expuestas
- TurnVideoOn: capacidad de activar el vídeo
- UnmuteMicrophone: capacidad para desactivar el micrófono
- ShareScreen: capacidad de compartir pantalla
- RemoveParticipant: capacidad de quitar un participante
- HangUpForEveryOne: capacidad de colgar para todos los usuarios
- AddCommunicationUser: capacidad de agregar un usuario de comunicación
- AddTeamsUser: capacidad de agregar usuarios de Teams
- AddPhoneNumber: capacidad de agregar un número de teléfono
- ManageLobby: capacidad de administrar la sala de espera
- SpotlightParticipant: capacidad para destacar al participante
- RemoveParticipantSpotlight: capacidad de quitar contenido destacado del participante
- BlurBackground: capacidad para desenfocar el fondo
- CustomBackground: capacidad de aplicar un fondo personalizado
- StartLiveCaptions: capacidad de iniciar subtítulos en directo
- RaiseHand: capacidad de levantar la mano
- MuteOthers: capacidad de silenciar temporalmente a participantes remotos en la reunión
Configuración del sistema
Siga estos pasos para configurar el sistema.
Creación del proyecto de Xcode
En Xcode, cree un nuevo proyecto de iOS y seleccione la plantilla Aplicación de una vista. En este artículo se usa el marco SwiftUI, por lo que debe establecer el Lenguaje en Swift y la Interfaz en SwiftUI.
No va a crear pruebas en este artículo. Puede desactivar la casilla Incluir pruebas.
Instalación del paquete y las dependencias mediante CocoaPods
Cree un Podfile para la aplicación, como en este ejemplo:
platform :ios, '13.0' use_frameworks! target 'AzureCommunicationCallingSample' do pod 'AzureCommunicationCalling', '~> 1.0.0' end
Ejecute
pod install
.Abra
.xcworkspace
mediante Xcode.
Solicitud de acceso al micrófono
Para acceder al micrófono del dispositivo, debe actualizar la lista de propiedades de información de la aplicación mediante NSMicrophoneUsageDescription
. Establezca el valor asociado en una cadena que se incluye en el cuadro de diálogo empleado por el sistema para solicitar acceso al usuario.
Haga clic con el botón derecho en la entrada Info.plist del árbol del proyecto y seleccione Abrir como>Código fuente. Agregue las líneas siguientes a la sección <dict>
de nivel superior y guarde el archivo.
<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>
Instalación del marco de la aplicación
Abra el archivo ContentView.swift
del proyecto. Agregue una declaración import
a la parte superior del archivo para importar la biblioteca AzureCommunicationCalling
. Además, importe AVFoundation
. Lo necesitará para las solicitudes de permiso de audio en el código.
import AzureCommunicationCalling
import AVFoundation
Inicialización de CallAgent
Para crear una instancia de CallAgent
a partir de CallClient
, debe usar el método callClient.createCallAgent
, que devuelve de manera asincrónica un objeto CallAgent
después de que se inicializa.
Para crear un cliente de llamada, pase un objeto 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)
}
Pase el objeto CommunicationTokenCredential
que ha creado a CallClient
y establezca el nombre para mostrar:
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")
}
})
La característica de funcionalidades es una característica extendida de la API Call
principal y le permite obtener las funcionalidades del participante local en la llamada actual.
La característica permite registrarse para un agente de escucha de eventos con el fin de escuchar los cambios en funcionalidades.
Para usar la característica de llamada Capabilities para Windows, el primer paso es obtener el objeto de API de características Capabilities:
Obtención de la característica de funcionalidades
let capabilitiesCallFeature =call.feature(Features.capabilities)
Obtención de las funcionalidades del participante local
El objeto Capabilities tiene las funcionalidades de los participantes locales y es de tipo ParticipantCapability
. Entre las propiedades de las funcionalidades se incluyen las siguientes:
- isAllowed indica si se puede usar una funcionalidad.
- reason indica el motivo de resolución de la funcionalidad.
var capabilities = capabilitiesCallFeature.capabilities
Suscribirse al evento capabilitiesChanged
capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()
public class CapabilitiesCallDelegate : CapabilitiesCallFeatureDelegate
{
public func capabilitiesCallFeature(_ capabilitiesCallFeature: CapabilitiesCallFeature, didChangeCapabilities args: CapabilitiesChangedEventArgs) {
let changedReason = args.reason
let changedCapabilities = args.changedCapabilities
}
}
Funcionalidades expuestas
- TurnVideoOn: capacidad de activar el vídeo
- UnmuteMicrophone: capacidad para desactivar el micrófono
- ShareScreen: capacidad de compartir pantalla
- RemoveParticipant: capacidad de quitar un participante
- HangUpForEveryOne: capacidad de colgar para todos los usuarios
- AddCommunicationUser: capacidad de agregar un usuario de comunicación
- AddTeamsUser: capacidad de agregar usuarios de Teams
- AddPhoneNumber: capacidad de agregar un número de teléfono
- ManageLobby: capacidad de administrar la sala de espera
- SpotlightParticipant: capacidad para destacar al participante
- RemoveParticipantSpotlight: capacidad de quitar contenido destacado del participante
- BlurBackground: capacidad para desenfocar el fondo
- CustomBackground: capacidad de aplicar un fondo personalizado
- StartLiveCaptions: capacidad de iniciar subtítulos en directo
- RaiseHand: capacidad de levantar la mano
- MuteOthers: capacidad de silenciar temporalmente a participantes remotos en la reunión
Tipos de llamadas admitidos
Actualmente, la característica solo se admite para el tipo de llamada de salas de Azure Communication Services y el tipo de llamada de reunión de Teams.
Motivos
En la siguiente tabla se proporciona información adicional sobre por qué la acción no está disponible y se proporcionan sugerencias sobre cómo hacer que la acción esté disponible.
Motivo | Descripción | Resolución |
---|---|---|
Capaz | Se permite la acción. | |
CapabilityNotApplicableForTheCallType | El tipo de llamada bloquea la acción. | Considere otro tipo de llamada si necesita esta acción. Los tipos de llamada son: llamada individual, llamada de grupo, llamada de interoperabilidad de Teams individual, llamada de grupo de interoperabilidad de Teams, Sala y Reunión. |
ClientRestricted | El entorno en runtime está bloqueando esta acción | Desbloquee la acción en el dispositivo cambiando el sistema operativo, los exploradores, la plataforma o el hardware. Puede encontrar el entorno admitido en nuestra documentación. |
UserPolicyRestricted | La directiva del usuario de Microsoft 365 bloquea la acción. | Habilite esta acción cambiando la directiva asignada al organizador de la reunión, al iniciador de la llamada o al usuario de Microsoft 365 mediante el SDK de ACS. El usuario de destino depende del tipo de acción. Obtenga más información sobre la directiva de Teams en Teams. El administrador de Teams puede cambiar las directivas. |
RoleRestricted | El rol asignado bloquea la acción. | Promueva al usuario a un rol diferente para que la acción esté disponible. |
FeatureNotSupported | La característica de funcionalidades no se admite en este tipo de llamada. | Háganos saber en el canal Azure Feedback que le gustaría tener esta característica disponible para este tipo de llamada. |
MeetingRestricted | La opción de reunión de Teams bloquea la acción. | El organizador o coorganizador de la reunión de los equipos debe cambiar la opción de reunión para habilitar esta acción. |
NotInitialized | La característica de funcionalidades aún no se ha inicializado. | Suscríbase al evento capabilitiesChanged en this.call.feature(Features.Capabilities) saber cuándo se inicializa la funcionalidad. |
NotCapable | El tipo de usuario bloquea la acción. | La acción solo se permite a un tipo específico de identidad. Habilite esta acción mediante la identidad de Microsoft 365. |
TeamsPremiumLicenseRestricted | El usuario de Microsoft 365 debe tener asignada la licencia Premium de Teams. | Habilite esta acción asignando la licencia Premium de Teams al organizador de la reunión de Teams o al usuario de Microsoft 365 mediante el SDK. El usuario de destino depende del tipo de acción. El administrador de Microsoft 365 puede asignar una licencia necesaria. |
ExplicitConsentRequired | Se requiere consentimiento para permitir la acción. | Proporcione el consentimiento para la grabación o transcripción mediante una llamada al método grantTeamsConsent() en this.call.feature(Features.Recording) o this.call.feature(Features.Transcription) . |