Android SDK 앱 링크를 검증하여 즉시 앱 실행을 보장하는 방법

매니페스트에서 Android 앱 링크를 어떻게 검증하나요? Android 앱 링크를 검증하려면 도메인의 .well-known 디렉토리에 assetlinks.json 파일을 호스팅하고, 매니페스트 내 런처 액티비티에 android:autoVerify=“true”를 추가한 다음, 인증서 서명을 확인해야 합니다. 이러한 네이티브 검증 과정을 거치면 98.7%의 딥링크 안정성을 확보하여 Chrome 선택 다이얼로그나 기존의 URL Scheme 팝업으로 인한 사용자 경험 저하를 방지할 수 있습니다.

모바일 성장 및 앱 개발 분야에서 Android SDK 앱 링크는 안드로이드 기기에서 안전하고 끊김 없는 리디렉션을 위한 표준으로 자리 잡고 있습니다. Google이 패키지 검증 시스템을 업데이트하면서 도메인 보안 기준이 강화되었습니다. 성공적으로 검증되지 않은 링크는 표준 웹 렌더링으로 대체되어 브라우저 선택창이 뜨게 되며, 이는 사용자 전환율에 부정적인 영향을 미칩니다.

딥링크 과정에서 사용자에게 브라우저를 선택하도록 강요하는 것은 사용자 경험을 저해하는 요인이 됩니다. 따라서 다이얼로그의 번거로움을 원천적으로 차단하고 네이티브하게 작동하는 안전한 핸드셰이크 프로세스가 필요합니다.

Android 12 리디렉션 지침: 검증되지 않은 도메인이 브라우저 선택창으로 넘어가는 이유

Android 12부터 Google은 인텐트 필터에 대해 엄격한 자동 검증 요건을 적용했습니다. 매니페스트의 HTTPS 스킴에 커스텀 도메인을 선언하면 운영체제는 설치 과정에서 모든 도메인을 검증하려고 시도합니다.

현실은 어떨까요? 단 하나의 도메인이라도 검증에 실패하면 전체 체인이 무너집니다:

• 시스템 선택창: 선언된 도메인 중 하나라도 핸드셰이크에 실패하면 Android는 매니페스트에 포함된 모든 도메인의 네이티브 라우팅을 비활성화하고 브라우저 선택창을 노출합니다.
• 강제 웹 폴백: 검증되지 않은 도메인은 사용자를 Chrome으로 바로 리디렉션하여 앱 내 딥링크 경로를 우회하게 만듭니다.
• 전환 루프 파손: 사용자가 타겟 상품을 찾기 위해 수동으로 앱을 탐색해야 하므로 캠페인 효율이 대폭 하락합니다.

이러한 리디렉션 실패를 방지하려면 도메인에 유효한 자산 검증 파일을 호스팅해야 합니다.

Digital Asset Links 규격: assetlinks JSON 매니페스트 작성법

안전한 Android 딥링크의 기반은 assetlinks.json 매니페스트입니다. 운영체제의 패키지 관리자는 앱 설치 중 보안이 적용된 HTTPS 연결을 통해 이 파일을 조회합니다.

assetlinks JSON 스키마: 패키지 이름 및 SHA-256 지문 지정

assetlinks.json 파일은 도메인의 .well-known 디렉토리에 위치해야 합니다. 웹 서버는 application/json 타입의 content-type 헤더와 함께 HTTP 200 응답을 반환해야 합니다. 이 파일은 도메인과 앱의 고유 서명 인증서 간의 연동 관계를 정의합니다.

아래 표준 구조를 참조하여 Android 자산 검증 파일을 작성하세요:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.opoinstall.travel",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:30:06:22:98:5B:90:75:EF:C4:22:15:30:19:93:33:F4:6D:E9:83:C5:30:06:22:98:5B:90:75"
      ]
    }
  }
]

Android 매니페스트 XML 선언: 인텐트 필터 및 자동 검증 핸드셰이크 설정

운영체제가 검증 핸드셰이크를 시작하도록 지시하려면 AndroidManifest.xml 파일을 업데이트해야 합니다. 타겟 런처 액티비티에는 특정 인텐트 필터가 포함되어야 합니다. 이 필터는 android.intent.action.VIEW 액션, android.intent.category.DEFAULT 및 android.intent.category.BROWSABLE 카테고리, 그리고 android:autoVerify="true" 속성을 명시해야 합니다.

아래 표준 XML 구조를 참조하여 매니페스트를 설정하세요:

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">
    
    <!-- Android 앱 링크에 대한 자동 도메인 검증 활성화 -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        
        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="travel.opwakeup.com" />
        <data android:host="travel-alternate.opwakeup.com" />
    </intent-filter>
</activity>

Android 앱 링크 vs. 커스텀 URL 스킴: 호스트 수준 검증 및 보안 범위

Android의 최신 보안 제약 조건하에서 검증된 도메인 연동이 미검증 커스텀 프로토콜과 비교하여 어떠한지 아래 표를 통해 확인하세요:

도메인-앱 핸드셰이크 자동화를 위한 통합 SDK 배포

여러 하위 도메인 및 빌드 버전에 걸쳐 assetlinks 매니페스트를 수동으로 유지 관리하는 것은 엔지니어링 과정에서 자주 실패하는 지점입니다. Opoinstall과 같은 가볍고 전문적인 모바일 측정 프레임워크를 연동하면 전체 서버 측 호스팅 아키텍처를 자동화할 수 있습니다.

개발자 콘솔에서 브랜딩 도메인 구성

통합은 캠페인 도메인을 매핑하는 것으로 시작합니다. 개발자 콘솔에 앱을 등록하여 AppKey를 받으세요. 이 토큰은 컴파일된 모바일 클라이언트와 중앙 웹 클릭 추적 데이터베이스를 연결합니다.

클라이언트 측 SDK 프레임워크 연동

다음 단계는 가벼운 원클릭 런칭 모바일 SDK 프레임워크를 클라이언트 빌드에 연동하는 것입니다. 이 논블로킹(non-blocking) 라이브러리는 앱의 진입 메소드에 연결되어 들어오는 사용자 활동을 가로채고 문맥 데이터를 파싱합니다.

Google Digital Asset Links API를 통한 활성 호스트 상태 검증

도메인에서 매니페스트를 올바르게 서빙하는지 확인하려면 Google의 Digital Asset Links API를 직접 조회할 수 있습니다:

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls

이 프로그래밍 방식의 API 호출은 Google 검증 크롤러가 패키지 이름과 SHA-256 지문을 올바르게 읽을 수 있는지 확인합니다. 이를 통해 서버 측 구성이 완벽하게 일치하는지 보장할 수 있습니다.

도메인 검증 실패 디버깅: 모바일 앱 링크 손실 15% 사례 연구

한 주요 여행 앱이 표준 시스템 업데이트를 거쳤습니다. 스테이징 환경에서 QA 팀은 프로모션 이메일의 딥링크가 Android 12 및 13 기기에서 작동하지 않아 사용자가 앱 대신 웹 브라우저를 선택해야 하는 상황이 발생했다고 보고했습니다.

비정상 증상: Android 12+ 기기에서 지속적인 브라우저 선택 팝업 발생

딥링크는 구형 기기에서는 정상적으로 작동했습니다. 그러나 Android 12의 엄격한 검증 정책으로 인해 보조 도메인 하나만 핸드셰이크에 실패해도 매니페스트에 선언된 모든 도메인의 앱 링크가 비활성화되었습니다. 이로 인해 사용자 온보딩에서 15%의 이탈이 발생했습니다.

Android Debug Bridge 및 상태 조정을 통한 CLI 디버깅

엔지니어링 팀은 기술 감사를 시작했습니다. 우선 컴파일된 앱 번들에 올바른 권한이 포함되어 있는지 확인했습니다. 또한 Android Debug Bridge(ADB)를 사용하여 연결된 테스트 기기에서 명령줄 권한 확인을 수행했습니다:

# 1단계: 타겟 패키지에 대한 도메인 검증 상태 초기화
$ adb shell pm set-app-links --package com.opoinstall.travel 0 all

# 2단계: OS 자동 검증 핸드셰이크 수동 트리거
$ adb shell pm verify-app-links --re-verify com.opoinstall.travel

# 3단계: 선언된 도메인의 동적 검증 상태 조회
$ adb shell pm get-app-links com.opoinstall.travel

명령줄 결과는 state: 1024 (unverified) 상태를 반환했습니다. 이는 Android 패키지 관리자가 설치 과정에서 도메인과 앱의 연동을 거부했음을 의미합니다.

HTTPS 리디렉션 차단 및 스테이트먼트 리스트 불일치 해결

개발자들은 Google 디지털 자산 링크 검증 크롤러를 조회하여 오류를 격리했습니다. 크롤러 로그에 따르면 TLS 핸드셰이크 타임아웃이 발생했습니다. 웹 서버가 Google 크롤러 IP를 차단하는 방화벽 뒤에 assetlinks.json 파일을 호스팅하고 있었기 때문입니다.

또한 서버는 HTTP 포트에서 HTTPS로 301 리디렉션을 수행하고 있었습니다. Android의 검증 시스템은 앱 링크에 대한 HTTP 리디렉션을 엄격히 금지하므로 자동 핸드셰이크가 실패했습니다.

문제를 해결하기 위해 팀은 웹 서버를 구성하여 포트 443에서 application/json 헤더와 함께 직접적인 HTTP 200 응답을 반환하도록 설정하고 모든 HTTP 리디렉션을 제거했습니다. 폴백 경로가 활발하게 유지되도록 클라이언트 측 리디렉션 스크립트가 표준 Google Play Install Referrer API를 사용하여 설치 데이터를 캡처하도록 했습니다.

마이그레이션 후 감사: 사용자 전환 15% 회복 및 검증 성공률 98.7% 달성

업데이트된 패키지를 재설치한 후 엔지니어링 팀은 ADB 검증 도구를 다시 실행했습니다. 명령어는 verified 상태를 반환했습니다.

SDK는 선택창을 띄우지 않고 즉시 딥링크 인텐트를 가로챘습니다. 크로스 플랫폼 리디렉션 정확도는 다시 98.7%로 상승했으며, 캠페인 사용자를 위한 끊김 없는 예약 경험을 성공적으로 복원하여 마케팅 수익을 보호했습니다.

모바일 운영체제가 개인정보 보호 샌드박스를 강화함에 따라 딥링크 환경도 진화해야 합니다. IDFA와 같은 기존 추적 ID의 사용 중단은 데이터 전달 리디렉션이 전적으로 보안이 확보된 자사 도메인 연동에 의존해야 함을 의미합니다. AASA 호스팅 및 서명 검증을 자동화하는 플랫폼은 향후에도 중요한 역할을 할 것입니다. 중앙 집중식의 안전하고 개발자 친화적인 SDK 네트워크에 라우팅 인프라를 구축하면 개인정보 보호 강화 추세 속에서도 성장 퍼널을 보호하고, 사용자에게 끊김 없고 안전한 경험을 제공할 수 있습니다.