在 iOS 上建立 Dynamic Links

已淘汰：Firebase Dynamic Links已淘汰，建議在尚未採用的專案中不應採用。這項服務將於 2025 年 8 月 25 日停止服務。 詳情請參閱「動態連結淘汰常見問題」。

您可以使用 Firebase Dynamic Links Builder API 建立短或長的 Dynamic Links。這個 API 可接受長的動態連結或包含動態連結參數的物件，並傳回網址，範例如下：

https://example.com/link/WXYZ
https://example.page.link/WXYZ

先備知識

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

設定 Firebase 和 Dynamic Links SDK

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

請參閱安裝指南，瞭解將 Firebase SDK 新增至 Apple 專案的不同方式，包括直接匯入架構及使用 CocoaPods。

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

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

注意：新專案應使用預設的 SDK 版本 (最新) 版本，但您也可以視需要選擇較舊的版本。
3. 選擇 Dynamic Links 程式庫。
4. 在目標建構設定的「Other Linker Flags」部分中新增 -ObjC 標記。
5. 為了讓動態連結獲得最佳體驗，建議您在 Firebase 專案中啟用 Google Analytics (分析)，並將 Google Analytics (分析) 專用 Firebase SDK 加到應用程式。您可以選取不使用 IDFA 收集功能的程式庫，或利用 IDFA 收集功能。
6. 完成後，Xcode 會自動開始在背景解析並下載依附元件。

現在，請執行一些設定步驟：

1. 在 Firebase 控制台中開啟「Dynamic Links」部分。

2. 如果您尚未接受服務條款，並且為動態連結設定 URI 前置字串，請在系統提示時完成這項操作。

   如果您已經有 Dynamic Links URI 前置字串，請加以記下。您必須在以程式輔助方式建立 Dynamic Links 時提供。

   

3. 建議：指定深層連結和備用連結允許的網址模式。這樣一來，就能避免未經授權的對象建立動態連結，將該網域重新導向到由您控管的網站。請參閱「允許特定網址模式」。

4. 請務必在應用程式的設定中指定應用程式的 App Store ID 和應用程式 ID 前置字串，如要查看及編輯應用程式設定，請前往 Firebase 專案的 設定頁面，並選取 iOS 應用程式。

   開啟在 Dynamic Links 網域上代管的 apple-app-site-association 檔案，確認 Firebase 專案已在 iOS 應用程式中正確設定使用 Dynamic Links。Firebase 會從網域的根目錄和 .well-known 子目錄提供 apple-app-site-association 檔案。例如：

       https://example.com/apple-app-site-association
       https://example.com/.well-known/apple-app-site-association
       

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

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

   如果 details 屬性為空白，請再次確認您已指定應用程式 ID 前置字串。請注意，您的應用程式 ID 前置字串可能與團隊 ID 不同。

將 Firebase 新增至應用程式

1. 將 FirebaseCore 模組匯入 UIApplicationDelegate，以及應用程式委派使用的任何其他 Firebase 模組。例如，如要使用 Cloud Firestore 和驗證：

   SwiftUI

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

   Swift

   import FirebaseCore
   import FirebaseFirestore
   import FirebaseAuth
   // ...
         

   Objective-C

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

2. 在應用程式委派的 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];

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

   SwiftUI

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

使用 Firebase 控制台

如果您想產生單一動態連結 (無論是為了測試目的，或是要讓行銷團隊輕鬆建立可用於社群媒體貼文等項目的連結)，最簡單的方法就是造訪 Firebase 主控台，然後按照逐步表單手動建立。

使用 iOS Builder API

您可以使用 iOS Builder API 根據參數建立 Dynamic Links，或縮短長的動態連結。

根據參數建立動態連結

如要建立動態連結，請建立新的 DynamicLinkComponents 物件，並透過設定物件的對應屬性來指定 Dynamic Link 參數。接著，從物件的 url 屬性取得長連結，或呼叫 shorten() 取得短連結。

下列最精簡的範例會建立指向 https://www.example.com/my-page 的長動態連結，並透過 iOS 應用程式、Android 上的應用程式 com.example.android 開啟：

Swift

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

guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPrefix: dynamicLinksDomainURIPRefix)
linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

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

NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                               domainURIPrefix:dynamicLinksDomainURIPrefix];
linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];

NSLog(@"The long URL is: %@", linkBuilder.url);

如要建立短動態連結，請以相同方式建構 DynamicLinkComponents，然後呼叫 shorten()。

建立短連結需要網路呼叫，因此 shorten() 會接受在要求完成時呼叫的完成處理常式，而不是直接傳回連結。例如：

Swift

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

linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

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

[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];
      

根據預設，簡短的動態連結會產生 17 個字元的連結後置字串，避免他人猜到有效的動態連結。以您的用途來說，如果使用者成功猜到短連結並無任何傷害，可以設定 dynamicLinkComponentsOptions 屬性，建立僅是唯一必要且不重複的後置字串：

Swift

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

linkBuilder.options = DynamicLinkComponentsOptions()
linkBuilder.options.pathLength = .short
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

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

linkBuilder.dynamicLinkComponentsOptions = [[FIRDynamicLinkComponentsOptions alloc] init];
linkBuilder.dynamicLinkComponentsOptions.pathLength = FIRShortDynamicLinkPathLengthShort;
[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];
      

動態連結參數

您可以使用 Dynamic Link Builder API 使用任何支援的參數建立 Dynamic Links。詳情請參閱 API 參考資料。

下例會使用幾個常用參數的動態連結建立動態連結：

Swift

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

guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPRefix: dynamicLinksDomainURIPrefix)

linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.iOSParameters.appStoreID = "123456789"
linkBuilder.iOSParameters.minimumAppVersion = "1.2.3"

linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")
linkBuilder.androidParameters.minimumVersion = 123

linkBuilder.analyticsParameters = DynamicLinkGoogleAnalyticsParameters(source: "orkut",
                                                                       medium: "social",
                                                                       campaign: "example-promo")

linkBuilder.iTunesConnectParameters = DynamicLinkItunesConnectAnalyticsParameters()
linkBuilder.iTunesConnectParameters.providerToken = "123456"
linkBuilder.iTunesConnectParameters.campaignToken = "example-promo"

linkBuilder.socialMetaTagParameters = DynamicLinkSocialMetaTagParameters()
linkBuilder.socialMetaTagParameters.title = "Example of a Dynamic Link"
linkBuilder.socialMetaTagParameters.descriptionText = "This link works whether the app is installed or not!"
linkBuilder.socialMetaTagParameters.imageURL = "https://www.example.com/my-image.jpg"

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

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

NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                         domainURIPrefix:dynamicLinksDomainURIPrefix];

linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.iOSParameters.appStoreID = @"123456789";
linkBuilder.iOSParameters.minimumAppVersion = @"1.2.3";

linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];
linkBuilder.androidParameters.minimumVersion = 123;

linkBuilder.analyticsParameters = [[FIRDynamicLinkGoogleAnalyticsParameters alloc]
                                   initWithSource:@"orkut"
                                           medium:@"social"
                                         campaign:@"example-promo"];

linkBuilder.iTunesConnectParameters = [[FIRDynamicLinkItunesConnectAnalyticsParameters alloc] init];
linkBuilder.iTunesConnectParameters.providerToken = @"123456";
linkBuilder.iTunesConnectParameters.campaignToken = @"example-promo";

linkBuilder.socialMetaTagParameters = [[FIRDynamicLinkSocialMetaTagParameters alloc] init];
linkBuilder.socialMetaTagParameters.title = @"Example of a Dynamic Link";
linkBuilder.socialMetaTagParameters.descriptionText = @"This link works whether the app is installed or not!";
linkBuilder.socialMetaTagParameters.imageURL = @"https://www.example.com/my-image.jpg";

NSLog(@"The long URL is: %@", linkBuilder.url);

您可以利用下列物件和屬性設定 Dynamic Link 參數：

DynamicLinkComponents
連結	應用程式會開啟的連結。指定應用程式可處理的網址，通常是應用程式的內容或酬載，從而啟動應用程式專屬的邏輯 (例如運用優待券獎勵使用者，或顯示歡迎畫面)。這個連結必須是格式正確的網址、採用正確的網址編碼、使用 HTTP 或 HTTPS，且不能是其他動態連結。 使用者在電腦版網路瀏覽器中開啟動態連結時，會載入這個網址 (除非指定 ofl 參數)。如果您沒有與連結內容相對應的網站，則該網址不需要指向有效的網路資源。在這種情況下，請設定將這個網址重新導向到首頁等項目的網址。
網域 URIPrefix	動態連結網址前置字串，可在 Firebase 控制台中找到。Dynamic Link 網域如以下範例所示： https://example.com/link https://example.page.link

DynamicLinkAndroid 參數
備用網址	未安裝應用程式時開啟的連結。除了從 Play 商店安裝應用程式之外，您也可以指定上述操作以外的操作，例如開啟行動版網站內容，或顯示應用程式的宣傳頁面。
最低版本	可開啟連結的應用程式最低版本 versionCode。如果安裝的應用程式是較舊的版本，系統會引導使用者前往 Play 商店升級應用程式。

DynamicLinkIOS 參數
應用程式商店 ID	應用程式的 App Store ID，可在未安裝應用程式時將使用者導向 App Store
備用網址	未安裝應用程式時開啟的連結。除了從 App Store 安裝應用程式之外，請指定這項額外操作；例如，開啟行動版網站的內容，或顯示應用程式的宣傳頁面。
自訂配置	應用程式的自訂網址通訊協定 (如果定義並非應用程式軟體包 ID)
iPadFallbackURL	未安裝應用程式時，在 iPad 上開啟的連結。除了從 App Store 安裝應用程式之外，請指定這項額外操作，例如開啟網頁內容或顯示應用程式的宣傳頁面。
iPadBundleID	要在 iPad 上開啟連結的 iOS 應用程式軟體包 ID。應用程式必須在 Firebase 控制台的「總覽」頁面中，連結至您的專案。
最低應用程式版本	可開啟連結的應用程式最低版本版本號碼。此旗標會在應用程式開啟時傳遞至應用程式，因此應用程式必須決定使用方式。

DynamicLinkNavigationInfoParameters
forcedRedirectEnabled	如果設為「1」，請在開啟動態連結時略過應用程式預覽頁面，改為重新導向至應用程式或商店。使用者在應用程式中開啟 Dynamic Links 時，應用程式預覽頁面 (預設為啟用) 可更穩定地將他們導向最適當的目的地；不過，如果您希望動態連結只有在沒有這個網頁也能順利開啟 Dynamic Links 的應用程式中開啟，就可以使用這個參數停用。這個參數只會影響 iOS 上的 Dynamic Links 行為。

DynamicLinkSocialMetaTagParameters
名稱	在社群媒體貼文中分享 Dynamic Link 時使用的標題。
說明文字	在社群媒體貼文中分享 Dynamic Link 時使用的說明。
圖片網址	這個連結相關圖片的網址。圖片不得小於 300x200 像素，小於 300 KB。

DynamicLinkGoogleAnalyticsParameters
來源 媒介 廣告活動 字詞 內容	Google Play 數據分析參數。這些參數 (utm_source、utm_medium、utm_campaign、utm_term、utm_content) 會傳遞至 Play 商店，並附加至連結酬載。

DynamicLinkItunesConnectAnalyticsParameters
providerToken affiliateToken campaignToken	iTunes 連結數據分析參數。這些參數 (pt、at、ct) 會傳遞到 App Store。

縮短完整動態連結

如要縮短長的動態連結，請將長的動態連結連同 DynamicLinkComponentsOptions 物件傳遞至 shortenURL(url:options:)，以產生含有短後置字串的連結：

Swift

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

DynamicLinkComponents.shortenURL(url: longLinkUrl, options: nil) { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

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

[FIRDynamicLinkComponents shortenURL:longLinkUrl
                             options:nil
                          completion:^(NSURL * _Nullable shortURL,
                                       NSArray<NSString *> * _Nullable warnings,
                                       NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

為 Dynamic Links 指定自訂網址通訊協定

根據預設，Dynamic Links 會使用應用程式的軟體包 ID 做為開啟應用程式所需的網址通訊協定。建議您沿用這個預設值，讓實作方式較為簡單。

不過，如果開發人員已基於其他用途使用自訂網址通訊協定，可能會想將同樣的自訂網址用於動態連結。如有這種情況，您可以按照下列步驟，為 Firebase 動態連結指定不同的網址配置：

1. 設定應用程式時，請務必先指定應用程式要使用的預設網址通訊協定，再設定 FirebaseApp 共用執行個體：

   Swift

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

   func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication
                      .LaunchOptionsKey: Any]?) -> Bool {
     // Set deepLinkURLScheme to the custom URL scheme you defined in your
     // Xcode project.
     FirebaseOptions.defaultOptions()?.deepLinkURLScheme = customURLScheme
     FirebaseApp.configure()
   
     return true
   }
   

   Objective-C

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

   - (BOOL)application:(UIApplication *)application
       didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     // Set deepLinkURLScheme to the custom URL scheme you defined in your
     // Xcode project.
     [FIROptions defaultOptions].deepLinkURLScheme = CUSTOM_URL_SCHEME;
     [FIRApp configure];
   
     return YES;
   }

2. 每當您建立動態連結時，您都必須指定應用程式使用的自訂網址通訊協定。方法是透過 Firebase 控制台，在 Builder API 中設定 customScheme、在網址中指定 ius 參數，或是將 iosCustomScheme 參數傳送至 REST API。

後續步驟

現在，您已建立動態連結，您需要設定應用程式來接收 Dynamic Links，並在使用者開啟連結後，將他們帶往應用程式中的正確位置。

如要在應用程式中接收 Dynamic Links，請參閱 iOS、Android、C++ 和 Unity 的說明文件。