在 iOS 上接收 Dynamic Links

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

事前準備

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

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

  1. 在 Xcode 中保持開啟應用程式專案,然後依序點選「File」>「Add Packages」
  2. 系統提示時,請新增 Firebase Apple 平台 SDK 存放區:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. 選擇 Dynamic Links 程式庫。
  5. -ObjC 標記新增至目標的建構設定「Other Linker Flags」部分。
  6. 為提供最佳的 Dynamic Links 體驗,建議您在 Firebase 專案中啟用 Google Analytics,並將 Google Analytics 專用 Firebase SDK 新增至應用程式。您可以選擇不收集 IDFA 的程式庫,也可以選擇收集 IDFA 的程式庫。
  7. 完成後,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

  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 FirestoreAuthentication

    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,則必須建立應用程式委派程式,並透過 UIApplicationDelegateAdaptorNSApplicationDelegateAdaptor 將其附加至 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,系統會呼叫這個方法,並將 DynamicLinkurl 設為 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;
    }