Custom URI Scheme

Definition

A custom URI scheme is a non-standard URL protocol, such as myapp://, that an app registers with the operating system so that URLs beginning with it open that app.

It is the oldest form of mobile deep linking and the only one that works with no server, no domain and no verification — which is exactly why it is also the least trustworthy. Nothing stops a second app from registering the same scheme, and nothing happens at all if the app is not installed. Modern setups use Universal Links and App Links for user-facing links and keep a scheme for the jobs those cannot do.

Declaring a scheme on both platforms

iOS registers schemes in Info.plist; Android registers them as another <data> element on an intent filter. Neither declaration is checked against anything.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <!-- Reverse-DNS, so the OS can distinguish duplicate claims -->
    <key>CFBundleURLName</key>
    <string>com.example.shop</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>shopapp</string>
    </array>
  </dict>
</array>

<!-- Required before canOpenURL: can return true for another app -->
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>partnerapp</string>
</array>

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />

  <!-- shopapp://products/42 -->
  <data android:scheme="shopapp" android:host="products" />
</intent-filter>

A valid scheme starts with a letter and contains only letters, digits, +, - and .. Keep it lowercase — Android matches schemes case-sensitively and only against lowercase, so ShopApp in the manifest matches nothing.

Why schemes are not trustworthy

There is no registry. Registration is a claim in a bundle, verified by nobody, so a second app can declare shopapp and receive links intended for yours — including links carrying an OAuth authorisation code or a password reset token.

The second structural problem is what happens when the app is missing. A scheme URL has no fallback: iOS shows an error, and Android throws ActivityNotFoundException. There is no way to route the user to the store from the URL alone, which is what the fallback chain exists to solve.

Where a scheme is still the right tool

The honest list of remaining jobs is short: local testing, app-to-app handoffs between apps you control, OAuth callbacks where the provider does not support HTTPS redirects, and the last hop of an intent:// URL used to escape an in-app browser.

# iOS Simulator
xcrun simctl openurl booted "shopapp://products/42"

# Android device or emulator
adb shell am start -W -a android.intent.action.VIEW \
  -d "shopapp://products/42" com.example.shop

# Android: scheme wrapped in an intent:// URL with a web fallback,
# which is how you escape an in-app browser
adb shell am start -W -a android.intent.action.VIEW -d \
  "intent://products/42#Intent;scheme=shopapp;\
package=com.example.shop;\
S.browser_fallback_url=https%3A%2F%2Fexample.com%2Fproducts%2F42;end"

Receiving the URL in code

A scheme URL and a Universal Link arrive through different entry points on iOS, which is why an app can handle one and ignore the other.

@main
struct ShopApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                // shopapp://products/42
                .onOpenURL { url in
                    Router.shared.handle(url)
                }
                // https://example.com/products/42
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
                    guard let url = activity.webpageURL else { return }
                    Router.shared.handle(url)
                }
        }
    }
}

In UIKit the equivalents are application(_:open:options:) for schemes and application(_:continue:restorationHandler:) for Universal Links. On Android both arrive as an Intent on the same activity, so the split does not exist there.