從動態鏈接遷移到應用程式連結和應用程式鏈接通用連結

本遷移指南重點在於如何使用App Links和Universal Links ，並可選擇使用 Firebase Hosting 來託管您的應用程式網站關聯檔。

此遷移取代了以下 Firebase 動態連結功能：

特徵	Firebase 動態鏈接	應用程式鏈接/通用鏈接
只需單擊一個連結即可將用戶引導至適合其設備的正確商店		★
使用延遲深層連結在下載並安裝您的應用程式後為用戶提供繼續旅程		★
使用應用程式中的深層連結內容為用戶提供上下文體驗（如果已安裝）
提供與動態連結點擊事件相關的分析數據
提供建立短連結 URL 的能力

如果您繼續需要本指南不支援的其他 Firebase 動態連結功能進行遷移，請參閱動態連結棄用常見問題解答文件中的其他遷移方案。

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

動態連結範例
連結名稱	歡迎來到Example.com
深層連結	https://example.web.app/welcome
安卓應用程式	com.example.android
蘋果應用程式	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

使用 App Link / Universal Link 深層鏈接，如下所示：

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

請注意，應用程式連結/通用連結深層連結將為您的用戶提供以下內容：

• 他們可以單擊一個深層鏈接，在安裝後打開您的應用程式
• 用戶旅程的延續，在打開應用程式時將他們導航到應用程式的特定部分

但是，應用程式連結/通用連結深層連結不會為您的使用者提供以下行為（Firebase 動態連結之前已提供）：

• 引導用戶前往其裝置的正確商店下載並安裝您的應用程式
• 在首次下載、安裝和打開應用程式後提供用戶旅程的延續

請注意這些應用程式連結/通用連結與上表中列出的 Firebase 動態連結在行為和功能上的差異。

在你開始之前

Firebase 動態連結在其自己的底層實作中利用應用程式連結（在 Android 上）和通用連結（在 iOS 上），以便在安裝應用程式後提供深度連結功能。

本指南將介紹如何使用 Firebase 託管創建您自己的應用鏈接和通用鏈接，以替換 Firebase 動態鏈接提供的部分功能，同時將 Firebase 動態鏈接遷移到新的應用鏈接/通用鏈接遷移解決方案。

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

• 您打算遷移的 Firebase 動態鏈接
• 動態連結中包含的深層連結 URL 參數
• 您打算用來取代先前的 Firebase 動態連結網域的網域（如果適用）

您可以使用匯出動態連結元資料指南匯出現有連結元資料並取得上面列出的資訊。

遷移步驟概述

1. 設定一個新網域（如果您還沒有想要使用的網域）來使用 Firebase 託管託管您的應用程式連結/通用連結設定檔。

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

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

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

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

6. 將您發布或共享的 Firebase 動態連結取代為應用程式連結和通用連結。

第一步對於應用程式連結或通用連結遷移流程都是通用的。其餘部分將根據平台的不同而有所不同，因此請根據您要先遷移的平台導航到下面的指南部分。

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

使用 Firebase 託管配置新網域來託管您的應用程式連結/通用連結設定文件

選擇域名

第一步是選擇您想要用於應用程式連結/通用連結的網域。這將是用於您將共享給用戶的新連結的網域。

如果您使用Firebase Hosting ，則會自動免費設定格式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檔案允許我們提供授權應用程式的列表，這些應用程式可以處理我們將用於應用程式連結的 Web 網域的內容。 assetlinks.json 檔案本身需要託管在 Web 網域的根目錄中的路徑下： /.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 從此金鑰庫中取得 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 動態連結中使用的深層連結架構相符的新應用連結

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

例如，假設您有以下 Firebase 動態連結：

動態連結範例
連結名稱	歡迎來到Example.com
深層連結	https://example.web.app/welcome
安卓應用程式	com.example.android
蘋果應用程式	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/歡迎
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 Studio 指南，但主要步驟包括：

1. 確定哪些活動應處理各自的深層鏈接
2. 在 AndroidManifest.xml 檔案中為這些活動新增 Intent Filter
3. 接收活動應用程式程式碼中的深層鏈接

假設您想使用 MainActivity 來處理一些深層連結。為此，您需要將以下 Intent Filter 新增至 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測試您的 App Links 集成，或對您已配置的 App Link URL 使用以下命令，以確保其正確啟動匹配的 Activity：

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

將您發布或共享的 Firebase 動態連結替換為應用程式鏈接

遷移的最後一步是盡可能將已發布或共享的 Firebase 動態連結替換為應用程式鏈接，並繼續使用應用程式連結。

完成此步驟將取決於您發布 Firebase 動態鏈接的位置和方式，但為了幫助您跟踪存在哪些鏈接，您可以導出現有的 Firebase 動態鏈接元數據。請參閱匯出動態連結元資料指南。

iOS 上通用連結的遷移步驟

在新的託管網域上建立並託管您的通用連結配置文件

為了使用通用鏈接，您必須託管一個配置文件，該文件有助於在連結中使用的網域和應用程式之間建立安全關聯。對於通用鏈接，這是apple-app-site-association檔案（也稱為 AASA 檔案）。

建立和託管 apple-app-site-association 檔案的步驟

AASA 檔案允許我們提供授權應用程式的列表，這些應用程式可以處理我們將用於通用連結的 Web 網域的內容。 AASA 檔案本身需要託管在 Web 網域的根目錄下的路徑：/.well-known 中。

請依照以下步驟完成此配置：

1. 在 Firebase 託管根目錄的 public 資料夾下建立「 .wellknown 」資料夾。

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 動態連結：

動態連結範例
連結名稱	歡迎來到Example.com
深層連結	https://example.web.app/welcome
安卓應用程式	com.example.android
蘋果應用程式	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/歡迎
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 應用程式和應用程式程式碼以接收新的深層連結。

我們建議您按照此處的完整通用鏈接文檔來配置您的應用程式以處理深層鏈接，但主要步驟包括：

1. 更新您的專案配置以使您的應用程式能夠處理來自新建立的網域的深層鏈接

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

為了更新您的專案配置以使您的應用程式能夠處理深層鏈接，您需要在 xCode 中為您現在計劃用於託管 apple-app-site 的網域添加一個額外的關聯域 -關聯文件。

這可以透過以下方式完成：

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)
}

上面的程式碼會覆寫通用連結回呼方法並記錄深層連結 URL（如果存在）。

現在我們也將從 SceneDelegate 類別中呼叫相同的showReceivedUrl方法，因為如果使用者點擊通用連結時應用程式已經打開，則SceneDelegate內的通用連結回呼將被呼叫。

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

測試通用連結

您可以透過在實體設備或模擬器上執行應用程式來測試剛剛建立的通用連結。

您需要使用為通用鏈接配置的網域創建可單擊的鏈接，然後單擊該鏈接以確保它打開到您的應用程式中並將您導航到應用程式中的預期螢幕。

支援智慧應用橫幅

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

使用智慧型應用程式橫幅，如果您的應用程式尚未安裝在使用者的裝置上，他們將被帶到 App Store 來查看您的應用程式清單。您也可以選擇配置一個參數，以便在下載並安裝應用程式後傳遞到應用程式中，以便為使用者提供旅程的延續。如果您的應用程式已安裝，它將打開將參數傳遞給您的應用程序，以幫助用戶根據他們單擊的智慧型應用程式橫幅導航到適當的內容。

將您發布或共享的 Firebase 動態連結替換為應用程式鏈接

遷移的最後一步是盡可能將已發布或共享的 Firebase 動態鏈接替換為通用鏈接，並繼續使用通用鏈接。

完成此步驟將取決於您發布 Firebase 動態連結的位置和方式。

為了幫助您追蹤要遷移的現有 Firebase 動態鏈接，我們將發布有關如何從 Firebase 動態鏈接導出短鏈接元數據的指南。請返回查看我們的動態連結棄用常見問題解答文件以獲取更多更新。