在 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. 將 -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. 如果尚未接受服務條款並為 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. 在 FirebaseCore 中匯入 UIApplicationDelegate 模組，以及應用程式委派使用的任何其他 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 長度，在 iOS 上以 iOS 應用程式開啟，在 Android 上則以 com.example.android 應用程式開啟：https://www.example.com/my-page

Swift

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
[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 Link。Dynamic Links如果您的用途是短連結遭人猜中也無妨，您可能會偏好產生長度足以確保不重複的後置字串，這時可以設定 dynamicLinkComponentsOptions 屬性：

Swift

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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，且不得為其他動態連結。
domainURIPrefix 您的 Dynamic Link 網址前置字元，您可以在 Firebase 控制台中找到。A Dynamic Link 網域看起來會像下列範例： 
https://example.com/link
https://example.page.link
DynamicLinkAndroidParameters
fallbackURL 應用程式未安裝時要開啟的連結。如果應用程式尚未安裝，您可以指定此動作，以便執行安裝應用程式以外的動作，例如開啟內容的行動版網頁，或顯示應用程式的宣傳頁面。
minimumVersion 可開啟連結的應用程式最低版本versionCode。如果安裝的應用程式版本較舊，系統會將使用者帶往 Play 商店升級應用程式。
DynamicLinkIOSParameters
appStoreID 應用程式的 App Store ID，用於在應用程式未安裝時將使用者導向 App Store
fallbackURL 應用程式未安裝時要開啟的連結。如果應用程式尚未安裝，您可以指定此動作，以便執行安裝以外的作業，例如開啟內容的行動版網頁，或顯示應用程式的宣傳頁面。
customScheme 應用程式的自訂網址通訊協定 (如果定義為應用程式軟體包 ID 以外的項目)
iPadFallbackURL 如果未安裝應用程式，則在 iPad 上開啟的連結。如果應用程式未安裝，請指定此項目，以便執行從 App Store 安裝應用程式以外的動作，例如開啟內容的網頁版，或顯示應用程式的宣傳頁面。
iPadBundleID 在 iPad 上開啟連結時使用的 iOS 應用程式套件 ID。應用程式必須從 Firebase 控制台的「總覽」頁面連結至專案。
minimumAppVersion 可開啟連結的應用程式最低版本編號。這個標記會在應用程式開啟時傳遞至應用程式，而應用程式必須決定如何處理。
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled 如果設為「1」，開啟 Dynamic Link 時會略過應用程式預覽頁面，並改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可在使用者開啟應用程式中的 Dynamic Links 時，更可靠地將他們導向最合適的目的地。不過，如果您希望 Dynamic Link 只在可穩定開啟 Dynamic Links 的應用程式中開啟，且不需要這個頁面，可以使用這個參數停用預覽頁面。這個參數只會影響 iOS 上的 Dynamic Link 行為。
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) 會傳遞至 App Store。

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

Swift

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
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

注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
[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

    注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
    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

    注意：macOS、Mac Catalyst、tvOS 或 watchOS 目標不支援這項 Firebase 產品。 
    - (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 的說明文件。