Integration flows

The selection of the active VIA is done by ManageAssistActivity in CarSettings. This flow is triggered by the PackageInstaller app, as part of the Default apps section of the Settings screen.

Figure 1. Default apps on the Settings screen

The selected VIA is exposed to the system in two ways:

1. As part of the RolesManager system service
2. By the VoiceInteractionManagerService through the AssistUtils internal API.

A list of candidate VIAs can be obtained using RolesManager with the role name android.app.role.ASSISTANT.

Hotword triggering

Android provides AlwaysOnHotwordDetector as an abstraction on top of the hardware DSP. This provides a convenient way to associate a VoiceInteractionService to a voice model for low energy always-on voice recognition. This is the most common and well known interaction flow, where the user requests to interact with a Voice Application (VA) to initiate a new conversation. Voice sessions started this way are identified with SHOW_SOURCE_ASSIST_GESTURE flag.

Figure 2. Hotword triggering

Legend. System services appear in light blue, VIA components in green.

PTT triggering

This applies to a long or short hardware button press. In AAOS, PTT is handled by CarInputService. In a default implementation, this service handles input events received through the Vehicle HAL, and in the particular case of voice interaction, it applies the following logic to key events:

• Short PTT events (KeyEvent.KEYCODE_VOICE_ASSIST) are directed to VoiceInteractionManagerService to start a new voice session.
• Long PTT events are first handed to projection receivers (for example, Android Auto or CarPlay), then to Bluetooth-connected devices, and finally to the local VIA app.

Sessions started using this flow are identified with SHOW_SOURCE_PUSH_TO_TALK.

Figure 3. PTT triggering

To integrate a hardware voice-control button to AAOS, see Automotive Key Input integration.

Tap-to-Talk triggering (or software button)

Triggering voice interaction from system UI is done using AssistUtil. This is a hidden system API that can only be used by bundled system apps such as the system UI that enables:

• Interacting with VoiceInteractionManagerService to start voice control sessions.
• Determine which is the currently selected VIA.

To dynamically present the selected VIA app, system UI can use RoleManager and follow changes on the role holder for ROLE_ASSISTANT. An example of how to implement TTT triggering can be found in CarSystemUI, AssistantButton.

Figure 4. Tap-to-Talk triggering

Voice assistant Tap-to-Read (TTR)

Figure 5. Notifications

For more information on how to implement this flow, see Handle messaging commands.

Launch VIA from car launcher

As any other app, VIAs can include one or more launcher activities on their manifest. It is up to the app developer and the OEM accepting to pre-installing this app to decide what these activities would do.

Important. In Automotive, all activities, including system activities, are subject to UX restrictions while driving. If the experience you want to enable from a launcher icon must be available while driving, either add it to the allowlist (if you are an OEM) or annotate the activity with distractionOptimized metadata. For more information, see Driver distraction guidelines.

DSP and audio HAL

Be sure to review the updated guidelines regarding concurrent always-on audio recording and audio HAL at Concurrent capture. Access to these APIs may have a significant impact on the performance of hotword detection as explained at Responding to hotwords.

Permissions

Grant system-privileged permissions

Given that privileged permission cannot be granted by the user, if a VIA needs any of them, OEMs must preload their APK in their system images, and grant those permissions explicitly in their builds. See Request permissions.

To do so, add a privilege allowlist dependency to your project:

Android.bp

android_app {
     ...
     required: ["privapp_allowlist_com.example.myvoicecontrol"],
     ...
}

Add the system-privilege allowlist permission file to the yourdata/etc/car folder:

vendor/…/data/etc/car/Android.bp

prebuilt_etc {
    name:privapp_allowlist_com.example.myvoicecontrol",
    sub_dir: "permissions",
    src: "com.example.myvoicecontrol.xml",
    filename_from_src: true,
}

vendor/…/data/etc/car/com.example.myvoicecontrol.xml

<?xml version="1.0" encoding="utf-8"?>
<permissions>
    <privapp-permissions package="com.android.car.voicecontrol">
        <permission name="android.permission.MEDIA_CONTENT_CONTROL"/>
    </privapp-permissions>
</permissions>

Dangerous permissions pre-grants

As indicated in Request permissions, VIA requires user consent to access certain functionalities. Some of these permissions are pregranted to the default VoiceInteractionService (see DefaultPermissionGrantPolicy.java). For more information about permissions for default handlers, see Permissions used only in default handlers. It is also possible to pre-grant permissions using the default-permissions.xml configuration file. For details on restrictions regarding pre-granting of permissions, see Section 9 in the Android Compatibility Definition Document (CDD).

Important. In all cases, only the default VIA would have these permissions pre-granted. If the system has more than one VIA preloaded, the non-default VIA must explicitly request permissions to the user as part of its setup or during first use.

Distribution (pre-install and deploy updates)

Pre-installed VIAs must live under /product/priv-apps or /vendor/priv-apps partitions and folders (see more about partitions at Partitions overview and Build product partitions).

In the second case, given that the vendor partition could be updated separately from system, apps hosted here won't be able to access @hide system APIs. Depending on the location of the pre-installed apps, updates could be performed as an OTA (see OTA updates) or through app updates from an app store.

Customization

As mentioned in Automotive-specific concepts, UI/UX consistency and customization are more important in automotive than in any other form factor. For maximum interoperability, the use of the AAOS Car UI library is strongly recommended. This library includes components and resources that can be integrated into automotive apps designed to be customized by OEMs. This way, a single APK can be built in a way such that its UI can be customized to the design of each car model.