Integrate deep links to Media apps

This document aims to describe how third party (3P) app developers can add deep links to AAOS media apps. Media deep links enable you to open AAOS Media apps through deep links in the same way as on a mobile device.

Supported versions

To get the latest supported version, see the latest Build Artifacts.

  • CarMediaApp.apk
  • TestMediaApp.apk

How it works

When a deep link is opened on AAOS, it opens the media app that handles the particular scheme. The media app then decodes the URL, creating a Media intent with the information in that link and then using that intent to open the media screen.

The implementation to support new intents and new extras:

  • Provides an updated format of the intents that can be handled by the Media to 3P developers so they can send necessary information through the intent to the Media.

  • Handles the intents from 3P apps that contain a specific media item or a search query and then open a page with the requested information in Media.

3P developers are responsible for updating their app so that the app can be invoked by the web URI intents and send the necessary information to the Media through an intent.

Requirement for 3P apps

The TmaTrampolineActivity in the TestMediaApp app is provided as an example.

Step 1

Developers must have an activity similar to TmaTrampolineActivity in TestMediaApp. To deep link, this activity needs an intent filter in the manifest. This intent filter should include all the URLs to be handled as described in Add intent filters for incoming links.

We suggest that the intent filter include the schemes and hosts that the phone version app uses to make sure the deep links work across platforms.

<activity android:name=".automotive.TmaTrampolineActivity"
                  android:exported="true">
            <intent-filter android:label="TmaTrampolineActivity_label">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="app"
                      android:host="com.android.car.media.testmediaapp"/>
            </intent-filter>
        </activity>

Step 2

In this activity, the Media app retrieves the information from the link and creates an intent to the Media.

The Media supports two functions. The first function is to open a media item with a specific media item and the second is to show the results of a search query. The media item ID or the search query string must be included in the intent extra.

Intent information

To use this feature, developers must install the most recent version of the Media to support the Intent action, ACTION_MEDIA_TEMPLATE_V2. The Intent action, and the following intent extras, are included in the MediaIntentExtras.java class. These extras can be added to the intent.

Extra name Value Description
EXTRA_KEY_MEDIA_COMPONENT String for componentName Key used as a string extra field with ACTION_MEDIA_TEMPLATE_V2 to specify the MediaBrowserService on which the user wants to start the media. When unspecified, the active media source is opened.
EXTRA_KEY_MEDIA_ID Media ID Key used as a string extra field with ACTION_MEDIA_TEMPLATE_V2 specify the media item that should be displayed in the Browse view. Must match the IDs used in the MediaBrowserServiceCompat API.
EXTRA_KEY_SEARCH_QUERY Search query Key used as a string extra field with ACTION_MEDIA_TEMPLATE_V2 to specify the search query to send either to the current MediaBrowserService or the one specified with EXTRA_KEY_MEDIA_COMPONENT
EXTRA_KEY_SEARCH_ACTION

Integer:

  • 0: EXTRA_VALUE_NO_SEARCH_ACTION
  • 1: EXTRA_VALUE_PLAY_FIRST_ITEM_FROM_SEARCH
 Key used as an int extra field with ACTION_MEDIA_TEMPLATE_V2 to specify the action for the Media to perform after the search query is loaded.

The value is one of EXTRA_VALUE_NO_SEARCH_ACTION or EXTRA_VALUE_PLAY_FIRST_ITEM_FROM_SEARCH. This extra should only be used with EXTRA_KEY_SEARCH_QUERY.

If this extra is not specified, then no further action is taken after the search results are loaded.

Special cases

If several extras are added to the intent together, such as both EXTRA_KEY_MEDIA_ID and EXTRA_KEY_SEARCH_QUERY are included in this intent, the current implementation handles the media ID first, and only when the media ID is empty does the Media run the search query.

Test

Once integration of the 3P media app is complete, use an adb command to send a deep link. Media opens up with the desired information. For example, this command for TestMediaApp:

adb shell am start -W -a android.intent.action.VIEW -d "https://www.testmediaapp.com/path?search=normal\&searchAction=1"