從 Dynamic Links 遷移至應用程式連結 &

本遷移指南著重於使用應用程式連結和通用連結，並選擇性使用 Firebase Hosting 代管應用程式與網站關聯檔案。

這項遷移作業會取代下列 Firebase Dynamic Links 功能：

如果遷移作業仍需要本指南未涵蓋的 Firebase Dynamic Links 功能，請參閱Dynamic Links 淘汰常見問題說明文件中的其他遷移情境。

假設您有如下所示的 Firebase 動態連結：

本遷移指南的目標是取代 Firebase Dynamic Links，如下所示：

https://example.page.link/m9Mm

使用應用程式連結 / 通用連結深層連結，如下所示：

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

請注意，應用程式連結 / 通用連結深層連結會為使用者提供下列功能：

• 使用者點選後會開啟應用程式的深層連結 (如果已安裝)
• 延續使用者歷程，在開啟應用程式時將使用者帶往特定部分

不過，應用程式連結 / 通用連結深層連結不會為使用者提供下列行為 (Firebase Dynamic Links 先前會提供)：

• 將使用者導向裝置適用的商店，下載及安裝您的應用程式
• 在使用者下載、安裝及首次開啟應用程式後，繼續提供使用者體驗

請注意，與 Firebase 動態連結相比，這些應用程式連結 / 通用連結的行為和功能有所不同，詳情請參閱上表。

事前準備

Firebase Dynamic Links 會在底層實作中採用應用程式連結 (Android) 和通用連結 (iOS)，以便在應用程式安裝完成後提供深層連結功能。

本指南將逐步說明如何使用 Firebase Hosting 建立自己的應用程式連結和通用連結，取代 Firebase 動態連結提供的部分功能，同時將 Firebase 動態連結遷移至新的應用程式連結 / 通用連結遷移解決方案。

如要完成遷移作業，您需要下列資訊：

• 您打算遷移的 Firebase 動態連結
• 動態連結中包含的深層連結網址參數
• 您打算用來取代先前 Firebase Dynamic Links 網域的網域 (如適用)

您可以參閱匯出動態連結中繼資料指南，匯出現有連結中繼資料，並取得上述資訊。

遷移步驟總覽

1. 使用 Firebase Hosting 佈建新網域 (如果沒有要使用的網域)，以代管應用程式連結 / 通用連結設定檔。

2. 在代管網域中建立並代管應用程式連結 / 通用連結設定檔。

3. 建立與 Firebase Dynamic Links 中使用的深層連結結構定義相符的新應用程式連結 / 通用連結。

4. 更新 Android / iOS 應用程式和應用程式碼，以接收深層連結。

5. 測試應用程式連結 / 通用連結整合。

6. 將已發布或共用的 Firebase 動態連結替換為應用程式連結和通用連結。

無論是應用程式連結或通用連結遷移流程，第一步都是相同的。其餘步驟會因平台而異，因此請根據您想先遷移的平台，前往下方指南的相關章節。

• Android 應用程式連結的遷移步驟
• iOS 通用連結的遷移步驟

使用 Firebase Hosting 佈建新網域，代管應用程式連結 / 通用連結設定檔

選擇網域

首先，請選擇要用於應用程式連結/通用連結的網域。這個網域將用於您分享給使用者的全新連結。

如果您使用 Firebase Hosting，系統會自動免費佈建 your-project-domain.web.app 或 your-project-domain.firebaseapp.com 格式的專案子網域。您也可以選擇使用自訂網域 (無論是否搭配 Firebase 託管)，代管應用程式連結 / 通用連結設定檔。

設定 Firebase 託管

接著，您需要設定及配置 Firebase Hosting 執行個體。

設定 Firebase 託管執行個體後，您會取得類似 your-project-domain.web.app 的網域，或視需要取得自訂網域。

Android 應用程式連結的遷移步驟

在新代管網域中建立及代管應用程式連結設定檔

如要使用應用程式連結，您必須代管設定檔，協助在連結中使用的網域與應用程式之間建立安全關聯。如果是應用程式連結，這個檔案就是 assetlinks.json 檔案。

建立及代管 assetlinks.json 檔案的步驟

assetlinks.json 檔案可讓我們提供授權應用程式清單，這些應用程式可處理我們將用於應用程式連結的網域內容。assetlinks.json 檔案本身必須託管在網域根目錄中，路徑為 /.well-known。

請按照下列步驟完成這項設定：

1. 在 Firebase Hosting 根目錄的 public 資料夾下建立 .well-known 資料夾。

2. 在 .well-known 資料夾下建立名為 assetlinks.json 的檔案。

3. 將下列內容複製到 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 Studio 採用的 debug.keystore 檔案，產生 sha256_cert_fingerprints 記錄，以利偵錯。您可以在 Mac 和 Linux 的 /Users/<username>/.android/debug.keystore，以及 Windows 的 C:\Users\<username>\.android\debug.keystore 中找到檔案。

   您可以使用 keytool 從這個金鑰儲存區擷取 SHA256 值。

   如需完成這個步驟的更多操作說明，請參閱應用程式連結說明文件的這個部分。

   您也可以使用 Android Studio 中的 App Links Assistant，產生 assetlinks.json 檔案內容，並設定應用程式處理應用程式連結。

4. 更新 firebase.json 檔案，為託管服務建立檔案索引。

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

5. 現在我們已設定好 assetlinks.json 檔案，請執行 firebase deploy 來代管變更。

   請注意，您必須安裝 Firebase CLI，才能執行上述部署指令。

   firebase deploy --only hosting
   

6. 前往 https://your-project-domain.web.app/.well-known/assetlinks.json

建立與 Firebase 動態連結所用深層連結結構定義相符的應用程式連結

在這個步驟中，您將使用與為應用程式連結建立的新網域相符的一般深層連結網址，重新建立 Firebase 動態連結中的深層連結。

舉例來說，假設您有下列 Firebase 動態連結：

在這種情況下，您會擷取深層連結參數 (即 https://example.web.app/welcome)，並將其做為應用程式的應用程式連結參數。

針對要改用應用程式連結 / 通用連結的每個 Firebase 動態連結，重複這個程序，並複製您使用的深層連結結構定義。

舉例來說，請參閱下列 Firebase 動態連結短網址、深層連結參數和遷移的深層連結值：

接著，您需要將所有已發布或分享的 Firebase Dynamic Links 執行個體，替換為新的遷移深層連結，這樣使用者就會點選這些應用程式連結，而不是先前的 Firebase Dynamic Links。

更新 Android 應用程式和應用程式程式碼，接收深層連結

選取網域、選擇深層連結結構定義，並將 Firebase 動態連結遷移至應用程式連結後，下一步就是更新 Android 應用程式和應用程式程式碼，以接收新的深層連結。

建議您參閱這份完整的應用程式連結說明文件，或這份 Android Studio 指南，瞭解如何設定應用程式來處理深層連結。主要步驟包括：

1. 找出應處理各深層連結的活動
2. 在 AndroidManifest.xml 檔案中為這些活動新增意圖篩選器
3. 在活動的應用程式程式碼中接收深層連結

假設您想使用 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 模擬器上執行應用程式。

您必須使用為應用程式連結設定的網域建立可點選的連結，然後點選該連結，確保連結會開啟應用程式並將您導向預期活動。

您也可以使用 Android Studio 中的 App Links Assistant 測試應用程式連結整合，或使用下列指令，針對您設定的應用程式連結網址進行測試，確保系統能正確啟動相符的活動：

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

將已發布或共用的 Firebase 動態連結替換為應用程式連結

遷移的最後一個步驟是盡可能以應用程式連結取代已發布或共用的 Firebase Dynamic Links，並繼續使用應用程式連結。

完成這個步驟的方式，取決於您發布 Firebase Dynamic Links 的位置和方式，但為了協助您追蹤現有連結，您可以匯出現有的 Firebase Dynamic Links 中繼資料。請參閱匯出動態連結中繼資料指南。

iOS 通用連結的遷移步驟

在新的代管網域中建立及代管通用連結設定檔

如要使用通用連結，您必須代管設定檔，協助在連結中使用的網域與應用程式之間建立安全關聯。如果是通用連結，這個檔案就是 apple-app-site-association 檔案 (也稱為 AASA 檔案)。

建立及代管 apple-app-site-association 檔案的步驟

AASA 檔案可讓我們提供授權應用程式清單，這些應用程式可處理我們將用於通用連結的網域內容。AASA 檔案本身必須代管在網域根目錄的 /.well-known 路徑下。

請按照下列步驟完成這項設定：

1. 在 Firebase Hosting 根目錄的公開資料夾下，建立「.well-known」資料夾。

2. 在「.well-known」資料夾下建立名為「apple-app-site-association」的檔案。

3. 將下列內容複製到 apple-app-site-association 檔案，並注意以下各個欄位的意義：

   {
     "applinks": {
       "apps": [],
       "details": [
         {
           "appID": "$TEAM_ID.com.firebase.UniversalLinks",
           "paths": [
             "NOT /_/*",
             "/*"
           ]
         }
       ]
     }
   }
   

   • $TEAM_ID.BundleId - 獲授權處理連結的完整應用程式名稱

4. 更新 firebase.json 檔案，為託管服務建立檔案索引。

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

5. 現在我們已備妥 AASA 檔案，請執行 firebase deploy 來代管變更。

6. 前往 https://your-project-domain.web.app/.well-known/app-app-site-association 驗證 AASA 檔案

建立與 Firebase 動態連結中使用的深層連結結構定義相符的通用連結

在這個步驟中，您將使用與為通用連結建立的新網域相符的一般深層連結網址，重新建立 Firebase Dynamic Links 中的深層連結。

舉例來說，假設您有下列 Firebase 動態連結：

在這種情況下，您會擷取深層連結參數 (即 https://example.web.app/welcome)，並將此參數做為應用程式的通用連結參數。

針對要改用應用程式連結 / 通用連結的每個 Firebase 動態連結，重複這個程序，並複製您使用的深層連結結構定義。

舉例來說，請參閱下列 Firebase 動態連結短網址、深層連結參數和遷移的深層連結值：

接著，您需要將所有已發布或分享的 Firebase 動態連結例項，替換為新的遷移深層連結，這樣使用者就會點選這些通用連結，而不是先前的 Firebase 動態連結。

更新 iOS 應用程式和應用程式程式碼，接收深層連結

選取網域、選擇深層連結結構，並將 Firebase 動態連結遷移至通用連結後，下一步就是更新 iOS 應用程式和應用程式程式碼，以接收新的深層連結。

建議您參閱這份通用連結完整文件，瞭解如何設定應用程式來處理深層連結，但主要步驟包括：

1. 更新專案設定，讓應用程式處理來自新建立網域的深層連結

2. 在應用程式程式碼中接收深層連結

如要更新專案設定，讓應用程式處理深層連結，您必須在 Xcode 中為專案新增相關聯的網域，也就是您現在打算用來託管 apple-app-site-associate 檔案的網域。

方法如下：

1. 開啟 Xcode
2. 在檔案導覽器中選取專案
3. 前往專案設定的「簽署與功能」分頁
4. 向下捲動至「關聯網域」部分
5. 按一下「+」按鈕，以「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)
}

上述程式碼會覆寫通用連結回呼方法，並記錄深層連結網址 (如有)。

現在我們也會從 SceneDelegate 類別呼叫相同的 showReceivedUrl 方法，因為如果使用者點按通用連結時應用程式已開啟，系統會叫用 SceneDelegate 內的通用連結回呼。

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

測試通用連結

如要測試剛建立的通用連結，請在實體裝置或模擬器上執行應用程式。

您需要使用為通用連結設定的網域建立可點選的連結，然後點選該連結，確保連結會在應用程式中開啟，並將您導向應用程式中的預期畫面。

支援智慧型應用程式橫幅廣告

強烈建議您使用智慧應用程式橫幅，為使用者提供類似 Firebase 動態連結的體驗。

如果使用者尚未在裝置上安裝您的應用程式，系統會使用智慧型應用程式橫幅，將他們帶往應用程式的 App Store 資訊頁面。您也可以選擇設定參數，在應用程式下載及安裝後傳遞至應用程式，讓使用者繼續完成流程。如果已安裝應用程式，系統會開啟應用程式，並將參數傳遞至應用程式，根據使用者點選的智慧型應用程式橫幅，協助使用者前往適當的內容。

將已發布或共用的 Firebase 動態連結替換為應用程式連結

遷移的最後一個步驟是盡可能以通用連結取代已發布或共用的 Firebase 動態連結，並繼續使用通用連結。

完成這個步驟的方式會因發布 Firebase 動態連結的位置和方式而異。

為協助您追蹤要遷移的現有 Firebase Dynamic Links，我們將發布指南，說明如何從 Firebase Dynamic Links 匯出簡短連結中繼資料。如需最新消息，請參閱「動態連結淘汰常見問題」文件。