Developer

Customize the Communications Frontend

Last edit: 2023.07.27

As TomTom Digital Cockpit provides a way to create a custom connection service (see Create a Custom Connection Service for details), it also has tools to customize its visual representation.

The customization is possible through the use of policies. Currently, there is one communications policy -- CallDetailsPolicy. This policy maps the active Call and the calling Contact into a CallDetails. This class contains the necessary information for the Stock Communications frontend implementation to display the call, such as the call title, call image, etc. See the API reference for more information.

How to create a custom communications frontend

The following sections describe how to create and implement a custom communications frontend.

Example code illustrating how to implement the concepts described in this document can be found in examples/telephony/custompolicies.

Frontend extension module setup

Add dependencies to the CallDetailsPolicy and CommunicationsPolicyFrontendExtension in your build.gradle.kts:

1dependencies {
2    implementation(libraries.iviAppsuiteCommunicationsApiCommonFrontend)
3    implementation(libraries.iviPlatformFrontendApiCommonUicontrols)
4}

The dependency on the UI Controls library is necessary for the CallDetailsPolicy implementation.

Configure the application and Communications frontend within it:

1ivi {
2    optInToExperimentalApis = true
3

4    application {
5        enabled = true
6        iviInstances {
7            create(IviInstanceIdentifier.default) {
8                applyGroups {
9                    includeDefaultPlatformGroups()
10                    includeDefaultAppsuiteGroups()
11                }
12                frontends {
13                    configure(communicationsFrontend)
14                }
15            }
16        }
17    }
18}

Implement a custom policy

CallDetailsPolicy helps developers configure the visual representation of a calling process by providing the Communications frontend with specific details about the call.

Let's customize the way the frontend should display the call. For this example we set the phone number as the call title, the call creation time as its state, and the contact's company name (if available) as its description. We also set a static image, disable DTMF support, and allow opening the Communications Frontend from the process panel only when the contact is a favorite:

1import com.tomtom.ivi.appsuite.communications.api.common.frontend.CallDetails
2import com.tomtom.ivi.appsuite.communications.api.common.frontend.CallDetailsPolicy
3import com.tomtom.ivi.platform.contacts.api.common.model.Contact
4import com.tomtom.ivi.platform.telecom.api.common.model.Call
5import com.tomtom.tools.android.api.resourceresolution.drawable.ResourceDrawableResolver
6import com.tomtom.tools.android.api.resourceresolution.string.StaticStringResolver
7import com.tomtom.tools.android.api.resourceresolution.string.StringResolver
8import com.tomtom.tools.android.api.uicontrols.imageview.ImageDescriptor
9

10internal class ExampleCallDetailsPolicy : CallDetailsPolicy {
11    override fun invoke(call: Call?, contact: Contact?): CallDetails = CallDetails(
12        title = getTitle(call),
13        state = getState(call),
14        description = getDescription(contact),
15        image = getImage(),
16        isDtmfSupported = false,
17        shouldOpenFrontendOnContactTap = contact?.favorite ?: false
18    )
19

20    private fun getTitle(call: Call?): StringResolver =
21        StaticStringResolver(call?.phoneNumber ?: "Example fallback title")
22

23    private fun getState(call: Call?): StringResolver =
24        StaticStringResolver(call?.creationTime ?: "Example fallback state")
25

26    private fun getDescription(contact: Contact?): StringResolver? =
27        contact?.let { StaticStringResolver(contact.companyName) }
28

29    private fun getImage(): ImageDescriptor =
30        ImageDescriptor(ResourceDrawableResolver(R.drawable.ic_example_call_image))
31}

Create frontend extension

To include the custom policy into the application, you can define a CommunicationsPolicyFrontendExtension. This class holds information as to which policy corresponds to which phone account ID (the call type identifier). In this example, we set it to "ExampleID":

1import com.tomtom.ivi.appsuite.communications.api.common.frontend.CommunicationsPolicyFrontendExtension
2import com.tomtom.ivi.platform.frontend.api.common.frontend.FrontendExtension
3

4internal val exampleCommunicationsFrontendExtension: FrontendExtension =
5    CommunicationsPolicyFrontendExtension(
6        phoneAccountId = "ExampleID",
7        callDetailsPolicy = ExampleCallDetailsPolicy()
8    )

All that is left to do is add the extension to the frontend configuration:

1frontends {
2    configure(communicationsFrontend) {
3        addExtension(exampleCommunicationsFrontendExtension)
4    }
5}

The guide on How to create a frontend plugin and the documentation for FrontendExtension are available for more details.

External links