UI Library use cases

Use components and composites in the Azure Communication Services UI Library to create call and chat experiences in your applications.

In a composite, call and chat capabilities are built in directly and exposed when you integrate the composite into an application. In a UI component, call and chat capabilities are exposed through a combination of UI functionality and underlying stateful libraries. To take full advantage of these capabilities, we recommend that you use UI components with stateful call and chat client libraries.

Get more conceptual documentation, quickstarts, and examples in the UI Library storybook.

Call use cases

Area Use cases
Call types Join a Microsoft Teams meeting
Join an Azure Communication Services call by using a group ID
Teams interoperability Join the call lobby
Display a transcription and recording alert banner
Call controls Mute and unmute a call
Turn video on and off during a call
Turn on screen sharing
End a call
Participant gallery Show remote participants on a grid
Make video preview available throughout a call for a local user
Make default avatars available when video is off
Show shared screen content in the participant gallery
Call configuration Manage the microphone device
Manage the camera device
Manage the speaker device
Make local preview available for user to check video
Participants Show a participant roster

Chat use cases

Area Use cases
Chat types Join a Microsoft Teams meeting chat
Join an Azure Communication Services chat thread
Chat actions Send a chat message
Receive a chat message
Chat events Show typing indicators
Show a read receipt
Show when a participant is added or removed
Show changes to the chat title
Participants Show a participant roster

Supported identities

To initialize a composite and authenticate to the service, a user must have an Azure Communication Services identity. For more information, see Authenticate to Azure Communication Services and Quickstart: Create and manage access tokens.

Teams interoperability

For Teams interoperability scenarios, you can use UI Library composites to add a user to a Teams meeting via Communication Services. To enable Teams interoperability, use either the default features in the call composite or the chat composite, or use UI components to build a custom experience.

When you add both calling and chat to an application, it's important to remember that the chat client can't be initialized until the participant is admitted to the call. After the participant is admitted, the chat client can be initialized to join the meeting chat thread. The pattern is demonstrated in the following figure:

Diagram that shows the Teams interoperability pattern for calling and chat.

If you use UI components to deliver Teams interoperability experiences, begin by using UI Library examples to create key pieces of the experience:

  • Lobby example. A sample lobby where a participant can wait to be admitted to a call.
  • Compliance banner. A sample banner that shows the user if the call is being recorded.
  • Teams theme. A sample theme that makes UI Library elements look like Microsoft Teams.

Customization

Use UI Library patterns to modify components to match the look and feel of your application. Customization is a key difference between composites and UI components in Communication Services. Composites have fewer customization options for a simpler integration experience.

The following table compares composites and UI components for customization use cases:

Use case Composites UI components
Use Fluent-based theming X X
Compose the experience layout X
Use CSS styling to modify style properties X
Replace icons X
Modify the participant gallery layout X
Modify the call control layout X X
Inject data models to modify user metadata X X

Observability

The state management architecture of UI Library is decoupled, so you can access stateful call and chat clients directly. You can hook into the stateful client to read the state, handle events, and override behavior to pass onto the UI components.

The following table compares composites and UI components for observability use cases:

Use case Composites UI components
Access call and chat client state X X
Access and handle client events X X
Access and handle UI events X X

Initialize a composite and base components by using an Azure Communication Services access token. It's important to get access tokens from Communication Services through a trusted service that you manage. For more information, see Quickstart: Create and manage access tokens and the trusted service tutorial.

Diagram that shows the recommended UI Library architecture.

Call and chat client libraries must have the context for the call or chat they join. Like user access tokens, disseminate the context to clients by using your own trusted service.

The following table summarizes initialization and resource management functions that are required to add context to a client library:

Contoso responsibilities UI Library responsibilities
Provide an access token from Azure Pass through the provided access token to initialize components
Provide a refresh function Refresh the access token by using a developer-provided function
Retrieve and pass join information for the call or chat Pass through call and chat information to initialize components
Retrieve and pass user information for any custom data model Pass through a custom data model to components to render

Platform support

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

* The current version of Chrome and the two preceding releases are supported.

** Safari version 13.1 and later versions are supported. Outgoing video for Safari macOS isn't yet supported, but it is supported for iOS. Outgoing screen sharing is supported only on desktop iOS.

Accessibility

Accessibility by design is a principle across Microsoft products. UI Library follows this principle, and all UI components are fully accessible.

Localization

Localization is key to making products for users around the world and who speak different languages. UI Library provides default support for some languages and capabilities, including right-to-left languages. You can provide their own localization files to use with UI Library.

Use the call composite in the Azure Communication Services UI Library to create call experiences in your for iOS and Android applications. By using a couple lines of code, you can easily integrate an entire call experience in your application. Composites in Communication Services manage the entire lifecycle of the call, from setup until the call ends.

Call use cases

You can use the call composite in Communication Services to create these use cases:

Area Use cases
Call types Join a Microsoft Teams meeting
Join a call by using a group ID
Teams interoperability Join the call lobby
Display a transcription and recording alert banner
Participant gallery Show remote participants on a grid
Make video preview available throughout a call for a local user
Make default avatars available when video is off
Show shared screen content in the participant gallery
Enable participant avatar customization
Show a participant roster
Call configuration Manage the microphone device
Manage the camera device
Manage the speaker device (wired or Bluetooth)
Make local preview available for a user to check video
Call controls Mute and unmute a call
Turn video on or off during a call
End a call
Hold and resume a call after audio interruption

Supported identities

To initialize a composite and authenticate to the service, a user must have an Azure Communication Services identity. For more information, see Authenticate to Azure Communication Services and Quickstart: Create and manage access tokens.

Teams interoperability

For Teams interoperability scenarios, you can use UI Library composites to add a user to a Teams meeting via Communication Services. To enable Teams interoperability, use the call composite. The composite manages the entire lifecycle of joining a Teams interoperability call.

Diagram that shows the Teams interoperability pattern for call and chat.

The following figure shows an example of the user experience before a caller is added to a Teams meeting:

Screenshot that shows the user experience before a caller is added to a Teams meeting.

View shared content

Through the UI Library for mobile native platforms, call participants can view shared content when other participants share their screens during a Teams call. A remote participant can use stretch and pinch gestures to zoom in or out on the shared content in the call.

Theming

You can use the UI Library call composite for iOS and Android to create a custom theme of a caller's experience. To create the platform experience, pass a set of theming colors as shown in the following table. For more information, see How to create your theme.

Android iOS
Screenshot that shows Android theming for a caller experience. Screenshot that shows iOS theming for a caller experience.

Screen size

You can adapt the Azure Communication Services call composite to adapt to screen sizes from 5 inches to tablet size. Use split mode and tablet mode in the call composite to get the dynamic participants' roster layout, provide clarity on the view, and focus on the conversation.

Split mode Tablet mode
Screenshot that demonstrates a split-screen view. Screenshot that demonstrates tablet mode.

Localization

Localization is key to making products for users around the world and who speak different languages. UI Library supports 12 languages: English, Spanish, French, German, Italian, Japanese, Korean, Dutch, Portuguese, Russian, Turkish, and Chinese. It also supports right-to-left languages. For more information, see How to add localization to your app.

Accessibility

Accessibility is a key focus of the call libraries. You can use a screen reader to make important announcements about call status and to help ensure that visually impaired users can effectively participate when they use the application.

Participant view data injection

Use the UI Library for mobile native platforms to give local and remote participants the option to modify how they appear as users in a call. A local participant can choose a local avatar and custom display name when a call begins. A remote user can create a customized avatar when they join the meeting. For more information, see How to customize participant views.

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

Initialize a composite by using an Azure Communication Services access token. It's important to get access tokens from Azure Communication Services through a trusted service that you manage. For more information, see Quickstart: Create and manage access tokens and the trusted service tutorial.

Diagram that shows the recommended architecture for UI Library.

Call and chat client libraries must have the context for the call they join. Like user access tokens, disseminate the context to clients by using your own trusted service. The following table summarizes the initialization and resource management functions that are required to add context to a client library:

Contoso responsibilities UI Library responsibilities
Provide an access token from Azure Pass through the provided access token to initialize components
Provide a refresh function Refresh the access token by using a developer-provided function
Retrieve and pass join information for the call or chat Pass through call and chat information to initialize components
Retrieve and pass user information for any custom data model Pass through a custom data model to components to render

Platform support

Platform Versions
iOS iOS 14 and later
Android API 21 and later