Car User Experience Restrictions

Before you continue, review Driving Distraction Guidelines.

This page describes the Car User Experience (UX) Restrictions rules you can use to create multiple UX Restrictions rule configurations (for example, European Union versus Japan) and then determine which set of rules to apply at run time. For more information, see CarUxRestrictions.

The Car UX Restrictions service enables developers to define a new Car UX Restrictions configuration. Should a developer want to modify the restriction rules (such as to comply with local safety standards), the developer can use the API to define the new configuration.

The API to set the configuration persists in the new configuration only. In other words, the configuration does not take effect immediately. Instead, the new configuration is loaded when the UX Restrictions service restarts and the car is in Park. The car service ensures the car is in Park before reloading the new configuration.

In addition to the new UX Restrictions service method, APIs are provided to construct the configuration. The state of gear selection and speed is converted to one of three drivingstates:

• Parked. Gear in Park.
• Idling. Gear not in Park and speed is zero.
• Moving. Gear not in Park and speed isn't zero.

To learn how apps consume a car's driving state and the corresponding UX restrictions, see Consuming Car Driving State and UX Restrictions.

Restriction configuration based on drive states

To prevent driver distraction, Android maps the driving state to a set of UX Restriction /packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java

• Parked. Unrestricted.
• Idling. No video and no configuration screen.
• Moving. Fully restricted (all restrictions are required).

The mapping illustrated above is pre-determined and configured as an XML resource. The /packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java then saves the rules in memory. The service then maps the current driving state to UX Restrictions and broadcasts the current restrictions to the entire system.

<!-- No restrictions when car is parked -->
<DrivingState car:state="parked">
    <Restrictions car:requiresDistractionOptimization="false"
                  car:uxr="baseline"/>
</DrivingState>

<!-- Restrictions when car is idling -->
<DrivingState car:state="idling">
    <Restrictions car:requiresDistractionOptimization="true"
                  car:uxr="no_video|no_config"/>
</DrivingState>

<!-- Restrictions for speed >= 0 m/s -->
<DrivingState car:state="moving" car:minSpeed="0.0">
    <Restrictions car:requiresDistractionOptimization="true"
                  car:uxr="fully_restricted"/>
</DrivingState>

Configurations for multiple displays

By default, no restrictions are applied to additional displays. To create restriction configurations for multiple displays, include the RestrictionMapping tag with the physicalPort for that display. The appropriate restrictions are automatically applied to each display. In the following example, the displays with physical Port Ids 1 and 2 have different configurations:

<RestrictionMapping car:physicalPort="1">
       <DrivingState car:state="moving">
           <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_keyboard|no_video"/>
       </DrivingState>
   </RestrictionMapping>

   <RestrictionMapping car:physicalPort="2">
       <DrivingState car:state="moving">
           <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_video"/>
       </DrivingState>
  </RestrictionMapping>

Configurations for restriction modes

You can select any name for the mode, such as teen. In the following example, different restrictions are configured for default and passenger modes (previously, only passenger mode was supported):

<DrivingState car:state="idling">
    <Restrictions car:mode="passenger" car:requiresDistractionOptimization="false" car:uxr="baseline"/>
    <Restrictions car:requiresDistractionOptimization="true" car:uxr="no_video"/>
</DrivingState>
</Restrictions>

You can use the API to set any string name for the mode. For instance, the setRestrictionMode(@NonNull String mode) method in CarUxRestrictionsManager. (Previously, you would use the setRestrictionMode(@CarUxRestrictionsManager.UxRestrictionMode int mode) method in CarUxRestrictionsManager).

CarUxRestrictionsConfiguration APIs

Restrictions with CarUxRestrictionsConfiguration

The new class CarUxRestrictionsConfiguration is mapped 1:1 to the current XML configuration schema. CarUxRestrictionsConfiguration can be constructed with CarUxRestrictions.Builder, which validates the configuration upon build().

new CarUxRestrictionsConfiguration.Builder()
        // Explicitly set restrictions for each driving state.
        .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_PARKED,
                /* requiresOptimization= */ false,
                /* restrictions= */ UX_RESTRICTIONS_BASELINE)
        .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_IDLING,
                true,
                UX_RESTRICTIONS_NO_VIDEO|UX_RESTRICTIONS_NO_SETUP)
        .setUxRestrictions(CarDrivingStateEvent.DRIVING_STATE_MOVING,
                true,
                UX_RESTRICTIONS_FULLY_RESTRICTED)
        // Set restriction parameters.
        .setMaxStringLength(int max)
        .setMaxCumulativeContentItems(int max)
        .setMaxContentDepth(int max)
        // Build a new CarUxRestrictionsConfiguration.
        .build();

CarUxRestrictionsManager API

Set CarUxRestrictionsConfiguration for the next drive with CarUxRestrictionsManager. This method requires permission, Car.PERMISSION_CAR_UX_RESTRICTIONS_CONFIGURATION.

public synchronized boolean saveUxRestrictionsConfigurationForNextBoot(
        CarUxRestrictionsConfiguration config);

Persist a new UX Restrictions configuration

When a new configuration is passed in, the UX Restrictions service returns a boolean to indicate whether the new configuration has been successfully saved. This new configuration is only used when the Integrated Head Unit (IHU) restarts and the car is parked. Internally, the UX Restrictions service contains two sets of configurations:

• Production. While optional, this configuration is often present. The UX Restrictions service reads this configuration when starting.
• Staged. Also optional, this configuration has no effect on UX Restrictions and is promoted to Production when the car service starts and when the car is parked.

Figure 1. Production configuration

Address failures

Until driving state information is received from CarPropertyManager (for example, during boot-up), UX Restrictions won't be enforced. The system performs as if the driving state is Parked.

Should reading a saved configuration fail (for example, SettingNotFoundException results), the UX Restrictions service falls back to the hard-coded, fully restricted mode:

// Idling/moving state is fully restricted.
private static CarUxRestrictionsConfiguration generateDefaultConfig() {}

Driving state and user restrictions

The following content describes the interactions displayed in the following design diagram:

Figure 2. Driving state interactions

Properties used to derive driving state

Use the following three VehiclePropertyIds to derive the driving state:

• VehicleProperty.PERF_VEHICLE_SPEED
• VehicleProperty.GEAR_SELECTION
• VehicleProperty.PARKING_BRAKE_ON

APIs available to apps

The code resides in the following locations:

Code	Location
CarUxRestrictionsManager Public APIs to register for UX Restriction changes.	/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
CarUxRestrictions UX restrictions definition.	/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java
CarDrivingStateManager System APIs to register for driving state changes.	/packages/services/Car/+/main/car-lib/src/android/car/drivingstate/CarDrivingStateManager.java

To simulate driving states, see Testing.