웹 인텐트 확인

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

앱은 다음 중 하나를 실행하여 이 승인을 받을 수 있습니다.

앱에서 웹 인텐트를 호출하면 사용자에게 작업 확인을 요청하는 메시지나 대화상자를 추가하는 것이 좋습니다.

웹 인텐트 속성

웹 인텐트는 다음 특성이 포함된 인텐트입니다.

탐색 가능한 카테고리가 포함되어야 하는 웹 인텐트 필터

Android 12부터 웹 인텐트 필터는 주어진 웹 인텐트가 앱의 활동으로 확인되도록 CATEGORY_BROWSABLE 카테고리도 선언해야 합니다.

Android 8.0(API 수준 26) 이상에서 제공되는 Android App LinksDigital Asset Links API를 사용하여 특정 앱을 웹 도메인과 연결합니다. 이 연결을 통해 시스템은 도메인의 링크가 자동으로 열리도록 웹사이트에서 앱을 승인했다고 신뢰할 수 있습니다.

Android 12부터 수동으로 도메인 확인을 호출하여 시스템이 Android App Links를 확인하는 방법을 평가할 수 있습니다.

Android 12를 타겟팅하는 앱에서 시스템은 Android App Links를 확인하는 방법을 몇 가지 변경합니다. 이러한 변경사항은 앱 연결 환경의 안정성을 개선하고 앱 개발자와 최종 사용자에게 더 많은 제어권을 제공합니다. 수동으로 도메인 확인을 호출하여 선언의 안정성을 테스트할 수 있습니다.

Android 12를 타겟팅하고 Android App Links 확인을 사용하여 앱에서 웹 링크를 연다면 변경된 확인 프로세스를 지원하도록 Android App Links 선언을 업데이트하세요.

Android App Links 선언 업데이트

도메인 확인 프로세스는 인터넷 연결이 필요하고 완료하는 데 다소 시간이 걸릴 수 있습니다. 프로세스의 효율성을 개선할 수 있도록 시스템은 Android 12를 타겟팅하는 앱의 도메인이 특별히 형식이 지정된 <intent-filter> 요소 내에 있는 경우에만 이 도메인을 확인합니다. <intent-filter> 요소에는 다음 스니펫과 같이 작업, 카테고리, 체계가 포함되어야 합니다.

<!-- Make sure you explicitly set android:autoVerify to "true". -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.BROWSABLE" />
    <category android:name="android.intent.category.DEFAULT" />

    <!-- If a user clicks on a shared link that uses the "http" scheme, your
         app should be able to delegate that traffic to "https". -->
    <data android:scheme="http" />
    <data android:scheme="https" />

    <!-- Include one or more domains that should be verified. -->
    <data android:host="..." />
</intent-filter>

수동으로 도메인 확인 호출

Android 12부터 기기에 설치된 앱의 도메인 확인을 수동으로 호출할 수 있습니다. 앱의 Android 12 타겟팅 여부와 관계없이 이 프로세스를 실행할 수 있습니다.

인터넷 연결

도메인 확인을 실행하려면 테스트 기기가 인터넷에 연결되어 있어야 합니다.

업데이트된 도메인 확인 프로세스 지원

앱이 Android 12를 타겟팅한다면 시스템은 업데이트된 도메인 확인 프로세스를 자동으로 사용합니다.

자동으로 사용하지 않으면 업데이트된 확인 프로세스를 수동으로 사용 설정하면 됩니다. 이렇게 하려면 터미널 창에서 다음 명령어를 실행하세요.

adb shell am compat enable 175408749 PACKAGE_NAME

기기에서 Android App Links 상태 재설정

기기에서 수동으로 도메인 확인을 호출하기 전에 테스트 기기에서 Android App Links 상태를 재설정해야 합니다. 이렇게 하려면 터미널 창에서 다음 명령어를 실행하세요.

adb shell pm set-app-links --package PACKAGE_NAME 0 all

이 명령어는 사용자가 도메인의 기본 앱을 선택하기 전 기기의 상태와 같은 상태로 기기를 설정합니다.

도메인 확인 프로세스 호출

기기에서 Android App Links 상태를 재설정하면 확인 자체를 실행할 수 있습니다. 이렇게 하려면 터미널 창에서 다음 명령어를 실행하세요.

adb shell pm verify-app-links --re-verify PACKAGE_NAME

확인 결과 검토

확인 에이전트가 요청을 완료하도록 잠시 기다린 후 확인 결과를 검토합니다. 이렇게 하려면 다음 명령어를 실행하세요.

adb shell pm get-app-links PACKAGE_NAME

이 명령어 결과는 다음과 같습니다.

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

확인을 통과한 도메인의 도메인 확인 상태는 verified입니다. 그 외 다른 상태는 도메인 확인을 실행할 수 없음을 나타냅니다. 특히 none 상태는 확인 에이전트가 아직 확인 프로세스를 완료하지 않았을 수 있음을 나타냅니다.

다음 목록은 주어진 도메인의 도메인 확인에서 반환할 수 있는 가능한 반환 값을 보여줍니다.

none
이 도메인에는 기록된 것이 없습니다. 확인 에이전트가 도메인 확인 관련 요청을 완료하도록 몇 분 정도 더 기다린 후 다시 도메인 확인 프로세스를 호출합니다.
verified
선언하는 앱의 도메인이 성공적으로 확인되었습니다.
approved
일반적으로 셸 명령어를 실행하여 도메인이 강제 승인되었습니다.
denied
일반적으로 셸 명령어를 실행하여 도메인이 강제 거부되었습니다.
migrated
시스템이 기존 도메인 확인을 사용한 이전 프로세스의 결과를 유지했습니다.
restored
사용자가 데이터 복원을 실행한 후 도메인이 승인되었습니다. 도메인이 이전에 확인된 것으로 추정됩니다.
legacy_failure
기존 인증 도구에서 도메인이 거부되었습니다. 구체적인 실패 이유는 알 수 없습니다.
system_configured
도메인이 기기 설정에서 자동으로 승인되었습니다.
1024 이상의 오류 코드

기기의 인증 도구와 관련된 맞춤 오류 코드입니다.

네트워크 연결을 설정했는지 다시 확인한 후 도메인 확인 프로세스를 다시 호출합니다.

사용자에게 앱을 도메인과 연결하라고 요청

앱이 도메인 승인을 받는 또 다른 방법은 사용자에게 앱을 도메인과 연결하라고 요청하는 것입니다.

앱이 도메인 승인을 이미 받았는지 확인

사용자에게 메시지를 표시하기 전에 앱이 <intent-filter> 요소에서 정의한 도메인의 기본 핸들러인지 확인합니다. 다음 메서드 중 하나를 사용하여 승인 상태를 쿼리할 수 있습니다.

DomainVerificationManager

다음 코드 스니펫은 DomainVerificationManager API 사용 방법을 보여줍니다.

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState.hostToStateMap
    .filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the user
// has associated with an app.
val selectedDomains = userState.hostToStateMap
    .filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState.hostToStateMap
    .filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

자바

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user has
        // associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

명령줄 프로그램

개발하는 동안 앱을 테스트할 때 다음 명령어를 실행하여 조직에서 소유한 도메인의 확인 상태를 쿼리할 수 있습니다.

adb shell pm get-app-links --user cur PACKAGE_NAME

다음 출력 예에서 앱은 'example.org' 도메인 확인에 실패했지만 사용자 0은 시스템 설정에서 수동으로 앱을 승인했고 이 도메인에서 확인된 다른 패키지는 없습니다.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

요청 컨텍스트 제공

도메인 승인을 요청하기 전에 사용자에게 컨텍스트를 제공합니다. 예를 들어 앱이 특정 도메인의 기본 핸들러여야 하는 이유를 사용자에게 설명하는 스플래시 화면이나 대화상자, 유사한 UI 요소를 사용자에게 표시할 수 있습니다.

요청하기

사용자가 앱에서 요청하는 작업을 파악하면 요청을 실행합니다. 다음 코드 스니펫과 같이 ACTION_APP_OPEN_BY_DEFAULT_SETTINGS 인텐트 작업과 타겟 앱의 package:com.example.pkg와 일치하는 데이터 문자열이 포함된 인텐트를 호출합니다.

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

자바

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package: " + context.getPackageName()));
context.startActivity(intent);

인텐트가 호출되면 사용자에게 기본적으로 열기라는 설정 화면이 표시됩니다. 이 화면에는 그림 1과 같이 지원되는 링크 열기라는 라디오 버튼이 있습니다.

사용자가 지원되는 링크 열기를 사용 설정하면 이 앱에서 열리는 링크 섹션 아래에 일련의 체크박스가 표시됩니다. 여기에서 사용자는 앱과 연결하려는 도메인을 선택할 수 있고 그림 2와 같이 링크 추가를 선택하여 도메인을 추가할 수도 있습니다. 나중에 사용자가 추가한 도메인 내에서 링크를 선택하면 링크가 앱에서 자동으로 열립니다.

라디오 버튼을 사용 설정하면 하단의 섹션에 체크박스와 &#39;링크 추가&#39; 버튼이 포함됩니다.
그림 1. 사용자가 기본적으로 앱에서 열리는 링크를 선택할 수 있는 시스템 설정 화면
각 체크박스는 추가할 수 있는 도메인을 나타냅니다. 대화상자의 버튼은 &#39;취소&#39;와 &#39;추가&#39;입니다.
그림 2. 사용자가 앱과 연결할 추가 도메인을 선택할 수 있는 대화상자

수동으로 도메인 승인 전환

도메인 확인과 사용자 선택은 모두 셸 명령어를 사용하여 전환할 수 있습니다. 이 명령어를 사용하면 개발자가 디버깅이나 테스트 실행, 인터넷 연결이 없는 경우를 위한 적절한 상태를 수동으로 설정할 수 있습니다.

이러한 명령어에 관한 자세한 설명은 adb shell pm 출력에서 확인할 수 있습니다.

셸 명령어를 통해 승인된 때도 동일한 확인된 우선순위와 단일 승인 제한사항이 모두 적용되므로 두 앱 변형 동시 설치와 같은 일부 특수 사례에는 의도된 앱에서 주어진 웹 링크를 열려면 특별한 처리가 필요합니다.

확인된 여러 앱

각각 같은 도메인과 연결된 앱을 여러 개 게시하면 각각 성공적으로 확인될 수 있습니다. 그러나 앱의 라이트 및 전체 버전과 마찬가지로 앱이 똑같은 도메인 호스트 및 경로를 확인할 수 있다면 가장 최근에 설치된 앱만 도메인의 웹 인텐트를 확인할 수 있습니다.

이러한 경우 필요한 패키지 공개 상태가 있다면 사용자 기기에서 충돌 가능성이 있는 앱을 확인합니다. 그런 다음 앱에서 queryIntentActivities() 호출의 결과가 포함된 맞춤 선택기 대화상자를 표시합니다. 사용자는 대화상자에 표시되는 일치하는 앱 목록에서 선호하는 앱을 선택할 수 있습니다.

앱에서 앱이 확인할 수 없는 도메인 열기

앱의 기본 기능은 처리된 도메인을 확인하는 기능 없이 링크를 타사로 여는 것일 수 있습니다. 이 경우 사용자가 웹 링크를 선택할 때 자사 앱과 타사 앱 중에서 선택할 수 없다고 사용자에게 설명합니다. 사용자는 도메인을 타사 앱과 수동으로 연결해야 합니다.

또한 사용자가 원한다면 자사 앱에서 링크를 열 수 있는 대화상자나 트램펄린 활동을 도입하여 프록시 역할을 하도록 하는 것이 좋습니다. 이러한 대화상자나 트램펄린 활동을 설정하기 전에 앱의 웹 인텐트 필터와 일치하는 자사 앱에 관한 패키지 공개 상태를 보유하도록 앱을 설정합니다.