UI Library use cases

Note

For detailed documentation on the UI Library, visit the UI Library Storybook. There you will find additional conceptual documentation, quickstarts and examples.

UI Library supports many cases across calling and chat experiences. These capabilities are available through UI Components and Composites. For Composites, these capabilities are built directly in and exposed when the composite is integrated into an application. For UI Components, these capabilities are exposed through a combination of UI functionality and underlying stateful libraries. To take full advantage of these capabilities, we recommend using the UI Components with the stateful call and chat client libraries.

Calling use cases

Area Use Cases
Call Types Join Teams Meeting
Join Azure Communication Services call with Group ID
Teams Interop Call Lobby
Transcription and recording alert banner
Call Controls Mute/unmute call
Video on/off on call
Screen Sharing
End call
Participant Gallery Remote participants are displayed on grid
Video preview available throughout call for local user
Default avatars available when video is off
Shared screen content displayed on participant gallery
Call configuration Microphone device management
Camera device management
Speaker device management
Local preview available for user to check video
Participants Participant roster

Chat use cases

Area Use Cases
Chat Types Join a Teams Meeting Chat
Join an Azure Communication Services chat thread
Chat Actions Send chat message
Receive chat message
Chat Events Typing Indicators
Read Receipt
Participant added/removed
Chat title changed
Participants Participant roster

Supported identities

An Azure Communication Services identity is required to initialize the stateful client libraries and authenticate to the service. For more information on authentication, see Authentication and Access Tokens

Teams Interop Use Case

For Teams Interop scenarios, developers can use UI Library Components to join Teams meetings through Azure Communication Services. To enable Teams Interop, developers can either use calling and chat composites directly or use UI Components to build a custom experience. When enabling applications with both calling and chat, its important to remember that the chat client can't be initialized until the participant has been admitted to the call. Once admitted, the chat client can be initialized to join the meeting chat thread. See the diagram below for guidance:

Teams Interop pattern for calling and chat

When using UI Components to deliver Teams Interop experiences, UI Library provides examples for key pieces of the experience. For example:

  • Lobby Example: Sample lobby for participant to wait to be admitted to the call.
  • Compliance banner: Sample banner to show the user whether the call is being recorded or not.
  • Teams Theme: Sample theme that makes the UI Library looks like Microsoft Teams.

Customization

UI Library exposes patterns for developers to modify components to fit the look and feel of their application. These capabilities are a key area of differentiation between Composites and UI Components, where Composites provide less customization options in favor of a simpler integration experience.

Use Case Composites UI Components
Fluent based Theming X X
Experience layout is composable X
CSS Styling can be used to modify style properties X
Icons can be replaced X
Participant gallery layout can be modified X
Call control layout can be modified X X
Data models can be injected to modify user metadata X X

Observability

As part of the decoupled state management architecture of the UI Library, developers are able to access the stateful calling and chat clients directly.

Developers can hook into the stateful client to read the state, handle events and override behavior to pass onto the UI Components.

Use Case Composites UI Components
Call/Chat client state can be accessed X X
Client events can be accessed and handled X X
UI events can be accessed and handled X X

UI Library recommended client-server architecture

Composite and Base Components are initialized using an Azure Communication Services access token. Access tokens should be procured from Azure Communication Services through a trusted service that you manage. See Quickstart: Create Access Tokens and Trusted Service Tutorial for more information.

These client libraries also require the context for the call or chat they will join. Similar to user access tokens, this context should be disseminated to clients via your own trusted service. The list below summarizes the initialization and resource management functions that you need to operationalize.

Contoso Responsibilities UI Library Responsibilities
Provide access token from Azure Pass through given access token to initialize components
Provide refresh function Refresh access token using developer provided function
Retrieve/Pass join information for call or chat Pass through call and chat information to initialize components
Retrieve/Pass user information for any custom data model Pass through custom data model to components to render

Platform support

SDK Windows macOS Ubuntu Linux Android iOS
UI SDK Chrome*, new Edge Chrome*, Safari** Chrome* Chrome* Chrome* Safari**

*Note that the latest version of Chrome is supported in addition to the previous two releases.

**Note that Safari versions 13.1+ are supported. Outgoing video for Safari macOS is not yet supported, but it is supported on iOS. Outgoing screen sharing is only supported on desktop iOS.

Accessibility

Accessibility by design is a principle across Microsoft products. UI Library follows this principle in making sure that all UI Components are fully accessible.

Localization

Localization is a key to making products that can be used across the world and by people who who speak different languages. UI Library will provide out of the box support for some languages and capabilities such as RTL. Developers can provide their own localization files to be used for the UI Library.

The UI Library for iOS and Android supports calling use cases by using the calling composite.

Composites enable developers to easily integrate a whole calling experience into their application with only a couple of lines of code; those composites take care of the entire lifecycle of the call from setup to the call ending.

Calling

Area Use Cases
Call Types Join Teams Meeting
Join Azure Communication Services call with Group ID
Teams Interop Call Lobby
Transcription and recording alert banner
Participant Gallery Remote participants are displayed on grid
Video preview available throughout call for local user
Default avatars available when video is off
Shared screen content displayed on participant gallery
Participant Avatar Customization
Participant roster
Call configuration Microphone device management
Camera device management
Speaker device management(wired & bluetooth supported)
Local preview available for user to check video
Call Controls Mute/unmute call
Video on/off on call
End call
Hold/Resume Call on Audio Interruption

Supported Identities

An Azure Communication Services identity is required to initialize the composites and authenticate to the service. For more information on authentication, see Authentication and Access Tokens

Teams Interop

Teams Interop pattern for calling and chat

For Teams Interop scenarios, developers can use the UI Library composites to join Teams meetings through Azure Communication Services. To enable Teams Interop, developers can use the calling composite, which will take care of the lifecycle of joining a Teams Interop call.

Pre-meeting experience

View shared content

The UI Library for Mobile native platforms provides the capability of the calling participants to view the shared content when other participants share their screens during the calling. Also, the participant can zoom on the screen, making the pinching gestures over the screen to get a better look over the shared content.

Theming

The UI Library Calling Composite for iOS and Android provides the capability for developers to create a custom theme of the all experience by passing a set of theming colors. How to create your theme.

Android iOS
android theming iOS theming

Screen size

The calling composite offers to adapt to any screen size that would bring support from 5" screens to tablets, get the dynamic participants' roster layout, provide clarity on the view, and focus on the conversation.

Split mode Tablet mode
split screen tablet mode

Localization

Localization is a key to making products that can be used across the world and by people who speak different languages. The UI Library, provides support for 12 languages: English, Spanish, French, German, Italian, Japanese, Korean, Dutch, Portuguese, Russian, Turkish and Chinese and RTL capabilities. How to add localization to your app.

Accessibility

Accessibility is a key focus of the calling libraries. Screen Readers are supported to make important announcements regarding calling status and to help ensure that visibility impaired users can effectively participate in using the application.

Participant View Data Injection

The UI Library for Mobile native platforms gives the developers the ability to modify both Local and Remote Participants and how they are displayed in the call. On call launch the developer can supply a local avatar and custom display name to show to the local user. For Remote Users, methods are available to allow customization of avatars as they join the meetings. How to customize participant views.

Gif animation shows the pre-meeting experience and joining experience on iOS.

Composites are initialized using an Azure Communication Services access token. Access tokens should be procured from Azure Communication Services through a trusted service that you manage. See Quickstart: Create Access Tokens and Trusted Service Tutorial for more information.

Recommended architecture diagram

These client libraries also require the context for the call they'll join. Similar to user access tokens, this context should be disseminated to clients via your own trusted service. The list below summarizes the initialization and resource management functions that you need to operationalize.

Contoso Responsibilities UI Library Responsibilities
Provide access token from Azure Pass through given access token to initialize components
Provide refresh function Refresh access token using developer provided function
Retrieve/Pass join information for call or chat Pass through call and chat information to initialize components
Retrieve/Pass user information for any custom data model Pass through custom data model to components to render

Platform support

Platform Versions
iOS iOS 14+
Android Api 21+