2025년 3월 27일부터 AOSP를 빌드하고 기여하려면 aosp-main 대신 android-latest-release를 사용하는 것이 좋습니다. 자세한 내용은 AOSP 변경사항을 참고하세요.
미디어 앱에 딥 링크 통합
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서에서는 서드 파티 (3P) 앱 개발자가 AAOS 미디어 앱에 딥 링크를 추가하는 방법을 설명합니다. 미디어 딥 링크를 사용하면 휴대기기에서와 동일한 방식으로 딥 링크를 통해 AAOS 미디어 앱을 열 수 있습니다.
지원되는 버전
지원되는 최신 버전을 확인하려면 최신 빌드 아티팩트를 참고하세요.
CarMediaApp.apkTestMediaApp.apk
작동 방식
AAOS에서 딥 링크가 열리면 특정 스키마를 처리하는 미디어 앱이 열립니다. 그러면 미디어 앱이 URL을 디코딩하여 해당 링크의 정보로 미디어 인텐트를 만든 다음 이 인텐트를 사용하여 미디어 화면을 엽니다.
새 인텐트와 새 추가 항목을 지원하는 구현:
서드 파티 개발자는 앱이 웹 URI 인텐트로 호출될 수 있도록 앱을 업데이트하고 인텐트를 통해 미디어에 필요한 정보를 전송할 책임이 있습니다.
서드 파티 앱 요구사항
TestMediaApp 앱의 TmaTrampolineActivity가 예로 제공됩니다.
1단계
개발자는 TestMediaApp에 TmaTrampolineActivity와 유사한 활동이 있어야 합니다. 딥 링크를 사용하려면 이 활동에 매니페스트에 인텐트 필터가 있어야 합니다. 이 인텐트 필터에는 수신 링크의 인텐트 필터 추가에 설명된 대로 처리할 모든 URL이 포함되어야 합니다.
인텐트 필터에는 휴대전화 버전 앱에서 딥 링크가 여러 플랫폼에서 작동하도록 하는 데 사용하는 스키마와 호스트를 포함하는 것이 좋습니다.
<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>
2단계
이 활동에서 Media 앱은 링크에서 정보를 가져와 Media에 대한 인텐트를 만듭니다.
Media는 두 가지 함수를 지원합니다. 첫 번째 함수는 특정 미디어 항목이 포함된 미디어 항목을 열고 두 번째 함수는 검색어의 결과를 표시합니다. 미디어 항목 ID 또는 검색어 문자열이 인텐트 extra에 포함되어야 합니다.
이 기능을 사용하려면 개발자가 인텐트 작업 ACTION_MEDIA_TEMPLATE_V2를 지원하는 최신 버전의 Media를 설치해야 합니다. 인텐트 작업과 다음 인텐트 추가 항목은 MediaIntentExtras.java 클래스에 포함되어 있습니다. 이러한 데이터는 인텐트에 추가할 수 있습니다.
| 추가 이름 |
값 |
설명 |
| EXTRA_KEY_MEDIA_COMPONENT |
componentName의 문자열 |
사용자가 미디어를 시작하려는 MediaBrowserService를 지정하기 위해 ACTION_MEDIA_TEMPLATE_V2와 함께 문자열 추가 필드로 사용되는 키입니다.
지정하지 않으면 활성 미디어 소스가 열립니다. |
| EXTRA_KEY_MEDIA_ID |
미디어 ID |
ACTION_MEDIA_TEMPLATE_V2와 함께 문자열 추가 필드로 사용되는 키로, 탐색 뷰에 표시해야 하는 미디어 항목을 지정합니다. MediaBrowserServiceCompat API에서 사용된 ID와 일치해야 합니다. |
| EXTRA_KEY_SEARCH_QUERY |
검색어 |
ACTION_MEDIA_TEMPLATE_V2와 함께 문자열 추가 필드로 사용되어 현재 MediaBrowserService 또는 EXTRA_KEY_MEDIA_COMPONENT로 지정된 MediaBrowserService에 전송할 검색어를 지정하는 키입니다. |
| EXTRA_KEY_SEARCH_ACTION |
정수:
- 0: EXTRA_VALUE_NO_SEARCH_ACTION
- 1: EXTRA_VALUE_PLAY_FIRST_ITEM_FROM_SEARCH
|
ACTION_MEDIA_TEMPLATE_V2와 함께 int 추가 필드로 사용되어 검색 쿼리가 로드된 후 미디어가 실행할 작업을 지정합니다.
값은 EXTRA_VALUE_NO_SEARCH_ACTION 또는 EXTRA_VALUE_PLAY_FIRST_ITEM_FROM_SEARCH 중 하나입니다. 이 추가 항목은 EXTRA_KEY_SEARCH_QUERY와 함께만 사용해야 합니다.
이 추가 항목을 지정하지 않으면 검색 결과가 로드된 후 추가 작업이 실행되지 않습니다.
|
특수한 케이스
여러 개의 추가 항목이 인텐트에 함께 추가되는 경우(예: 이 인텐트에 EXTRA_KEY_MEDIA_ID 및 EXTRA_KEY_SEARCH_QUERY가 모두 포함됨) 현재 구현은 미디어 ID를 먼저 처리하고 미디어 ID가 비어 있는 경우에만 미디어가 검색 쿼리를 실행합니다.
테스트
서드 파티 미디어 앱 통합이 완료되면 adb 명령어를 사용하여 딥 링크를 전송합니다. 원하는 정보가 포함된 미디어가 열립니다. 예를 들어 TestMediaApp의 경우 다음과 같은 명령어를 사용합니다.
adb shell am start -W -a android.intent.action.VIEW -d "https://www.testmediaapp.com/path?search=normal\&searchAction=1"
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-06-12(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-06-12(UTC)"],[],[],null,["# Integrate deep links to Media apps\n\nThis document aims to describe how third party (3P) app developers can add deep\nlinks to AAOS media apps. Media deep links enable you to open AAOS Media apps\nthrough deep links in the same way as on a mobile device.\n\nSupported versions\n------------------\n\nTo get the latest supported version, see the latest\n[Build Artifacts](https://ci.android.com/builds/branches/aosp-ub-automotive-master/grid?legacy=1).\n\n- `CarMediaApp.apk`\n- `TestMediaApp.apk`\n\n### How it works\n\nWhen a deep link is opened on AAOS, it opens the media app that handles the\nparticular scheme. The media app then decodes the URL, creating a Media intent\nwith the information in that link and then using that intent to open the media\nscreen.\n\nThe implementation to support new intents and new extras:\n\n- Provides an updated format of the intents that can be handled by the Media\n to 3P developers so they can send necessary information through the intent\n to the Media.\n\n- Handles the intents from 3P apps that contain a specific media item or a\n search query and then open a page with the requested information in Media.\n\n3P developers are responsible for updating their app so that the app can be\ninvoked by the web URI intents and send the necessary information to the Media\nthrough an intent.\n\nRequirement for 3P apps\n-----------------------\n\nThe `TmaTrampolineActivity` in the `TestMediaApp` app is provided as an example.\n\n### Step 1\n\nDevelopers must have an activity similar to `TmaTrampolineActivity` in\n`TestMediaApp`. To deep link, this activity needs an intent filter in the\nmanifest. This intent filter should include all the URLs to be handled\nas described in [Add intent filters for incoming links](https://developer.android.com/training/app-links/deep-linking#adding-filters).\n\nWe suggest that the intent filter include the schemes and hosts that the\nphone version app uses to make sure the deep links work across platforms. \n\n \u003cactivity android:name=\".automotive.TmaTrampolineActivity\"\n android:exported=\"true\"\u003e\n \u003cintent-filter android:label=\"TmaTrampolineActivity_label\"\u003e\n \u003caction android:name=\"android.intent.action.VIEW\" /\u003e\n \u003ccategory android:name=\"android.intent.category.DEFAULT\" /\u003e\n \u003ccategory android:name=\"android.intent.category.BROWSABLE\" /\u003e\n \u003cdata android:scheme=\"app\"\n android:host=\"com.android.car.media.testmediaapp\"/\u003e\n \u003c/intent-filter\u003e\n \u003c/activity\u003e\n\n### Step 2\n\nIn this activity, the Media app retrieves the information from the link and\ncreates an intent to the Media.\n\nThe Media supports two functions. The first function is to open a\nmedia item with a specific media item and the second is to show the\nresults of a search query. The media item ID or the search query string must\nbe included in the intent extra.\n\n#### Intent information\n\nTo use this feature, developers must install the most recent version of the\nMedia to support the Intent action, `ACTION_MEDIA_TEMPLATE_V2`. The Intent\naction, and the following intent extras, are included in the\n`MediaIntentExtras.java` class. These extras can be added to the intent.\n\n| Extra name | Value | Description |\n|---------------------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 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. |\n| 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. |\n| 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 |\n| 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. |\n\n#### Special cases\n\nIf several extras are added to the intent together, such as both\n`EXTRA_KEY_MEDIA_ID` and `EXTRA_KEY_SEARCH_QUERY` are included in this intent,\nthe current implementation handles the media ID first, and only when the media\nID is empty does the Media run the search query.\n\nTest\n----\n\nOnce integration of the 3P media app is complete, use an `adb` command to send\na deep link. Media opens up with the desired information. For example, this\ncommand for `TestMediaApp`: \n\n```\nadb shell am start -W -a android.intent.action.VIEW -d \"https://www.testmediaapp.com/path?search=normal\\&searchAction=1\"\n```"]]
