Compartilhar via


Observar os recursos do usuário

Tenho permissão para ligar o vídeo, tenho permissão para ligar o microfone, tenho permissão para compartilhar a tela? Essas permissões são alguns exemplos de funcionalidades de participante que você pode aprender com a API de recursos. Aprender os recursos pode ajudar a criar uma interface do usuário que mostra apenas os botões relacionados às ações às quais o usuário local tem permissões.

Pré-requisitos

Instalar o SDK

Use o comando npm install para instalar o SDK Comum e de Chamada dos Serviços de Comunicação do Azure para JavaScript:

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

Inicializar objetos necessários

Uma instância CallClient é necessária para a maioria das operações de chamada. Ao criar uma instância de CallClient, você pode configurá-la com opções personalizadas, como uma instância de Logger.

Com a instância de CallClient, você pode criar uma instância de CallAgent chamando o createCallAgent. Esse método retorna de modo assíncrono um objeto de instância CallAgent.

O método createCallAgent usa CommunicationTokenCredential como um argumento. Ele aceita um token de acesso do usuário.

Você pode usar o método getDeviceManager na instância CallClient para acessar o 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()

Como gerenciar melhor a conectividade do SDK com a infraestrutura da Microsoft

A instância Call Agent ajuda você a gerenciar chamadas (para ingressar ou iniciar chamadas). Para trabalhar, o SDK de chamada precisa se conectar à infraestrutura da Microsoft para receber notificações de chamadas de entrada e coordenar outros detalhes da chamada. O seu Call Agent tem dois estados possíveis:

Conectado: um valor connectionStatue Call Agent de Connected significa que o SDK do cliente está conectado e capaz de receber notificações da infraestrutura da Microsoft.

Desconectado: um valor connectionStatue Call Agent de Disconnected declara que há um problema que está impedindo o SDK de se conectar corretamente. Call Agent deve ser recriado.

  • invalidToken: se um token tiver expirado ou for inválido, a instância Call Agent se desconecta com este erro.
  • connectionIssue: se houver um problema com o cliente se conectando à infraestrutura da Microsoft, depois de muitas tentativas Call Agent expõe o erro connectionIssue.

Você pode verificar se o local Call Agent está conectado à infraestrutura da Microsoft inspecionando o valor atual da propriedade connectionState. Durante uma chamada ativa, você pode ouvir o evento connectionStateChanged para determinar se Call Agent é alterado do estado Conectado ao 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);

O recurso recursos é um recurso estendido da API principal Call e permite que você obtenha os recursos do participante local na chamada atual.

O recurso permite que você se registre para um ouvinte de eventos, para ouvir as alterações de funcionalidade.

Registre-se no recurso de funcionalidades:

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

Obtenha os recursos do participante local: o objeto Capabilities tem os recursos dos participantes locais e é do tipo ParticipantCapabilities. As propriedades dos recursos incluem:

  • isPresent indica se uma funcionalidade está presente.
  • motivo indica o motivo da resolução da funcionalidade.
const capabilities =  capabilitiesFeature.capabilities;

Inscreva-se no capabilitiesChanged evento:

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 expostas

  • turnVideoOn: Capacidade de ativar o vídeo
  • unmuteMic: capacidade de ativar o microfone
  • shareScreen: Capacidade de compartilhar tela
  • removeParticipant: capacidade de remover um participante
  • hangUpForEveryOne: Capacidade de desligar para todos
  • addCommunicationUser: capacidade de adicionar um usuário de comunicação
  • addTeamsUser: capacidade de adicionar o usuário do Teams
  • addPhoneNumber: Capacidade de adicionar número de telefone
  • manageLobby: Capacidade de gerenciar lobby (somente beta)
  • spotlightParticipant: Capacidade de destacar Participante (somente beta)
  • removeParticipantsSpotlight: Capacidade de remover o destaque do participante (somente beta)
  • startLiveCaptions: capacidade de iniciar legendas ao vivo (somente beta)
  • stopLiveCaptions: capacidade de parar legendas ao vivo (somente beta)
  • raiseHand: Capacidade de levantar a mão (somente beta)
  • muteOthers: capacidade de silenciar suavemente os participantes remotos na reunião
  • reação: Capacidade de reagir na reunião (somente beta)
  • viewAttendeeNames: capacidade de exibir os nomes dos participantes na reunião

Instalar o SDK

Localize o arquivo build.gradle de nível do projeto e adicione mavenCentral() à lista de repositórios em buildscript e allprojects:

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

Em seguida, no arquivo build.gradle no nível do módulo, adicione as seguintes linhas à seção dependencies:

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

Inicializar objetos necessários

Para criar uma instância CallAgent, você precisa chamar o método createCallAgent em uma instância CallClient. Essa chamada retorna de forma assíncrona um objeto de instância CallAgent.

O método createCallAgent usa CommunicationUserCredential como argumento, que encapsula um token de acesso.

Para acessar DeviceManager, você deverá criar uma instância callAgent primeiro. Em seguida, você poderá usar o método CallClient.getDeviceManager para obter 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 definir um nome de exibição para o chamador, 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();

O recurso recursos é um recurso estendido da API principal Call e permite que você obtenha os recursos do participante local na chamada atual.

O recurso permite que você se registre para um ouvinte de eventos, para ouvir as alterações de funcionalidade.

Para usar o recurso de chamada de recursos para Windows, a primeira etapa é obter o objeto API do recurso de recursos:

Recurso de obtenção de recursos

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

Obtenha os recursos do participante local

O objeto de capacidades possui as capacidades dos participantes locais e é do tipo ParticipantCapability. As propriedades dos recursos incluem:

  • isAllowed indica se um recurso pode ser usado.
  • motivo indica o motivo da resolução da funcionalidade.
List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();

Inscreva-se em capabilitiesChanged evento


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 expostas

  • TurnVideoOn: Capacidade de ativar o vídeo
  • UnmuteMicrophone: Capacidade de ativar o microfone
  • ShareScreen: Capacidade de compartilhar tela
  • RemoveParticipant: Capacidade de remover um participante
  • HangUpForEveryone: Capacidade de desligar para todos
  • AddCommunicationUser: Capacidade de adicionar um usuário de comunicação
  • AddTeamsUser: Capacidade de adicionar usuário do Teams
  • AddPhoneNumber: Capacidade de adicionar número de telefone
  • ManageLobby: Capacidade de gerenciar lobby
  • SpotlightParticipant: Capacidade de destacar o participante
  • RemoveParticipantSpotlight: Capacidade de remover o destaque do participante
  • BlurBackground: Capacidade de desfocar o fundo
  • CustomBackground: Capacidade de aplicar um plano de fundo personalizado
  • StartLiveCaptions: Capacidade de iniciar legendas ao vivo
  • RaiseHand: Capacidade de levantar a mão
  • MuteOthers: capacidade de silenciar suavemente os participantes remotos na reunião

Configurar o backup do sistema

Siga essas etapas para configurar seu sistema.

Criar o projeto do Visual Studio

Para um aplicativo da Plataforma Universal do Windows, no Visual Studio 2022, crie um projeto de Aplicativo em branco (Universal do Windows). Depois de inserir o nome do projeto, fique à vontade para escolher qualquer SDK do Windows posterior a 10.0.17763.0.

Para um aplicativo WinUI 3, crie um novo projeto com o modelo Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) para configurar um aplicativo WinUI 3 de página única. O SDK do Aplicativo do Windows versão 1.3 ou posterior é necessário.

Instalar o pacote e as dependências usando o Gerenciador de Pacotes do NuGet

As bibliotecas e as APIs do SDK de Chamada estão disponíveis publicamente por meio de um pacote NuGet.

Para localizar, baixar e instalar o pacote NuGet do SDK de Chamada, faça o seguinte:

  1. Abra o Gerenciador de Pacotes do NuGet selecionando Ferramentas>Gerenciador de Pacotes do NuGet>Gerenciar de Pacotes do NuGet para Solução.
  2. Selecione Procurar e insira Azure.Communication.Calling.WindowsClient na caixa de pesquisa.
  3. Verifique se a caixa de seleção Incluir pré-lançamento está marcada.
  4. Selecione o pacote Azure.Communication.Calling.WindowsClient e Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 ou uma versão mais recente.
  5. Marque a caixa de seleção que corresponde ao projeto dos Serviços de Comunicação do Azure no painel direito.
  6. Selecione Instalar.

O recurso recursos é um recurso estendido da API principal Call e permite que você obtenha os recursos do participante local na chamada atual.

O recurso permite que você se registre para um ouvinte de eventos, para ouvir as alterações de funcionalidade.

Para usar o recurso de chamada de recursos para Windows, a primeira etapa é obter o objeto API do recurso de recursos:

Recurso de obtenção de recursos

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

Obtenha os recursos do participante local

O objeto de capacidades possui as capacidades dos participantes locais e é do tipo ParticipantCapability. As propriedades dos recursos incluem:

  • isAllowed indica se um recurso pode ser usado.
  • motivo indica o motivo da resolução da funcionalidade.
var capabilities = capabilitiesCallFeature.Capabilities;

Inscreva-se em capabilitiesChanged evento

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 expostas

  • TurnVideoOn: Capacidade de ativar o vídeo
  • UnmuteMicrophone: Capacidade de ativar o microfone
  • ShareScreen: Capacidade de compartilhar tela
  • RemoveParticipant: Capacidade de remover um participante
  • HangUpForEveryone: Capacidade de desligar para todos
  • AddCommunicationUser: Capacidade de adicionar um usuário de comunicação
  • AddTeamsUser: Capacidade de adicionar usuário do Teams
  • AddPhoneNumber: Capacidade de adicionar número de telefone
  • ManageLobby: Capacidade de gerenciar lobby
  • SpotlightParticipant: Capacidade de destacar o participante
  • RemoveParticipantSpotlight: Capacidade de remover o destaque do participante
  • BlurBackground: Capacidade de desfocar o fundo
  • CustomBackground: Capacidade de aplicar um plano de fundo personalizado
  • StartLiveCaptions: Capacidade de iniciar legendas ao vivo
  • RaiseHand: Capacidade de levantar a mão
  • MuteOthers: capacidade de silenciar suavemente os participantes remotos na reunião

Configurar o backup do sistema

Siga essas etapas para configurar seu sistema.

Criar o projeto do Xcode

No Xcode, crie um projeto do iOS e selecione o modelo Aplicativo de Modo de Exibição Único. Como este artigo usa a estrutura SwiftUI, defina Linguagem como Swift e Interface como SwiftUI.

Você não criará testes neste artigo. Fique à vontade para limpar a caixa de seleção Incluir Testes.

Captura de tela que mostra a janela para a criação de um projeto no Xcode.

Instalar o pacote e as dependências usando o CocoaPods

  1. Crie um Podfile para seu aplicativo, como este exemplo:

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

  3. Abra o .xcworkspace usando o Xcode.

Solicitar acesso ao microfone

Para acessar o microfone do dispositivo, você precisa atualizar a lista de propriedades de informações do aplicativo usando NSMicrophoneUsageDescription. Defina o valor associado como uma cadeia de caracteres incluída na caixa de diálogo que é usada pelo sistema para solicitar o acesso do usuário.

Clique com o botão direito do mouse na entrada Info.plist da árvore de projeto e selecione Abrir Como>Código-Fonte. Adicione as linhas a seguir na seção do nível superior<dict>e, em seguida, salve o arquivo.

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

Configurar o framework de aplicativos

Abra o arquivo ContentView.swift do projeto. Adicione uma declaração import à parte superior do arquivo para importar a biblioteca AzureCommunicationCalling. Além disso, importeAVFoundation. Você precisa dele para solicitações de permissão de áudio no código.

import AzureCommunicationCalling
import AVFoundation

Inicialização do CallAgent

Para criar umaCallAgentinstânciaCallClient,você precisa usar um método callClient.createCallAgentque retorne de modo assíncrono um objetoCallAgentdepois que ele for inicializado.

Para criar um cliente de chamada, passe um 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)
}

Passe o objeto CommunicationTokenCredential que você criou para CallClient e defina o nome de exibição:

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

O recurso recursos é um recurso estendido da API principal Call e permite que você obtenha os recursos do participante local na chamada atual.

O recurso permite que você se registre para um ouvinte de eventos, para ouvir as alterações de funcionalidade.

Para usar o recurso de chamada de recursos para Windows, a primeira etapa é obter o objeto API do recurso de recursos:

Recurso de obtenção de recursos

let capabilitiesCallFeature =call.feature(Features.capabilities)

Obtenha os recursos do participante local

O objeto de capacidades possui as capacidades dos participantes locais e é do tipo ParticipantCapability. As propriedades dos recursos incluem:

  • isAllowed indica se um recurso pode ser usado.
  • motivo indica o motivo da resolução da funcionalidade.
var capabilities = capabilitiesCallFeature.capabilities

Inscreva-se em capabilitiesChanged evento


capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()

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

Funcionalidades expostas

  • TurnVideoOn: Capacidade de ativar o vídeo
  • UnmuteMicrophone: Capacidade de ativar o microfone
  • ShareScreen: Capacidade de compartilhar tela
  • RemoveParticipant: Capacidade de remover um participante
  • HangUpForEveryone: Capacidade de desligar para todos
  • AddCommunicationUser: Capacidade de adicionar um usuário de comunicação
  • AddTeamsUser: Capacidade de adicionar usuário do Teams
  • AddPhoneNumber: Capacidade de adicionar número de telefone
  • ManageLobby: Capacidade de gerenciar lobby
  • SpotlightParticipant: Capacidade de destacar o participante
  • RemoveParticipantSpotlight: Capacidade de remover o destaque do participante
  • BlurBackground: Capacidade de desfocar o fundo
  • CustomBackground: Capacidade de aplicar um plano de fundo personalizado
  • StartLiveCaptions: Capacidade de iniciar legendas ao vivo
  • RaiseHand: Capacidade de levantar a mão
  • MuteOthers: capacidade de silenciar suavemente os participantes remotos na reunião

Tipos de chamadas com suporte

No momento, o recurso tem suporte apenas para o tipo de chamada das Serviços de Comunicação do Azure e o tipo de chamada de reunião de equipes

Motivos

A tabela a seguir apresenta informações adicionais sobre por que a ação não está disponível e fornece dicas de como disponibilizar a ação.

Motivo Descrição Resolução
Capable A ação é permitida.
CapabilityNotApplicableForTheCallType O tipo de chamada bloqueia a ação. Considere outro tipo de chamada se você precisar dessa ação. Os tipos de chamada são: chamada 1:1, chamada em grupo, chamada de interoperabilidade do Teams 1:1, chamada de grupo de interoperabilidade do Teams 1:1, Sala e Reunião.
ClientRestricted O ambiente de runtime está bloqueando essa ação Desbloqueie a ação em seu dispositivo alterando o sistema operacional, navegadores, plataforma ou hardware. Você pode encontrar um ambiente com suporte em nossa documentação.
UserPolicyRestricted A política do usuário do Microsoft 365 bloqueia a ação. Habilite essa ação alterando a política atribuída ao organizador da reunião, ao iniciador da chamada ou ao usuário do Microsoft 365 usando o SDK do ACS. O usuário de destino depende do tipo de ação. Saiba mais sobre a política do Teams no Teams. O administrador do Teams pode alterar as políticas.
RoleRestricted A função atribuída bloqueia a ação. Promova o usuário para uma função diferente para disponibilizar a ação.
FeatureNotSupported Não há suporte para o recurso de funcionalidades nesse tipo de chamada. No canal comentários do Azure, informe-nos que você gostaria de ter esse recurso disponível para esse tipo de chamada.
MeetingRestricted A opção de reunião do Teams bloqueia a ação. O organizador ou co-organizador da reunião do Teams precisa alterar a opção de reunião para habilitar essa ação.
NotInitialized O recurso das funcionalidades ainda não foi inicializado. Inscreva-se no evento capabilitiesChanged em this.call.feature(Features.Capabilities) para saber quando a funcionalidade é inicializada.
NotCapable O tipo de usuário bloqueia a ação. A ação só tem permissão para um tipo específico de identidade. Habilite essa ação usando a identidade do Microsoft 365.
TeamsPremiumLicenseRestricted O usuário do Microsoft 365 precisa ter a licença do Teams Premium atribuída a ele. Habilite essa ação atribuindo a licença do Teams Premium ao organizador da reunião do Teams ou ao usuário do Microsoft 365 usando o SDK. O usuário de destino depende do tipo de ação. O administrador do Microsoft 365 pode atribuir a licença necessária.
ExplicitConsentRequired É necessário o consentimento para permitir a ação. Forneça o consentimento para gravação ou transcrição pelo método de chamada grantTeamsConsent() em this.call.feature(Features.Recording) ou this.call.feature(Features.Transcription).

Próximas etapas