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
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Um recurso dos Serviços de Comunicação implantado. Crie um recurso dos Serviços de Comunicação.
- Um token de acesso de usuário para habilitar o cliente de chamada. Para saber mais, confira Criar e gerenciar token de acesso.
- Opcional: conclua o início rápido para adicionar chamadas de voz ao seu aplicativo
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ânciaCall Agent
se desconecta com este erro.connectionIssue
: se houver um problema com o cliente se conectando à infraestrutura da Microsoft, depois de muitas tentativasCall Agent
expõe o erroconnectionIssue
.
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:
- Abra o Gerenciador de Pacotes do NuGet selecionando Ferramentas>Gerenciador de Pacotes do NuGet>Gerenciar de Pacotes do NuGet para Solução.
- Selecione Procurar e insira Azure.Communication.Calling.WindowsClient na caixa de pesquisa.
- Verifique se a caixa de seleção Incluir pré-lançamento está marcada.
- Selecione o pacote Azure.Communication.Calling.WindowsClient e Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 ou uma versão mais recente.
- Marque a caixa de seleção que corresponde ao projeto dos Serviços de Comunicação do Azure no painel direito.
- 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.
Instalar o pacote e as dependências usando o CocoaPods
Crie um Podfile para seu aplicativo, como este exemplo:
platform :ios, '13.0' use_frameworks! target 'AzureCommunicationCallingSample' do pod 'AzureCommunicationCalling', '~> 1.0.0' end
Execute
pod install
.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 umaCallAgent
instânciaCallClient
,você precisa usar um método callClient.createCallAgent
que retorne de modo assíncrono um objetoCallAgent
depois 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) . |