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.

Important

This feature of Azure Communication Services is currently in public preview. Preview APIs and SDKs are provided without a service-level agreement, and are not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Mobile 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 roster
Call configuration Microphone device management
Camera device management
Speaker device management
Local preview available for user to check video
Call Controls Mute/unmute call
Video on/off on call
End call

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 Mobile UI Library Components 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

Theming

The UI Library Calling Composite for iOS and Android provides the capability for developers to update the theme of the all experience by passing a primary color. The Composite uses that primary color to provide appropriate theming across the experience.

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

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

Platform Versions
iOS iOS 13+
Android v23+