Casos de uso da biblioteca da interface do usuário

Use componentes e composições na biblioteca de interface do usuário dos Serviços de Comunicação do Azure para criar experiências de chamada e chat em seus aplicativos.

Em uma composição, os recursos de chamada e chat são integrados diretamente e expostos quando você integra a composição a um aplicativo. Em um componente de interface do usuário, os recursos de chamada e chat são expostos por meio de uma combinação de funcionalidade de interface do usuário e bibliotecas com estado subjacentes. Para aproveitar ao máximo esses recursos, é recomendável usar os componentes da interface do usuário com a chamada com estado e as bibliotecas de cliente de chat.

Obtenha mais documentação conceitual, guias de início rápido e exemplos no storybook da Biblioteca de Interface do Usuário.

Casos de uso de chamada

Área	Casos de uso
Tipos de chamada	Ingressar em uma reunião do Microsoft Teams
	Ingressar em uma chamada dos Serviços de Comunicação do Azure usando uma ID de grupo
	Ingresse em uma Sala de Serviços de Comunicação do Azure
	Iniciar uma chamada de saída para outro usuário dos Serviços de Comunicação do Azure
	Iniciar uma chamada de saída para um número de telefone
Interoperabilidade do Teams	Ingressar no lobby de chamadas
	Exibir uma faixa de alerta de transcrição e gravação
Controles de chamada	Ativar e desativar o mudo de chamadas
	Ativar ou desativar o vídeo durante uma chamada
	Ativar compartilhamento de tela
	Encerrar uma chamada
Galeria de participantes	Mostrar participantes remotos em uma grade
	Disponibilizar a visualização de vídeo em uma chamada para um usuário local
	Disponibilizar avatars padrão disponíveis quando o vídeo está desativado
	Mostrar conteúdo de tela compartilhada na galeria de participantes
Configuração de chamada	Gerenciar o dispositivo de microfone
	Gerenciar o dispositivo de câmera
	Gerenciar o dispositivo de alto-falante
	Disponibilizar a visualização local para o usuário verificar o vídeo
Participantes	Mostrar uma lista de participantes

Casos de uso de chat

Área	Azure Communication Services Chat	Interoperabilidade do chat do Teams
Tipos de chat	Participar de um thread de chat dos Serviços de Comunicação do Azure	Ingressar em um chat de reunião do Microsoft Teams
Ações de chat	Enviar e receber mensagens de texto	Enviar e receber mensagens de texto
	Receber mensagens em rich text	Receber mensagens em rich text
	-	Receber imagens em linha*
	Enviar e receber anexos de arquivo	Receber anexos de arquivo*
Eventos de chat	Enviar e receber indicadores de digitação	Enviar e receber indicadores de digitação**
	Enviar e receber confirmações de leitura	Enviar e receber confirmações de leitura
	Mostrar quando um participante é adicionado ou removido	Mostrar quando um participante é adicionado ou removido
Participantes	Mostrar uma lista de participantes	Mostrar uma lista de participantes

*O suporte a anexos de arquivo e imagem em linha estão atualmente em visualização pública. Versões prévias das APIs e dos SDKs são fornecidas sem um contrato de nível de serviço. É recomendável que você não as use para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou talvez ter restrição de recursos. Para saber mais, consulte os Termos de Uso Complementares das Versões Prévias do Microsoft Azure.

**O nome de exibição do evento de digitação do usuário do Teams pode não ser exibido corretamente.

Identidades com suporte

Para inicializar um composto e se autenticar no serviço, um usuário deve ter uma identidade dos Serviços de Comunicação do Azure. Para obter mais informações, confira Autenticar-se nos Serviços de Comunicação do Azure e Guia de início rápido: criar e gerenciar tokens de acesso.

Interoperabilidade do Teams

Para cenários de interoperabilidade do Teams, você pode usar composições da Biblioteca de IU para adicionar um usuário a uma reunião do Teams por meio dos Serviços de Comunicação. Para habilitar a interoperabilidade do Teams, use os recursos padrão na composição de chamada ou na composição de chat ou use componentes de interface do usuário para criar uma experiência personalizada.

Quando você adiciona chamada e chat a um aplicativo, é importante lembrar que o cliente de chat não pode ser inicializado até que o participante seja admitido na chamada. Depois que o participante for admitido, o cliente de chat poderá ser inicializado para ingressar no encadeamento de chat da reunião. Esse padrão é demonstrado na seguinte figura:

Se você usar componentes de interface do usuário para fornecer experiências de interoperabilidade do Teams, comece usando exemplos da Biblioteca de Interface do Usuário para criar partes-chave da experiência:

• Exemplo de lobby. Um lobby de amostra em que um participante pode esperar para ser admitido em uma chamada.
• Faixa de conformidade. Uma faixa de amostra que exibe o usuário se a chamada estiver sendo gravada.
• Tema do Teams. Um tema de amostra que faz com que os elementos da Biblioteca de Interface do Usuário se pareçam com o Microsoft Teams.
• Compartilhamento de imagens*. Um exemplo de usuário final dos Serviços de Comunicação do Azure pode receber imagens enviadas pelo usuário do Teams.
• Compartilhamento de arquivos*. Um exemplo de usuário final dos Serviços de Comunicação do Azure pode receber anexos de arquivo enviadas pelo usuário do Teams.

Personalização

Use os padrões da biblioteca de interface do usuário para modificar componentes para corresponder à aparência do seu aplicativo. A personalização é uma diferença fundamental entre compostos e componentes de interface do usuário nos Serviços de Comunicação. Os compostos têm menos opções de personalização para uma experiência de integração mais simples.

A seguinte tabela compara composições e componentes de interface do usuário para casos de uso de personalização:

Caso de uso	Composições	Componentes da interface do usuário
Usar temas baseados em Fluent	X	X
Redigir o layout da experiência		X
Usar o estilo CSS para modificar propriedades de estilo		X
Substituir ícones		X
Modificar o layout da galeria de participantes		X
Modificar o layout do controle de chamada	X	X
Injetar modelos de dados para modificar metadados do usuário	X	X

Observabilidade

A arquitetura de gerenciamento de estado da Biblioteca de Interface do Usuário é desacoplada, para que você possa acessar diretamente clientes de chat e de chamada com estado. Você pode se conectar ao cliente com estado para ler o estado, manipular eventos e substituir o comportamento para passar para os componentes da interface do usuário.

A seguinte tabela compara composições e componentes de interface do usuário para casos de uso de observabilidade:

Caso de uso	Composições	Componentes da interface do usuário
Acessar o estado do cliente de chamada e chat	X	X
Acessar e manipular eventos do cliente	X	X
Acessar e manipular eventos de interface do usuário	X	X

Arquitetura recomendada

Inicialize um composto e componente de base usando um token de acesso dos Serviços de Comunicação do Azure. É importante obter tokens de acesso dos Serviços de Comunicação por meio de um serviço confiável que você gerencia. Para obter mais informações, confira Guia de início rápido: criar e gerenciar tokens de acesso e o tutorial de serviço confiável.

As bibliotecas de clientes de chamada e chat precisam ter o contexto da chamada em que ingressam. Como no caso dos tokens de acesso do usuário, dissemine o contexto aos clientes usando seu próprio serviço confiável.

A seguinte tabela resume as funções de inicialização e gerenciamento de recursos necessárias para adicionar contexto a uma biblioteca de clientes:

Responsabilidades da Contoso	Responsabilidades da Biblioteca de IU
Fornecer o token de acesso do Azure	Passar o token de acesso fornecido para inicialização de componentes
Fornecer a função de atualização	Atualizar o token de acesso usando uma função fornecida pelo desenvolvedor
Recuperar e passar informações de ingresso na chamada ou no chat	Passar informações de chamada e chat para inicialização de componentes
Recuperar e passar informações do usuário a qualquer modelo de dados personalizado	Passar o modelo de dados personalizado aos componentes a serem renderizados

Suporte a plataforma

.	Windows	macOS	Ubuntu	Linux	Android	iOS
SDK da interface do usuário	Chrome*, Microsoft Edge	Chrome*, Safari**	Chrome*	Chrome*	Chrome*	Safari**

* Há suporte para a versão atual do Chrome e as duas versões anteriores.

** Há suporte para o Safari versão 13.1 e versões posteriores. Ainda não há suporte para vídeo de saída para o Safari no macOS, mas há suporte no iOS. Só há suporte para o compartilhamento de tela de saída no iOS desktop.

Acessibilidade

A acessibilidade por padrão é um princípio nos produtos da Microsoft. A biblioteca de interface do usuário segue esse princípio e todos os componentes de interface do usuário são totalmente acessíveis.

Localização

A localização é fundamental para criar produtos para usuários no mundo todo e que falam diferentes idiomas. A biblioteca de interface do usuário fornece suporte padrão para alguns idiomas e recursos, incluindo idiomas com leitura e escrita da direita para a esquerda. Você pode fornecer seus próprios arquivos de localização para usar com a Biblioteca de interface do usuário.

Problemas conhecidos

• No momento, a biblioteca da interface do usuário não dá suporte para a atualização do tipo de mensagem ao editar as mensagens existentes. A adição da formatação de rich text a uma mensagem existente adicionará estilo HTML ao conteúdo do texto. Como isso não altera o tipo de mensagem, pode resultar na exibição do conteúdo HTML como texto simples no thread da mensagem.

Visitar o storybook da biblioteca de interface do usuário

Use o CallComposite e o ChatComposite na Biblioteca de IU para Serviços de Comunicação do Azure a fim de criar experiências de chamada em aplicativos iOS e Android. Usando algumas linhas de código, você pode integrar facilmente ao aplicativo uma experiência de chamada e chat completa. As composições nos Serviços de Comunicação gerenciam todo o ciclo de vida da chamada e do chat, desde a instalação até o término da chamada e do chat.

Chamando casos de uso

Você pode usar a composição de chamada nos Serviços de Comunicação para criar estes casos de uso:

Área	Casos de uso
Tipos de chamada	Ingressar em uma reunião do Microsoft Teams
	Ingressar em uma chamada usando uma ID de grupo
Interoperabilidade do Teams	Ingressar no lobby de chamadas
	Exibir uma faixa de alerta de transcrição e gravação
Galeria de participantes	Mostrar participantes remotos em uma grade
	Disponibilizar a visualização de vídeo em uma chamada para um usuário local
	Disponibilizar avatars padrão disponíveis quando o vídeo está desativado
	Mostrar conteúdo de tela compartilhada na galeria de participantes
	Habilitar a personalização de avatar de participante
	Mostrar uma lista de participantes
Configuração de chamada	Gerenciar o dispositivo de microfone
	Gerenciar o dispositivo de câmera
	Gerenciar o dispositivo de alto-falante (com fio ou Bluetooth)
	Disponibilizar a visualização local para o usuário verificar o vídeo
	Habilitar a caixa de diálogo de confirmação de encerramento de chamada
Controles de chamada	Ativar e desativar o mudo de chamadas
	Ativar ou desativar o vídeo durante uma chamada
	Encerrar uma chamada
	Segurar e retomar uma chamada após a interrupção do áudio

Interoperabilidade do Teams

Para cenários de interoperabilidade do Teams, você pode usar composições da Biblioteca de IU para adicionar um usuário a uma reunião do Teams por meio dos Serviços de Comunicação. Para habilitar a interoperabilidade do Teams, use a composição de chamada. A composição gerencia todo o ciclo de vida de ingresso em uma chamada de interoperabilidade do Teams.

A seguinte figura mostra um exemplo da experiência do usuário antes que um chamador seja adicionado a uma reunião do Teams:

Ver conteúdo compartilhado

Por meio da Biblioteca de IU para plataformas nativas móveis, os participantes de chamadas podem ver o conteúdo compartilhado quando outros participantes compartilham as telas durante uma chamada do Teams. Um participante remoto pode usar gestos de ampliação e pinçagem para ampliar ou reduzir o conteúdo compartilhado na chamada.

Temas

Você pode usar a composição de chamada da Biblioteca de IU para iOS e Android para criar um tema personalizado da experiência de um chamador. Para criar a experiência de plataforma, passe um conjunto de cores de temas, conforme é mostrado na tabela a seguir. Para obter mais informações, confira Como criar um tema.

Android	iOS

Tamanho da tela

Você pode adaptar a composição de chamada dos Serviços de Comunicação do Azure a tamanhos de tela que variam de cinco polegadas até o tamanho do tablet. Use o modo dividido e o modo tablet na composição de chamada para obter o layout dinâmico de lista de participantes, aumentar a clareza da exibição e se concentrar na conversa.

Modo de divisão	Modo tablet

Localização

A localização é fundamental para criar produtos para usuários no mundo todo e que falam diferentes idiomas. A Biblioteca de IU dá suporte a 12 idiomas: inglês, espanhol, francês, alemão, italiano, japonês, coreano, holandês, português, russo, turco e chinês. Ela também dá suporte a idiomas da direita para a esquerda. Para obter mais informações, confira Como adicionar localização ao aplicativo.

Acessibilidade

A acessibilidade é o foco fundamental das bibliotecas de chamadas. Você pode usar um leitor de tela para fazer anúncios importantes sobre o status da chamada e garantir que usuários com deficiência visual possam participar efetivamente quando usarem o aplicativo.

Exibir a injeção de dados

Use a Biblioteca de Interface do Usuário para plataformas nativas móveis para dar aos participantes locais e remotos a opção de personalizar como eles aparecerão como usuários em uma chamada. Um participante local poderá escolher um avatar local, o nome de exibição personalizado, o título e o subtítulo da navegação na tela de Configuração quando uma chamada iniciar. Um usuário remoto pode criar um avatar personalizado ao ingressar na reunião. Para obter mais informações, consulte Como personalizar a exibição de pré-reunião.

Ignorar tela de instalação

A Biblioteca da Interface do Usuário fornece a capacidade de ingressar em uma chamada ignorando a tela de configuração da experiência de ingresso na chamada. Por padrão, o usuário passa por uma tela de configuração para ingressar em uma chamada. Aqui, o usuário define a configuração da chamada, como ativar ou desativar a câmera, ativar ou desativar o microfone e a seleção do dispositivo de áudio antes de ingressar em uma chamada. Essa tela requer a interação do usuário para ingressar em uma chamada, o que pode ser desnecessário para alguns usuários. Portanto, fornecemos a capacidade de ingressar em uma chamada ignorando a tela de configuração e fornecendo as APIs de configuração de chamada. Para obter mais informações, confira Como usar o recurso Ignorar a tela de instalação.

Modo Somente Áudio

O Modo Somente Áudio na Biblioteca de Interface do Usuário permite que os participantes participem de chamadas usando apenas o áudio, sem compartilhar nem receber vídeo. Esse recurso é usado para conservar a largura de banda e maximizar a privacidade. Quando ativado, o Modo Somente Áudio desabilita automaticamente as funcionalidades de vídeo para enviar e receber fluxos e ajusta a interface do usuário para refletir essa alteração, removendo controles relacionados a vídeo. Este modo pode ser habilitado por meio da configuração CallComposite; mais informações estão disponíveis por meio do Início Rápido Somente Áudio.

Orientação

A Biblioteca da Interface do Usuário dá suporte à configuração de orientação de tela para cada uma das telas separadamente antes de iniciar a experiência da biblioteca. Isso permite que os desenvolvedores de aplicativos configurem uma orientação fixa para a experiência de chamada, o que alinharia a orientação do aplicativo. Para saber mais sobre a lista de orientação com suporte para a plataforma Android e iOS e o uso da API, confira Como usar o recurso de orientação.

Multitarefa e Picture in Picture

A Biblioteca da Interface do Usuário dá suporte ao modo picture in picture da tela de chamada. Enquanto estiver na chamada, o usuário pode clicar no botão Voltar na tela de chamada para habilitar a multitarefa, o que levará o usuário de volta à tela anterior. Se picture in picture estiver habilitado, um picture in picture do sistema será exibido para chamada. Para saber mais sobre a multitarefa e o recurso picture-in-picture para a plataforma Android e iOS e o uso da API, confira Como usar o recurso picture-in-picture.

Suporte ao CallKit

A Biblioteca da Interface do Usuário dá suporte à integração do CallKit para lidar com a interação com o CallKit para chamadas. Para saber mais sobre a integração da plataforma iOS e o uso da API, confira Como usar o CallKit.

Suporte a chamadas individuais e notificações por push

A Biblioteca da Interface do Usuário dá suporte à chamada VoIP individual para discar usuários pelo identificador de comunicação. Para receber a Biblioteca da Interface do Usuário de chamada recebida, também dá suporte ao registro para notificações por push. Para saber mais sobre a integração para a plataforma Android e iOS e o uso da API, confira Como fazer uma chamada um-para-um e receber notificações por PUSH.

Desabilitar o prompt de encerramento de chamada

Ao desenvolver aplicativos que integram recursos de chamada, garantir uma experiência de usuário perfeita e intuitiva é crucial. Uma área em que a UX pode ser simplificada é durante o processo de encerramento de chamada. Especificamente, os desenvolvedores podem achar benéfico desabilitar o prompt de confirmação de chamada à esquerda que aparece quando um usuário deseja encerrar a chamada. Esse recurso, embora útil na prevenção de encerramento acidental de chamadas, às vezes pode dificultar a experiência do usuário, especialmente em ambientes em que a velocidade e a eficiência são cruciais. Como desabilitar a confirmação da chamada

Ambientes de comunicação em ritmo acelerado: em ambientes como pregões, call centers de emergência ou centros de atendimento ao cliente em que as decisões e ações devem ser executadas rapidamente, a etapa adicional de confirmação do encerramento da chamada pode impedir a eficiência do fluxo de trabalho.

Casos de uso de chat

Importante

Este recurso dos Serviços de Comunicação do Azure estão atualmente em versão prévia.

Versões prévias das APIs e dos SDKs são fornecidas sem um contrato de nível de serviço. É recomendável que você não as use para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou talvez ter restrição de recursos.

Para saber mais, consulte os Termos de Uso Complementares das Versões Prévias do Microsoft Azure.

Área	Casos de uso
Tipos de chat	Participar de um thread de chat dos Serviços de Comunicação do Azure
Ações de chat	Enviar uma mensagem de chat
	Receber uma mensagem de chat
Eventos de chat	Mostrar indicadores de digitação
	Mostrar uma confirmação de leitura
	Mostrar quando um participante é adicionado ou removido
	Mostrar alterações no título do chat

Flexibilidade

O ChatComposite foi projetado para se ajustar a diferentes layouts e exibições no aplicativo. Por exemplo, você pode colocar o Chat em uma exibição de navegação, modal ou de outros tipos. O ChatComposite se ajusta sozinho e garante uma experiência perfeita para o usuário.

Na exibição de navegação	Na exibição modal

Identidades com suporte

Para inicializar um composto e se autenticar no serviço, um usuário deve ter uma identidade dos Serviços de Comunicação do Azure. Para obter mais informações, confira Autenticar-se nos Serviços de Comunicação do Azure e Guia de início rápido: criar e gerenciar tokens de acesso.

Arquitetura recomendada

Inicialize uma composição usando um token de acesso dos Serviços de Comunicação do Azure. É importante obter tokens de acesso dos Serviços de Comunicação do Azure por meio de um serviço confiável que você gerencia. Para obter mais informações, confira Guia de início rápido: criar e gerenciar tokens de acesso e o tutorial de serviço confiável.

As bibliotecas de clientes de chamada e chat precisam ter o contexto da chamada em que ingressam. Como no caso dos tokens de acesso do usuário, dissemine o contexto aos clientes usando seu próprio serviço confiável. A seguinte tabela resume as funções de inicialização e gerenciamento de recursos necessárias para adicionar contexto a uma biblioteca de clientes:

Responsabilidades da Contoso	Responsabilidades da Biblioteca de IU
Fornecer o token de acesso do Azure	Passar o token de acesso fornecido para inicialização de componentes
Fornecer a função de atualização	Atualizar o token de acesso usando uma função fornecida pelo desenvolvedor
Recuperar e passar informações de ingresso na chamada ou no chat	Passar informações de chamada e chat para inicialização de componentes
Recuperar e passar informações do usuário a qualquer modelo de dados personalizado	Passar o modelo de dados personalizado aos componentes a serem renderizados

Suporte a plataforma

Plataforma	Versões
iOS	iOS 14 e posteriores
Android	API 21 e posteriores

Guia de Solução de Problemas

Quando a solução de problemas ocorre nas chamadas de voz ou vídeo, você pode ser solicitado a fornecer uma CallID; essa ID é usada para identificar chamadas dos Serviços de Comunicação.

Essa CallID pode ser recuperada por meio da barra de ações na parte inferior da tela de chamada, em um botão de reticências. Depois que o usuário executar a ação de toque de uma opção de "Compartilhar informações de diagnóstico", o usuário poderá compartilhar as informações de diagnóstico, que são necessárias para equipe de suporte acompanhar qualquer problema.

Para obter acesso programático ao CallID, confira "Como obter informações de depuração programaticamente".

Você pode saber mais sobre as diretrizes de solução de problemas aqui: página de "Solução de problemas no Serviços de Comunicação do Azure".

Tela de chamada	Menu de informações de diagnóstico	Compartilhar CallID

Guias de Início Rápido