创建动态链接 (iOS)

已弃用：Firebase Dynamic Links 已弃用，不应在尚未使用它的项目中采用。该服务将于 2025 年 8 月 25 日关停。如需了解详情，请参阅 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 项目中。

设置 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. 将 -ObjC 标志添加到目标 build 设置的“其他链接器标志”部分。
5. 为了获得最佳的 Dynamic Links 使用体验，我们建议您在 Firebase 项目中启用 Google Analytics，并将 Firebase SDK for Google Analytics 添加到您的应用中。您可以选择收集或者不收集 IDFA 的库。
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 模块，以及您的应用委托 (app delegate) 使用的所有其他 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

如需创建 Dynamic Link，请创建一个新的 DynamicLinkComponents 对象，并通过设置该对象的相应属性来指定 Dynamic Link 参数。然后，从该对象的 url 属性中获取长链接或通过调用 shorten() 获取短链接。

下面这个极为简单的示例创建了一个指向 https://www.example.com/my-page 的长 Dynamic Link，此链接会在您的 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);
}];
      

默认情况下，生成的短 Dynamic Links 有 17 个字符的链接后缀，这样他人基本上不可能猜测出有效的 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 个参数

您可以使用 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 时，浏览器将加载此网址（除非指定了 ofl 参数）。如果您没有与所链接的内容相对应的 Web 资源，该网址就无需指向一个有效的 Web 资源。在这种情况下，您应设置一个从此网址重定向到的网址，例如您的首页。
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	要在用户未安装应用的情况下打开的链接。指定此链接是为了在用户未安装应用的情况下，执行一些除了从 App Store 安装您的应用之外的其他操作，比如打开内容的移动网络版或显示该应用的宣传页面。
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
标题	在社交贴子中分享 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，请将长 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 指定自定义网址架构

默认情况下，Dynamic Links 使用您的应用的软件包标识符作为打开该应用所需的网址架构。我们建议您保留此默认值，以确保实现方式简单明了。

但是，如果开发者已出于其他原因使用自定义网址架构，则可能希望为其 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 的文档。