Expo Router + Appy: open the installed app, send everyone else to the right store

This guide is for Expo apps that use Expo Router and ship as a development or release build, made with EAS Build or npx expo run:ios and npx expo run:android. You give an Appy link a deep link to one of your screens. On Pro and Business no Appy code goes into the app: Appy’s page opens the deep link and sends phones without the app to their store. On Enterprise the React Native and Expo SDK adds Universal Links, App Links and deferred deep links.

What works on each plan#

What happens when someone taps the link#

A phone that opens a link with a Deeplink URL in a browser gets a short page from Appy instead of a redirect. iPhones, iPads, Android and Huawei phones all get it; computers go straight to the default destination URL.

The store is chosen per device, the same way as for links without a deep link: the App Store on iPhone and iPad, and Google Play, AppGallery, Galaxy Store, GetApps or a country rule on Android. A device without a store URL on the link goes to the default destination URL.

Register your scheme#

{
  "expo": {
    "scheme": "acme",
    "ios": { "bundleIdentifier": "com.acme.shop" },
    "android": { "package": "com.acme.shop" }
  }
}

• A scheme starts with a lowercase letter and contains only lowercase letters, digits, +, . and -. Pick one specific to your app rather than a common word.
• The same keys work in app.config.ts.
• The scheme is part of the native project. After adding or changing it, make a new build; an older build and Expo Go don’t know it.
• Without scheme, Expo registers ios.bundleIdentifier and android.package as schemes.

Map the deep link to a route#

Every Expo Router screen has a URL. For a custom scheme, Expo Router reads everything after :// as the path, so the host is the first segment. For an https link it drops the domain.

Projects from the default template keep routes in src/app since SDK 55; older projects use app. Read the route and query values with useLocalSearchParams:

import { useLocalSearchParams } from 'expo-router';
import { Text } from 'react-native';

export default function Product() {
  const { id, ref } = useLocalSearchParams<{ id: string; ref?: string }>();
  return <Text>Product {id}{ref ? ` from ${ref}` : ''}</Text>;
}

Expo Router reserves screen, params, initial and state, so don’t use them as parameter names in your deep links.

Rewrite deep links that don’t match a file#

If deep links you already use have another shape, rewrite them in src/app/+native-intent.tsx instead of changing every link. Expo Router passes each incoming URL to redirectSystemPath on iOS and Android before it picks a route:

export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
  return path.replace('acme://acme.com/', 'acme://');
}

Create the Appy link#

1. 1

   Default destination

   Create a link in the dashboard. The Default destination URL is where computers go, usually the matching page of your website.

2. 2

   Store URLs

   Under Mobile app store overrides, paste the full App Store URL and the Google Play URL in the https://play.google.com/store/apps/details?id=com.acme.shop form. Appy reads your package name from id for in-app browsers on Android.

3. 3

   Deep link

   Under Deeplink, turn on Enable deeplink redirect and enter acme://product/42 as Deeplink URL.

On Business you can create the same link with the REST API:

{
  "slug": "acme-spring",
  "fallbackUrl": "https://www.acme.com/spring",
  "deeplinkUrl": "acme://product/42",
  "targets": {
    "iphone": "https://apps.apple.com/app/id123456789",
    "android": "https://play.google.com/store/apps/details?id=com.acme.shop"
  }
}

The Deep Link Generator builds the scheme link and the Android intent URL from your scheme and path, if you want to check them before you create the link.

An https link on your own domain#

If the app already handles Universal Links and App Links on your domain, the Deeplink URL can be one of them, such as https://www.acme.com/product/42. The domain goes into the app config:

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:www.acme.com"]
    },
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [{ "scheme": "https", "host": "www.acme.com", "pathPrefix": "/product" }],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

• Write associatedDomains entries without https://.
• Your domain serves /.well-known/apple-app-site-association and /.well-known/assetlinks.json over HTTPS. The AASA and assetlinks generator writes both, and the Universal Link Validator checks them.
• The Android fingerprint is the SHA256 Fingerprint that eas credentials -p android lists for your build profile, or Google Play’s app signing key in Play Console if you don’t sign with EAS.
• iOS downloads the association file when the app is installed or updated, so a change reaches existing users with the next App Store update.

Your own domain and parameters (Business)#

• Add go.acme.com as a custom domain. Every link then also works as https://go.acme.com/acme-spring, with the same deep link behaviour.
• Turn on parameter forwarding for the link. A tap on https://go.acme.com/acme-spring?ref=newsletter then opens acme://product/42?ref=newsletter, and the same parameter goes to the store and website URLs. A key the deep link already sets keeps its value.
• On Business, the custom domain carries your links. Universal Links and App Links on it, which open the app without a page, are part of Enterprise.

Universal Links, App Links and deferred deep links (Enterprise)#

On Enterprise, Appy serves the association files for your app on its subdomain, such as acme.appy.to, or on your custom domain, and react-native-appy receives the links. The full setup is in the React Native and Expo SDK guide. Compared with Pro:

• The link opens the app directly: iOS and Android hand https://acme.appy.to/spring to the app before any page loads. Without the app, the same link goes to the store.
• The first launch after an install receives the link the person tapped, so a new user lands on the same screen, and you see which link brought each install.
• Keep scheme in the app config and the scheme deep link on your links. In-app browsers that ignore Universal Links open the app through Appy’s page with it.

{
  "expo": {
    "scheme": "acme",
    "plugins": [
      ["react-native-appy", { "linkDomains": ["acme.appy.to"] }]
    ]
  }
}

Expo Router would also try to open /spring for https://acme.appy.to/spring. Return null for Appy links in +native-intent.tsx and route them from Appy.addDeepLinkListener, as shown in Expo Router and React Navigation. For links on go.acme.com, see App links on your domain.

Test on a simulator and a device#

Run a development or release build that includes your scheme; Expo Go uses its own exp:// scheme. Test the deep link on its own first:

npx uri-scheme open "acme://product/42" --ios
npx uri-scheme open "acme://product/42" --android

xcrun simctl openurl booted "acme://product/42"
adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "acme://product/42"

Then open the Appy link, which goes through Appy’s page like a real tap:

xcrun simctl openurl booted "https://appy.to/acme-spring"
adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://appy.to/acme-spring"

• App installed: the app opens on the product screen.
• App removed: after about five seconds the page continues to the App Store or Google Play.
• On a phone, send yourself the link in Notes or Messages and tap it, as your users would. Typing a URL into the address bar doesn’t always open an app.
• Inside Instagram or TikTok, Appy shows the Open the app page. Tap Open the app.
• On a computer, the link opens the default destination URL.
• With an https deep link on Android, adb shell pm get-app-links com.acme.shop lists your domain as verified once Android has checked it.

Troubleshooting#

Tools and further reading#