创建动态链接 (iOS)

您可以使用 Firebase Dynamic Links Builder API 创建短动态链接或长动态链接。此 API 接受一个长动态链接或一个包含动态链接参数的对象，并返回如下所示的网址：

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

前提条件

Firebase 动态链接要求使用 iOS 8 或更新版本的系统。您可以在应用中将 iOS 7 定为目标，但 Firebase Dynamic Links SDK 调用只在 iOS 8 或更高版本系统上运行的应用中才能运行。

  1. 将 Firebase 添加到您的 iOS 项目。 在您的 Podfile 中添加以下 pod：
    pod 'Firebase/Analytics'
pod 'Firebase/DynamicLinks'
  2. 运行 pod install 并打开创建的 .xcworkspace 文件。
  3. 在 Firebase 控制台中，打开动态链接部分。

  4. 如果您尚未接受服务条款并为动态链接设置 URI 前缀，请在收到提示时执行相关操作。

    如果您已有动态链接 URI 前缀，请记下它。在以编程方式创建动态链接时，您需要提供该动态链接 URI 前缀。

  5. 推荐：指定可以在您的深层链接和后备链接中使用的网址格式。这样做可以防止未经授权者创建动态链接，从您的网域重定向至您无法控制的网站。请参阅白名单网址格式。

  6. 确保已在您的应用的设置中指定应用的 App Store ID 和应用 ID 前缀。要查看和修改应用的设置，请转到 Firebase 项目的“设置”页面，然后选择您的 iOS 应用。

    打开托管在动态链接网域上的 apple-app-site-association 文件，确认您的 Firebase 项目已正确配置为在 iOS 应用中使用动态链接。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 文件中包含对应用的 App Store ID 和软件包 ID 的引用。例如：

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

    如果 details 属性为空，请仔细检查您是否指定了应用 ID 前缀。请注意，应用 ID 前缀可能与团队 ID 不同。

将 Firebase 添加至您的应用

  1. 在 UIApplicationDelegate 中导入 Firebase 模块：

    Swift

    import Firebase

    Objective-C

    @import Firebase;
  2. 配置一个 FirebaseApp 共享实例（通常在应用的 application:didFinishLaunchingWithOptions: 方法中）：

    Swift

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
[FIRApp configure];

使用 Firebase 控制台

如果您想生成一个动态链接（无论是出于测试目的，还是为了让您的营销团队轻松创建可以在社交媒体帖子等地方使用的链接），最简单的方法就是访问 Firebase 控制台并按照分步说明手动创建一个。

使用 iOS Builder API

您可以使用 iOS Builder API 利用参数构建动态链接，也可以将长动态链接缩短。

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

下面这个极为简单的示例创建了一个指向 https://www.example.com/my-page 的长动态链接，此链接会在您的 iOS 应用和 Android 应用 com.example.android 中打开：

Swift

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

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

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

Objective-C

[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

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

Objective-C

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 创建带有任何受支持参数的动态链接。如需了解详细信息，请参阅 API 参考。

以下示例创建了一个带有几个常见参数的动态链接：

Swift

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

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);

您可以使用以下对象和属性设置动态链接参数：

DynamicLinkComponents
link

您的应用将打开的链接。指定一个您的应用能够处理的网址，通常是应用的内容或负载，用于启动应用特有的逻辑（例如为用户发放优惠券或显示欢迎页面）。此链接必须是格式正确的网址、采用正确的网址编码、使用 HTTP 或 HTTPS 架构，并且不能是另一个动态链接。
domainURIPrefix 您的动态链接网址前缀，可在 Firebase 控制台中找到。动态链接网域类似于以下示例：

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”，当动态链接打开时，会跳过应用预览页面，重定向到相关应用或商店。当用户在应用中打开动态链接时，应用预览页面（默认为启用状态）可以更加可靠地将用户引导至最合适的目标位置；但是，如果您希望动态链接仅在无需此页面也能可靠地打开它的应用中打开，则可以使用此参数停用应用预览页面。注意：应用预览页面当前仅在 iOS 上显示，但最终可能会在 Android 上显示。此参数将影响动态链接在这两种平台上的行为。
DynamicLinkSocialMetaTagParameters
title 在社交贴子中分享动态链接时要使用的标题。
descriptionText 在社交贴子中分享动态链接时要使用的描述。
imageURL 与此链接关联的图片的网址。该图片的尺寸应至少为 300x200 像素，且小于 300 KB。
DynamicLinkGoogleAnalyticsParameters
source
medium
campaign
term
content		 Google Play Analytics 参数。这些参数（utm_source、utm_medium、utm_campaign、utm_term、utm_content）会传递到 Play 商店并附加到链接负载。
DynamicLinkItunesConnectAnalyticsParameters
providerToken
affiliateToken
campaignToken		 iTunes Connect Analytics 参数。这些参数（pt、at、ct）会传递到 App Store。

要缩短长动态链接，请将长动态链接与 DynamicLinkComponentsOptions 对象一起传递给 shortenURL(url:options:)（如果您想生成具有短后缀的链接）：

Swift

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

[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);
}];

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

但是，如果开发者已出于其他原因使用自定义网址架构，则可能希望为其动态链接使用相同的自定义网址架构。如果您属于这种情况，则可以按照以下步骤为您的 Firebase 动态链接指定不同的网址架构：

  1. 设置您的应用时，请确保在配置 FirebaseApp 共享实例之前指定该应用将使用的默认网址架构：

    Swift

    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 = self.customURLScheme
  FirebaseApp.configure()

  return true
}

    Objective-C

    - (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。

后续步骤

现在您已创建动态链接，此时您需要设置您的应用以接收动态链接，并在用户打开动态链接时将用户引至您的应用中的相应位置。

要在您的应用中接收动态链接，请参阅适用于 iOS、Android、C++ 和 Unity 的文档。