Deep linking in push notifications

Prerequisites

Before you can use this feature, you’ll need to integrate the Swift Braze SDK.

Handling deep links

Step 1: Register 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: Add 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)

As defined by Apple , “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 are similar to the following.

Example Error 1:

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

Example Error 2:

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.

Working with ATS

You can handle ATS in either of the following ways, but we recommend complying with ATS requirements.

• comply
• partially disable
• fully disable

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>

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

Decoding URLs

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 and in-app messages.

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 options

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.

Examples

BrazeDelegate

Here’s an example using BrazeDelegate. For more information, see Braze Swift SDK reference .

• 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;
}