iOS Universal Links

Associated domains, apple-app-site-association, and CDN hosting - the iOS cookbook for opening https:// marketing URLs directly in your Expo SDK 57 app without a custom scheme disambiguation sheet.

Recipe

Quick-reference recipe card - copy-paste ready.

// app.config.ts
export default {
  expo: {
    scheme: "shopapp",
    ios: {
      bundleIdentifier: "com.example.shopapp",
      associatedDomains: ["applinks:shop.example.com"],
    },
  },
};

// https://shop.example.com/.well-known/apple-app-site-association
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.example.shopapp",
        "paths": ["/orders/*", "/product/*", "/invite/*"]
      }
    ]
  }
}

When to reach for this:

• Email and SMS campaigns use https:// links that should open the app when installed.
• You want seamless handoff from your marketing site without myapp:// prompts.
• App Store listings and smart banners reference the same canonical URLs as the app.
• You need iOS to verify domain ownership before opening links in-app.

Working Example

End-to-end setup for https://shop.example.com/orders/* on an Expo prebuild app.

Step 1 - Entitlements via app.config.ts

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  scheme: "shopapp",
  ios: {
    bundleIdentifier: "com.example.shopapp",
    associatedDomains: ["applinks:shop.example.com"],
  },
  android: {
    package: "com.example.shopapp",
  },
};
 
export default config;

Step 2 - Host AASA on your CDN

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.shopapp",
        "paths": [
          "/orders/*",
          "/product/*",
          "NOT /admin/*",
          "NOT /api/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.shopapp"]
  }
}

Serve at both paths (Apple checks either):

• https://shop.example.com/apple-app-site-association
• https://shop.example.com/.well-known/apple-app-site-association

Step 3 - CDN response headers

Content-Type: application/json
Cache-Control: max-age=3600

• No 301/302 redirects on the AASA URL - Apple rejects redirected association files.
• File must be unsigned - no .json extension required; raw JSON body.
• Replace ABCDE12345 with your Apple Team ID from the Developer portal.

Step 4 - Expo Router screen

// app/orders/[id].tsx
import { useLocalSearchParams } from "expo-router";
import { Text, View } from "react-native";
 
export default function OrderScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return (
    <View style={{ padding: 16 }}>
      <Text>Order {id}</Text>
    </View>
  );
}

Step 5 - Build and verify

npx expo prebuild --platform ios
npx expo run:ios
# Simulator: open universal link
xcrun simctl openurl booted "https://shop.example.com/orders/42"

What this demonstrates:

• associatedDomains entitlement generated at prebuild.
• AASA path rules limiting which URLs open the app.
• CDN headers required for Apple's crawler.
• Expo Router dynamic route matching /orders/42.
• Simulator testing before TestFlight.

Deep Dive

How It Works

• At install, iOS fetches AASA from each applinks: domain in your entitlements.
• Apple caches association data on device - updates propagate slowly (hours, sometimes days).
• When the user taps a matching https:// link, iOS opens your app and passes the URL to React Native.
• If verification fails or the path is excluded, Safari handles the URL normally.
• Custom schemes still work in parallel - universal links are preferred for marketing.

AASA Path Rules

CDN Checklist

iOS Notes

# Validate AASA with Apple's CDN (device will eventually see same data)
curl -s "https://app-site-association.cdn-apple.com/a/v1/shop.example.com" | jq .

• After changing AASA, bump CDN cache or purge edge nodes - stale files cause "works in staging, broken in prod."
• TestFlight builds use the production bundle ID - match appID exactly.
• Users who chose "Open in Safari" disable universal links per site until reset in Settings.

Gotchas

• Wrong Team ID in appID - link opens Safari silently. Fix: TEAMID.bundleIdentifier from Apple Developer → Membership.
• AASA behind redirect - www → apex redirect breaks fetch. Fix: serve AASA on the exact host in associatedDomains.
• Forgetting to rebuild after adding associatedDomains - entitlement missing in IPA. Fix: eas build --platform ios after config change.
• Including /api/* in paths - API JSON responses should not open the app. Fix: explicit NOT rules or narrow prefixes.
• Expecting instant AASA updates - iOS caches aggressively. Fix: change paths only with versioned marketing campaigns; keep old paths during transition.
• Universal link from same domain in WKWebView - in-app browser may not hand off. Fix: use SFSafariViewController or <a target="_blank"> for external open.

Alternatives

FAQs

Related

• Deep Linking Basics - scheme vs HTTPS overview
• expo-linking API - parse and listener patterns
• Android App Links - parallel Android verification
• Deep Link Testing Matrix - iOS simulator and device matrix
• ../expo-router/expo-router-basics/expo-router-basics.md - route file layout
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - deep-link review rules

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).

Y29kZWd1aWRlcy5pb3xjZ2lvOTE2fDIwMjYwNw