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

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

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

特徵	Firebase Dynamic Links	應用程式連結 / 通用連結
使用者只要按一下連結，就能前往適合自己的裝置商店		★
使用延遲深層連結，在使用者下載及安裝應用程式後，繼續提供不同的歷程		★
透過應用程式中的深層連結內容 (已安裝) 為使用者提供內容相關體驗
提供與動態連結點擊事件相關的分析資料
提供建立短連結網址的功能

如需本指南未支援的其他 Firebase 動態連結功能執行遷移作業，請參閱動態連結淘汰常見問題說明文件中的其他遷移情境。

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

動態連結範例
連結名稱	歡迎使用 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 Dynamic Links：

https://example.page.link/m9Mm

使用應用程式連結 / 通用連結深層連結時，看起來會像這樣：

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

請注意，應用程式連結 / 通用連結深層連結可為使用者提供下列內容：

• 使用者可點擊的深層連結，在已安裝應用程式的情況下開啟您的應用程式
• 接續使用者歷程，從使用者開啟應用程式的特定部分前往特定部分

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

• 將使用者導向正確的裝置商店，讓他們下載及安裝應用程式
• 在下載、安裝及開啟應用程式後，繼續提供使用者歷程

請注意，這些應用程式連結 / 通用連結與 Firebase Dynamic Links 在行為和功能上有何差異 (上表所述)。

事前準備

Firebase Dynamic Links 會在自己的基礎實作項目中使用應用程式連結 (Android) 和通用連結 (iOS)，以便在應用程式安裝後提供深層連結功能。

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

您需要以下資訊，才能完成遷移作業：

• 要遷移的 Firebase Dynamic Links
• 動態連結內含的深層連結網址參數
• 打算用來取代舊 Firebase 動態連結網域的網域 (如果有的話)

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

遷移步驟總覽

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 應用程式連結的遷移步驟

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

如要使用應用程式連結，您必須託管設定檔，協助在連結和應用程式所用的網域之間建立安全關聯。以應用程式連結來說，這是 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 檔案中宣告的應用程式 ID
   • sha256_cert_fingerprints - 指的是您用來簽署應用程式的 KeyStore 檔案 SHA256 指紋。

   您可以使用 Android Studio 使用的 debug.keystore 檔案產生 sha256_cert_fingerprints 記錄，以便進行偵錯。您可以在 Mac 和 Linux 的 /Users/<username>/.android/debug.keystore 及 Windows 的 C:\Users\<username>\.android\debug.keystore 中找到該檔案。

   您可以從這個 KeyStore 使用 Keytool 擷取 SHA256 值。

   如要進一步瞭解如何完成這個步驟，請參閱應用程式連結說明文件的這個部分。

   您也可以使用 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 動態連結的深層連結。

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

動態連結範例
連結名稱	歡迎使用 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 Dynamic Links 短連結、深層連結參數和遷移的深層連結值：

短連結	深層連結參數	已遷移的深層連結
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
您的 app.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
您的 app.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

接下來，您將需要替換已發布或與新遷移深層連結共用的所有 Firebase Dynamic Links 執行個體，讓使用者點選這些應用程式連結，而非先前的 Firebase 動態連結。

請更新 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 動態連結，並在日後繼續使用應用程式連結。

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

iOS 通用連結遷移步驟

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

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

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

我們可以利用 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 Dynamic Links 中使用的深層連結結構定義，建立新的通用連結

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

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

動態連結範例
連結名稱	歡迎使用 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 Dynamic Links 短連結、深層連結參數和遷移的深層連結值：

短連結	深層連結參數	已遷移的深層連結
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
您的 app.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
您的 app.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

接下來，您將需要替換已發布或與新遷移深層連結共用的所有 Firebase Dynamic Links 執行個體，讓使用者點選這些通用連結，而非先前的 Firebase 動態連結。

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

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

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

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

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

如要更新專案設定，讓應用程式能處理深層連結，您需要針對目前打算用來託管 apple-app-site-associate 檔案的網域，在 xCode 中將額外的關聯網域新增至專案。

做法如下：

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 Dynamic Links

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

完成這個步驟會因您發布 Firebase Dynamic Links 的位置和方式而異。

為協助您追蹤要遷移的現有 Firebase Dynamic Links，我們即將發布指南，說明如何從 Firebase Dynamic Links 匯出短連結中繼資料。如需更多資訊，請參閱 Dynamic Links 淘汰常見問題文件。