앱 링크 문제 해결

이 가이드에서는 일반적인 문제와 문제 해결 방법을 설명합니다. Play Console 딥 링크 페이지 또는 Android 스튜디오 앱 링크 어시스턴트의 문제 해결 도구를 사용할 수도 있습니다. 자세한 내용은 앱 링크 개발자 도구를 참고하세요.

  • 문제: 앱을 열어야 하는 링크를 클릭했지만 웹 브라우저에서 열리거나 선택 대화상자가 표시됩니다.
  • 해결 방법:
    • assetlinks.json 확인: 파일이 유효한 JSON이고 https://<your-domain>/.well-known/assetlinks.json에서 액세스할 수 있으며 리디렉션 없이 HTTPS를 통해 제공되는지 확인합니다. 온라인 유효성 검사기를 사용합니다.
    • SHA-256 디지털 지문 확인: assetlinks.json의 sha256_cert_fingerprints가 앱 출시의 서명 키 디지털 지문과 정확히 일치하는지 다시 한번 확인합니다 (Play 앱 서명을 사용하는 경우 Play Console의 디지털 지문을 사용). 서명은 대문자여야 합니다.
    • autoVerify 확인: <intent-filter> AndroidManifest.xml에 android:autoVerify="true"가 포함되어 있는지 확인합니다.
    • 서버 측 리디렉션 확인: http에서 https로 또는 www가 아닌 도메인에서 www로 리디렉션하면 인증이 실패할 수 있습니다.
    • 강제 재인증: 앱 링크 테스트 가이드에서 ADB 명령어를 실행하여 최신 인증 결과를 가져옵니다.

Android 15 이상에서 동적 규칙이 업데이트되지 않음

  • 문제: assetlinks.json 파일에서 규칙을 업데이트했지만 앱에서 새 링크를 처리하지 않습니다.
  • 해결 방법:
    • 강제 재인증: 변경사항을 테스트하는 가장 확실한 방법은 adb shell pm verify-app-links --re-verify. <your-package-name>를 사용하여 강제로 다시 가져오는 것입니다.
    • 오타 확인: 규칙의 패턴 일치자에서 구문 오류가 있는지 주의 깊게 검토합니다.
    • 매니페스트 필터 규칙 확인: 앱 매니페스트의 인텐트 필터 규칙을 검토하여 링크 경로가 필터링되지 않도록 합니다. 링크가 필터링되는 경우 앱 매니페스트의 인텐트 필터를 덜 제한적으로 만듭니다.

일반적인 구현 오류 수정

Android App Links를 확인할 수 없는 경우 다음과 같은 일반적인 오류를 확인하세요. 이 섹션에서는 example.com을 자리표시자 도메인 이름으로 사용합니다. 이러한 검사를 실행할 때는 example.com을 서버의 실제 도메인 이름으로 대체하세요.

잘못된 인텐트 필터 설정
앱이 소유하지 않은 URL을 <intent-filter> 요소에 포함하는지 확인합니다.
잘못된 서버 구성

서버의 JSON 구성을 확인하고 SHA 값이 올바른지 확인합니다.

또한 example.com. (마침표 포함)이 콘텐츠를 example.com과 동일하게 제공하는지 확인합니다.

서버 측 리디렉션

다음과 같은 리디렉션을 설정하면 시스템에서 앱의 Android App Links를 전혀 확인하지 않습니다.

  • http://example.com에서 https://example.com으로
  • example.com에서 www.example.com으로

이 동작은 앱의 보안을 보호합니다.

서버 안정성

클라이언트 앱이 서버에 연결할 수 있는지 확인합니다.

확인할 수 없는 링크

테스트 목적으로 확인 불가능한 링크를 의도적으로 추가할 수 있습니다. Android 11 이하에서는 이러한 링크로 인해 시스템에서 앱의 모든 Android App Links를 확인하지 않는다는 점에 유의하세요.

assetlinks.json의 잘못된 서명

서명이 올바르고 앱 서명에 사용된 서명과 일치하는지 확인합니다. 일반적인 실수는 다음과 같습니다.