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 Whitelist 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 Store ID 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:

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

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:

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

[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:

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)")
}

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:

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

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:

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

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:

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

[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.