在 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」。
  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 的程式庫。
  6. 完成後，Xcode 就會自動開始在背景中解析並下載依附元件。

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

  1. 在 Firebase 主控台中，開啟「Dynamic Links」專區。

  2. 如果您尚未接受服務條款，並為 Dynamic Links 設定 URI 前置字串，請在系統提示時完成這些步驟。

    如果您已擁有 Dynamic Links URI 前置字串，請記下這項資訊。您需要在以程式輔助方式建立 Dynamic Links 時提供這項資訊。

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

  4. 請確認應用程式的 App Store ID 和 App 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 結構體。您也必須停用應用程式委派程式 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()
      }
    }
  }
}

使用 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 上開啟應用程式連結 (如果未安裝應用程式)。指定這個值，即可在未安裝應用程式時，執行其他操作 (例如開啟內容的網頁版，或顯示應用程式宣傳頁面)，而非從 App Store 安裝應用程式。
iPadBundleID 在 iPad 上用來開啟連結的 iOS 應用程式軟體包 ID。您必須透過 Firebase 控制台的總覽頁面，將應用程式連結至專案。
minimumAppVersion 可開啟連結的應用程式最低版本的版本編號。這個標記會在應用程式開啟時傳遞給應用程式，而應用程式必須決定如何處理這個標記。
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled 如果設為「1」，系統會在開啟 Dynamic Link 時略過應用程式預覽頁面，改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可在使用者在應用程式中開啟 Dynamic Links 時，將他們送往最適當的目的地。不過，如果您希望只在可靠開啟 Dynamic Links 的應用程式中開啟 Dynamic Link，可以使用這個參數停用該頁面。這個參數只會影響 iOS 版 Dynamic Link 的行為。
DynamicLinkSocialMetaTagParameters
名稱 在社群媒體貼文中分享 Dynamic Link 時使用的標題。
descriptionText 在社群媒體貼文中分享 Dynamic Link 時使用的說明。
imageURL 與此連結相關的圖片網址。圖片尺寸不得小於 300 x 200 像素，且大小不得超過 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 連同 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 會使用應用程式的軟體包 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 的說明文件。