Customizing user information - KaleyraVideo/VideoiOSSDK GitHub Wiki
This guide will discuss how you can customize the appeareance of the Kaleyra Video Call and Chat user interface changing the user information shown to the end user while taking a call or messaging through the Kaleyra Video 4.0 version. If you are looking at the guide for 3.x versions please take a look at this guide instead.
Table of contents
Overview
Kaleyra Video SDKs are designed to work with the bare minimum information about a user, this means that user contact information like her name, avatar image and so on, are not available in the SDK. We refer to a user in the Kaleyra Video platform through hers/his "userId", which is an alphanumeric string unique within a company (you can think of it as a slug). This approach has the advantage that we don't store any user information on our back-end, but it has one drawback, whenever the end user has to be presented with information about another user, the only information when can show her/him is an "userId".
As you can see from the image above, when the call user interface is presented to the user, the Kaleyra Video will show the user id of the user by default, because it doesn't have any other information to show about the user being called. In order for the SDK to show some other user information it must be given those information and it must be told how to present them.
Server side integration
Since every client has to provide their implementation of an UserDetailsProvider, we released a convenient and centralized way to achieve the same result implementing this functionality only once in your back-end system. This feature relays on Webhooks called by our back-end system when the display information of an user is needed by the SDK.
In order to enable this feature you must specify a valid user_details_provider_url through the company update rest API. More details can be found here.
Client side integration
The Kaleyra Video provides a protocol named UserDetailsProvider which serve the purpose of "retrieving" the user information to be displayed when the call or the chat user interface is displayed to the end-user. In order for the Kaleyra Video to use it, you must conform one of your class to the UserDetailsProvider protocol and provide an instance of that class to the Kaleyra Video SDK before initializing it or to the call (or chat) view controller configuration object before presenting it. The following snippet of code shows how the UserDetailsProvider protocol can be implemented:
import Foundation
import CallKit
import KaleyraVideoSDK
final class Provider: UserDetailsProvider {
private let addressBook: AddressBook
init(_ addressBook: AddressBook) {
self.addressBook = addressBook
}
func provideDetails(_ userIds: [String], completion: @escaping (Result<[UserDetails], Error>) -> Void) {
completion(.success(userIds.map {
let contact = addressBook.findContact(userID: $0)
return .init(userId: $0, name: contact?.fullName, image: contact?.profileImageURL, handle: contact?.fullName.map { .init(type: .generic, value: $0) })
}))
}
}
In the above snippet of code, we are pretending there's a class in our app named "AddressBook" which contains "Contact" information for any user. The class Provider conforms to the SDK protocol and creates an array of UserDetails getting the information from the "AddressBook" and then calls the completion block to signal the Kaleyra Video SDK it finished gathering the user information the SDK requested.
In order for the Kaleyra Video SDK to use an instance of the "Provider" class we created, we must provide it to the userDetailsProvider property on the Kaleyra Video singleton instance.
Eventually, the final result looks like this:
CallKit contact handles
As you might have noticed, the UserDetails requires you to provide a CXHandle in its initialiser. An handle is needed by the SDK when CallKit support is enabled and the SDK needs to update the native system UI with user information.
CallKit needs CXHandle objects to identify a contact inside the end-user's address book. When an incoming or outgoing call is going to be processed by CallKit, the Kaleyra Video SDK must provide those CXHandle objects to it.
