Deep linking

Deep linking is a way of providing a link that launches a native app, shows specific content, or takes some specific action. If you’re looking to implement deep links in your iOS app for the first time, follow these steps.

For general information on what deep links are, refer to our FAQ article.

Step 1: Registering a scheme

To handle deep linking, a custom scheme must be stated in your Info.plist file. The navigation structure is defined by an array of dictionaries. Each of those dictionaries contains an array of strings.

Use Xcode to edit your Info.plist file:

1. Add a new key, URL types. Xcode will automatically make this an array containing a dictionary called Item 0.
2. Within Item 0, add a key URL identifier. Set the value to your custom scheme.
3. Within Item 0, add a key URL Schemes. This will automatically be an array containing a Item 0 string.
4. Set URL Schemes » Item 0 to your custom scheme.

Alternatively, if you wish to edit your Info.plist file directly, you can follow this spec:

1
2
3
4
5
6
7
8
9
10
11
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>YOUR.SCHEME</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR.SCHEME</string>
        </array>
    </dict>
</array>

Step 2: Adding a scheme allowlist

You must declare the URL schemes you wish to pass to canOpenURL(_:) by adding the LSApplicationQueriesSchemes key to your app’s Info.plist file. Attempting to call schemes outside this allowlist will cause the system to record an error in the device’s logs, and the deep link will not open. An example of this error will look like this:

1
<Warning>: -canOpenURL: failed for URL: "yourapp://deeplink" – error: "This app is not allowed to query for scheme yourapp"

For example, if an in-app message should open the Facebook app when tapped, the app has to have the Facebook custom scheme (fb) in your allowlist. Otherwise, the system will reject the deep link. Deep links that direct to a page or view inside your own app still require that your app’s custom scheme be listed in your app’s Info.plist.

Your example allowlist might look something like:

1
2
3
4
5
6
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>myapp</string>
    <string>fb</string>
    <string>twitter</string>
</array>

For more information, refer to Apple’s documentation on the LSApplicationQueriesSchemes key.

Step 3: Implement a handler

After activating your app, iOS will call the method application:openURL:options:. The important argument is the NSURL object.

• swift
• objective-c

1
2
3
4
5
6
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  let path = url.path
  let query = url.query
  // Insert your code here to take some action based upon the path and query.
  return true
}

1
2
3
4
5
6
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
  NSString *path  = [url path];
  NSString *query = [url query];
  // Insert your code here to take some action based upon the path and query.
  return YES;
}

App transport security (ATS)

ATS requirements

From Apple’s documentation: “App Transport Security is a feature that improves the security of connections between an app and web services. The feature consists of default connection requirements that conform to best practices for secure connections. Apps can override this default behavior and turn off transport security.”

ATS is applied by default. It requires that all connections use HTTPS and are encrypted using TLS 1.2 with forward secrecy. Refer to Requirements for Connecting Using ATS for more information. All images served by Braze to end devices are handled by a content delivery network (“CDN”) that supports TLS 1.2 and is compatible with ATS.

Unless they are specified as exceptions in your application’s Info.plist, connections that do not follow these requirements will fail with errors that look something like this:

1
2
CFNetwork SSLHandshake failed (-9801)
Error Domain=NSURLErrorDomain Code=-1200 "An SSL error has occurred, and a secure connection to the server cannot be made."

1
NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9802)

ATS compliance is enforced for links opened within the mobile app (our default handling of clicked links) and does not apply to sites opened externally via a web browser.

Handling ATS requirements

You can handle ATS in one of the following three ways:

Ensure all links are ATS-compliant (recommended)

Your Braze integration can satisfy ATS requirements by ensuring that any existing links you drive users to (for example, though in-app message and push campaigns) satisfy ATS requirements. While there are ways to bypass ATS restrictions, our recommendation is to ensure that all linked URLs are ATS-compliant. Given Apple’s increasing emphasis on application security, the following approaches to allowing ATS exceptions are not guaranteed to be supported by Apple.

Partially disable ATS

You can allow a subset of links with certain domains or schemes to be treated as exceptions to the ATS rules. Your Braze integration will satisfy ATS requirements if every link you use in a Braze messaging channel is either ATS compliant or handled by an exception.

To add a domain as an exception of the ATS, add following to your app’s Info.plist file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

Refer to Apple’s article on app transport security keys for more information.

Disable ATS entirely

You can turn off ATS entirely. Note that this is not recommended practice, due to both lost security protections and future iOS compatibility. To disable ATS, insert the following in your app’s Info.plist file:

1
2
3
4
5
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

URL encoding

The SDK percent-encodes links to create valid URLs. All link characters that are not allowed in a properly formed URL, such as Unicode characters, will be percent escaped.

To decode an encoded link, use the String property removingPercentEncoding. You must also return true in the BrazeDelegate.braze(_:shouldOpenURL:). A call to action is required to trigger the handling of the URL by your app.

For example:

• swift
• objective-c

1
2
3
4
5
  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let urlString = url.absoluteString.removingPercentEncoding
    // Handle urlString
    return true
  }

1
2
3
4
5
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options {
  NSString *urlString = [url.absoluteString stringByRemovingPercentEncoding];
  // Handle urlString
  return YES;
}

Deep linking to app settings

You can take advantage of UIApplicationOpenSettingsURLString to deep link users to your app’s settings from Braze push notifications, in-app messages, and the News Feed.

To take users from your app into the iOS settings:

1. First, make sure your application is set up for either scheme-based deep links or universal links.
2. Decide on a URI for deep linking to the Settings page (for example, myapp://settings or https://www.braze.com/settings).
3. If you are using custom scheme-based deep links, add the following code to your application:openURL:options: method:

• swift
• objective-c

1
2
3
4
5
6
7
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  let path = url.path
  if (path == "settings") {
    UIApplication.shared.openURL(URL(string:UIApplication.openSettingsURLString)!)
  }
  return true
}

1
2
3
4
5
6
7
8
9
10
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  NSString *path  = [url path];
  if ([path isEqualToString:@"settings"]) {
    NSURL *settingsURL = [NSURL URLWithString:UIApplicationOpenSettingsURLString];
    [[UIApplication sharedApplication] openURL:settingsURL];
  }
  return YES;
}

Customization

Default WebView customization

The Braze.WebViewController class displays web URLs opened by the SDK, typically when “Open Web URL Inside App” is selected for a web deep link.

You can customize the Braze.WebViewController via the BrazeDelegate.braze(_:willPresentModalWithContext:) delegate method.

Linking handling customization

The BrazeDelegate protocol can be used to customize the handling of URLs such as deep links, web URLs, and universal links. To set the delegate during Braze initialization, set a delegate object on the Braze instance. Braze will then call your delegate’s implementation of shouldOpenURL before handling any URIs.

Universal links

Braze supports universal links in push notifications, in-app messages, and Content Cards. To enable universal link support, configuration.forwardUniversalLinks must be set to true.

When enabled, Braze will forward universal links to your app’s AppDelegate via the application:continueUserActivity:restorationHandler: method.

Your application also needs to be set up to handle universal links. Refer to Apple’s documentation to ensure your application is configured correctly for universal links.

Integration example: BrazeDelegate

• swift
• objective-c

1
2
3
4
5
6
7
8
func braze(_ braze: Braze, shouldOpenURL context: Braze.URLContext) -> Bool {
  if context.url.host == "MY-DOMAIN.com" {
    // Custom handle link here
    return false
  }
  // Let Braze handle links otherwise
  return true
}

1
2
3
4
5
6
7
8
- (BOOL)braze:(Braze *)braze shouldOpenURL:(BRZURLContext *)context {
  if ([[context.url.host lowercaseString] isEqualToString:@"MY-DOMAIN.com"]) {
    // Custom handle link here
    return NO;
  }
  // Let Braze handle links otherwise
  return YES;
}

For more information, see BrazeDelegate.