Edit

Custom Data Model Injection

  • Article

Azure Communication Services uses an identity agnostic model where developers can bring their own identities. Contoso can get their data model and link it to Azure Communication Services identities. A developer's data model for a user most likely includes information such as their display name, profile picture or avatar, and other details. Information is used by developers to power their applications and platforms.

The UI Library makes it simple for developers to inject that user data model into the UI Components. When rendered, they show users provided information rather than generic information that Azure Communication Services has.

Prerequisites

Note

For detailed documentation and quickstarts about the Web UI Library visit the Web UI Library Storybook.

Azure Communication UI open source library for Android and the sample application code can be found here

Local Participant View Customization

The UI Library gives developers the ability to provide a more customized experience regarding Participant information. At launch, developers can optionally inject local participant data. This local data isn't shared with the server and can be used to customize the display name and avatar of the local user.

Local Options

CallCompositeLocalOptions is the data model that can have CallCompositeParticipantViewData and CallCompositeSetupScreenViewData. It represents the local participant. By default, for remote participants, the UI library displays the displayName injected in RemoteOptions that is sent to Azure Communication Service backend server. If CallCompositeParticipantViewData is injected, the participant displayName and avatar are displayed in all avatar components locally.

Similarly, for CallCompositeSetupScreenViewData, the title and subtitle in CallCompositeSetupScreenViewData overwrites the navigation bar's title and subtitle in premeeting screen respectively. By default, the UI library displays 'Setup' as the title and nothing as the subtitle.

Local Participant View Data

CallCompositeParticipantViewData is a class that set the displayName, avatarBitmap and scaleType for avatar control. This class is passed to the CallCompositeLocalOptions in order to customize the local participants view information.

This class is held in the CallCompositeLocalOptions object that represents options used locally on the device making the call.

displayName differs from the displayName passed in via the CallCompositeRemoteOptions. CallCompositeParticipantViewData displayName is only used locally as an override, where CallCompositeRemoteOptions displayName is passed to the server and shared with other participants. When CallCompositeParticipantViewData displayName isn't provided, CallCompositeRemoteOptions displayName is used.

Setup Screen View Data

CallCompositeSetupScreenViewData is an object that sets the title and subtitle for the navigationBar on call setup screen. If subtitle isn't defined, then subtitle is hidden. Here title is a required to set the subtitle but subtitle is optional when title is set. This class is locally stored and its information aren't sent up to the server.

Usage

To use the CallCompositeLocalOptions, pass the instance of CallCompositeParticipantViewData and/or CallCompositeSetupScreenViewData and inject CallCompositeLocalOptions to callComposite.launch.

val participantViewData: CallCompositeParticipantViewData = CallCompositeParticipantViewData()
    .setAvatarBitmap((Bitmap) avatarBitmap)
    .setScaleType((ImageView.ScaleType) scaleType)
    .setDisplayName((String) displayName)

val setupScreenViewData: CallCompositeSetupScreenViewData = CallCompositeSetupScreenViewData()
    .setTitle((String) title)
    .setSubtitle((String) subTitle)

val localOptions: CallCompositeLocalOptions = CallCompositeLocalOptions()
    .setParticipantViewData(participantViewData)
    .setSetupScreenViewData(setupScreenViewData)

callComposite.launch(callLauncherActivity, remoteOptions, localOptions)
Setup View Calling Experience View
Screenshot of an Android data custom model injection. Screenshot of an Android data custom model injection with name.

Remote Participant View Customization

In some instances, you may wish to provide local overrides for remote participants to allow custom avatars and titles.

The process is similar to the local participant process, however the data is set when participants join the call. As a developer you would need to add a listener to when remote participants join the call, and then call a method to set the CallCompositeParticipantViewData for that remote user.

Usage

To set the participant view data for remote participant, set setOnRemoteParticipantJoinedHandler. On remote participant join, use callComposite setRemoteParticipantViewData to inject view data for remote participant. The participant identifier CommunicationIdentifier is to uniquely identify a remote participant.

Calls to setRemoteParticipantViewData return a result of CallCompositeSetParticipantViewDataResult, which has the following values.

  • CallCompositeSetParticipantViewDataResult.SUCCESS
  • CallCompositeSetParticipantViewDataResult.PARTICIPANT_NOT_IN_CALL
callComposite.addOnRemoteParticipantJoinedEventHandler { remoteParticipantJoinedEvent -> 
                remoteParticipantJoinedEvent.identifiers.forEach { identifier ->
                    // get displayName, bitmap for identifier
                    callComposite.setRemoteParticipantViewData(identifier,
                        CallCompositeParticipantViewData().setDisplayName("displayName")) // setAvatarBitmap for bitmap
                }
            }
Participants list
Screenshot of the Android remote participants view data injection.

Azure Communication UI open source library for iOS and the sample application code can be found here

Local Participant View Data Injection

The UI Library now gives developers the ability to provide a more customized experience. At launch, developers can now inject an optional Local Data Options. This object can contain a UIimage that represents the avatar to render, and a display name they can optionally display instead. None of this information is sent to Azure Communication Services and is held locally in the UI library.

Local Options

LocalOptions is data model that consists of ParticipantViewData and SetupScreenViewData. By default for ParticipantViewData, the UI library displays the displayName injected in RemoteOptions that is sent to Azure Communication Service backend server. If ParticipantViewData is injected, the participant displayName and avatar are displayed in all avatar components.

Similarly, for 'SetupScreenViewData', by default, the UI library displays 'Setup' as the title and nothing as subtitle. The title and subtitle in 'SetupScreenViewData' overwrites the navigation bar's title and subtitle in premeeting screen respectively.

Local Participant View Data

ParticipantViewData is an object that sets the displayName and avatar UIImage for avatar components. This class is injected into the UI Library to set avatar information. It's stored locally and never sent up to the server.

Setup Screen View Data

SetupScreenViewData is an object that sets the title and subtitle for the navigationBar on premeeting screen (also known as Setup View). If SetupScreenViewData is defined, then 'title' must be provided as it's a required field. 'subtitle', however, isn't required. If subtitle isn't defined, then it's hidden. This class is locally stored and its information isn't sent up to the server.

Usage

// LocalOptions (data not sent to server)
let localParticipantViewData = ParticipantViewData(avatar: <Some UIImage>,
                                                   displayName: "<DISPLAY_NAME>")
let localSetupScreenViewData = SetupScreenViewData(title: "<NAV_TITLE>",
                                                               subtitle: "<NAV_SUBTITLE>")
let localOptions = LocalOptions(participantViewData: localParticipantViewData, 
                                setupScreenViewData: localSetupScreenViewData)
// RemoteOptions (data sent to server)
let remoteOptions = RemoteOptions(for: .groupCall(groupId: UUID()),
                                  credential: <Some CommunicationTokenCredential>,
                                  displayName: "<DISPLAY_NAME>")
// Launch
callComposite.launch(remoteOptions: remoteOptions, localOptions: localOptions)
Setup View Calling Experience View
Screenshot of the iOS data custom model injection. Screenshot of the iOS data custom model injection with name.

Remote Participant View Data Injection

On remote participant join, developers can inject the participant view data for remote participant. This participant view data can contain a UIImage that represents the avatar to render, and a display name they can optionally display instead. None of this information is sent to Azure Communication Services and is held locally in the UI library.

Usage

To set the participant view data for remote participant, set onRemoteParticipantJoined completion for events handler. On remote participant join, use CallComposite set(remoteParticipantViewData:, for:, completionHandler:) to inject view data for remote participant. The participant identifier CommunicationIdentifier is used to uniquely identify a remote participant. The optional completion handler is used for returning result of the set operation.

callComposite.events.onRemoteParticipantJoined = { [weak callComposite] identifiers in
  for identifier in identifiers {
    // map identifier to displayName
    let participantViewData = ParticipantViewData(displayName: "<DISPLAY_NAME>")
    callComposite?.set(remoteParticipantViewData: participantViewData,
                       for: identifier) { result in
      switch result {
      case .success:
        print("Set participant view data succeeded")
      case .failure(let error):
        print("Set participant view data failed with \(error)")
      }
    }
  }
}
Participants list
Screenshot of the iOS remote participants view data injection.

Next steps