Criando uma experiência de preparação de chamada usando os Serviços de Comunicação do Azure

2025-04-22

Importante

Este recurso dos Serviços de Comunicação do Azure estão atualmente em versão prévia. Os recursos em versão prévia estão disponíveis publicamente e podem ser usados por todos os clientes novos e existentes da Microsoft.

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 recursos podem ser restritos.

Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Neste tutorial, estamos usando os Serviços de Comunicação do Azure com a Biblioteca de Interface do Usuário para criar uma experiência que prepara os usuários para ingressar em uma chamada. A Biblioteca de Interface do Usuário fornece um conjunto de componentes avançados e controles de interface do usuário que podem ser usados para produzir uma experiência de Preparação de Chamadas e um conjunto avançado de APIs para entender o estado do usuário.

Pré-requisitos

Siga o processo de instalação do aplicativo na parte anterior deste tutorial: Preparação de Chamadas – Visão geral

Código de download

Acesse o código completo deste tutorial sobre GitHub.

Verificando se há suporte ao navegador

Para garantir que o usuário obtenha a melhor experiência, queremos primeiro verificar se ele está em um navegador com suporte. Nesta seção, criamos uma página que exibe "Preparando sua sessão" enquanto executamos uma rápida verificação de suporte em segundo plano no navegador do usuário.

Gif mostrando a verificação do navegador sendo executada

Preparando sua página de sessão

Crie um novo arquivo chamado PreparingYourSession.tsx onde criamos um spinner para mostrar ao usuário enquanto executamos verificações assíncronas em segundo plano:

src/PreparingYourSession.tsx

import { useTheme } from '@azure/communication-react';
import { ISpinnerStyles, IStackStyles, ITextStyles, ITheme, Spinner, Stack, Text } from '@fluentui/react';

/** This page displays a spinner to the user. This is used to show the user that background checks are being performed. */
export const PreparingYourSession = (): JSX.Element => {
  const theme = useTheme();
  return (
    <Stack verticalFill verticalAlign="center" horizontalAlign="center" tokens={{ childrenGap: '3rem' }}>
      <Stack styles={spinnerContainerStyles(theme)}>
        <Spinner styles={spinnerStyles} />
      </Stack>
      <Stack horizontalAlign="center">
        <Text styles={headingStyles} variant="large">Preparing your session</Text>
        <Text variant="medium">Please be patient</Text>
      </Stack>
    </Stack>
  );
};

const headingStyles: ITextStyles = {
  root: {
    fontWeight: '600',
    lineHeight: '2rem'
  }
};

const spinnerStyles: ISpinnerStyles = {
  circle: {
    height: '2.75rem',
    width: '2.75rem',
    borderWidth: '0.2rem'
  }
};

const spinnerContainerStyles = (theme: ITheme): IStackStyles => ({
  root: {
    padding: '1.75rem',
    borderRadius: '50%',
    background: theme.palette?.themeLighterAlt
  }
});

Em seguida, podemos conectar essa tela Preparando sua sessão em nosso Aplicativo. Em App.tsx e em uma variável testState para acompanhar o estado do aplicativo e, enquanto testState estiver no estado runningEnvironmentChecks, mostraremos a tela Preparando sua sessão.

Primeiro, adicione as seguintes importações ao arquivo App.tsx que criamos na visão geral:

import { useState } from 'react';
import { PreparingYourSession } from './PreparingYourSession';

Depois que isso terminar, atualize nosso App.tsx arquivo para incluir o novo spinner.

type TestingState = 'runningEnvironmentChecks' | 'finished';

const App = (): JSX.Element => {
  const [testState, setTestState] = useState<TestingState>('runningEnvironmentChecks');

  return (
    <FluentThemeProvider>
      <CallClientProvider callClient={callClient}>
        {/* Show a Preparing your session screen while running the call readiness checks */}
        {testState === 'runningEnvironmentChecks' && (
          <>
            <PreparingYourSession />
          </>
        )}

        {/* After the device setup is complete, take the user to the call. For this sample we show a test complete page. */}
        {testState === 'finished' && <TestComplete />}
      </CallClientProvider>
    </FluentThemeProvider>
  );
}

Executando uma verificação de informações de ambiente

Primeiro, crie um arquivo de utilitário chamado environmentSupportUtils.ts. Dentro dessa chamada, adicionamos um método checkEnvironmentSupport. Esse método usa o Cliente com Estado de Chamada para executar uma solicitação para as informações de ambiente em que o Cliente com Estado de Chamada está em execução.

src/environmentSupportUtils.ts

import { Features, EnvironmentInfo } from "@azure/communication-calling";
import { StatefulCallClient } from "@azure/communication-react";

/** Use the CallClient's getEnvironmentInfo() method to check if the browser is supported. */
export const checkEnvironmentSupport = async (callClient: StatefulCallClient): Promise<EnvironmentInfo> => {
  const environmentInfo = await callClient.feature(Features.DebugInfo).getEnvironmentInfo();
  console.info(environmentInfo); // view console logs in the browser to see what environment info is returned
  return environmentInfo;
}

Uma linha retornada de checkEnvironmentSupport contém as seguintes informações:

Suporte do navegador
Suporte à versão do navegador
Suporte ao sistema operacional (Plataforma)
Informações detalhadas do ambiente

Informando ao usuário que ele está em um navegador sem suporte

Em seguida, precisamos usar essas informações fornecidas do SDK de Chamada para informar o usuário sobre o estado de seu ambiente se houver um problema. A biblioteca de interface do usuário fornece três componentes diferentes para atender a essa finalidade, dependendo do problema.

UnsupportedOperatingSystem
UnsupportedBrowser
UnsupportedBrowserVersion

Começamos hospedando os componentes da Biblioteca de Interface do Usuário dentro de um FluentUI Modal: Crie um novo arquivo chamado UnsupportedEnvironmentPrompts.tsx no qual criamos os prompts diferentes:

src/UnsupportedEnvironmentPrompts.tsx

import { UnsupportedOperatingSystem, UnsupportedBrowser, UnsupportedBrowserVersion } from '@azure/communication-react';
import { Modal } from '@fluentui/react';

/**
 * Modal dialog that shows a Browser Version Unsupported Prompt
 * Use the `onTroubleShootingClick` argument to redirect the user to further troubleshooting.
 * Use the `onContinueAnywayClick` argument to allow the user to continue to the next step even though they are on an unsupported browser version.
 */
export const BrowserVersionUnsupportedPrompt = (props: { isOpen: boolean, onContinueAnyway:() => void }): JSX.    Element => (
  <Modal isOpen={props.isOpen}>
    <UnsupportedBrowserVersion
      onTroubleshootingClick={() => alert('This callback should be used to take the user to further troubleshooting')}
      onContinueAnywayClick={() => props.onContinueAnyway()}
    />
  </Modal>
);

/**
 * Modal dialog that shows a Browser Unsupported Prompt
 * Use the `onTroubleShootingClick` argument to redirect the user to further troubleshooting.
 */
export const BrowserUnsupportedPrompt = (props: { isOpen: boolean }): JSX.Element => (
  <Modal isOpen={props.isOpen}>
    <UnsupportedBrowser
      onTroubleshootingClick={() => alert('This callback should be used to take the user to further troubleshooting')}
    />
  </Modal>
);

/**
 * Modal dialog that shows an Operating System Unsupported Prompt
 * Use the `onTroubleShootingClick` argument to redirect the user to further troubleshooting.
 */
export const OperatingSystemUnsupportedPrompt = (props: { isOpen: boolean }): JSX.Element => (
  <Modal isOpen={props.isOpen}>
    <UnsupportedOperatingSystem
      onTroubleshootingClick={() => alert('This callback should be used to take the user to further troubleshooting')}
    />
  </Modal>
);

Em seguida, podemos mostrar esses prompts em um componente de verificação de ambiente. Crie um arquivo chamado EnvironmentChecksComponent.tsx que contenha a lógica para mostrar este prompt: esse componente tem um retorno onTestsSuccessful de chamada que pode levar o usuário para a próxima página no Aplicativo.

src/EnvironmentChecksComponent.tsx

import { useEffect, useState } from 'react';
import { BrowserUnsupportedPrompt, BrowserVersionUnsupportedPrompt, OperatingSystemUnsupportedPrompt } from './UnsupportedEnvironmentPrompts';
import { useCallClient } from '@azure/communication-react';
import { checkEnvironmentSupport } from './environmentSupportUtils';

export type EnvironmentChecksState = 'runningEnvironmentChecks' |
  'operatingSystemUnsupported' |
  'browserUnsupported' |
  'browserVersionUnsupported';

/**
 * This component is a demo of how to use the StatefulCallClient with CallReadiness Components to get a user
 * ready to join a call.
 * This component checks the browser support.
 */
export const EnvironmentChecksComponent = (props: {
  /**
   * Callback triggered when the tests are complete and successful
   */
  onTestsSuccessful: () => void
}): JSX.Element => {
  const [currentCheckState, setCurrentCheckState] = useState<EnvironmentChecksState>('runningEnvironmentChecks');
  

  // Run call readiness checks when component mounts
  const callClient = useCallClient();
  useEffect(() => {
    const runEnvironmentChecks = async (): Promise<void> => {

      // First we get the environment information from the calling SDK.
      const environmentInfo = await checkEnvironmentSupport(callClient);

      if (!environmentInfo.isSupportedPlatform) {
        setCurrentCheckState('operatingSystemUnsupported');
        // If the platform or operating system is not supported we stop here and display a modal to the user.
        return;
      } else if (!environmentInfo.isSupportedBrowser) {
        setCurrentCheckState('browserUnsupported');
        // If browser support fails, we stop here and display a modal to the user.
        return;
      } else if (!environmentInfo.isSupportedBrowserVersion) {
        setCurrentCheckState('browserVersionUnsupported');
        /**
         *  If the browser version is unsupported, we stop here and show a modal that can allow the user 
         *  to continue into the call.
         */
        return;
      } else {
        props.onTestsSuccessful();
      }
    };

    runEnvironmentChecks();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  return (
    <>
      {/* We show this when the operating system is unsupported */}
      <OperatingSystemUnsupportedPrompt isOpen={currentCheckState === 'operatingSystemUnsupported'} />

      {/* We show this when the browser is unsupported */}
      <BrowserUnsupportedPrompt isOpen={currentCheckState === 'browserUnsupported'} />

      {/* We show this when the browser version is unsupported */}
      <BrowserVersionUnsupportedPrompt isOpen={currentCheckState === 'browserVersionUnsupported'} onContinueAnyway={props.onTestsSuccessful} />
    </>
  );
}

Em seguida, podemos adicionar o EnvironmentChecksComponent ao App.tsx. Em seguida, o aplicativo conduz o usuário para a fase Verificações de dispositivo depois que o teste é bem-sucedido usando o retorno de chamada onTestsSuccessful:

Agora importamos o novo componente para nosso aplicativo em App.tsx

import { EnvironmentChecksComponent } from './EnvironmentChecksComponent';

Em seguida, vamos atualizar o componente App em App.tsx:

const App = (): JSX.Element => {
  const [testState, setTestState] = useState<TestingState>('runningEnvironmentChecks');

  return (
    <FluentThemeProvider>
      <CallClientProvider callClient={callClient}>
        {/* Show a Preparing your session screen while running the call readiness checks */}
        {testState === 'runningEnvironmentChecks' && (
          <>
            <PreparingYourSession />
            <EnvironmentChecksComponent
              onTestsSuccessful={() => setTestState('finished')}
            />
          </>
        )}

        {/* After the device setup is complete, take the user to the call. For this sample we show a test complete page. */}
        {testState === 'finished' && <TestComplete />}
      </CallClientProvider>
    </FluentThemeProvider>
  );
}

Agora você pode executar o aplicativo. Tente executar em um navegador sem suporte e você verá o prompt do navegador sem suporte:

Gif mostrando falha na verificação do navegador

Próximas etapas

Parte 2: Solicitar acesso à câmera e ao microfone

Compartilhar via