앱 링크를 지원하려면 디지털 애셋 링크 JSON 파일(assetlinks.json)을 만들어 웹사이트의 잘 알려진 위치에 게시해야 합니다. 이 파일은 도메인의 링크를 처리할 권한이 있는 앱을 공개적으로 선언하며, Android 기기는 서버에서 이 파일을 검색하여 딥 링크를 확인합니다.
Android 15 이상의 동적 앱 링크의 경우 assetlinks.json 파일은 경로, 프래그먼트, 쿼리 매개변수의 패턴 매처와 같은 동적 규칙 구성을 정의하는 곳이기도 합니다. Android 15(API 수준 35) 이상을 실행하고 Google 서비스가 설치된 Android 기기는 주기적으로 파일을 가져와 앱 매니페스트의 정적 구성과 동적 구성을 병합합니다.
이 가이드에서는 assetlinks.json 파일을 준비하고 웹사이트에 게시하는 방법을 설명합니다. 원하는 경우 Play 딥 링크 도구 또는 Android 스튜디오 앱 링크 어시스턴트에서 assetlinks.json 파일을 생성할 수 있습니다.
자세한 내용은 App Links 개발자 도구를 참고하세요.
웹사이트 연결 선언하기
디지털 애셋 링크 JSON 파일을 웹사이트에 게시하여 웹사이트와 연결된 Android 앱을 나타내고 앱의 URL 인텐트를 인증해야 합니다. JSON 파일은 다음 필드를 사용하여 연결된 앱을 식별합니다.
package_name: 앱의build.gradle파일에 선언된 애플리케이션 ID입니다.sha256_cert_fingerprints: 앱 서명 인증서의 SHA256 지문입니다. 다음 명령어를 사용하여 Java keytool을 통해 지문을 생성할 수 있습니다.
keytool -list -v -keystore my-release-key.keystore
- 이 필드는 디버그 빌드나 프로덕션 빌드와 같이 다양한 버전의 앱을 지원하는 데 사용할 수 있는 여러 지문 파일을 지원합니다. 앱에 Play 앱 서명을 사용 중인 경우 로컬에서
keytool를 실행하여 생성된 인증서 지문은 일반적으로 사용자 기기의 인증서 지문과 일치하지 않습니다. Play Console 개발자 계정의Release > Setup > App signing에서 앱에 Play 앱 서명을 사용하고 있는지 확인할 수 있습니다. 사용하고 있다면 같은 페이지에서 앱에 적합한 디지털 애셋 링크 JSON 스니펫도 확인할 수 있습니다.
다음 예제 assetlinks.json 파일은 com.example Android 앱에 링크 열기 권한을 부여합니다.
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]
웹사이트와 여러 앱 연결하기
웹사이트는 동일한 assetlinks.json 파일에서 여러 앱과의 연결 관계를 선언할 수 있습니다. 다음 파일 목록은 두 개 앱과의 연관 관계를 별도로 선언하고 https://www.example.com/.well-known/assetlinks.json에 위치하는 명령문 파일의 예를 보여줍니다.
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.puppies.app",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
},
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.monkeys.app",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]
서로 다른 앱이 같은 웹 호스트에서 다른 리소스 링크를 처리할 수 있습니다.
예를 들어 app1이 https://example.com/articles의 인텐트 필터를 선언하고 app2가 https://example.com/videos의 인텐트 필터를 선언할 수 있습니다.
여러 웹사이트와 단일 앱 연결하기
여러 웹사이트에서 각 assetlinks.json 파일에 동일한 앱과의 연결을 선언할 수 있습니다. 다음 파일 목록은 example.com과 app1의 연결 및 example.net과 app1의 연결을 선언하는 방법의 예입니다. 첫 번째 목록은 example.com과 app1의 연결을 보여줍니다.
https://www.example.com/.well-known/assetlinks.json
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.mycompany.app1",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]
다음 목록은 example.net과 app1의 연결을 보여줍니다. 이러한 파일이 호스팅되는 위치만 다릅니다 (.com 및 .net).
https://www.example.net/.well-known/assetlinks.json
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.mycompany.app1",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]
동적 규칙 구성
Android 15 이상의 동적 앱 링크를 사용하면 앱 매니페스트에 정적으로 정의한 규칙과 함께 작동하는 서버 측 딥 링크 일치 규칙을 사용할 수 있습니다. assetlinks.json 파일은 동적 규칙을 정의하는 곳입니다. 포함 여부는 선택사항입니다.
Android 15 (API 수준 35) 이상을 실행하고 Google 서비스가 설치된 Android 기기는 서버에서 이 파일을 주기적으로 가져와 앱 매니페스트의 정적 구성과 동적 규칙 구성을 병합합니다. 다음은 동적 규칙이 있는 assetlinks.json 파일의 예시입니다.
[
{
"relation": [
"delegate_permission/common.handle_all_urls"
],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [...]
},
"relation_extensions": {
"delegate_permission/common.handle_all_urls": {
"dynamic_app_link_components": [
{"?": {"dl": "*"}},
{"#": "app"},
{"/": "/products/*"},
{"/": "/shoes", "?": {"in_app": "true"}},
{"/": "*", "exclude": true}
]
}
}
}
]
코드에 관한 핵심 사항
- 동적 앱 링크는
dynamic_app_link_components라는 새로운 디지털 애셋 링크 관계 확장 프로그램을 추가합니다. 여기에서 동적 규칙을 구성합니다. - 동적 규칙에는 경로, 프래그먼트, 쿼리 매개변수의 패턴 매처가 포함될 수 있습니다.
- 패턴 매처를 제외됨으로 표시하여 일치하는 URL이 앱을 열지 않도록 할 수도 있습니다.
- 이 예시에서는 경로 (
"/"), 프래그먼트 ("#"), 쿼리 매개변수 ("?")의 일치자와 제외된 일치자 ("exclude")의 예를 보여줍니다. - 파일의 필드 중 하나가 형식이 잘못되었거나 비어 있으면 Android는 동적 규칙을 삭제하고 기기는 앱의 매니페스트에 정적으로 정의된 규칙으로 대체됩니다.
동적 규칙은 앱의 매니페스트 파일에 선언된 도메인의 범위 내에 적용되는 규칙만 지정할 수 있습니다. 아래를 참고하세요.
동적 규칙 선언
동적 앱 링크는 규칙 객체의 배열을 보유하는 새로운 dynamic_app_link_components 관계 확장 프로그램을 지원합니다. 각 규칙은 앱을 여는 경로, 프래그먼트, 쿼리 매개변수의 패턴 매처를 사용하여 정의됩니다. 매처를 개별적으로 제외하여 앱이 열리지 않도록 할 수도 있습니다. 이 모든 것은 선택사항입니다.
- 경로 일치
- 키: '/'
- 값: URL 경로의 일치 표현식인 단일 문자열
- 프래그먼트 일치
- 키: '#'
- 값: URL 프래그먼트의 일치 표현식인 단일 문자열
- 쿼리 매개변수 일치
- 키: '?'
- 값: URL 쿼리 매개변수에서 키/값 쌍을 일치시킬 사전입니다.
- 예를 들어 {'
?", {"dl": "*", "in_app":"true'} 사전은 '?in_app=true&dl=abc' 검색어와 일치합니다. - 사전의 키/값 쌍 순서는 쿼리 문자열의 쌍 순서와 일치하지 않아도 됩니다. 또한 사전이 쿼리 문자열의 모든 키/값 쌍과 일치할 필요는 없지만 모든 사전 항목에 대해 일치하는 항목이 있어야 합니다.
- 예를 들어 사전은 쿼리 문자열 '
?lang=en&in_app=true&tz=pst&dl=abc'와도 일치하지만 쿼리 문자열 '?lang=en&tz=pst&dl=abc'과는 일치하지 않습니다.
- 제외됨
- 키: 'exclude'
- 값:
dynamic_app_link_components에 정의된 각 규칙의 선택적 true/false 값입니다 (예 참고).
패턴 매처에서 다음 특수문자를 사용할 수 있습니다.
- '*'는 패턴의 와일드 카드 뒤에 있는 문자가 일치하는 문자열에서 발견될 때까지 0개 이상의 문자와 일치합니다.
- '?'는 단일 문자와 일치합니다.
- '?*'는 하나 이상의 문자와 일치합니다.
값에 대한 다른 문자 제한은 없습니다.
동적 규칙 순서 지정
규칙이 선언되는 순서가 중요합니다. Android는 일치하는 항목을 찾을 때까지 각 규칙을 순서대로 평가합니다.
다음 예는 순서가 처리에 미치는 영향을 보여줍니다. 첫 번째 규칙은 모든 경로 ('*')와 일치하지만 일치를 제외 (exclude: true)하므로 앱을 여는 모든 URL을 제외합니다. 이 경우 '/path1'을 허용하는 두 번째 규칙은 평가되지 않습니다.
dynamic_app_link_components: [
{"/": "*", exclude: true},
{"/": "/path1"}
]
하지만 다음 예에서는 '/path1' 규칙이 먼저 선언되므로 먼저 평가되고 '/path1'과 일치하는 URL에 앱이 열립니다. 앱을 여는 모든 URL을 제외하는 두 번째 규칙은 두 번째로 평가되지만 첫 번째 규칙이 일치하지 않는 경우에만 평가됩니다.
dynamic_app_link_components: [
{"/": "/path1"},
{"/": "*", exclude: true}
]
동적 규칙의 범위를 적절하게 지정
Android 15 이상에서 동적 앱 링크와 함께 사용할 서버 측 규칙을 정의할 때는 앱 매니페스트에 선언된 정적 인텐트 필터와 함께 작동하고 이를 보완할 수 있도록 적절하게 범위를 지정해야 합니다.
assetlinks.json 파일에 선언된 동적 규칙은 앱의 AndroidManifest.xml 파일에 선언된 호스트의 규칙만 지정할 수 있습니다. 동적 규칙은 앱 매니페스트에 정적으로 선언한 URL 규칙의 범위를 확장할 수 없습니다.
따라서 동적 규칙과 정적 규칙 모두에서 이 방법을 사용하는 것이 좋습니다.
- 앱 매니페스트에서 스키마와 도메인만 선언하는 등 가능한 가장 광범위한 범위로 규칙을 설정합니다.
- 경로 수준 라우팅과 같은 추가 개선을 위해 서버 측 동적 규칙을 사용합니다.
이 이상적인 구성을 사용하면 앱 매니페스트에 설정한 광범위한 범위 내에 포함된다는 것을 알고 필요에 따라 assetlinks.json 파일에 새 앱 링크 경로를 동적으로 추가할 수 있습니다.
dynamic_app_link_components를 한 번만 선언
규칙을 올바르게 처리하려면 특정 사이트, 관계, 앱의 문에서 하나의 dynamic_app_link_components 객체만 선언하세요.
- 동일한 사이트, 관계, 앱에 대해 dynamic_app_link_components 객체를 선언하는 여러 문을 찾습니다.
- 단일 문에서 선언된 여러 dynamic_app_link_components 객체를 찾습니다.
이러한 경우 Android는 어떤 동적 규칙 구성이 사용될지 보장하지 않습니다.
이전 앱 링크 구성과의 동적 규칙 호환성
이미 App Links를 지원하는 경우 기존 assetlinks.json 파일에 Dynamic App Links 지원을 직접 추가할 수 있습니다. 앱 링크 확인을 위한 관계 필드는 동일하게 유지되며 다른 변경사항 없이 동적 규칙을 위한 새 관계 확장 프로그램 필드를 추가할 수 있습니다.
Android 14 (API 수준 34 이하)를 실행하는 Android 기기는 동적 규칙의 새로운 관계 확장 프로그램 필드를 무시하지만 Android 15 이상을 실행하는 기기는 이러한 규칙을 매니페스트 정의 규칙과 병합합니다.
JSON 인증 파일 게시
다음 위치에서 JSON 인증 파일을 게시해야 합니다.
https://domain.name/.well-known/assetlinks.json
다음 사항을 확인하세요.
assetlinks.json파일이 콘텐츠 유형application/json과 함께 제공됩니다.assetlinks.json파일은 앱의 인텐트 필터에서 HTTPS를 데이터 스키마로 선언하는지와 관계없이 HTTPS 연결을 통해 액세스 가능해야 합니다.assetlinks.json파일은 리디렉션 없이 (301 또는 302 리디렉션 없음) 액세스할 수 있어야 합니다.- 앱 링크에서 여러 호스트 도메인을 지원하면 각 도메인에
assetlinks.json파일을 게시해야 합니다. 여러 호스트에서 앱 링크 지원을 참고하세요. - 매니페스트 파일에서 공개적인 액세스가 불가능한 테스트 URL (예: VPN으로만 액세스 가능)에 앱을 게시하면 안 됩니다. 이런 경우에는 빌드 변형을 구성하여 개발 빌드용으로 다른 manifest 파일을 생성하여 일시적으로 해결할 수 있습니다.
다음 관련 가이드를 참고하세요.