從 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 Dynamic Links 有所不同。

事前準備

Firebase Dynamic Links 會在其本身的基礎實作中使用應用程式連結 (在 Android 上) 和通用連結 (在 iOS 上)，以便在應用程式安裝完成後提供深層連結功能。

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

您需要提供下列資訊才能完成遷移作業：

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

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

遷移步驟總覽

1. 如果您尚未有要使用的網域，請佈建新的網域，以便使用 Firebase 代管服務代管應用程式連結 / 通用連結設定檔。

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

3. 建立新的應用程式連結 / 通用連結，以符合 Firebase 動態連結中使用的深層連結架構。

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

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

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

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

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

使用 Firebase 託管功能，配置新的網域來代管 App Link / 通用連結設定檔

選擇網域

第一步是選擇要用於應用程式連結/通用連結的網域。這個網域會用於您要分享給使用者的新連結。

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

設定 Firebase 託管

接下來，您需要設定 Firebase 代管執行個體。

設定 Firebase 託管例項後，您將擁有類似 your-project-domain.web.app 的網域，或者您偏好的自訂網域。

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

在新託管網域上建立及代管 App Link 設定檔

如要使用 App Links，您必須代管設定檔，以便在連結和應用程式使用的網域之間建立安全關聯。對於 App Links，這就是 assetlinks.json 檔案。

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

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

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

1. 在 Firebase 代管根目錄的 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 從這個 KeyStore 擷取 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 驗證 assetlinks.json 檔案

建立新的應用程式連結，與 Firebase 動態連結中使用的深層連結架構相符

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

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

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

請針對每個要遷移至應用程式連結 / 通用連結的 Firebase 動態連結，重複這個程序，並複製您使用的深層連結配置。

例如，請參閱下列 Firebase Dynamic Links 短連結、深層連結參數和已遷移的深層連結值：

接著，您需要將已發布或共用的所有 Firebase Dynamic Links 例項，替換為新遷移的深層連結，這樣使用者就會點選這些應用程式連結，而非先前的 Firebase Dynamic Links。

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

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

如要設定應用程式以處理深層連結，建議您參閱 這裡的完整應用程式連結說明文件，或是 Android Studio 指南。主要步驟如下：

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

假設您想使用 MainActivity 處理部分深層連結。如要執行這項操作，您必須在 AndroidManifest.xml 檔案的 MainActivity 中加入下列 Intent 篩選器：

<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 Studio 中的 App Links Assistant 測試應用程式連結整合功能，或是針對已設定的應用程式連結網址使用下列指令，確保系統能正確啟動相符的活動：

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

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

遷移作業的最後一個步驟，就是盡可能使用 App Links 取代已發布或共用的 Firebase Dynamic Links，並繼續使用 App Links。

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

iOS 版通用連結的遷移步驟

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

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

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

透過 AASA 檔案，我們可以提供一覽表，列出可處理通用連結所用網域內容的授權應用程式。AASA 檔案本身必須代管在網域根目錄的 /.well-known 路徑下。

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

1. 在 Firebase 代管根目錄的公開資料夾下建立「.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 部署作業，以便代管變更。

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

建立新的通用連結，與 Firebase 動態連結中使用的深層連結架構相符

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

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

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

請針對每個要遷移至應用程式連結 / 通用連結的 Firebase 動態連結，重複這個程序，並複製您使用的深層連結配置。

例如，請參閱下列 Firebase Dynamic Links 短連結、深層連結參數和已遷移的深層連結值：

接著，您需要將已發布或共用的任何 Firebase 動態連結，替換為新遷移的深層連結，這樣使用者就會點選這些通用連結，而非先前的 Firebase 動態連結。

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

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

如要設定應用程式以處理深層連結，建議您參閱 這裡的通用連結說明文件，但主要步驟包括：

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

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

如要更新專案設定，讓應用程式能夠處理深層連結，您必須在 xCode 中為要用來代管 apple-app-site-associate 檔案的網域，新增額外的 Associated Domain。

方法如下：

1. 開啟 Xcode
2. 在檔案總管中選取專案
3. 前往專案設定的「Signing & Capabilities」(簽署與功能) 分頁
4. 向下捲動至「Associated Domains」(關聯網域) 部分
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 中的通用連結回呼，因此我們現在也會從 SceneDelegate 類別呼叫相同的 showReceivedUrl 方法。

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

測試通用連結

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

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

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

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

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

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

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

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

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