Custom Data Model Injection

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 add Participant View 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 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.

Usage

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

val viewData = CallCompositeParticipantViewData().setDisplayName("displayName") // setAvatarBitmap for bitmap
val localOptions = CallCompositeLocalOptions(viewData)
callComposite.launch(this, 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 showing the Android data custom model remote 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 will be sent to Azure Communication Services and will be only held locally in the UI library.

Local Options

LocalOptions is data model that can have ParticipantViewData that will represent the local participant. By default, the UI library will display the displayName injected in RemoteOptions that is sent to Azure Communication Service backend server. If ParticipantViewData is injected, the participant displayName and avatar will be displayed in all avatar components.

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, and it will always be locally stored and never sent up to the server.

Usage

// LocalOptions (data not sent to server)
let localParticipantViewData = ParticipantViewData(avatar: <Some UIImage>,
                                                   displayName: "<DISPLAY_NAME>")
let localOptions = LocalOptions(participantViewData: localParticipantViewData)

// 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 will be sent to Azure Communication Services and will be only 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 = { 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