Handle URLs in the SDK for iOS

Control how your app responds to URLs in push notifications and inbox messages by implementing the URL handling protocol. The SDK passes URLs from CloudPages push notifications, OpenDirect push notifications, and inbox messages to your app, but doesn’t automatically present them. Implement the URLHandlingDelegate protocol to open URLs in Safari, display them in your app using SFSafariViewController, or trigger custom app logic based on URL parameters.

To implement URL handling, follow these steps.

Implement the URLHandlingDelegate (v8.x) or MarketingCloudSDKURLHandlingDelegate (v7.x) protocol in your app.
Use setURLHandlingDelegate (v8.x) or sfmc_setURLHandlingDelegate: method to set a delegate for the protocol.
Implement the protocol method sfmc_handleURL:type:.

When the SDK receives an OpenDirect or CloudPages push notification, it passes a NSURL value to sfmc_handleURL:type:. This value contains the push notification or inbox message, and includes the URL. A type value also reflects the source of the URL, which is either SFMCURLTypeCloudPages or SFMCURLTypeOpenDirect.

If the development language is Swift, make the class that implements URLHandlingDelegate in version 8 or later or MarketingCloudSDKURLHandlingDelegate in version 7 Objective-C compatible. To make the delegate compatible, prefix the class with @objc and extend NSObject, as shown in these examples.

Important

This code example shows how to handle URLs using version 10 or higher of the SDK.

1// Framework import
2// The SFMCSDK module is included in the dependency packages for the SDK. Don't install it
3// separately or list it in your podfile.
4import SFMCSDK
5import MarketingCloudSDK
6import PushFeatureSDK
7
8// Make sure your class adopts the protocol
9@objc class MyClass: NSObject, URLHandlingDelegate
10
11...
12// Set the delegate somewhere in your application code after configuring the SDK
13  PushFeature.requestSdk { pushFeature in
14    pushFeature?.setURLHandlingDelegate(self)
15  }
16...
17
18// EXAMPLE IMPLEMENTATIONS
19// Implement the protocol method and have iOS handle the URL itself
20func sfmc_handleURL(_ url: URL, type: String) {
21  if UIApplication.shared.canOpenURL(url) == true {
22    if #available(iOS 10.0, *) {
23      UIApplication.shared.open(url, options: [:], completionHandler: { success in
24        if success {
25          print("url (url) opened successfully")
26        } else {
27          print("url (url) could not be opened")
28        }
29      })
30    } else {
31      if UIApplication.shared.openURL(url) == true {
32        print("URL (url) opened successfully")
33      } else {
34        print("Couldn't open URL (url)")
35      }
36    }
37  }
38}
39
40// Implement the protocol method and use SFSafariViewController to present the
41// URL within your app
42func sfmc_handleURL(_ url: URL, type: String) {
43  let safariViewController = SFSafariViewController(url: url)
44  window?.topViewController()?.present(safariViewController, animated: true) {}
45}
46
47// Implement the protocol method and take app-specific actions based on the URL
48func sfmc_handleURL(_ url: URL, type: String) {
49  let queryItems = URLComponents(string: url.absoluteString)?.queryItems
50  for item: URLQueryItem? in queryItems ?? [] {
51    // do something in your application based on the parameters in the URL
52  }
53}

For version 8.1 of the SDK, use this code.

1// Framework import
2// The SFMCSDK module is included in the dependency packages for the SDK. Don't install it
3// separately or list it in your podfile.
4import SFMCSDK
5import MarketingCloudSDK
6
7// Make sure your class adopts the protocol
8@objc class MyClass: NSObject, URLHandlingDelegate
9
10...
11// Set the delegate somewhere in your application code after configuring the SDK
12SFMCSdk.requestPushSdk { mp in
13    mp.setURLHandlingDelegate(self)
14}
15...
16
17// EXAMPLE IMPLEMENTATIONS
18// Implement the protocol method and have iOS handle the URL itself
19func sfmc_handleURL(_ url: URL, type: String) {
20  if UIApplication.shared.canOpenURL(url) == true {
21    if #available(iOS 10.0, *) {
22      UIApplication.shared.open(url, options: [:], completionHandler: { success in
23        if success {
24          print("url (url) opened successfully")
25        } else {
26          print("url (url) could not be opened")
27        }
28      })
29    } else {
30      if UIApplication.shared.openURL(url) == true {
31        print("url (url) opened successfully")
32      } else {
33        print("url (url) could not be opened")
34      }
35    }
36  }
37}
38
39// Implement the protocol method and use SFSafariViewController to present the
40// URL within your app
41func sfmc_handleURL(_ url: URL, type: String) {
42    let safariViewController = SFSafariViewController(url: url)
43    window?.topViewController()?.present(safariViewController, animated: true) {
44    }
45}
46
47// Implement the protocol method and take app-specific actions based on the URL
48func sfmc_handleURL(_ url: URL, type: String) {
49    let queryItems = URLComponents(string: url.absoluteString)?.queryItems
50    for item: URLQueryItem? in queryItems ?? [] {
51        // do something interesting in your application based on the parameters in the URL
52    }
53}

For version 8.0 of the SDK, use this code.

1// Framework import
2// The SFMCSDK module is included in the dependency packages for the SDK. Don't install it
3// separately or list it in your podfile.
4import SFMCSDK
5import MarketingCloudSDK
6
7// Make sure your class adopts the protocol
8@objc class MyClass: NSObject, URLHandlingDelegate
9
10...
11// Set the delegate somewhere in your application code after configuring the SDK
12// and confirming that the SDK is operational
13    mp.setURLHandlingDelegate(self)
14...
15// EXAMPLE IMPLEMENTATIONS
16// Implement the protocol method and have iOS handle the URL itself
17func sfmc_handleURL(_ url: URL, type: String) {
18  if UIApplication.shared.canOpenURL(url) == true {
19    if #available(iOS 10.0, *) {
20      UIApplication.shared.open(url, options: [:], completionHandler: { success in
21          if success {
22            print("url (url) opened successfully")
23          } else {
24            print("url (url) could not be opened")
25          }
26      })
27    } else {
28      if UIApplication.shared.openURL(url) == true {
29        print("url (url) opened successfully")
30      } else {
31        print("url (url) could not be opened")
32      }
33    }
34  }
35}
36
37// Implement the protocol method and use SFSafariViewController to present the
38// URL within your app
39func sfmc_handleURL(_ url: URL, type: String) {
40  let safariViewController = SFSafariViewController(url: url)
41  window?.topViewController()?.present(safariViewController, animated: true) {
42  }
43}
44
45// Implement the protocol method and take app-specific actions based on the URL
46func sfmc_handleURL(_ url: URL, type: String) {
47  let queryItems = URLComponents(string: url.absoluteString)?.queryItems
48  for item: URLQueryItem? in queryItems ?? [] {
49    // do something in the app based on the parameters in the URL
50  }
51}

For version 7 of the SDK, use this code.

1// Framework import
2import MarketingCloudSDK
3
4// Make sure your class adopts the protocol
5@objc class MyClass: NSObject, MarketingCloudSDKURLHandlingDelegate
6
7...
8// Set the delegate somewhere in your application code after configuring the SDK
9MarketingCloudSDK.sharedInstance().sfmc_setURLHandlingDelegate(self)
10...
11// EXAMPLE IMPLEMENTATIONS
12// Implement the protocol method and have iOS handle the URL itself
13func sfmc_handleURL(_ url: URL, type: String) {
14  if UIApplication.shared.canOpenURL(url) == true {
15    if #available(iOS 10.0, *) {
16      UIApplication.shared.open(url, options: [:], completionHandler: { success in
17        if success {
18          print("url (url) opened successfully")
19        } else {
20          print("url (url) could not be opened")
21        }
22      })
23    } else {
24      if UIApplication.shared.openURL(url) == true {
25        print("url (url) opened successfully")
26      } else {
27        print("url (url) could not be opened")
28      }
29    }
30  }
31}
32
33// Implement the protocol method and use SFSafariViewController to present the
34// URL within your app
35func sfmc_handleURL(_ url: URL, type: String) {
36  let safariViewController = SFSafariViewController(url: url)
37  window?.topViewController()?.present(safariViewController, animated: true) {
38  }
39}
40
41// Implement the protocol method and take app-specific actions based on the URL
42func sfmc_handleURL(_ url: URL, type: String) {
43  let queryItems = URLComponents(string: url.absoluteString)?.queryItems
44  for item: URLQueryItem? in queryItems ?? [] {
45    // do something in the app based on the parameters in the URL
46  }
47}