0Pricing
React Native Academy · Lesson

Configuring Custom URL Schemes

Define a custom URL scheme in app.json for Expo, test opening the app from a terminal with xcrun openurl or adb, and read the initial URL on app launch.

Configuring Custom URL Schemes is a free React Native Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Native Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is Deep Linking?

Deep linking allows external URLs — in emails, web browsers, QR codes, or other apps — to open your React Native app and navigate directly to a specific screen rather than the home screen. This dramatically improves user experience for notifications, marketing campaigns, and cross-app flows.

There are two types of deep links: custom URL schemes (like myapp://profile/123) and universal links (like https://example.com/profile/123). This lesson covers custom URL schemes, which are simpler to set up and work on both iOS and Android.

Configuring the Scheme in app.json

In an Expo managed app, you register your custom URL scheme in app.json under the scheme key. Choose a scheme that is unique to your app — using a generic term risks conflicts with other apps. Convention is to use your app name in lowercase, like myappname.

After adding the scheme, you must rebuild the native app (run npx expo run:ios or run:android) because scheme registration requires native configuration. The scheme is read from app.json by Expo's prebuild pipeline and injected into the native project files automatically.

// app.json
{
  'expo': {
    'name': 'MyApp',
    'slug': 'my-app',
    'scheme': 'myapp',  // registers myapp:// scheme
    'ios': {
      'bundleIdentifier': 'com.example.myapp'
    },
    'android': {
      'package': 'com.example.myapp'
    }
  }
}

What Happens Under the Hood

When you define a scheme in app.json, Expo's prebuild writes the necessary native configurations:

  • iOS: adds a CFBundleURLSchemes entry in Info.plist so the system routes myapp:// URLs to your app
  • Android: adds an intent-filter in AndroidManifest.xml with action VIEW and scheme matching your custom scheme

These registrations tell the operating system that your app handles URLs of that scheme. When another app or a web page opens such a URL, the OS launches your app and passes the URL to it.

// What Expo writes to AndroidManifest.xml:
// <intent-filter>
//   <action android:name='android.intent.action.VIEW' />
//   <category android:name='android.intent.category.DEFAULT' />
//   <category android:name='android.intent.category.BROWSABLE' />
//   <data android:scheme='myapp' />
// </intent-filter>

Testing the URL Scheme Locally

You can test your custom URL scheme from a terminal without building a special test harness. On iOS simulator use xcrun simctl openurl booted 'myapp://profile/123'. On Android emulator use adb shell am start -W -a android.intent.action.VIEW -d 'myapp://profile/123'.

Both commands launch the app (or bring it to foreground if running) and pass the URL. This lets you verify scheme handling before integrating with actual links in other apps or web pages.

# iOS Simulator:
xcrun simctl openurl booted 'myapp://profile/123'

# Android Emulator (ADB):
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d 'myapp://profile/123'

Reading the Initial URL on Launch

When the app is opened cold (not running) via a deep link, you need to read the URL that triggered the launch. Use Linking.getInitialURL() from React Native's built-in Linking module. It returns a Promise that resolves with the URL string or null if the app launched normally.

Call this in a useEffect with an empty dependency array so it runs once on mount. Parse the URL to extract the route and navigate accordingly once the navigation stack is ready.

import { Linking } from 'react-native';
import { useEffect } from 'react';

useEffect(() => {
  Linking.getInitialURL().then((url) => {
    if (url) {
      console.log('App opened via URL:', url);
      // Parse and navigate
      handleDeepLink(url);
    }
  }).catch((err) => {
    console.error('getInitialURL error:', err);
  });
}, []);

Handling Links While App Is Running

When the app is already running and a deep link URL opens it, getInitialURL() returns null. Instead, you need to subscribe to URL events using Linking.addEventListener('url', callback). This fires whenever a new URL arrives while the app is in the foreground or background.

Always remove the event listener in the cleanup function returned from useEffect to prevent memory leaks. Both the initial URL check and the event listener should call the same URL handler for consistency.

useEffect(() => {
  // Cold launch:
  Linking.getInitialURL().then((url) => {
    if (url) handleDeepLink(url);
  });

  // While running:
  const subscription = Linking.addEventListener('url', ({ url }) => {
    handleDeepLink(url);
  });

  return () => subscription.remove(); // cleanup
}, []);

Parsing Deep Link URLs

The URL you receive is a raw string like myapp://profile/123?tab=posts. Parse it using the URL Web API (available in React Native via the Hermes runtime) or a helper library. Extract the pathname to determine the screen and query parameters for additional data.

A simple approach for basic deep links: split the URL on :// to get the path, then split the path on / to get segments. For query params, use URLSearchParams.

function handleDeepLink(url) {
  // url = 'myapp://profile/123?tab=posts'
  const parsed = new URL(url);
  // parsed.hostname = 'profile'
  // parsed.pathname = '/123'
  // parsed.searchParams.get('tab') = 'posts'

  const screen = parsed.hostname;
  const id = parsed.pathname.replace('/', '');
  const tab = parsed.searchParams.get('tab');

  if (screen === 'profile') {
    navigation.navigate('Profile', { id, tab });
  }
}

Multiple URL Scheme Support

An app can register multiple URL schemes — for example, one for production use (myapp://) and one for development/staging (myapp-dev://). In Expo you define the primary scheme in the top-level scheme field; additional schemes require a config plugin to add extra intent-filters to AndroidManifest and additional CFBundleURLSchemes entries to Info.plist.

Separate schemes per environment prevent staging deep links from accidentally opening the production app on the same device during QA testing.

// app.json - single scheme (managed):
{
  'expo': {
    'scheme': 'myapp'
  }
}

// For multiple schemes, use a config plugin:
// withMySchemes.js
const { withAndroidManifest } = require('@expo/config-plugins');
module.exports = (config) =>
  withAndroidManifest(config, (config) => {
    // Add extra intent-filters to main activity
    return config;
  });

Scheme Conflicts and Best Practices

Custom URL schemes are not globally registered — any app can claim the same scheme, and on iOS if two apps share a scheme the most recently installed one wins. This is why custom schemes are not suitable for security-sensitive flows like OAuth callbacks where you need to guarantee which app receives the redirect.

Best practices for custom schemes: use a reverse-domain format (com.yourcompany.yourapp://), keep the scheme in your app name format, and for anything security-sensitive (OAuth, payment callbacks) use universal links (HTTPS URLs) instead.

// Avoid generic schemes:
// 'app://' or 'mobile://' — easily conflicts

// Better: reverse domain or unique name:
// 'com.acme.myapp://'
// 'acmemyapp://'

// In app.json:
{
  'expo': {
    'scheme': 'acmemyapp'
  }
}

Opening Other Apps' URL Schemes

Your app can also open other apps via their URL schemes using Linking.openURL(url). Call Linking.canOpenURL(url) first to check if the scheme is available on the device. Use this to open maps, email, phone dialer, or other apps from within your app.

On iOS, you must declare any schemes your app opens in the LSApplicationQueriesSchemes array in Info.plist — otherwise canOpenURL always returns false. Expo config plugins or the ios.infoPlist key in app.json handle this.

import { Linking } from 'react-native';

async function openMaps(address) {
  const url = 'maps://0,0?q=' + encodeURIComponent(address);
  const supported = await Linking.canOpenURL(url);
  if (supported) {
    await Linking.openURL(url);
  } else {
    // Fallback to Google Maps web:
    await Linking.openURL(
      'https://maps.google.com/?q=' + encodeURIComponent(address)
    );
  }
}

Debugging Deep Link Issues

Common deep link problems and their solutions:

  • URL not received — check scheme is in app.json and the native app was rebuilt after adding it.
  • getInitialURL returns null — add a listener too; sometimes the URL arrives as an event even for cold launches on certain OS versions.
  • Navigation not working — ensure navigation is ready before calling navigate; use a ref to the navigator with onReady.
  • Android emulator ADB test fails — verify the correct package name and that the app is installed.

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: the scheme key in app.json registers a custom URL scheme that routes URLs to your app on both iOS and Android, Linking.getInitialURL() reads the URL that launched the app cold, and Linking.addEventListener handles deep link URLs while the app is already running. Next up we use the Linking API to parse incoming URLs and dispatch navigation actions.

Frequently asked questions

Is the “Configuring Custom URL Schemes” lesson free?

Yes — the full text of “Configuring Custom URL Schemes” is free to read here on the web, and the React Native Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Native Academy course, upgrade to CoddyKit PRO.

What will I learn in “Configuring Custom URL Schemes”?

Define a custom URL scheme in app.json for Expo, test opening the app from a terminal with xcrun openurl or adb, and read the initial URL on app launch. You practise React Native Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start React Native Academy?

No prior experience is required. React Native Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Configuring Custom URL Schemes” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this React Native Academy lesson?

Yes. Every React Native Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Configuring Custom URL Schemes
  2. Linking API and URL Parsing
  3. React Navigation Deep Link Configuration
  4. Universal Links (HTTPS Deep Links) on iOS and Android
← Back to React Native Academy