使用 Azure 通訊服務建立通話整備體驗

發行項
04/28/2024

重要

此 Azure 通訊服務功能目前處於預覽狀態。

提供的預覽 API 和 SDK 並無服務等級協定。建議您不要將其用於生產工作負載。部分功能可能不受支援，或是在功能上有所限制。

如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用規定。

在本教學課程中，我們會使用 Azure 通訊服務搭配 UI 連結庫，以建立可讓使用者準備好加入通話的體驗。 UI 連結庫提供一組豐富的元件和 UI 控制項，可用來產生通話整備體驗，以及一組豐富的 API 來了解使用者狀態。

必要條件

遵循本教學課程前一部分中的應用程式設定程式: 通話整備 - 概觀

下載程式碼

在 GitHub 上存取本教學課程的完整程式碼。

檢查瀏覽器支援

為了確保使用者獲得最佳體驗，我們想要先確定他們在受支援的瀏覽器中。在本節中，我們會建立一個頁面，以顯示「準備您的工作階段」，同時我們在使用者瀏覽器的背景中執行快速支援檢查。

Gif showing browser check being performed

準備您的工作階段頁面

建立名為 PreparingYourSession.tsx 的新檔案，並在背景中執行異步檢查時，建立要向使用者顯示的微調程式:

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

然後，我們可以將此 [準備您的工作階段] 畫面連結至我們的應用程式。在 App.tsx 和變數 testState 中追蹤應用程式的狀態，而 testState 處於 runningEnvironmentChecks 狀態，我們會顯示準備您的工作階段畫面。

首先，將下列匯入新增至我們在概觀中建立的 App.tsx 檔案:

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

完成後，請更新我們的 App.tsx 檔案，以包含新的微調程式。

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

執行環境資訊檢查

首先建立公用程式檔案呼叫 environmentSupportUtils.ts。在此呼叫中，我們會新增方法 checkEnvironmentSupport。這個方法會使用呼叫具狀態用戶端來執行呼叫具狀態用戶端執行環境資訊的要求。

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;
}

從 checkEnvironmentSupport 傳回的資料包含下列資訊:

瀏覽器支援
瀏覽器版本支援
作業系統 (平台) 支援
詳細的環境資訊

通知使用者他們在不受支援的瀏覽器中

接下來，我們需要使用呼叫 SDK 所提供的這項資訊，以通知使用者是否有問題時的環境狀態。 UI 連結庫提供三個不同的元件，以根據問題是什麼來提供此用途。

UnsupportedOperatingSystem
UnsupportedBrowser
UnsupportedBrowserVersion

首先，我們會在 FluentUI Modal 內裝載 UI 連結庫的元件: 建立名為 UnsupportedEnvironmentPrompts.tsx 的新檔案，在其中建立不同的提示:

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 troublshooting.
 * 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 troublshooting.
 */
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 troublshooting.
 */
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>
);

然後，我們可以在環境檢查元件中顯示這些提示。建立名為 EnvironmentChecksComponent.tsx 的檔案，其中包含顯示此提示的邏輯: 此元件具有回呼 onTestsSuccessful，可將使用者帶到應用程式中的下一頁。

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} />
    </>
  );
}

然後，我們可以將 EnvironmentChecksComponent 新增至 App.tsx。然後，應用程式會在測試成功后，使用 onTestsSuccessful 回呼，將使用者移至 裝置檢查 階段:

現在，我們會在 App.tsx 中將新的元件匯入應用程式

import { EnvironmentChecksComponent } from './EnvironmentChecksComponent';

接著，讓我們更新 App.tsx 中的 App 元件:

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

您現在可以執行應用程式。請嘗試在不受支援的瀏覽器上執行，您會看到不支援的瀏覽器提示:

Gif showing browser check failing

下一步

第 2 部分: 要求相機和麥克風存取

共用方式為