在 iOS 上建立 Dynamic Links

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

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

必要條件

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

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

  1. 在 Xcode 中保持開啟應用程式專案，然後依序點選「File」(檔案) 和「Add Packages」(新增 Package)。
  2. 系統提示時，請新增 Firebase Apple 平台 SDK 存放區：
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. 選擇 Dynamic Links 程式庫。
  4. 在目標建構設定的「Other Linker Flags」部分，新增 -ObjC 標記。
  5. 為確保 Dynamic Links 運作順暢，建議您在 Firebase 專案中啟用 Google Analytics，並在應用程式中加入 Google Analytics 專用 Firebase SDK。您可以選擇不收集廣告識別碼 (IDFA) 的程式庫，也可以選擇收集廣告識別碼的程式庫。請參閱常見問題，瞭解 Firebase SDK Google Analytics 中模組的最新組織方式。
  6. 完成後，Xcode 會自動開始在背景解析及下載依附元件。

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

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

  2. 如果您尚未接受服務條款，也未設定 Dynamic Links 的 URI 前置字元，請在系統提示時完成這些操作。

    如果您已有 Dynamic Links URI 前置字元，請記下來。您必須在透過程式輔助方式建立 Dynamic Links 時提供這項資訊。

  3. 建議：指定深層連結和備用連結中允許的網址模式。這樣一來，未經授權的第三方就無法建立 Dynamic Links，從您的網域重新導向至您無法控制的網站。請參閱「允許特定網址模式」。

  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. 在 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;
// ...
  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 控制台

如要產生單一 Dynamic Link (用於測試，或方便行銷團隊建立連結，用於社群媒體貼文等)，最簡單的方法是前往 Firebase 控制台，按照逐步表單手動建立。

使用 iOS Builder API

您可以使用 iOS Builder API，透過參數建構 Dynamic Links，或縮短長 Dynamic Link。

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

以下精簡範例會建立長 Dynamic Link 至 https://www.example.com/my-page，在 iOS 上使用 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);

如要建立短 Dynamic Link，請以相同方式建構 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 個字元的連結後置字串Dynamic Links，因此幾乎不可能猜出有效的 Dynamic Link。如果您的用途不擔心有人猜中短連結，可以考慮產生長度剛好能確保不重複的後置字串，只要設定 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 參考資料。

以下範例會建立 Dynamic Link，並設定幾個常見參數：

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，且不得為其他 Dynamic Link。
domainURIPrefix Dynamic Link 網址前置字元，可在 Firebase 控制台找到。Dynamic Link 網域如下所示： 
https://example.com/link
https://example.page.link
DynamicLinkAndroidParameters
fallbackURL 未安裝應用程式時要開啟的連結。如果使用者未安裝應用程式，您可以指定這項參數，執行從 Play 商店安裝應用程式以外的操作，例如開啟行動版網站內容，或顯示應用程式的宣傳頁面。
minimumVersion 可開啟連結的應用程式最低版本 versionCode。如果安裝的是舊版應用程式，系統會將使用者導向 Play 商店，以便升級應用程式。
DynamicLinkIOSParameters
appStoreID 應用程式的 App Store ID，用於在未安裝應用程式時將使用者導向 App Store
fallbackURL 未安裝應用程式時要開啟的連結。指定這項參數後，如果使用者未安裝應用程式，系統就不會從應用程式商店安裝應用程式，而是執行其他動作，例如開啟行動版網站內容，或顯示應用程式的宣傳頁面。
customScheme 應用程式的自訂網址配置 (如果定義為應用程式軟體包 ID 以外的值)
iPadFallbackURL 未安裝應用程式時，在 iPad 上開啟的連結。如果使用者未安裝應用程式，您可以指定這項參數，執行從應用程式商店安裝應用程式以外的操作，例如開啟網頁版內容，或顯示應用程式的宣傳頁面。
iPadBundleID 在 iPad 上開啟連結時，要使用的 iOS 應用程式軟體包 ID。應用程式必須從 Firebase 控制台的「總覽」頁面連結至專案。
minimumAppVersion 可開啟連結的應用程式最低版本號碼。應用程式開啟時，系統會將這個標記傳遞給應用程式，應用程式必須決定如何處理。
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled 如果設為「1」，則在開啟 Dynamic Link 時略過應用程式預覽頁面，改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可更可靠地將使用者導向最合適的目的地，當他們在應用程式中開啟 Dynamic Links 時；不過，如果您預期 Dynamic Link 只會在能可靠開啟 Dynamic Links 的應用程式中開啟，而不需要這個頁面，則可以使用這個參數停用它。這項參數只會影響 Dynamic Link 在 iOS 上的行為。
DynamicLinkSocialMetaTagParameters
title 在社群貼文中分享Dynamic Link時使用的標題。
descriptionText 在社群貼文中分享Dynamic Link時使用的說明。
imageURL 與這個連結相關的圖片網址。圖片大小至少須為 300x200 像素，且不得超過 300 KB。
DynamicLinkGoogleAnalyticsParameters
source
medium
campaign
term
content		 Google Play 數據分析參數。這些參數 (utm_source、utm_medium、utm_campaign、utm_term、utm_content) 會傳遞至 Play 商店，並附加至連結酬載。
DynamicLinkItunesConnectAnalyticsParameters
providerToken
affiliateToken
campaignToken		 iTunes Connect 數據分析參數。這些參數 (pt、at、ct) 會傳遞至應用程式商店。

如要縮短長 Dynamic Link，請將長 Dynamic Link 傳遞至 shortenURL(url:options:)，並搭配 DynamicLinkComponentsOptions 物件，以便產生具有短尾碼的連結：

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 會使用應用程式的軟體包 ID 做為開啟應用程式所需的網址配置。建議您保留這個預設值，簡化導入作業。

不過，如果開發人員已將自訂網址配置用於其他用途，可能也會想將相同的自訂網址配置用於 Dynamic Links。在這種情況下，您可以按照下列步驟為 Firebase Dynamic Links 指定不同的網址配置：

  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. 每當您建立任何 Dynamic Link 時，都必須指定應用程式使用的自訂網址配置。您可以透過 Firebase 控制台、在 Builder API 中設定 customScheme、在網址中指定 ius 參數，或將 iosCustomScheme 參數傳送至 REST API，來執行這項操作

後續步驟

建立 Dynamic Links 後，您需要設定應用程式來接收 Dynamic Links，並在使用者開啟後將他們導向應用程式中的正確位置。

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