Defining a Custom URL Scheme for Your App

Custom URL schemes provide a way to reference resources inside your app. Users tapping a custom URL in an email, for example, launch your app in a specified context. Other apps can also trigger your app to launch with specific context data; for example, a photo library app might display a specified image.

Apple supports common schemes associated with system apps, such as mailto, tel, sms, and facetime. You can define your own custom scheme and register your app to support it.

Support a custom URL scheme by doing the following:

1. Define the format for your app's URLs.

2. Register your scheme so that the system directs appropriate URLs to your app.

3. Handle the URLs that your app receives.

URLs must start with your custom scheme name. Add parameters for any options your app supports. For example, a photo library app might define a URL format that includes the name or index of a photo album to display. Examples of URLs for such a scheme could include the following:

myphotoapp:albumname?name=”albumname”
myphotoapp:albumname?index=1

Clients craft URLs based on your scheme and ask your app to open them by calling the open(_:options:completionHandler:) method of UIApplication. Clients can ask the system to inform them when your app opens the URL.

let url = URL(string: "myphotoapp:Vacation?index=1")
       
UIApplication.shared.open(url!) { (result) in
    if result {
       // The URL was delivered successfully!
    }
}

URL scheme registration specifies which URLs to redirect to your app. Register your scheme in Xcode from the Info tab of your project settings. Update the URL Types section to declare all of the URL schemes your app supports, as in Figure 1:

• Specify the prefix you use for your URLs in the URL Schemes box.

• Choose a role for your app:

  • Specify an editor role for URL schemes that you define.

  • Specify a viewer role for schemes that your app adopts, but does not define.

• Specify an identifier for your app.

The identifier you supply with your scheme distinguishes your app from others that declare support for the same scheme. To ensure uniqueness, specify a reverse DNS string that incorporates your company’s domain and app name. Although using a reverse DNS string is a best practice, it does not prevent other apps from registering the same scheme and handling the associated links. Use universal links instead of custom URL schemes to define links that are uniquely associated with your website.

You cannot claim support for some well-known URL schemes, including http, https, mailto, tel, sms, facetime, and facetime-audio. The system directs well-known types of URLs to the corresponding system apps and well-known http–based URLs to specific apps, such as Maps, YouTube, and Music. For information about the schemes supported by Apple, see Apple URL Scheme Reference.

When another app opens a URL containing your custom scheme, the system launches your app, if necessary, and brings it to the foreground. The system delivers the URL to your app by calling your app delegate’s application(_:open:options:) method. Add code to the method to parse the contents of the URL and take appropriate actions. To ensure the URL is parsed correctly, use NSURLComponents APIs to extract the components. Obtain additonal information about the URL, such as which app opened it, from the system-provided options dictionary.

func application(_ application: UIApplication,
                 open url: URL,
                 options: [UIApplicationOpenURLOptionsKey : Any] = [:] ) -> Bool {
    
    // Determine who sent the URL.
    let sendingAppID = options[.sourceApplication]
    print("source application = \(sendingAppID ?? "Unknown")")
    
    // Process the URL.
    guard let components = NSURLComponents(url: url, resolvingAgainstBaseURL: true),
        let albumPath = components.path,
        let params = components.queryItems else {
            print("Invalid URL or album path missing")
            return false
    }
    
    if let photoIndex = params.first(where: { $0.name == "index" })?.value {
        print("albumPath = \(albumPath)")
        print("photoIndex = \(photoIndex)")
        return true
    } else {
        print("Photo index missing")
        return false
    }
}

The system also uses your app delegate's application(_:open:options:) method to open custom file types that your app supports.