System components and user flows

The following diagram illustrates the components that interact with Media:

System components

Figure 1. System components

The elements in this figure are described in the table:

Component Description
Home Screen Represents other surfaces in the car UI that display and control the currently playing media. In AOSP, this is the main screen displayed when the system starts. From this screen, users can view details of the media item being played and execute a limited set of standard and custom actions (for example, Play and Pause).
System UI Provides functionality that includes global UI navigation options such as to navigate to Media.
Assistants Android provides mechanisms for different voice assistant apps to interact with the system. These apps can interact with Media Sources in the background (for example, playing a song as the result of a voice command), or navigate to Media in the foreground (for example, when a voice assistant app is instructed to display the UI of a specific Media Source).
App Launcher All Android apps start in the App Launcher, including Media Sources. Media can present its own Media Source selector, complementing or replacing the App Launcher as the starting place for media.
Google Play Store When GAS is being used, this is where users locate and install new apps in an Android device. For media, once apps are installed, users are directed to the Media to complete the sign-in process or to start interacting with the app.
Media Session Manager Android system service that tracks and controls media sessions from all media sources. It provides mechanisms to detect when a Media Source becomes the foreground media source. Media, and all other apps displaying the currently playing media source (for example, the Home screen), use Media Session Manager to detect these events and update the UI accordingly. Media Sources interact with Media Session Manager by means of the Media Session API.
Radio Specialized app to interact with the radio hardware. Radio searches for radio stations, quickly selecting recently identified stations and switching between radio bands. UI components shared by both Radio and Media enable the user to switch between the two experiences.
Driver Distraction Engine Android system service used to impose UX restrictions based on the driving state of the car. For the media sources sign-in and settings UX (where the screen is controlled directly by the media sources), this service ensures no unsafe content is displayed when the car is in the driving state. OEMs can customize the definition of these states and how the system reacts in these situations (for example, by displaying a blocking screen overlay).

User flows

Media app launch

The process that launches Media appears below.

Media app launch

Figure 2. Media app launch

Media must be launched using the following implicit CAR_INTENT_ACTION_MEDIA_TEMPLATE. This intent can have the following information as extras:

  • android.car.intent.extra.MEDIA_COMPONENT (optional). String extra to represent the flattened component name of a MediaBrowserService in the media app to which the Media is to connect. If not provided, Media displays the currently selected media app. This intent is used from the following entry points:

    • System UI. Used to return to the Media experience or to start using it for the first time. In this case, the above Intent would be used without any extras so as to cause Media to display the currently selected media app.

    • Home Screen, Assistants, and Notification Center. Users can navigate to Media to display the currently selected media app. In all cases, the implicit Intent without extras is triggered.

    • App Launcher. When users select a media app from the App Launcher, the above intent includes the CAR_EXTRA_MEDIA_COMPONENT extra, which contains the selected media app. Media designates this as the newly selected app and connects to it. For details, see the section below, App Launcher to Media integration.

App launcher to Media integration

Media apps aren't permitted to provide any activity annotated with the android.intent.category.LAUNCHER category. As a result, the App Launcher (or its equivalent) must implement special logic to address media source integration:

  • App Launcher must scan the system for packages implementing MediaBrowserService.SERVICE_INTERFACE. For these packages, App Launcher fetches the service icon similar to that used to fetch other activities.

  • App Launcher then combines these packages with those that implement android.intent.category.LAUNCHER activities. If an app provides a MediaBrowserService implementation and a launcher activity, the service takes precedence.

    As of this writing, no media source app can provide a launcher activity.

  • An example of this logic can be found in the AOSP code at AppLauncherUtils#getAllLauncherApps().

Sign-in flow and configuration options

Media apps can include a vehicle-optimized Settings activity. Such an activity can be used to implement user flows not addressed by the Android Media APIs, for example:

  • Sign-in
  • Sign-out
  • Account switching
  • Display to which the user is currently logged in (if any)
  • Service configuration

Sign-n flow

Figure 3. Sign-in flow

This Settings activity is declared by the media app with the following intent filter:

<activity android:name=".AppSettingsActivity"
          android:exported="true
          android:theme="@style/SettingsActivity"
           android:label="@string/app_settings_activity_title">
   <intent-filter>
       <action android:name="android.intent.action.APPLICATION_PREFERENCES"/>
   </intent-filter>
</activity>

Media must implement the following logic:

  • Check that the currently selected media app includes an activity with the given Intent Filter.

  • If so, allow the user to navigate to the activity.

  • If Car UX Restrictions are in effect (for example, the car is moving), this affordance should be disabled as Settings activity is not a Driver Optimized UI.

Error handling and required sign-in

Media interacts with media apps through the Android Media Session API. As part of this API, Media receives a PlaybackState object, which communicates the current state of the media app.

The sign-in process starts when the media app changes PlaybackState to STATE_ERROR, including a specific error code (see details below). When this happens, Media displays the error description and an affordance to navigate to a sign-in activity implemented by the media app.

This same flow can be used by apps to signal other error situations (for example, a server connectivity error).

Error handling

Figure 4. Error handling

As part of normal PlaybackState error handling, Media must check for the following input.

  • PlaybackState error code equal to PlaybackStateCompat#ERROR_CODE_AUTHENTICATION_EXPIRED. This signals that the media app requires sign-in to continue operation. Other error codes can be received, which would indicate other types of error situations.

  • PlaybackState error message (set by media apps using the PlaybackStateCompat.Builder#setErrorMessage method) contains a human-readable explanation (for example, "You are not signed in."). This message must be displayed to the user and it must be driving distraction optimized (DO).

  • Optionally, PlaybackState can include the following extras (set by media apps with the PlaybackStateCompat.Builder#setExtras method) with the following keys.

    • android.media.extras.ERROR_RESOLUTION_ACTION_LABEL. Set to a string that contains the human-readable message to be displayed on the button touched by the user to start the sign-in flow.

    • android.media.extras.ERROR_RESOLUTION_ACTION_INTENT. Set with a PendingIntent to be triggered when the user clicks on the above mentioned button. This PendingIntent points to a custom sign-in activity implemented by the same media app.

  • PlaybackState state is equal to STATE_ERROR. This signals no other operation is possible until sign-in is completed.