이 페이지는 Cloud Translation API를 통해 번역되었습니다.

딥 링크 만들기

딥 링크를 사용하면 웹브라우저, 알림, 소셜 미디어, 광고 및 기타 소스에서 사용자를 앱으로 바로 연결할 수 있습니다. 딥 링크는 앱 간 및 웹-앱 간 전환을 직접 제공하여 맥락에 맞는 타겟팅 콘텐츠를 통해 참여도를 높이는 데 도움이 됩니다.

이 가이드에서는 딥 링크의 작동 방식과 콘텐츠로 연결되는 딥 링크를 만들고 테스트하는 방법을 설명합니다.

자체 웹사이트 또는 도메인을 참조하는 딥 링크의 경우 사용자에게 원활하고 신뢰할 수 있는 환경을 제공하는 앱 링크를 사용하는 것이 좋습니다.

딥 링크 작동 방식

딥 링크는 모든 버전, 모든 기기에서 지원되는 Android의 일반 시스템 기능입니다. Android의 인텐트 시스템을 활용하여 딥 링크를 관심 있는 앱으로 라우팅합니다. 특정 딥 링크 URI를 처리하려는 앱은 앱 매니페스트 파일에서 일치하는 인텐트 필터를 선언합니다.

런타임에 사용자가 링크를 탭하면 Android는 인텐트를 트리거하고 앱으로 라우팅하려고 시도합니다. 여러 앱이 지정된 URI와 일치하는 인텐트 필터를 선언할 수 있으므로 Android는 다음 순서로 인텐트를 라우팅합니다.

URI를 처리할 수 있는 사용자의 기본 앱(지정된 경우)을 엽니다.
URI를 처리할 수 있는, 사용 가능한 유일한 앱을 엽니다.
사용자가 명확성 대화상자에서 앱을 선택하도록 허용합니다.

즉, 인텐트 필터가 특정 URI와 일치하더라도 시스템이 딥 링크 인텐트를 앱으로 라우팅한다는 보장은 없습니다. 사용자는 인텐트를 처리하는 앱을 관리하는 데 중요한 역할을 하므로 제어 권한과 선택권을 갖습니다. 자체 웹사이트 및 도메인으로 연결되는 딥 링크를 더 세부적으로 관리하려면 App Links를 사용해 보세요.

Android의 명확성 대화상자를 사용하면 사용자가 딥 링크 인텐트를 처리하도록 등록된 설치된 앱을 모두 볼 수 있습니다. 사용자는 이 유형의 링크에 대한 기본값으로 앱을 선택할 수도 있습니다. 사용자가 기본값을 설정하면 시스템은 더 이상 해당 특정 인텐트의 대화상자를 표시하지 않으며 선택한 앱이 자동으로 열립니다.

그림 1. 명확성 대화상자

명확성 보장 대화상자의 동작은 Android 버전에 따라 발전해 왔습니다. 예를 들어 Android 12 이상에서는 인증된 앱 링크가 아닌 웹 링크가 기본적으로 웹브라우저에서 열리지만 이전 버전에서는 앱이 웹 링크를 처리할 수 있는 경우 명확성 대화상자가 표시될 수 있습니다.

참고: Android 12 (API 수준 31)부터 일반 웹 인텐트는 앱이 웹 인텐트에 포함된 특정 도메인에 관해 승인된 경우에만 앱의 활동으로 확인됩니다. 앱이 도메인에 관해 승인되지 않으면 웹 인텐트는 대신 사용자의 기본 브라우저 앱으로 확인됩니다.

딥 링크 유형

Android에서 지원할 수 있는 딥 링크에는 세 가지 유형이 있습니다.

맞춤 딥 링크: 맞춤 URI 스키마 (예: example://products/123)를 사용하여 사용자를 앱 내의 특정 콘텐츠로 바로 연결하는 딥 링크입니다. 내부 탐색이나 관리하는 소스의 링크에 유용하지만 표준 웹 링크가 아니며 다른 앱이 동일한 맞춤 스키마를 등록하는 경우 명확성 해소 대화상자가 트리거될 수 있습니다.
웹 링크: 표준 http 및 https 스키마를 사용하는 딥 링크입니다. 표준 URL이므로 더 다재다능하지만 Android 12 이상에서는 거의 항상 명확성 해소 대화상자를 트리거하므로 앱으로 라우팅되지 않고 기본적으로 사용자의 웹브라우저에서 처리될 가능성이 높습니다.
App Links: Android 6.0 (API 수준 23)부터 제공되며 인증된 웹 링크입니다. 웹사이트 연결 과정을 통해 Android 시스템에 도메인을 소유하고 있음을 증명할 수 있습니다. 인증이 완료되면 시스템에서 해당 도메인의 링크를 앱으로 바로 라우팅하여 명확성 대화상자를 완전히 건너뜁니다. 이를 통해 사용자에게 신뢰할 수 있고 원활한 환경을 제공할 수 있습니다.

수신 링크의 인텐트 필터 추가하기

앱 콘텐츠 링크를 만들려면 이러한 요소와 속성값이 포함된 인텐트 필터를 매니페스트에 추가합니다.

<action>

Google 검색에서 인텐트 필터에 도달할 수 있도록 ACTION_VIEW 인텐트 작업을 지정합니다.

<data>

<data> 태그를 하나 이상 추가합니다. 각 태그는 활동으로 확인되는 URI 형식을 나타냅니다. 최소한 <data> 태그에는 android:scheme 속성이 포함되어야 합니다.

속성을 추가하여 활동이 수락하는 URI 유형을 더욱 세분화할 수 있습니다. 예를 들어 유사한 URI를 수락하지만, 경로 이름에 따라 달라지는 여러 활동이 있을 수 있습니다. 이 경우 android:path 속성 또는 속성의 pathPattern이나 pathPrefix 변형을 사용하여 시스템이 다양한 URI 경로에 대해 열어야 하는 활동을 구분할 수 있습니다.

<category>

BROWSABLE 카테고리를 포함합니다. 이 속성은 웹브라우저에서 인텐트 필터에 액세스할 수 있으려면 필요합니다. 이 카테고리가 없는 경우 브라우저에서 링크를 클릭해도 앱으로 확인되지 않습니다.

DEFAULT 카테고리도 포함합니다. 그러면 앱이 암시적 인텐트에 응답할 수 있습니다. 이 카테고리가 없으면 인텐트에서 앱 구성요소 이름을 지정한 경우에만 활동을 시작할 수 있습니다.

다음 XML 스니펫은 매니페스트에서 딥 링크용 인텐트 필터를 지정할 수 있는 방법을 보여줍니다. "example://gizmos"와 "http://www.example.com/gizmos" URI 모두 이 활동으로 확인됩니다.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

두 인텐트 필터는 <data> 요소만 다릅니다. 동일한 필터에 여러 <data> 요소를 포함할 수 있지만, 고유한 URL (예: scheme 및 host의 특정 조합)을 선언하려는 경우에는 별도의 필터를 만들어야 합니다. 동일한 인텐트 필터의 여러 <data> 요소가 결합된 속성의 모든 변형을 설명하기 위해 실제로 함께 병합되기 때문입니다. 예를 들어 다음을 고려해 보세요.

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

https://www.example.com 및 app://open.my.app만 지원하는 것 같습니다. 하지만 실제로는 이 두 가지 외에 app://www.example.com 및 https://open.my.app도 지원합니다.

주의: 동일한 인증된 Android 앱 링크로 확인되는 인텐트 필터가 여러 활동에 포함된 경우 링크를 처리하는 활동이 무엇인지 보장할 수 없습니다.

활동 콘텐츠의 URI가 포함된 인텐트 필터를 앱 매니페스트에 추가하면 Android는 런타임 시 앱과 일치하는 URI가 있는 모든 Intent를 전달할 수 있습니다.

인텐트 필터 정의에 대해 자세히 알아보려면 다른 앱에서 내 앱의 활동을 시작하도록 허용하기를 참고하세요.

수신되는 인텐트에서 데이터 읽기

시스템이 인텐트 필터를 통해 활동을 시작하면 Intent에서 제공하는 데이터를 사용하여 렌더링해야 하는 대상을 결정할 수 있습니다. getData() 및 getAction() 메서드를 호출하여 수신 Intent와 연결된 데이터와 작업을 가져옵니다. 활동의 수명 주기 동안에는 이러한 메서드를 언제든 호출할 수 있지만, 일반적으로 onCreate()나 onStart와 같은 초기 콜백에서 호출해야 합니다.

다음은 Intent에서 데이터를 가져오는 방법을 보여주는 스니펫입니다.

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

자바

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

사용자의 경험을 향상하려면 다음 권장사항을 따르세요.

딥 링크는 요청 메시지, 전면 페이지, 로그인 없이 곧바로 사용자를 콘텐츠에 연결해야 합니다. 사용자가 이전에 애플리케이션을 연 적이 없더라도 앱 콘텐츠를 볼 수 있도록 만드세요. 후속 상호작용 또는 런처에서 앱을 열 때 사용자에게 메시지를 표시해도 괜찮습니다.
'뒤로' 및 '위로' 기능으로 이동하기에서 설명하는 설계 안내에 따라 사용자가 딥 링크를 통해 앱에 진입한 후 앱이 사용자의 역방향 이동 기대에 부합하도록 만듭니다.

딥 링크 테스트하기

Android 디버그 브리지를 활동 관리자 (am) 도구와 함께 사용하여 딥 링크용으로 지정한 인텐트 필터 URI가 올바른 앱 활동으로 확인되는지 테스트할 수 있습니다. 기기나 에뮬레이터에 관해 adb 명령어를 실행할 수 있습니다.

adb를 사용해 인텐트 필터 URI를 테스트하는 일반적인 구문은 다음과 같습니다.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

예를 들어 다음 명령어는 지정된 URI와 연결된 타겟 앱 활동을 봅니다.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

참고: **@Serializable data class Product(val colors: List)**와 같이 경로에서 기본 유형의 컬렉션을 정의하면 자동으로 생성되는 딥 링크 URL 형식은 **basePath?colors={value**}입니다. 쿼리 매개변수가 여러 개인 URI (예: **basepath?colors=red&colors=blue**)를 지정하려고 하면 앰퍼샌드(예: **basepath?colors=red\&colors=blue**)를 이스케이프해야 합니다.

설정한 매니페스트 선언과 인텐트 핸들러는 앱과 웹사이트 간의 연결 및 수신 링크로 해야 할 작업을 정의합니다. 그러나 시스템에서 앱이 URI 집합의 기본 핸들러로 취급되도록 하려면 이 연결을 인증하도록 시스템에 요청해야 합니다. 앱 링크 인증하기에서는 이러한 인증을 구현하는 방법을 설명합니다.

인텐트와 앱 링크를 자세히 알아보려면 다음 리소스를 참고하세요.

딥 링크 만들기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.