skip to content

In a bare React Native app, how do you register a custom URL scheme like resetapp:// on iOS and Android?

level: middleimportance: must knowfreq 50%

answer

  1. native config, not JavaScript
  2. iOS: CFBundleURLTypes in Info.plist
  3. Android: VIEW + DEFAULT + BROWSABLE
  4. a separate intent-filter on MainActivity
  5. rebuild the binary to apply

basics

~20 s

Register the scheme natively: on iOS add it under CFBundleURLTypes / CFBundleURLSchemes in Info.plist; on Android add an intent-filter with the VIEW action, DEFAULT and BROWSABLE categories and a data scheme to MainActivity. Then rebuild the app.

solid answer

~40 s

A scheme is claimed by the native app, not by JavaScript. On iOS I add a `CFBundleURLTypes` entry to `Info.plist` whose `CFBundleURLSchemes` array contains `resetapp`. On Android I add a new `<intent-filter>` to `MainActivity` in `AndroidManifest.xml` with the `android.intent.action.VIEW` action, the `DEFAULT` and `BROWSABLE` categories — `BROWSABLE` lets a browser link launch it — and `<data android:scheme="resetapp" />`; it must be its own filter, not added to the `MAIN`/`LAUNCHER` one. Both are native changes, so I rebuild and reinstall; a JavaScript reload or an over-the-air update does not apply them. Then I test with a real link, for example `npx uri-scheme open resetapp://reset-password --ios`. Handing the incoming URL to JavaScript on iOS also needs the `RCTLinkingManager` forwarding in the app delegate.

code

xml · 11 lines
xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.example.resetapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>resetapp</string>
    </array>
  </dict>
</array>

go deeper

for a junior

Remember that schemes are registered natively: CFBundleURLTypes in Info.plist on iOS and an intent filter in AndroidManifest.xml on Android.

for a middle

Explain each part of the Android filter, why it must be separate from the launcher filter, and why a rebuild rather than a reload is required.

for a senior

Choose a collision-resistant scheme, keep the number of schemes small, and remember any app can fire the scheme with arbitrary parameters.

for a principal

Decide which entry points deserve a custom scheme at all versus verified https links, weighing install state, security and support cost.

## Who owns a scheme A **custom URL scheme** such as `resetapp://` is a promise the operating system keeps: "when something opens a URL with this scheme, launch this app". The OS learns it from the app's **native configuration**, read at install time. Nothing in JavaScript — not `Linking`, not a navigation library's `prefixes` — registers a scheme. So registration is two native edits, one per platform, followed by a rebuild. ## iOS: CFBundleURLTypes In `ios/<App>/Info.plist`, add a `CFBundleURLTypes` array containing a dictionary whose `CFBundleURLSchemes` array lists the scheme: - `CFBundleURLTypes` — the list of URL types the app handles. - `CFBundleURLSchemes` — the schemes for one URL type, without `://`. - An optional `CFBundleURLName` identifies the URL type, commonly in reverse-DNS form. Xcode shows the same data under the target's **Info → URL Types**. For the URL to reach JavaScript, the app delegate forwards `application:openURL:options:` to `RCTLinkingManager`, as React Native's Linking documentation shows; how that URL is then received on cold and warm start is a separate topic. ## Android: an intent filter on MainActivity In `android/app/src/main/AndroidManifest.xml`, add an `<intent-filter>` inside the `MainActivity` `<activity>`: 1. `<action android:name="android.intent.action.VIEW" />` — the activity can display data given to it. 2. `<category android:name="android.intent.category.DEFAULT" />` — it can receive implicit intents. 3. `<category android:name="android.intent.category.BROWSABLE" />` — a browser may launch it from a tapped link. 4. `<data android:scheme="resetapp" />` — the scheme it claims (optionally with `android:host` to narrow it). Put it in a **separate** `<intent-filter>`: an intent filter matches as a unit, and the existing `MAIN`/`LAUNCHER` filter is what puts the app icon on the home screen. Expo's own manifest tooling follows the same rule — it recognises a link filter as one with the `VIEW` action and no `LAUNCHER` category, placed on the `singleTask` activity. ## Apply and test | Step | iOS | Android | |---|---|---| | Rebuild | rebuild and reinstall from Xcode or the CLI | rebuild and reinstall the APK | | Test | `npx uri-scheme open resetapp://reset-password --ios` | `npx uri-scheme open resetapp://reset-password --android` | | Also try | tap the link in Safari or Notes | tap the link in a browser page or chat | Neither a Metro reload nor an over-the-air JavaScript update can add a scheme: they change the JavaScript bundle, while the scheme lives in the installed binary's configuration. ## Choosing the scheme string - Use lowercase letters, and avoid generic words (`app`, `reset`, `myapp`) that another app might also claim. - A name derived from your bundle identifier is less likely to collide, but **nothing makes it unique**: any app can declare the same scheme. - Keep one scheme per app where possible; each extra scheme is another entry point to validate. ## What registration does not give you - It does not work when the app is **not installed**: the link simply fails, or the browser shows an error. Verified `https` links (Universal Links and App Links) fall back to the website instead. - It does not make links **trustworthy**. Any web page or app can open `resetapp://` with any parameters, so the screen it reaches must validate them. - It does not route the URL to a screen. Mapping `reset-password?token=…` onto a navigator's screen is the navigation library's linking configuration. ## What a strong answer shows It places the work in native config, names `CFBundleURLTypes`/`CFBundleURLSchemes` and the `VIEW`/`DEFAULT`/`BROWSABLE` filter with a `data` scheme, insists on a separate filter and a rebuild, and shows how to test the link from outside the app.

  • Why must the VIEW filter be separate from the MAIN/LAUNCHER filter on Android?
    Android matches an intent against each filter as a whole. The `MAIN`/`LAUNCHER` filter is what puts the app on the home screen; mixing the link's action, categories and data into it changes what that filter matches instead of adding a new entry point. A separate `VIEW`/`BROWSABLE` filter keeps both behaviours.
  • You added the scheme and reloaded Metro, but tapping resetapp:// still does nothing. Why?
    The scheme lives in `Info.plist` and `AndroidManifest.xml`, which the OS reads from the installed binary. A Metro reload only replaces the JavaScript bundle, so the old binary still does not claim the scheme. Rebuild and reinstall the app, then test again.

  • Adding the scheme to the navigation library's prefixes registers it with the OS.
  • A Metro reload or an over-the-air update is enough after adding a scheme.
  • The data element can go inside the existing MAIN/LAUNCHER intent filter.
  • Only the VIEW action is needed; BROWSABLE makes no difference for links in a browser.
  • Choosing an unusual scheme name guarantees no other app can claim it.