Create Dynamic Links on iOS

You can create short or long Dynamic Links with the Firebase Dynamic Links Builder API. This API accepts either a long Dynamic Link or an object containing Dynamic Link parameters, and returns URLs like the following examples:

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

Prerequisites

Firebase Dynamic Links requires iOS 8 or newer. You can target iOS 7 in your app, but Firebase Dynamic Links SDK calls only function on apps running iOS 8 or newer.

Set up Firebase and the Dynamic Links SDK

1. Add Firebase to your iOS project. Include the following pod in your Podfile:

   pod 'Firebase/Analytics'
   pod 'Firebase/DynamicLinks'
       

2. Run pod install and open the created .xcworkspace file.
3. In the Firebase console, open the Dynamic Links section.

4. If you have not already accepted the terms of service and set a URI prefix for your Dynamic Links, do so when prompted.

   If you already have a Dynamic Links URI prefix, take a note of it. You need to provide it when you programmatically create Dynamic Links.

   

5. Recommended: Specify the URL patterns allowed in your deep links and fallback links. By doing so, you prevent unauthorized parties from creating Dynamic Links that redirect from your domain to sites you don't control. See Allow specific URL patterns.

6. Ensure that your app's App Store ID and your App ID prefix is specified in your app's settings. To view and edit your app's settings, go to your Firebase project's Settings page and select your iOS app.

   Confirm that your Firebase project is properly configured to use Dynamic Links in your iOS app by opening the apple-app-site-association file that is hosted on your Dynamic Links domain. Firebase will serve the apple-app-site-association file from the root of the domain as well as the .well-known subdirectory. For example:

       https://example.com/apple-app-site-association
       https://example.com/.well-known/apple-app-site-association
       

   If your app is connected, the apple-app-site-association file contains a reference to your app's App ID prefix and bundle ID. For example:

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

   If the details property is empty, double-check that you specified your App ID prefix. Note that your App ID prefix may not be the same as your Team ID.

Add Firebase to your app

1. Import the Firebase module in your UIApplicationDelegate:

   Swift

   import Firebase

   Objective-C

   @import Firebase;

2. Configure a FirebaseApp shared instance, typically in your app's application:didFinishLaunchingWithOptions: method:

   Swift

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

   Objective-C

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

Use the Firebase console

If you want to generate a single Dynamic Link, either for testing purposes, or for your marketing team to easily create a link that can be used in something like a social media post, the simplest way would be to visit the Firebase console and create one manually following the step-by-step form.

Use the iOS Builder API

You can use the iOS Builder API to build Dynamic Links from parameters, or to shorten a long Dynamic Link.

Create a Dynamic Link from parameters

To create a Dynamic Link, create a new DynamicLinkComponents object and specify the Dynamic Link parameters by setting the object's corresponding properties. Then, get the long link from the object's url property or get the short link by calling shorten().

The following minimal example creates a long Dynamic Link to https://www.example.com/my-page that opens with your iOS app on iOS and the app com.example.android on 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);

To create a short Dynamic Link, build a DynamicLinkComponents the same way, and then call shorten().

Building a short link requires a network call, so instead of directly returning the link, shorten() accepts a completion handler, which is called when the request completes. For example:

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

By default, short Dynamic Links are generated with 17-character link suffixes that make it extremely unlikely that someone can guess a valid Dynamic Link. If, for your use case, there's no harm in someone successfully guessing a short link, you might prefer to generate suffixes that are only as long as necessary to be unique, which you can do by setting the dynamicLinkComponentsOptions property:

Swift

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

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 parameters

You can use the Dynamic Link Builder API to create Dynamic Links with any of the supported parameters. See the API reference for details.

The following example creates a Dynamic Link with several common parameters set:

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

You can set Dynamic Link parameters with the following objects and properties:

DynamicLinkComponents
link	The link your app will open. Specify a URL that your app can handle, typically the app's content or payload, which initiates app-specific logic (such as crediting the user with a coupon or displaying a welcome screen). This link must be a well-formatted URL, be properly URL-encoded, use either HTTP or HTTPS, and cannot be another Dynamic Link. When users open a Dynamic Link on a desktop web browser, they will load this URL (unless the ofl parameter is specified). If you don't have a web equivalent to the linked content, the URL doesn't need to point to a valid web resource. In this situation, you should set up a redirect from this URL to, for example, your home page.
domainURIPrefix	Your Dynamic Link URL prefix, which you can find in the Firebase console. A Dynamic Link domain looks like the following examples: https://example.com/link https://example.page.link

DynamicLinkAndroidParameters
fallbackURL	The link to open when the app isn't installed. Specify this to do something other than install your app from the Play Store when the app isn't installed, such as open the mobile web version of the content, or display a promotional page for your app.
minimumVersion	The versionCode of the minimum version of your app that can open the link. If the installed app is an older version, the user is taken to the Play Store to upgrade the app.

DynamicLinkIOSParameters
appStoreID	Your app's App Store ID, used to send users to the App Store when the app isn't installed
fallbackURL	The link to open when the app isn't installed. Specify this to do something other than install your app from the App Store when the app isn't installed, such as open the mobile web version of the content, or display a promotional page for your app.
customScheme	Your app's custom URL scheme, if defined to be something other than your app's bundle ID
iPadFallbackURL	The link to open on iPads when the app isn't installed. Specify this to do something other than install your app from the App Store when the app isn't installed, such as open the web version of the content, or display a promotional page for your app.
iPadBundleID	The bundle ID of the iOS app to use on iPads to open the link. The app must be connected to your project from the Overview page of the Firebase console.
minimumAppVersion	The version number of the minimum version of your app that can open the link. This flag is passed to your app when it is opened, and your app must decide what to do with it.

DynamicLinkNavigationInfoParameters

forcedRedirectEnabled

If set to '1', skip the app preview page when the Dynamic Link is opened, and instead redirect to the app or store. The app preview page (enabled by default) can more reliably send users to the most appropriate destination when they open Dynamic Links in apps; however, if you expect a Dynamic Link to be opened only in apps that can open Dynamic Links reliably without this page, you can disable it with this parameter. Note: the app preview page is only shown on iOS currently, but may eventually be shown on Android. This parameter will affect the behavior of the Dynamic Link on both platforms.

DynamicLinkSocialMetaTagParameters
title	The title to use when the Dynamic Link is shared in a social post.
descriptionText	The description to use when the Dynamic Link is shared in a social post.
imageURL	The URL to an image related to this link. The image should be at least 300x200 px, and less than 300 KB.

DynamicLinkGoogleAnalyticsParameters
source medium campaign term content	Google Play analytics parameters. These parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content) are passed on to the Play Store as well as appended to the link payload.

DynamicLinkItunesConnectAnalyticsParameters
providerToken affiliateToken campaignToken	iTunes Connect analytics parameters. These parameters (pt, at, ct) are passed to the App Store.

Shorten a long Dynamic Link

To shorten a long Dynamic Link, pass the long Dynamic Link to shortenURL(url:options:) along with a DynamicLinkComponentsOptions object if you want to generate a link with a short suffix:

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

Specifying a custom URL scheme for Dynamic Links

By default, Dynamic Links uses your app's bundle identifier as the URL scheme needed to open up your application. We recommend staying with this default value to keep your implementation simple.

However, developers who are already using a custom URL scheme for other purposes may wish to use this same custom URL scheme for their Dynamic Links as well. If you are in this situation, you can specify a different URL scheme for your Firebase Dynamic Links by following these steps:

1. When setting up your app, make sure you specify the default URL scheme to be used by your application before configuring your FirebaseApp shared instance:

   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. Whenever you create any Dynamic Link, you will need to specify the custom URL scheme that your app uses. You can do this through the Firebase console, setting the customScheme in the Builder API, specifying the ius parameter in your URL, or sending the iosCustomScheme parameter to the REST API

Next steps

Now that you've created Dynamic Links, you need to set up your app to receive Dynamic Links and send users to the right place in your app after a user opens them.

To receive Dynamic Links in your app, see the documentation for iOS, Android, C++, and Unity.