Expo Go supports the exp:// URL scheme and Expo-hosted URLs
Custom builds required for your own domain's universal links (applinks:yourdomain.com)

If you only need deep linking for development/testing, try npx expo start with Expo Go first. Only create custom builds when you need production universal links with your own domain.

Automated Setup (Recommended)

Run setup-safari with your Apple ID to automate credential lookup:

EXPO_APPLE_ID="your-apple-id@email.com" bunx setup-safari

This will:

Authenticate with Apple Developer Portal
Enable Associated Domains for your bundle ID
Output the AASA file content and meta tag

After running, you must manually:

1. Create the AASA file

Create public/.well-known/apple-app-site-association (no file extension):

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAM_ID.com.your.bundleid"],
        "components": [
          {
            "/": "*",
            "comment": "Matches all routes"
          }
        ]
      }
    ]
  },
  "activitycontinuation": {
    "apps": ["TEAM_ID.com.your.bundleid"]
  },
  "webcredentials": {
    "apps": ["TEAM_ID.com.your.bundleid"]
  }
}

2. Create src/app/+html.tsx with Smart App Banner

import { ScrollViewStyleReset } from "expo-router/html";

export default function Root({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1, shrink-to-fit=no"
        />
        <meta name="apple-itunes-app" content="app-id=YOUR_ITUNES_ID" />
        <ScrollViewStyleReset />
      </head>
      <body>{children}</body>
    </html>
  );
}

3. Add Associated Domains to app.json

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:yourdomain.com",
        "activitycontinuation:yourdomain.com",
        "webcredentials:yourdomain.com"
      ]
    }
  }
}

4. Deploy and Rebuild

# Deploy web (AASA file must be accessible)
npx expo export -p web && npx eas-cli deploy

# Rebuild iOS app with new entitlements
npx expo run:ios
# Or for TestFlight: npx testflight

Interactive Setup (Alternative)

For interactive mode (requires TTY):

bunx setup-safari

How Universal Links Work

Universal links require two parts:

AASA file on your server - Tells iOS which paths your app handles
Associated Domains entitlement - Tells your app which domains to claim

AASA File Format

Host at https://yourdomain.com/.well-known/apple-app-site-association:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.example.app",
        "paths": ["*"]
      }
    ]
  }
}

Path patterns:

* - Match all paths
/products/* - Match paths starting with /products/
/item/??? - Match exactly 3 characters after /item/
NOT /admin/* - Exclude paths

Associated Domains Entitlement

In your app.json or app.config.js:

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:yourdomain.com",
        "applinks:www.yourdomain.com"
      ]
    }
  }
}

Testing Universal Links

After setup, test with setup-safari:

npx setup-safari

Or manually test in Safari:

Open Safari on iOS device/simulator
Navigate to a URL that should open your app
Pull down to reveal the banner, or long-press the link

Testing with Tunnel (No Server Required)

Test universal links without deploying a website using Expo's tunnel feature:

Set a consistent tunnel subdomain:

export EXPO_TUNNEL_SUBDOMAIN=my-app-name

Configure associated domains with the ngrok URL:

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:my-app-name.ngrok.io"]
    }
  }
}

Build the development client:

npx expo run:ios

Start the dev server with tunnel:

npx expo start --tunnel

Test the link - Type https://my-app-name.ngrok.io in Safari on your device. It should open your app directly.

The tunnel creates a public HTTPS URL that serves the AASA file automatically, letting you test the full universal links flow during development.

Debugging

Check if Apple has cached your AASA:

curl "https://app-site-association.cdn-apple.com/a/v1/yourdomain.com"

Validate AASA file format:

curl https://yourdomain.com/.well-known/apple-app-site-association | jq

Common issues:

AASA must be served with Content-Type: application/json
HTTPS required (no self-signed certs)
Apple caches AASA files - changes may take time to propagate

Expo Router Integration

With Expo Router, handle incoming links automatically:

// app/[...path].tsx handles all deep link paths
// app/products/[id].tsx handles /products/:id links

Access link parameters:

import { useLocalSearchParams } from "expo-router";

export default function Product() {
  const { id } = useLocalSearchParams();
  return <Text>Product: {id}</Text>;
}

name	universal-links
description	Set up and test universal links for iOS using setup-safari

Use bunx setup-safari to configure and test universal links (deep links) on iOS.

Important: When Custom Builds Are Needed

Universal links with custom domains require custom native builds. Your app will no longer work in Expo Go.

However, for basic deep linking during development:

Expo Go supports the exp:// URL scheme and Expo-hosted URLs
Custom builds required for your own domain's universal links (applinks:yourdomain.com)

If you only need deep linking for development/testing, try npx expo start with Expo Go first. Only create custom builds when you need production universal links with your own domain.

Automated Setup (Recommended)

Run setup-safari with your Apple ID to automate credential lookup:

EXPO_APPLE_ID="your-apple-id@email.com" bunx setup-safari

This will:

Authenticate with Apple Developer Portal
Enable Associated Domains for your bundle ID
Output the AASA file content and meta tag

After running, you must manually:

1. Create the AASA file

Create public/.well-known/apple-app-site-association (no file extension):

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAM_ID.com.your.bundleid"],
        "components": [
          {
            "/": "*",
            "comment": "Matches all routes"
          }
        ]
      }
    ]
  },
  "activitycontinuation": {
    "apps": ["TEAM_ID.com.your.bundleid"]
  },
  "webcredentials": {
    "apps": ["TEAM_ID.com.your.bundleid"]
  }
}

2. Create src/app/+html.tsx with Smart App Banner

import { ScrollViewStyleReset } from "expo-router/html";

export default function Root({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1, shrink-to-fit=no"
        />
        <meta name="apple-itunes-app" content="app-id=YOUR_ITUNES_ID" />
        <ScrollViewStyleReset />
      </head>
      <body>{children}</body>
    </html>
  );
}

3. Add Associated Domains to app.json

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:yourdomain.com",
        "activitycontinuation:yourdomain.com",
        "webcredentials:yourdomain.com"
      ]
    }
  }
}

4. Deploy and Rebuild

# Deploy web (AASA file must be accessible)
npx expo export -p web && npx eas-cli deploy

# Rebuild iOS app with new entitlements
npx expo run:ios
# Or for TestFlight: npx testflight

Interactive Setup (Alternative)

For interactive mode (requires TTY):

bunx setup-safari

How Universal Links Work

Universal links require two parts:

AASA file on your server - Tells iOS which paths your app handles
Associated Domains entitlement - Tells your app which domains to claim

AASA File Format

Host at https://yourdomain.com/.well-known/apple-app-site-association:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.example.app",
        "paths": ["*"]
      }
    ]
  }
}

Path patterns:

* - Match all paths
/products/* - Match paths starting with /products/
/item/??? - Match exactly 3 characters after /item/
NOT /admin/* - Exclude paths

Associated Domains Entitlement

In your app.json or app.config.js:

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:yourdomain.com",
        "applinks:www.yourdomain.com"
      ]
    }
  }
}

Testing Universal Links

After setup, test with setup-safari:

npx setup-safari

Or manually test in Safari:

Open Safari on iOS device/simulator
Navigate to a URL that should open your app
Pull down to reveal the banner, or long-press the link

Testing with Tunnel (No Server Required)

Test universal links without deploying a website using Expo's tunnel feature:

Set a consistent tunnel subdomain:

export EXPO_TUNNEL_SUBDOMAIN=my-app-name

Configure associated domains with the ngrok URL:

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:my-app-name.ngrok.io"]
    }
  }
}

Build the development client:

npx expo run:ios

Start the dev server with tunnel:

npx expo start --tunnel

Test the link - Type https://my-app-name.ngrok.io in Safari on your device. It should open your app directly.

The tunnel creates a public HTTPS URL that serves the AASA file automatically, letting you test the full universal links flow during development.

Debugging

Check if Apple has cached your AASA:

curl "https://app-site-association.cdn-apple.com/a/v1/yourdomain.com"

Validate AASA file format:

curl https://yourdomain.com/.well-known/apple-app-site-association | jq

Common issues:

AASA must be served with Content-Type: application/json
HTTPS required (no self-signed certs)
Apple caches AASA files - changes may take time to propagate

Expo Router Integration

With Expo Router, handle incoming links automatically:

// app/[...path].tsx handles all deep link paths
// app/products/[id].tsx handles /products/:id links

Access link parameters:

import { useLocalSearchParams } from "expo-router";

export default function Product() {
  const { id } = useLocalSearchParams();
  return <Text>Product: {id}</Text>;
}

universal-links

이 저장소의 다른 Skills

이 저장소의 다른 Skills

Important: When Custom Builds Are Needed

Automated Setup (Recommended)

1. Create the AASA file

2. Create src/app/+html.tsx with Smart App Banner

3. Add Associated Domains to app.json

4. Deploy and Rebuild

Interactive Setup (Alternative)

How Universal Links Work

AASA File Format

Associated Domains Entitlement

Testing Universal Links

Testing with Tunnel (No Server Required)

Debugging

Expo Router Integration

Important: When Custom Builds Are Needed

Automated Setup (Recommended)

1. Create the AASA file

2. Create src/app/+html.tsx with Smart App Banner

3. Add Associated Domains to app.json

4. Deploy and Rebuild

Interactive Setup (Alternative)

How Universal Links Work

AASA File Format

Associated Domains Entitlement

Testing Universal Links

Testing with Tunnel (No Server Required)

Debugging

Expo Router Integration