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

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

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

如果遷移作業仍需使用本指南不支援的其他 Firebase Dynamic Links 功能，請參閱 Dynamic Links 淘汰常見問題說明文件，瞭解其他遷移情境。

假設您有下列 Firebase Dynamic Link：

本遷移指南的目標是取代 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 Dynamic Links 提供的部分功能，同時將 Firebase Dynamic Links 遷移至新的應用程式連結/通用連結遷移解決方案。

您需要下列資訊才能完成遷移：

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

您可以參閱匯出 Dynamic Links 中繼資料指南，瞭解如何匯出現有連結中繼資料，並取得上述資訊。

遷移步驟總覽

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

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

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

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

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

6. 將已發布或分享的 Firebase Dynamic Links 替換為應用程式連結和通用連結。

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

• 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。

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

1. 在 Firebase 託管根目錄的公用資料夾下，建立 .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 值。

   如需完成這個步驟的操作說明，請參閱 App Links 說明文件的這一節。

   您也可以使用 Android Studio 中的應用程式連結小幫手，產生 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 Dynamic Links 使用的深層連結結構定義相符

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

舉例來說，假設您有下列 Firebase Dynamic Link：

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

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

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

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

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

選取網域、選擇深層連結結構定義，並將 Firebase Dynamic Links 遷移至應用程式連結後，下一步是更新 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 Dynamic Links 時，可能已在應用程式中編寫的邏輯類似。

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 中使用應用程式連結小幫手測試應用程式連結整合，或使用下列指令，確保已設定的應用程式連結網址能正確啟動相應活動：

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

將已發布或分享的 Firebase Dynamic Links 替換為應用程式連結

遷移的最後一個步驟，是盡可能將已發布或分享的 Firebase Dynamic Links 替換為 App Links，並在日後繼續使用 App Links。

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

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 deploy 來託管變更。

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

建立新的通用連結，並與 Firebase Dynamic Links 使用的深層連結結構定義相符

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

舉例來說，假設您有下列 Firebase Dynamic Link：

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

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

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

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

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

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

建議您按照這份完整的通用連結說明文件，設定應用程式來處理深層連結，主要步驟包括：

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

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

如要更新專案設定，讓應用程式能夠處理深層連結，您必須在 xCode 中為專案新增關聯網域，用於託管 apple-app-site-associate 檔案。

方法如下：

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 類別呼叫相同的 showReceivedUrl 方法，因為如果使用者點選通用連結時，應用程式已開啟，系統就會叫用 SceneDelegate 內的通用連結回呼。

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

測試通用連結

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

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

支援智慧型應用程式橫幅

強烈建議您使用智慧型應用程式橫幅廣告，為使用者提供類似 Firebase Dynamic Links 的體驗。

如果使用者尚未在裝置上安裝應用程式，智慧型應用程式橫幅廣告會將他們帶往應用程式商店的應用程式資訊頁面。您也可以選擇設定參數，在應用程式下載並安裝後傳遞至應用程式，讓使用者能接續先前的操作。如果使用者已安裝應用程式，系統會開啟應用程式並傳遞參數，根據使用者點選的智慧型應用程式橫幅，將他們導向適當的內容。

將已發布或分享的 Firebase Dynamic Links 替換為應用程式連結

遷移的最後一步，是盡可能將已發布或分享的 Firebase Dynamic Links 替換為通用連結，並在日後繼續使用通用連結。

完成這個步驟的方式，取決於您發布 Firebase Dynamic Links 的位置和方式。

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