Skip to content

Commit 9476e54

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #220750 from JamesBurnside/call-readiness-tutorial
Call readiness tutorial
2 parents dca34a9 + d5bc39d commit 9476e54

12 files changed

+1327
-0
lines changed

‎articles/communication-services/toc.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,16 @@ items:
148148
href: quickstarts/telemetry-application-insights.md
149149
- name: Add file sharing to your application with UI Library
150150
href: tutorials/file-sharing-tutorial.md
151+
- name: Get users ready for their call with UI Library
152+
items:
153+
- name: Call Readiness Overview
154+
href: tutorials/call-readiness/call-readiness-overview.md
155+
- name: 1. Ensure user is on a supported browser
156+
href: tutorials/call-readiness/call-readiness-tutorial-part-1-browser-support.md
157+
- name: 2. Request camera and microphone permissions
158+
href: tutorials/call-readiness/call-readiness-tutorial-part-2-requesting-device-access.md
159+
- name: 3. Microphone and camera setup before a call
160+
href: tutorials/call-readiness/call-readiness-tutorial-part-3-camera-microphone-setup.md
151161
- name: Enable Push Notifications in your chat app
152162
href: tutorials/add-chat-push-notifications.md
153163
- name: Concepts

‎articles/communication-services/tutorials/call-readiness/call-readiness-overview.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Creating a Call Readiness Experience using Azure Communication Services UI Library
3+
titleSuffix: An Azure Communication Services tutorial
4+
description: Learn how to use Azure Communication Services with the UI Library to create an experience that gets users ready to join a call.
5+
author: jamesburnside
6+
manager: alkwa
7+
services: azure-communication-services
8+
9+
ms.author: jaburnsi
10+
ms.date: 11/17/2022
11+
ms.topic: tutorial
12+
ms.service: azure-communication-services
13+
ms.subservice: calling
14+
---
15+
# Getting started with Call Readiness and the UI Library
16+
17+
[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
18+
19+
![Flow of a user joining a call from an email link](../media/call-readiness/joining-call-from-email-link.png)
20+
21+
When a user intends to join a web call, their primary focus is on the conversation they want to have with the other person(s) on the call – this persona could be a doctor, teacher, financial advisor, or friend. The conversation itself may pose enough stress, let alone navigating the process of making sure they and their device(s) are ready to be seen and/or heard. It's critical to ensure the device and client they're using is ready for the call
22+
23+
It may be impossible to predict every issue or combination of issues that may arise, but by applying this tutorial you can:
24+
25+
- Reduce the likelihood of issues affecting a user during a call
26+
- Only expose an issue if it's going to negatively impact the experience
27+
- Avoid making a user hunt for a resolution; Offer guided help to resolve the issue
28+
29+
Related to this tutorial is the Azure Communication Services [Network Testing Diagnostic Tool](../../concepts/developer-tools/network-diagnostic.md). Users can use the Network Testing Diagnostics Tool for further troubleshooting in customer support scenarios.
30+
31+
## Tutorial Structure
32+
33+
In this tutorial, we use the Azure Communication Services UI Library to create an experience that gets the user ready to join a call. This tutorial is structured into three parts:
34+
35+
- Part 1: [Getting your user onto a supported browser](./call-readiness-tutorial-part-1-browser-support.md)
36+
- Part 2: [Ensuring your App has access to the microphone and camera](./call-readiness-tutorial-part-2-requesting-device-access.md)
37+
- Part 3: [Having your user select their desired microphone and camera](./call-readiness-tutorial-part-3-camera-microphone-setup.md)
38+
39+
## Prerequisites
40+
41+
- [Visual Studio Code](https://code.visualstudio.com/) on one of the [supported platforms](https://code.visualstudio.com/docs/supporting/requirements#_platforms).
42+
- [Node.js](https://nodejs.org/), Active LTS and Maintenance LTS versions (10.14.1 recommended). Use the `node --version` command to check your version.
43+
44+
## Download code
45+
46+
Access the full code for this tutorial on [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/ui-library-call-readiness).
47+
48+
## App Structure
49+
50+
Users have several hurdles to cross when joining a call from browser support to selecting the correct camera. This tutorial uses [React](https://reactjs.org/) with Azure Communication Services [UI Library](https://aka.ms/acsstorybook) to create an app that performs call readiness checks. These checks guide the user through browser support, camera and microphone permissions and finally device setup.
51+
52+
The user flow of the App is as follows:
53+
54+
![flow diagram showing user flow through the call readiness sample](../media/call-readiness/call-readiness-flow-diagram.png)
55+
<!--
56+
This is the mermaid definition for the above graph. Use this to edit and regenerate the graph.
57+
Note: Arrows have been split with a / to prevent this comment block from breaking.
58+
```mermaid
59+
flowchart TD
60+
Start -.-> BrowserCheck{Is Environment supported}
61+
subgraph S1[Part 1: Check Browser Support]
62+
BrowserCheck -/-> |supported| C1[Continue]
63+
BrowserCheck -/-> |operating system unsupported|BrowserUnsupportedPrompt[Show 'Browser Unsupported' Prompt]
64+
BrowserCheck -/-> |browser unsupported|BrowserUnsupportedPrompt[Show 'Browser Unsupported' Prompt]
65+
BrowserCheck -/-> |browser version unsupported|BrowserUnsupportedPrompt[Show 'Browser Unsupported' Prompt]
66+
end
67+
subgraph S2[Part 2: Get Device Permissions]
68+
C1 -.-> DeviceCheckStart{Check Device Permission State}
69+
DeviceCheckStart -/-> |Device Permissions Unknown|DeviceCheckerGeneric[Show 'Checking for device permissions' Prompt]
70+
DeviceCheckerGeneric -/->|Permissions updated| DeviceCheckStart
71+
DeviceCheckStart -/-> |User needs prompted|DeviceCheckerPrompt[Show 'Please Accept Permissions' Prompt]
72+
DeviceCheckerPrompt -/->|Permissions updated| DeviceCheckStart
73+
DeviceCheckStart -/-> |Permissions Denied|DeviceCheckerDenied[Show 'Permissions Denied' Prompt]
74+
DeviceCheckStart --/-> |Permissions Accepted|C2[Continue]
75+
end
76+
subgraph Part 3: Device Setup
77+
C2 -.-> DeviceSetup[Camera and Microphone Setup]
78+
DeviceSetup -/-> |User updates Audio and Video| DeviceSetup
79+
end
80+
DeviceSetup -.-> TestComplete[Call Readiness complete. User is ready to join their Call]
81+
```
82+
-->
83+
84+
Your final app prompts the user onto a supported browser and access for the camera and microphone, then let the user choose and preview their microphone and camera settings before joining the call:
85+
86+
![Gif showing the end to end experience of the call readiness checks and device setup](../media/call-readiness/call-readiness-user-flow.gif)
87+
88+
## Set up the Project
89+
90+
To set up the [React](https://reactjs.org/) App, we use the create-react-app template for this quickstart. This `create-react-app` command creates an easy to run TypeScript App powered by React. The command installs the Azure Communication Services npm packages, and the [FluentUI](https://developer.microsoft.com/fluentui/) npm package for creating advanced UI. For more information on create-react-app, see: [Get Started with React](https://reactjs.org/docs/create-a-new-react-app.html).
91+
92+
```bash
93+
# Create an Azure Communication Services App powered by React.
94+
npx create-react-app ui-library-call-readiness-app --template communication-react
95+
96+
# Change to the directory of the newly created App.
97+
cd ui-library-call-readiness-app
98+
```
99+
100+
At the end of this process, you should have a full application inside of the folder `ui-library-call-readiness-app`.
101+
For this quickstart, we modify the files inside of the `src` folder.
102+
103+
### Install Packages
104+
105+
As this feature is in public preview, you must use the beta versions of the Azure Communication Services npm packages. Use the `npm install` command to install these packages:
106+
107+
```bash
108+
# Install Public Preview versions of the Azure Communication Services Libraries.
109+
npm install @azure/[email protected] @azure/[email protected]
110+
```
111+
112+
> [!NOTE]
113+
> If you are installing the communication packages into an existing App, `@azure/communication-react` currently does not support React v18. To downgrade to React v17 or less follow [these instructions](https://azure.github.io/communication-ui-library/?path=/docs/setup-communication-react--page).
114+
115+
### Initial App Setup
116+
117+
To get us started, we replace the create-react-app default `App.tsx` content with a basic setup that:
118+
119+
- Registers the necessary icons we use in this tutorial
120+
- Sets a theme provider that can be used to set a custom theme
121+
- Create a [`StatefulCallClient`](https://azure.github.io/communication-ui-library/?path=/docs/statefulclient-overview--page) with a provider that gives child components access to the call client
122+
123+
`src/App.tsx`
124+
125+
```ts
126+
import { CallClientProvider, createStatefulCallClient, FluentThemeProvider, useTheme } from '@azure/communication-react';
127+
import { initializeIcons, registerIcons, Stack, Text } from '@fluentui/react';
128+
import { DEFAULT_COMPONENT_ICONS } from '@azure/communication-react';
129+
import { CheckmarkCircle48Filled } from '@fluentui/react-icons';
130+
131+
// Initializing and registering icons should only be done once per app.
132+
initializeIcons();
133+
registerIcons({ icons: DEFAULT_COMPONENT_ICONS });
134+
135+
const USER_ID = 'user1'; // In your production app replace this with an Azure Communication Services User ID
136+
const callClient = createStatefulCallClient({ userId: { communicationUserId: USER_ID } });
137+
138+
/**
139+
* Entry point of a React app.
140+
*/
141+
const App = (): JSX.Element => {
142+
return (
143+
<FluentThemeProvider>
144+
<CallClientProvider callClient={callClient}>
145+
<TestComplete />
146+
</CallClientProvider>
147+
</FluentThemeProvider>
148+
);
149+
}
150+
151+
export default App;
152+
153+
/**
154+
* Final page to highlight the call readiness checks have completed.
155+
* Replace this with your own App's next stage.
156+
*/
157+
export const TestComplete = (): JSX.Element => {
158+
const theme = useTheme();
159+
return (
160+
<Stack verticalFill verticalAlign="center" horizontalAlign="center" tokens={{ childrenGap: "1rem" }}>
161+
<CheckmarkCircle48Filled primaryFill={theme.palette.green} />
162+
<Text variant="xLarge">Call Readiness Complete</Text>
163+
<Text variant="medium">From here you can have the user join their call using their chosen settings.</Text>
164+
</Stack>
165+
);
166+
};
167+
```
168+
169+
### Run Create React App
170+
171+
Let's test our setup by running:
172+
173+
```bash
174+
# Run the React App
175+
npm start
176+
```
177+
178+
Once the App is running visit `http://localhost:3000` in your browser to see your running App.
179+
You should see a green checkmark with a `Test Complete` message.
180+
181+
## Next steps
182+
183+
> [!div class="nextstepaction"]
184+
> [Part 1: Browser Support](./call-readiness-tutorial-part-1-browser-support.md)

0 commit comments

Comments
 (0)