Compartir a través de


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

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 de Call 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 error connectionIssue.

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:

  1. Abra el Administrador de paquetes NuGet desde Herramientas>Administrador de paquetes NuGet>Administrar paquetes NuGet para la solución.
  2. Seleccione Explorar y, después, escriba Azure.Communication.Calling.WindowsClient en el cuadro de búsqueda.
  3. Asegúrese de que la casilla Incluir versión preliminar esté activada.
  4. 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.
  5. Seleccione la casilla correspondiente al proyecto de Azure Communication Services en el panel derecho.
  6. 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.

Captura de pantalla que muestra la ventana para crear un proyecto en Xcode.

Instalación del paquete y las dependencias mediante CocoaPods

  1. 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
    
  2. Ejecute pod install.

  3. 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) .

Pasos siguientes