동적 링크에서 앱 링크 및 범용 링크로 마이그레이션

이 마이그레이션 가이드에서는 앱 사이트 연결 파일 호스팅하기 위해 앱 링크와 범용 링크 사용(선택적으로 Firebase 호스팅 사용)에 중점을 둡니다.

이 마이그레이션은 다음 Firebase 동적 링크 기능을 대체합니다.

특성	Firebase 동적 링크	앱 링크/범용 링크
링크 클릭 한 번으로 사용자를 기기의 올바른 스토어로 안내		^★
지연된 딥 링크를 사용하여 앱을 다운로드하고 설치한 후 사용자에게 연속된 여정 제공		^★
앱에서 딥 링크가 설정된 콘텐츠를 사용하여 컨텍스트 기반 환경 제공(이미 설치된 경우)
동적 링크 클릭 이벤트와 관련된 분석 데이터 제공
짧은 링크 URL을 만드는 기능 제공

마이그레이션에 이 가이드에서 지원하지 않는 다른 Firebase 동적 링크 기능이 계속 필요한 경우 동적 링크 지원 중단 FAQ 문서의 다른 마이그레이션 시나리오를 참조하세요.

다음과 같은 Firebase 동적 링크가 있다고 가정해 보겠습니다.

동적 링크 예시
링크 이름	Welcome to Example.com
딥 링크	`https://example.web.app/welcome`
Android 앱	`com.example.android`
Apple 앱	`com.example.ios`
긴 동적 링크	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
짧은 동적 링크	`https://example.page.link/m9Mm`

이 마이그레이션 가이드의 목표는 다음과 같은 Firebase 동적 링크를

https://example.page.link/m9Mm

다음과 같은 앱 링크/범용 링크 딥 링크로 대체하는 것입니다.

https://your-project-domain.web.app/welcome

앱 링크/범용 링크 딥 링크는 사용자에게 다음을 제공합니다.

이미 설치되었을 때 클릭하면 앱이 열리는 딥 링크
앱이 열렸을 때 사용자를 앱의 특정 부분으로 안내하는 연속된 사용자 여정

하지만 앱 링크/범용 링크 딥 링크는 이전에 Firebase 동적 링크에서 했던 것처럼 사용자에게 다음과 같은 동작을 제공하지 않습니다.

앱을 다운로드하고 설치할 수 있도록 기기의 올바른 스토어로 사용자를 안내
다운로드하고 설치한 뒤 앱을 처음 실행한 후 연속된 사용자 여정 제공

위 표에서 설명한 Firebase 동적 링크와 비교할 때 앱 링크/범용 링크의 동작 및 기능에 차이가 있습니다.

시작하기 전에

Firebase 동적 링크는 앱 링크(Android) 및 범용 링크(iOS)를 자체 기본 구현에서 활용하여 앱이 이미 설치된 후 딥 링크 기능을 제공합니다.

이 가이드에서는 Firebase 호스팅을 사용하여 자체 앱 링크 및 범용 링크를 만들어 Firebase 동적 링크에서 제공하는 기능의 일부를 대체하면서 Firebase 동적 링크를 새로운 앱 링크/범용 링크 마이그레이션 솔루션으로 마이그레이션하는 방법을 설명합니다.

마이그레이션을 완료하려면 다음 정보가 필요합니다.

마이그레이션하려는 Firebase 동적 링크
동적 링크에 포함된 딥 링크 URL 매개변수
이전 Firebase 동적 링크 도메인을 대체하는 데 사용할 도메인(해당하는 경우)

동적 링크 메타데이터 내보내기 가이드를 사용하여 기존 링크 메타데이터를 내보내고 위에 나열된 정보를 가져올 수 있습니다.

마이그레이션 단계 개요

Firebase 호스팅을 사용하여 앱 링크/범용 링크 구성 파일을 호스팅할 새 도메인(아직 사용할 도메인이 없는 경우)을 프로비저닝합니다.
호스팅 도메인에서 앱 링크/범용 링크 구성 파일을 만들고 호스팅합니다.
Firebase 동적 링크에 사용되는 딥 링크 스키마와 일치하는 새 앱 링크/범용 링크를 만듭니다.
딥 링크를 수신하려면 Android/iOS 앱과 애플리케이션 코드를 업데이트하세요.
앱 링크/범용 링크 통합을 테스트합니다.
게시 또는 공유된 Firebase 동적 링크를 앱 링크 및 범용 링크로 바꿉니다.

첫 번째 단계는 앱 링크 또는 범용 링크 마이그레이션 흐름 모두에서 공통적입니다. 나머지는 플랫폼에 따라 다르므로 먼저 마이그레이션하려는 플랫폼에 따라 아래의 가이드 섹션으로 이동하세요.

Android 앱 링크의 마이그레이션 단계
iOS 범용 링크의 마이그레이션 단계

Firebase 호스팅을 사용하여 앱 링크/범용 링크 구성 파일을 호스팅할 새 도메인 프로비저닝

도메인 선택

첫 번째 단계는 앱 링크/범용 링크에 사용할 도메인을 선택하는 것입니다. 이 도메인이 사용자에게 공유할 새 링크에 사용됩니다.

Firebase 호스팅을 사용하는 경우 your-project-domain.web.app 또는 your-project-domain.firebaseapp.com 형식의 프로젝트 하위 도메인이 무료로 자동 프로비저닝됩니다. Firebase 호스팅 유무와 관계없이 커스텀 도메인을 사용하여 앱 링크/범용 링크 구성 파일을 호스팅할 수도 있습니다.

Firebase 호스팅 설정

다음으로 Firebase 호스팅 인스턴스를 설정하고 구성해야 합니다.

Firebase 호스팅 인스턴스 설정이 완료되면 your-project-domain.web.app과 유사한 도메인이나 원하는 경우 커스텀 도메인이 생성됩니다.

Android 앱 링크의 마이그레이션 단계

새 호스팅 도메인에서 앱 링크 구성 파일 만들기 및 호스팅

앱 링크를 사용하려면 링크에서 사용하는 도메인과 앱에 보안 연결을 설정하는 데 도움이 되는 구성 파일을 호스팅해야 합니다. 앱 링크의 경우 assetlinks.json 파일입니다.

assetlinks.json 파일을 만들고 호스팅하는 단계

assetlinks.json 파일을 사용하면 앱 링크에 사용할 웹 도메인의 콘텐츠를 처리할 수 있는 승인된 앱 목록을 제공할 수 있습니다. assetlinks.json 파일 자체는 웹 도메인 루트의 /.well-known 경로에 호스팅되어야 합니다.

이 구성을 완료하려면 아래 단계를 따르세요.

Firebase 호스팅 루트 디렉터리의 공개 폴더 아래에 .well-known 폴더를 만듭니다.
.well-known 폴더 아래에 assetlinks.json이라는 파일을 만듭니다.
다음 콘텐츠를 assetlinks.json 파일에 복사하고 아래 각 필드의 의미를 기록해 둡니다.
```
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.android",
    "sha256_cert_fingerprints":
      ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
  }
}]
```
- namespace - 제공하려는 애플리케이션의 이름을 나타냅니다.
- package_name - 앱의 build.gradle 파일에 선언된 applicationId를 나타냅니다.
- sha256_cert_fingerprints - 애플리케이션 서명에 사용하는 키 저장소 파일의 SHA256 디지털 지문을 나타냅니다.
Android 스튜디오에서 사용하는 debug.keystore 파일을 사용하여 디버깅 목적으로 sha256_cert_fingerprints 레코드를 생성할 수 있습니다. Mac과 Linux의 경우 /Users/<username>/.android/debug.keystore, Windows의 경우 C:\Users\<username>\.android\debug.keystore에서 파일을 찾을 수 있습니다.

이 키 저장소에서 Keytool을 사용하여 SHA256 값을 가져올 수 있습니다.

이 단계를 완료하는 방법에 대한 자세한 내용은 앱 링크 문서의 이 섹션을 참조하세요.

또는 Android 스튜디오의 App Links Assistant를 사용하여 assetlinks.json 파일 콘텐츠를 생성하고 앱 링크를 처리하도록 애플리케이션을 구성할 수도 있습니다.

호스팅용 파일의 색인을 생성하도록 firebase.json 파일을 업데이트합니다.

"headers": [
  {
    "source": "/.well-known/assetlinks.json",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

assetlinks.json 파일이 준비되었으므로 firebase deploy를 실행하여 변경사항을 호스팅합니다.

위의 deploy 명령어를 실행하려면 Firebase CLI를 설치해야 합니다.
```
firebase deploy --only hosting
```
https://your-project-domain.web.app/.well-known/assetlinks.json으로 이동하여 assetlinks.json 파일을 확인합니다.

Firebase 동적 링크에 사용되는 딥 링크 스키마와 일치하는 새 앱 링크 만들기

이 단계에서는 앱 링크에 대해 만든 새 도메인과 일치하는 일반 딥 링크 URL을 사용하여 Firebase 동적 링크에서 딥 링크를 다시 만듭니다.

예를 들어 다음과 같은 Firebase 동적 링크가 있다고 가정해 보겠습니다.

동적 링크 예시
링크 이름	Welcome to Example.com
딥 링크	`https://example.web.app/welcome`
Android 앱	`com.example.android`
Apple 앱	`com.example.ios`
긴 동적 링크	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
짧은 동적 링크	`https://example.page.link/m9Mm`

이 경우 딥 링크 매개변수(예: https://example.web.app/welcome)를 추출하여 이 매개변수를 앱의 앱 링크 매개변수로 사용합니다.

앱 링크/범용 링크를 사용하여 마이그레이션하려는 각 Firebase 동적 링크에 대해 이 프로세스를 반복하고 사용한 딥 링크 스키마를 복제하는 것이 좋습니다.

예를 들어 다음과 같은 Firebase 동적 링크 짧은 링크, 딥 링크 매개변수, 마이그레이션된 딥 링크 값의 집합을 참조하세요.

짧은 링크	딥 링크 매개변수	마이그레이션된 딥 링크
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

그런 다음 게시 또는 공유된 Firebase 동적 링크의 인스턴스를 새로 마이그레이션된 딥 링크로 대체하여 사용자가 이전 Firebase 동적 링크 대신 해당 앱 링크를 클릭하도록 해야 합니다.

딥 링크를 수신하도록 Android 앱 및 애플리케이션 코드 업데이트

도메인을 선택하고, 딥 링크 스키마를 선택하고, Firebase 동적 링크를 앱 링크로 마이그레이션한 후 다음 단계는 새로운 딥 링크를 수신하도록 Android 앱과 애플리케이션 코드를 업데이트하는 것입니다.

여기에서 앱 링크 문서 전체를 참조하거나 딥 링크를 처리하도록 앱을 구성하는 방법에 관한 Android 스튜디오 가이드를 따르는 것이 좋습니다. 주요 단계는 다음과 같습니다.

각 딥 링크를 처리해야 하는 활동 식별
AndroidManifest.xml에 이러한 활동의 인텐트 필터 추가
활동의 애플리케이션 코드에서 딥 링크 수신

MainActivity를 사용하여 일부 딥 링크를 처리하려 한다고 가정해 보겠습니다. 이렇게 하려면 AndroidManifest.xml 파일의 MainActivity에 다음 인텐트 필터를 추가해야 합니다.

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <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:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

이 단계에서는 MainActivity가 wxample.web.app 도메인의 딥 링크를 처리하기 위한 대상이며 /welcome 경로 프리픽스가 포함되어 있음을 지정합니다. 또한 이 특정 유형의 링크를 위한 기본 핸들러로 앱을 지정할 수 있는 android:autoVerify="true" 속성을 지정해야 합니다.

마지막으로 MainActivity에 코드를 추가하여 딥 링크 데이터를 검색하고 이를 사용하여 앱에서 딥 링크 환경을 제공해야 합니다. 이는 Firebase 동적 링크와 통합할 때 앱에 이미 코딩한 로직과 유사합니다.

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

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

앱 링크 테스트

실제 기기나 Android Emulator에서 앱을 실행하여 방금 만든 앱 링크를 테스트할 수 있습니다.

앱 링크에 구성된 도메인을 사용하여 클릭 가능한 링크를 만든 후 해당 링크를 클릭하여 앱이 열리고 의도한 활동으로 이동하는지 확인합니다.

또는 Android 스튜디오에서 App Links Assistant를 사용하여 앱 링크 통합을 테스트하거나 구성한 앱 링크 URL에 다음 명령어를 사용하여 일치하는 활동을 올바르게 실행하는지 확인합니다.

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

게시 또는 공유된 Firebase 동적 링크를 앱 링크로 대체

마이그레이션의 마지막 단계는 가능한 경우 게시 또는 공유된 Firebase 동적 링크를 앱 링크로 대체하고 앞으로 앱 링크를 계속 사용하는 것입니다.

이 단계를 완료하는 방법은 Firebase 동적 링크를 게시하는 위치와 방법에 따라 다르지만, 존재하는 Firebase 동적 링크를 추적하는 데 도움이 되도록 기존 Firebase 동적 링크 메타데이터를 내보낼 수 있습니다. 동적 링크 메타데이터 내보내기 가이드를 참조하세요.

iOS 범용 링크의 마이그레이션 단계

새 호스팅 도메인에서 범용 링크 구성 파일 만들기 및 호스팅

범용 링크를 사용하려면 링크에서 사용하는 도메인과 앱에 보안 연결을 설정하는 데 도움이 되는 구성 파일을 호스팅해야 합니다. 범용 링크의 경우 apple-app-site-association 파일(AASA 파일이라고도 함)입니다.

apple-app-site-association 파일을 만들고 호스팅하는 단계

AASA 파일을 사용하면 범용 링크에 사용할 웹 도메인의 콘텐츠를 처리할 수 있는 승인된 앱 목록을 제공할 수 있습니다. AASA 파일 자체는 웹 도메인 루트의 /.well-known 경로에 호스팅되어야 합니다.

이 구성을 완료하려면 아래 단계를 따르세요.

Firebase 호스팅 루트 디렉터리의 공개 폴더 아래에 '.well-known' 폴더를 만듭니다.
'.well-known' 폴더에 'apple-app-site-association'이라는 파일을 만듭니다.
다음 콘텐츠를 apple-app-site-association 파일에 복사하고 아래 각 필드의 의미를 기록해 둡니다.
```
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appId": "$TEAM_ID.com.firebase.UniversalLinks",
        "paths": [
          "NOT /_/*",
          "/*"
        ]
      }
    ]
  }
}
```
- $TEAM_ID.BundleId - 링크 처리를 승인받은 정규화된 애플리케이션 이름

호스팅용 파일의 색인을 생성하도록 firebase.json 파일을 업데이트합니다.

"headers": [
  {
    "source": "/.well-known/apple-app-site-association",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

이제 AASA 파일이 준비되었으므로 firebase deploy를 실행하여 변경사항을 호스팅합니다.
https://your-project-domain.web.app/.well-known/app-app-site-association으로 이동하여 AASA 파일을 확인합니다.

Firebase 동적 링크에 사용되는 딥 링크 스키마와 일치하는 새 범용 링크 만들기

이 단계에서는 범용 링크에 대해 만든 새 도메인과 일치하는 일반 딥 링크 URL을 사용하여 Firebase 동적 링크에서 딥 링크를 다시 만듭니다.

예를 들어 다음과 같은 Firebase 동적 링크가 있다고 가정해 보겠습니다.

동적 링크 예시
링크 이름	Welcome to Example.com
딥 링크	`https://example.web.app/welcome`
Android 앱	`com.example.android`
Apple 앱	`com.example.ios`
긴 동적 링크	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
짧은 동적 링크	`https://example.page.link/m9Mm`

이 경우 딥 링크 매개변수(예: https://example.web.app/welcome)를 추출하여 이 매개변수를 앱의 범용 링크 매개변수로 사용합니다.

예를 들어 다음과 같은 Firebase 동적 링크 짧은 링크, 딥 링크 매개변수, 마이그레이션된 딥 링크 값의 집합을 참조하세요.

짧은 링크	딥 링크 매개변수	마이그레이션된 딥 링크
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

그런 다음 게시 또는 공유된 Firebase 동적 링크의 인스턴스를 새로 마이그레이션된 딥 링크로 대체하여 사용자가 이전 Firebase 동적 링크 대신 해당 범용 링크를 클릭하도록 해야 합니다.

딥 링크를 수신하도록 iOS 앱 및 애플리케이션 코드 업데이트

도메인을 선택하고, 딥 링크 스키마를 선택하고, Firebase 동적 링크를 범용 링크로 마이그레이션한 후 다음 단계는 새로운 딥 링크를 수신하도록 iOS 앱과 애플리케이션 코드를 업데이트하는 것입니다.

딥 링크를 처리하도록 앱을 구성하는 방법에 관한 여기의 전체 범용 링크 문서를 따르는 것이 좋습니다. 주요 단계는 다음과 같습니다.

앱이 새로 생성된 도메인의 딥 링크를 처리할 수 있도록 프로젝트 구성 업데이트
애플리케이션 코드에서 딥 링크 수신

앱이 딥 링크를 처리할 수 있도록 프로젝트 구성을 업데이트하려면 이제 apple-app-site-associate 파일을 호스팅하는 데 사용하려는 도메인에 대해 xCode의 프로젝트에 연결된 도메인을 추가해야 합니다.

방법은 다음과 같습니다.

Xcode 열기
파일 탐색기에서 프로젝트 선택
프로젝트 설정의 서명 및 기능 탭으로 이동
연결된 도메인 섹션으로 이동
+ 버튼을 클릭하여 추가 도메인을 프로젝트에 'applinks:' 형식으로 추가합니다.

마지막으로 수신되는 딥 링크를 수신할 수 있도록 애플리케이션 코드를 업데이트해야 합니다.

이를 위해 먼저 다음 코드를 추가하여 범용 링크에 응답하도록 AppDelegate.swift 파일을 업데이트합니다.

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

위의 코드는 범용 링크 콜백 메서드를 재정의하고 딥 링크 URL이 있는 경우 이를 로깅합니다.

이제 SceneDelegate 클래스에서 동일한 showReceivedUrl 메서드도 호출하겠습니다. 사용자가 범용 링크를 클릭할 때 이미 앱이 열려 있다면 SceneDelegate 내부의 범용 링크 콜백이 호출되기 때문입니다.

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

범용 링크 테스트

실제 기기 또는 시뮬레이터에서 앱을 실행하여 방금 만든 범용 링크를 테스트할 수 있습니다.

범용 링크에 구성된 도메인을 사용하여 클릭 가능한 링크를 만든 후 해당 링크를 클릭하여 앱이 열리고 앱에서 의도한 화면으로 이동하는지 확인합니다.

스마트 앱 배너 지원

사용자에게 Firebase 동적 링크와 유사한 환경을 제공하려면 스마트 앱 배너를 사용하는 것이 좋습니다.

스마트 앱 배너를 사용하면 기기에 앱이 설치되어 있지 않은 사용자가 앱 등록정보의 App Store로 연결됩니다. 원하는 경우 앱을 다운로드하여 설치한 후 앱에 전달할 매개변수를 구성하여 사용자에게 연속된 여정을 제공할 수 있습니다. 앱이 설치되어 있는 경우 앱에 매개변수를 전달하여 사용자가 클릭한 스마트 앱 배너에 따라 적절한 콘텐츠로 사용자를 안내할 수 있습니다.

게시 또는 공유된 Firebase 동적 링크를 앱 링크로 대체

마이그레이션의 마지막 단계는 가능한 경우 게시 또는 공유된 Firebase 동적 링크를 범용 링크로 대체하고 앞으로 범용 링크를 계속 사용하는 것입니다.

이 단계를 완료하는 방법은 Firebase 동적 링크를 게시하는 위치와 방법에 따라 다릅니다.

마이그레이션될 기존 Firebase 동적 링크를 추적할 수 있도록 Firebase 동적 링크에서 짧은 링크 메타데이터를 내보내는 방법에 대한 가이드를 게시할 예정입니다. 자세한 내용은 동적 링크 지원 중단 FAQ 문서를 참조하세요.