在 iOS 上接收 Dynamic Links

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

如要接收 您建立的 Firebase Dynamic Links，您必須在應用程式中加入 Dynamic Links SDK，並在應用程式載入時呼叫 handleUniversalLink: 和 dynamicLinkFromCustomSchemeURL: 方法，以便取得 Dynamic Link 中傳遞的資料。

事前準備

開始之前，請務必將 Firebase 新增至 iOS 專案。

設定 Firebase 和 Dynamic Links SDK

使用 Swift Package Manager 安裝及管理 Firebase 依附元件。

1. 在 Xcode 中保持開啟應用程式專案，然後依序點選「File」>「Add Packages」。
2. 系統提示時，請新增 Firebase Apple 平台 SDK 存放區：

  https://github.com/firebase/firebase-ios-sdk.git

3. 選擇 Dynamic Links 程式庫。
4. 將 -ObjC 標記新增至目標的建構設定「Other Linker Flags」部分。
5. 為提供最佳的 Dynamic Links 體驗，建議您在 Firebase 專案中啟用 Google Analytics，並將 Google Analytics 專用 Firebase SDK 新增至應用程式。您可以選擇不收集 IDFA 的程式庫，也可以選擇收集 IDFA 的程式庫。請參閱我們的常見問題，瞭解 Firebase SDK Google Analytics 中最新的模組組織方式。
6. 完成後，Xcode 就會自動開始在背景中解析並下載依附元件。

接著，請執行一些設定步驟：

1. 在 Firebase 控制台中，開啟「Dynamic Links」部分。系統提示時，請接受服務條款。

2. 請確認應用程式的 App Store ID 和 App ID 前置字元已在應用程式設定中指定。如要查看及編輯應用程式設定，請前往 Firebase 專案的「設定」頁面，然後選取 iOS 應用程式。

   您可以開啟下列網址，確認 Firebase 專案是否已正確設定，可在 iOS 應用程式中使用 Dynamic Links：

   https://your_dynamic_links_domain/apple-app-site-association

   如果應用程式已連結，apple-app-site-association 檔案會包含應用程式 ID 前置字串和軟體包 ID 的參照。例如：

   {"applinks":{"apps":[],"details":[{"appID":"1234567890.com.example.ios","paths":["NOT /_/*","/*"]}]}}

   如果 details 欄位為空白，請仔細檢查是否已指定應用程式 ID 前置字串。請注意，應用程式 ID 前置碼可能與團隊 ID 不同。

3. 選用：停用 Dynamic Links SDK 對 iOS 剪貼簿的使用。

   根據預設，Dynamic Links SDK 會使用剪貼板，改善安裝後深層連結的可靠性。使用剪貼板後，Dynamic Links 就能確保使用者在開啟 Dynamic Link 時需要先安裝應用程式，且在安裝後首次開啟應用程式時，使用者能立即前往原始連結內容。

   缺點是，使用剪貼板會在 iOS 14 以上版本觸發通知。因此，當使用者首次開啟應用程式時，如果剪貼板含有網址，他們就會看到通知，指出您的應用程式存取了剪貼板，這可能會造成混淆。

   如要停用這項行為，請編輯 Xcode 專案的 Info.plist 檔案，並將 FirebaseDeepLinkPasteboardRetrievalEnabled 鍵設為 NO。

在應用程式中開啟 Dynamic Links

1. 在應用程式的 Xcode 專案「Info」分頁中，建立要用於 Dynamic Links 的新網址類型。將「Identifier」欄位設為專屬值，並將「URL scheme」欄位設為套件 ID，這是 Dynamic Links 使用的預設網址架構。
2. 在應用程式 Xcode 專案的「Capabilities」分頁中，啟用「Associated Domains」，並將下列內容新增至「Associated Domains」清單：

   applinks:your_dynamic_links_domain

3. 如果您想透過完全自訂的網域接收 Dynamic Links，請在 Xcode 專案的 Info.plist 檔案中建立名為 FirebaseDynamicLinksCustomDomains 的鍵，並將其設為應用程式的 Dynamic Links 網址前置字串。例如：

   FirebaseDynamicLinksCustomDomains
   
     https://example.com/promos
     https://example.com/links/share
   

4. 在 UIApplicationDelegate 中匯入 FirebaseCore 模組，以及應用程式委派程式使用的任何其他 Firebase 模組。例如，如要使用 Cloud Firestore 和 Authentication：

   SwiftUI

   import SwiftUI
   import FirebaseCore
   import FirebaseFirestore
   import FirebaseAuth
   // ...
         

   Swift

   import FirebaseCore
   import FirebaseFirestore
   import FirebaseAuth
   // ...
         

   Objective-C

   @import FirebaseCore;
   @import FirebaseFirestore;
   @import FirebaseAuth;
   // ...
         

5. 在應用程式委派作業的 application(_:didFinishLaunchingWithOptions:) 方法中，設定 FirebaseApp 共用例項：

   SwiftUI

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Swift

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Objective-C

   // Use Firebase library to configure APIs
   [FIRApp configure];

6. 如果您使用 SwiftUI，則必須建立應用程式委派程式，並透過 UIApplicationDelegateAdaptor 或 NSApplicationDelegateAdaptor 將其附加至 App 結構體。您也必須停用應用程式委派程式 swizzling 功能。詳情請參閱 SwiftUI 操作說明。

   SwiftUI

   @main
   struct YourApp: App {
     // register app delegate for Firebase setup
     @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
         

7. 接下來，在 application:continueUserActivity:restorationHandler: 方法中，處理在應用程式已安裝時，以 通用連結形式收到的連結：

   Swift

   注意：這項產品不適用於 macOS、Mac Catalyst、tvOS 或 watchOS 目標。

   func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
     let handled = DynamicLinks.dynamicLinks()
       .handleUniversalLink(userActivity.webpageURL!) { dynamiclink, error in
         // ...
       }
   
     return handled
   }

   Objective-C

   注意：這項產品不適用於 macOS、Mac Catalyst、tvOS 或 watchOS 目標。

   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(nonnull NSUserActivity *)userActivity
    restorationHandler:
   #if defined(__IPHONE_12_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_12_0)
   (nonnull void (^)(NSArray<id<UIUserActivityRestoring>> *_Nullable))restorationHandler {
   #else
       (nonnull void (^)(NSArray *_Nullable))restorationHandler {
   #endif  // __IPHONE_12_0
     BOOL handled = [[FIRDynamicLinks dynamicLinks] handleUniversalLink:userActivity.webpageURL
                                                             completion:^(FIRDynamicLink * _Nullable dynamicLink,
                                                                          NSError * _Nullable error) {
                                                               // ...
                                                             }];
     return handled;
   }

8. 最後，在 application:openURL:options: 中處理透過應用程式自訂網址通訊協定收到的連結。在應用程式安裝完成後首次開啟時，系統會呼叫這個方法。

   如果應用程式首次啟動時找不到 Dynamic Link，系統會呼叫這個方法，並將 DynamicLink 的 url 設為 nil，表示 SDK 無法找到相符的待處理 Dynamic Link。

   Swift

   注意：這項產品不適用於 macOS、Mac Catalyst、tvOS 或 watchOS 目標。

   @available(iOS 9.0, *)
   func application(_ app: UIApplication, open url: URL,
                    options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
     return application(app, open: url,
                        sourceApplication: options[UIApplication.OpenURLOptionsKey
                          .sourceApplication] as? String,
                        annotation: "")
   }
   
   func application(_ application: UIApplication, open url: URL, sourceApplication: String?,
                    annotation: Any) -> Bool {
     if let dynamicLink = DynamicLinks.dynamicLinks().dynamicLink(fromCustomSchemeURL: url) {
       // Handle the deep link. For example, show the deep-linked content or
       // apply a promotional offer to the user's account.
       // ...
       return true
     }
     return false
   }

   Objective-C

   注意：這項產品不適用於 macOS、Mac Catalyst、tvOS 或 watchOS 目標。

   - (BOOL)application:(UIApplication *)app
               openURL:(NSURL *)url
               options:(NSDictionary<NSString *, id> *)options {
     return [self application:app
                      openURL:url
            sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                   annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
   }
   
   - (BOOL)application:(UIApplication *)application
               openURL:(NSURL *)url
     sourceApplication:(NSString *)sourceApplication
            annotation:(id)annotation {
     FIRDynamicLink *dynamicLink = [[FIRDynamicLinks dynamicLinks] dynamicLinkFromCustomSchemeURL:url];
   
     if (dynamicLink) {
       if (dynamicLink.url) {
         // Handle the deep link. For example, show the deep-linked content,
         // apply a promotional offer to the user's account or show customized onboarding view.
         // ...
       } else {
         // Dynamic link has empty deep link. This situation will happens if
         // Firebase Dynamic Links iOS SDK tried to retrieve pending dynamic link,
         // but pending link is not available for this device/App combination.
         // At this point you may display default onboarding view.
       }
       return YES;
     }
     return NO;
   }