# Deep Linking - Core Patterns

> Core deep linking patterns: URI schemes, expo-linking API, handling incoming URLs, React Navigation linking config, Expo Router. See [SKILL.md](../SKILL.md) for decision guidance and red flags.

---

## Pattern 1: expo-linking API Essentials

### useURL Hook

Handles both cold start URLs and foreground URL changes in a single hook.

```typescript
import { useEffect } from "react";
import * as Linking from "expo-linking";

// useURL returns the initial URL on cold start AND subsequent URL changes
export function DeepLinkHandler({
  onNavigate,
}: {
  onNavigate: (path: string, params: Record<string, string>) => void;
}) {
  const url = Linking.useURL();

  useEffect(() => {
    if (!url) return;

    const { path, queryParams } = Linking.parse(url);
    if (path) {
      onNavigate(path, queryParams as Record<string, string>);
    }
  }, [url, onNavigate]);

  return null;
}
```

**Why good:** Single hook handles all app states (cold start, background resume, foreground), no need to manage `getInitialURL` + `addEventListener` separately

### createURL and parse

```typescript
import * as Linking from "expo-linking";

// Create a deep link URL for your app
const profileUrl = Linking.createURL("profile/123", {
  queryParams: { tab: "posts" },
});
// In dev: exp://127.0.0.1:8081/--/profile/123?tab=posts
// In production: myapp://profile/123?tab=posts

// Parse any URL into structured parts
const parsed = Linking.parse("myapp://profile/123?tab=posts");
// { scheme: "myapp", hostname: null, path: "profile/123", queryParams: { tab: "posts" } }

const parsedHttps = Linking.parse("https://example.com/product/456?ref=email");
// { scheme: "https", hostname: "example.com", path: "product/456", queryParams: { ref: "email" } }
```

**Why good:** `createURL` produces the correct format for dev (Expo Go `exp://`) and production (custom scheme), `parse` handles non-standard URL formats that `new URL()` would reject

### Manual Handling (Without useURL)

Use when you need more control over the lifecycle, such as integrating with a custom navigation solution.

```typescript
import { useEffect, useRef } from "react";
import * as Linking from "expo-linking";

export function useDeepLinkListener(onLink: (url: string) => void) {
  const hasHandledInitial = useRef(false);

  useEffect(() => {
    // Handle cold start URL (app was not running)
    async function handleInitialURL() {
      if (hasHandledInitial.current) return;
      hasHandledInitial.current = true;

      const initialUrl = await Linking.getInitialURL();
      if (initialUrl) {
        onLink(initialUrl);
      }
    }

    handleInitialURL();

    // Handle URLs received while app is running (foreground/background)
    const subscription = Linking.addEventListener("url", ({ url }) => {
      onLink(url);
    });

    return () => {
      subscription.remove();
    };
  }, [onLink]);
}
```

**Why good:** Explicit control over cold start vs foreground handling, ref prevents double-handling of initial URL on re-renders

---

## Pattern 2: React Navigation Linking Config

### Basic Setup

```typescript
import * as Linking from "expo-linking";
import type { LinkingOptions } from "@react-navigation/native";

type RootStackParamList = {
  Home: undefined;
  Profile: { id: string };
  Product: { slug: string };
  Settings: { section?: string };
  NotFound: undefined;
};

const linking: LinkingOptions<RootStackParamList> = {
  prefixes: [
    Linking.createURL("/"),       // Custom scheme (myapp://)
    "https://example.com",        // Universal Links / App Links
  ],
  config: {
    screens: {
      Home: "",                    // Matches root path
      Profile: "user/:id",        // Matches /user/123
      Product: {
        path: "product/:slug",
        parse: {
          slug: (slug: string) => slug.toLowerCase(),
        },
      },
      Settings: "settings/:section?", // Optional param
      NotFound: "*",               // Catch-all for unmatched URLs
    },
  },
};

// Pass to NavigationContainer
<NavigationContainer linking={linking} fallback={<ActivityIndicator />}>
  <Stack.Navigator>
    <Stack.Screen name="Home" component={HomeScreen} />
    <Stack.Screen name="Profile" component={ProfileScreen} />
    <Stack.Screen name="Product" component={ProductScreen} />
    <Stack.Screen name="Settings" component={SettingsScreen} />
    <Stack.Screen name="NotFound" component={NotFoundScreen} />
  </Stack.Navigator>
</NavigationContainer>
```

**Why good:** Type-safe linking config matches `RootStackParamList`, `parse` transforms params before they reach the screen, catch-all `*` prevents unhandled URLs

### Nested Navigator Config

The config structure must mirror the navigator nesting.

```typescript
const linking: LinkingOptions<RootStackParamList> = {
  prefixes: [Linking.createURL("/"), "https://example.com"],
  config: {
    screens: {
      HomeTabs: {
        screens: {
          Feed: "feed",
          Explore: "explore",
        },
      },
      Profile: {
        path: "user/:id",
        screens: {
          Posts: "posts", // Matches /user/123/posts
          Followers: "followers", // Matches /user/123/followers
        },
      },
      Auth: {
        screens: {
          Login: "login",
          Register: "register",
        },
        // initialRouteName ensures back button from deep link
        // goes to Login instead of nowhere
        initialRouteName: "Login",
      },
    },
  },
};
```

**Why good:** Mirrors navigator hierarchy, `initialRouteName` ensures sensible back navigation from deep-linked nested screens

### Static API Configuration (React Navigation 7+)

With the static API, linking is configured per-screen instead of in a separate config object.

```typescript
import { createStaticNavigation } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      linking: { path: "" },
    },
    Profile: {
      screen: ProfileScreen,
      linking: {
        path: "user/:id",
        parse: { id: (id: string) => id },
      },
    },
    Product: {
      screen: ProductScreen,
      linking: {
        path: "product/:slug",
        parse: { slug: (slug: string) => slug.toLowerCase() },
      },
    },
  },
});

const Navigation = createStaticNavigation(RootStack);

// In your app root:
export function App() {
  return (
    <Navigation
      linking={{
        enabled: "auto", // Auto-generates kebab-case paths from screen names
        prefixes: [Linking.createURL("/"), "https://example.com"],
      }}
    />
  );
}
```

**Why good:** Co-locates linking config with screen definition, `enabled: "auto"` generates paths from PascalCase screen names (Profile -> /profile)

---

## Pattern 3: Expo Router Automatic Deep Linking

Expo Router requires zero deep linking configuration. File paths are deep link paths.

```
app/
  _layout.tsx              ->  Layout wrapper (not a route)
  index.tsx                ->  /
  profile/[id].tsx         ->  /profile/123
  product/[slug].tsx       ->  /product/blue-shirt
  settings/index.tsx       ->  /settings
  settings/[section].tsx   ->  /settings/notifications
  [...missing].tsx         ->  Catch-all for unmatched routes
```

### Handling Parameters in Expo Router

```typescript
// app/profile/[id].tsx
import { useLocalSearchParams } from "expo-router";

export default function ProfileScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  // id is extracted from the URL path: /profile/123 -> id = "123"
  return <ProfileView userId={id} />;
}
```

### Handling Query Parameters

```typescript
// app/product/[slug].tsx
import { useLocalSearchParams } from "expo-router";

export default function ProductScreen() {
  const { slug, ref } = useLocalSearchParams<{ slug: string; ref?: string }>();
  // /product/blue-shirt?ref=email -> slug = "blue-shirt", ref = "email"
  return <ProductView slug={slug} referrer={ref} />;
}
```

**Why good:** No linking config to maintain, adding a file automatically creates a deep link, TypeScript params from `useLocalSearchParams`

---

## Pattern 4: URL Validation and Sanitization

Never trust incoming URLs. Validate paths and parameters before navigating.

```typescript
const VALID_DEEP_LINK_PATHS = new Set([
  "profile",
  "product",
  "settings",
  "order",
]);
const MAX_PARAM_LENGTH = 256;

interface DeepLinkResult {
  screen: string;
  params: Record<string, string>;
}

export function validateDeepLink(url: string): DeepLinkResult | null {
  const { path, queryParams } = Linking.parse(url);
  if (!path) return null;

  const segments = path.split("/").filter(Boolean);
  const rootPath = segments[0];

  if (!rootPath || !VALID_DEEP_LINK_PATHS.has(rootPath)) {
    return null; // Unknown path -- navigate to home or show error
  }

  // Sanitize parameters
  const sanitizedParams: Record<string, string> = {};
  for (const [key, value] of Object.entries(queryParams ?? {})) {
    if (typeof value === "string" && value.length <= MAX_PARAM_LENGTH) {
      sanitizedParams[key] = value.replace(/[<>]/g, ""); // Strip basic injection chars
    }
  }

  return {
    screen: rootPath,
    params: { ...sanitizedParams, id: segments[1] ?? "" },
  };
}
```

**Why good:** Allowlist of valid paths prevents navigation to unexpected screens, parameter sanitization prevents injection, length limit prevents abuse

---

## Pattern 5: Custom getInitialURL and subscribe (Push Notifications)

When deep links come from multiple sources (URL links + push notifications), customize `getInitialURL` and `subscribe`.

```typescript
import * as Linking from "expo-linking";
import type { LinkingOptions } from "@react-navigation/native";

const linking: LinkingOptions<RootStackParamList> = {
  prefixes: [Linking.createURL("/"), "https://example.com"],

  async getInitialURL() {
    // Check if app was opened from a push notification
    const notificationUrl = await getNotificationDeepLink();
    if (notificationUrl) return notificationUrl;

    // Fall back to standard deep link handling
    const url = await Linking.getInitialURL();
    return url;
  },

  subscribe(listener) {
    // Listen for standard deep links
    const linkingSubscription = Linking.addEventListener("url", ({ url }) => {
      listener(url);
    });

    // Listen for push notification deep links
    const notificationSubscription = subscribeToNotificationLinks((url) => {
      listener(url);
    });

    return () => {
      linkingSubscription.remove();
      notificationSubscription.remove();
    };
  },

  config: {
    screens: {
      Home: "",
      Profile: "user/:id",
      Order: "order/:orderId",
    },
  },
};
```

**Why good:** Handles multiple link sources (URL + push) in a unified way, cleanup functions prevent memory leaks, prioritizes notification links over standard deep links

---

## Pattern 6: Deferred Deep Link Handling

Deferred deep links persist the intended destination through the app store install flow. After install, check for a pending deep link on first open.

```typescript
import { useEffect, useRef } from "react";
import AsyncStorage from "@react-native-async-storage/async-storage";

const DEFERRED_LINK_KEY = "deferred_deep_link";
const DEFERRED_LINK_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours

interface DeferredLink {
  url: string;
  timestamp: number;
}

// Call on first app launch after install
export function useDeferredDeepLink(onLink: (url: string) => void) {
  const hasChecked = useRef(false);

  useEffect(() => {
    if (hasChecked.current) return;
    hasChecked.current = true;

    async function checkDeferredLink() {
      try {
        const stored = await AsyncStorage.getItem(DEFERRED_LINK_KEY);
        if (!stored) return;

        const parsed: DeferredLink = JSON.parse(stored);
        const age = Date.now() - parsed.timestamp;

        // Only honor links less than 24 hours old
        if (age < DEFERRED_LINK_MAX_AGE_MS) {
          onLink(parsed.url);
        }

        // Clean up regardless of age
        await AsyncStorage.removeItem(DEFERRED_LINK_KEY);
      } catch {
        // Silently fail -- deferred link is best-effort
      }
    }

    checkDeferredLink();
  }, [onLink]);
}
```

**Why good:** Expiry prevents stale navigation, single-use (deleted after read), error handling prevents crashes from corrupt storage

**Note:** For production deferred deep linking with install attribution, use a dedicated attribution SDK. The pattern above shows the client-side concept -- the server-side link persistence and device matching are handled by the attribution service.

# Deep Linking - Testing

> Testing deep links with CLI tools, debugging common issues, and validating verification files. See [SKILL.md](../SKILL.md) for decision guidance. See [examples/verification-files.md](verification-files.md) for AASA/assetlinks.json setup.

---

## Pattern 1: Testing with CLI Tools

### iOS Simulator (xcrun simctl)

```bash
# Test custom URI scheme
xcrun simctl openurl booted "myapp://profile/123"

# Test Universal Links (HTTPS)
xcrun simctl openurl booted "https://example.com/product/456"

# Test with query parameters
xcrun simctl openurl booted "myapp://settings?section=notifications"

# Specify a device (when multiple simulators are running)
xcrun simctl openurl 9F3E4A1B-2C5D-4E6F-8A7B-1C2D3E4F5A6B "myapp://profile/123"
```

**Limitation:** Universal Links on simulator are unreliable -- the OS may open Safari instead. Always validate Universal Links on a real device.

### Android Emulator/Device (adb)

```bash
# Test custom URI scheme
adb shell am start -W -a android.intent.action.VIEW \
  -d "myapp://profile/123" \
  com.example.myapp

# Test App Links (HTTPS)
adb shell am start -W -a android.intent.action.VIEW \
  -d "https://example.com/product/456" \
  com.example.myapp

# Test with query parameters
adb shell am start -W -a android.intent.action.VIEW \
  -d "myapp://settings?section=notifications" \
  com.example.myapp

# Verify App Links status for your app
adb shell pm get-app-links com.example.myapp

# Reset App Links verification (forces re-verification on next install)
adb shell pm set-app-links --package com.example.myapp 0 all
```

### Expo uri-scheme Tool

```bash
# Test on iOS
npx uri-scheme open "myapp://profile/123" --ios

# Test on Android
npx uri-scheme open "myapp://profile/123" --android

# List registered schemes
npx uri-scheme list --ios
npx uri-scheme list --android
```

**Why good:** `uri-scheme` is simpler than raw `xcrun`/`adb` commands and works in Expo-managed projects

---

## Pattern 2: Testing App States

Deep links behave differently depending on the app state. Test all three:

### Cold Start (App Not Running)

```bash
# 1. Force-quit the app
# iOS: Swipe up from app switcher
# Android:
adb shell am force-stop com.example.myapp

# 2. Open deep link (app launches from scratch)
adb shell am start -W -a android.intent.action.VIEW \
  -d "myapp://product/456" \
  com.example.myapp
```

**What to verify:** App launches and navigates directly to the target screen. The initial URL is captured by `Linking.getInitialURL()` or `useURL`.

### Background (App Suspended)

```bash
# 1. Open the app normally, then press Home button
# 2. Open deep link (app resumes from background)
adb shell am start -W -a android.intent.action.VIEW \
  -d "myapp://product/456" \
  com.example.myapp
```

**What to verify:** App comes to foreground and navigates to the target screen. The URL is captured by `addEventListener('url')` or `useURL`.

### Foreground (App Active)

```bash
# 1. Keep the app in the foreground
# 2. Open deep link from another terminal window
adb shell am start -W -a android.intent.action.VIEW \
  -d "myapp://product/456" \
  com.example.myapp
```

**What to verify:** App stays in foreground and navigates to the target screen without a visible app restart.

---

## Pattern 3: Validating Verification Files

### iOS AASA Validation

```bash
# Apple's CDN-cached version of your AASA file
curl -s "https://app-site-association.cdn-apple.com/a/v1/yourdomain.com" | jq .

# Direct fetch from your server
curl -sI "https://yourdomain.com/.well-known/apple-app-site-association"
# Verify: Content-Type is application/json, status is 200 (not redirect)

# Check the file content
curl -s "https://yourdomain.com/.well-known/apple-app-site-association" | jq .
```

**Key checks:**

- Content-Type header is `application/json`
- No redirects (must be a direct 200 response)
- `appIDs` format is `<TEAM_ID>.<BUNDLE_ID>`
- Paths match the URLs you want to handle

### Android assetlinks.json Validation

```bash
# Google's verification endpoint
curl -s "https://digitalassetlinks.googleapis.com/v1/statements:list?\
source.web.site=https://yourdomain.com&\
relation=delegate_permission/common.handle_all_urls" | jq .

# Direct fetch from your server
curl -s "https://yourdomain.com/.well-known/assetlinks.json" | jq .

# Check App Links verification status on device
adb shell pm get-app-links com.example.myapp
# Look for: "com.example.myapp: verified"
```

**Key checks:**

- Google's endpoint returns your app in the `statements` array
- `package_name` matches your app's package name
- `sha256_cert_fingerprints` includes both upload AND signing keys
- Status shows `verified` (not `legacy_failure` or `none`)

---

## Pattern 4: Common Debugging Scenarios

### Universal Links Not Opening App (iOS)

```
Problem: Tapping HTTPS link opens Safari instead of the app.

Checklist:
1. Is the link from a DIFFERENT domain? (Same-domain links always open in Safari)
2. Is the link tapped (not typed into Safari address bar)? (Typed URLs open in Safari)
3. Did you long-press and choose "Open in Safari" previously? (iOS remembers this choice)
   Fix: Long-press the link again and choose "Open in [App Name]"
4. Is the AASA file accessible? Check: curl https://yourdomain.com/.well-known/apple-app-site-association
5. Is associatedDomains configured WITHOUT https:// prefix?
6. Did you rebuild after adding associatedDomains? (Requires new native build)
7. Has the AASA cache expired? (Apple caches for up to 24 hours)
```

### App Links Not Verified (Android)

```
Problem: adb shell pm get-app-links shows "none" or "legacy_failure".

Checklist:
1. Is autoVerify: true set in intent filters?
2. Is assetlinks.json served over HTTPS with Content-Type: application/json?
3. Does the package_name match your android.package?
4. Are ALL signing key fingerprints included? (Both upload and Play Store signing keys)
5. Was the server accessible when the app was installed? (Verification happens at install time)
   Fix: Uninstall and reinstall the app
6. Try manual re-verification:
   adb shell pm set-app-links --package com.example.myapp 0 all
   adb shell pm verify-app-links --re-verify com.example.myapp
```

### Cold Start Link Not Handled

```
Problem: Opening a deep link when the app is not running does not navigate to the correct screen.

Checklist:
1. Are you calling Linking.getInitialURL() or using useURL()?
2. Is getInitialURL() called BEFORE the navigation container is ready?
   Fix: Delay navigation until the navigator is mounted
3. Is the initial URL being consumed before React Navigation processes it?
   Fix: Use React Navigation's linking config instead of manual handling
4. Is there a splash screen blocking the URL handling?
   Fix: Ensure URL processing happens after splash screen is dismissed
```

### URL Parameters Missing or Wrong

```
Problem: Screen receives empty or incorrect params from deep link.

Checklist:
1. Does the linking config path pattern match the URL structure?
   e.g., "user/:id" matches /user/123 but NOT /users/123
2. Are parse functions returning the correct types?
   e.g., parse: { id: Number } converts "123" to 123
3. Are query params being correctly extracted?
   Check: Linking.parse(url).queryParams
4. Is the URL properly encoded? Special characters need URL encoding.
```

# Deep Linking - Verification Files

> AASA (iOS) and assetlinks.json (Android) setup, hosting requirements, and validation. See [SKILL.md](../SKILL.md) for decision guidance. See [examples/core.md](core.md) for app-side configuration.

---

## Pattern 1: Apple App Site Association (AASA) File

### File Location

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

In Expo Router projects, place at: `public/.well-known/apple-app-site-association`

**No file extension.** The file is named `apple-app-site-association` without `.json`.

### Modern Format (iOS 13+)

```json
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.myapp"],
        "components": [
          {
            "/": "/product/*",
            "comment": "Matches product pages"
          },
          {
            "/": "/user/*",
            "comment": "Matches user profiles"
          },
          {
            "/": "/order/*",
            "comment": "Matches order details"
          },
          {
            "/": "/settings",
            "comment": "Matches settings page exactly"
          },
          {
            "/": "/admin/*",
            "exclude": true,
            "comment": "Exclude admin paths from opening in app"
          }
        ]
      }
    ]
  },
  "activitycontinuation": {
    "apps": ["ABCDE12345.com.example.myapp"]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.myapp"]
  }
}
```

**Format notes:**

- `appIDs` value format: `<APPLE_TEAM_ID>.<BUNDLE_ID>`
- Find your Team ID in Apple Developer portal under Membership
- `components` array uses pattern matching (iOS 13+, preferred)
- `exclude: true` prevents specific paths from opening the app
- `activitycontinuation` enables Handoff between devices
- `webcredentials` enables password autofill

### Legacy Format (iOS 12 and earlier)

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.myapp",
        "paths": ["/product/*", "/user/*", "/order/*", "NOT /admin/*"]
      }
    ]
  }
}
```

**Note:** `"apps": []` must be an empty array in the legacy format. Use `NOT` prefix to exclude paths.

### Wildcard Rules

| Pattern              | Matches                 | Does NOT Match                                       |
| -------------------- | ----------------------- | ---------------------------------------------------- |
| `/product/*`         | `/product/123`          | `/product/123/reviews` (single level only in legacy) |
| `/product/*/reviews` | `/product/123/reviews`  | `/product/123`                                       |
| `/user/?????`        | `/user/alice` (5 chars) | `/user/bob` (3 chars)                                |

**iOS 13+ components format:** The `*` wildcard in components matches across path separators, unlike the legacy format.

### App Config (Expo)

```json
{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:example.com"]
    }
  }
}
```

**Critical:** Do NOT include `https://` in the domain. Write `applinks:example.com`, not `applinks:https://example.com`.

---

## Pattern 2: Android Digital Asset Links (assetlinks.json)

### File Location

Host at: `https://yourdomain.com/.well-known/assetlinks.json`

In Expo Router projects, place at: `public/.well-known/assetlinks.json`

### File Structure

```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:7F:D8:4A:B4:2F:5E:E0:8F:3A:D6:F4:CA:41:1A:CF:45:BF:8D:10:76:76:CD:B1:55:AB:21:3E"
      ]
    }
  }
]
```

**Key fields:**

- `package_name`: Must match `android.package` in your app config
- `sha256_cert_fingerprints`: Array of SHA-256 fingerprints for your signing certificate(s)

### Getting SHA-256 Fingerprints

**Via EAS Build:**

```bash
eas credentials -p android
# Select your build profile
# Look for "SHA256 Fingerprint" in the output
```

**Via Google Play Console:**

Navigate to: Release > Setup > App Signing > Digital Asset Links JSON

**Via local keystore:**

```bash
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android
# Look for SHA256 fingerprint in the output
```

**Important:** Include fingerprints for BOTH your upload key AND the Google Play signing key. If you only include the upload key, App Links will fail for Play Store builds (Google re-signs your app).

### Multiple Fingerprints (Development + Production)

```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": ["AA:BB:CC:...", "DD:EE:FF:..."]
    }
  }
]
```

### App Config (Expo)

```json
{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "example.com",
              "pathPrefix": "/product"
            },
            {
              "scheme": "https",
              "host": "example.com",
              "pathPrefix": "/user"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}
```

**Critical:** `autoVerify: true` is required. Without it, Android treats these as regular deep links and shows a disambiguation dialog.

---

## Pattern 3: Hosting Requirements

### Both Platforms

| Requirement   | Detail                                                   |
| ------------- | -------------------------------------------------------- |
| Protocol      | HTTPS only (no HTTP, no redirects from HTTP)             |
| Content-Type  | `application/json`                                       |
| Accessibility | Publicly accessible (no authentication, no geo-blocking) |
| Response code | 200 (not 301, 302, or any redirect)                      |
| File size     | < 128KB (Apple limit)                                    |
| CDN caching   | Be aware of cache TTL when updating files                |

### iOS-Specific

- Apple's CDN fetches and caches AASA files -- changes can take up to 24 hours to propagate
- The file is fetched when the app is installed, not when a link is tapped
- Use Apple's AASA validator: `https://app-site-association.cdn-apple.com/a/v1/yourdomain.com`

### Android-Specific

- Verification happens at app install time
- If your server is down during install, verification fails (links open in browser)
- Use Google's Digital Asset Links validator: `https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls`

---

## Pattern 4: Combined Setup Checklist

```
iOS Universal Links:
[ ] AASA file at /.well-known/apple-app-site-association (no .json extension)
[ ] Served over HTTPS with Content-Type: application/json
[ ] appIDs format: <TEAM_ID>.<BUNDLE_ID>
[ ] associatedDomains in app.config.js (without https://)
[ ] New native build after config change
[ ] Tested on real device (not just simulator)

Android App Links:
[ ] assetlinks.json at /.well-known/assetlinks.json
[ ] Served over HTTPS with Content-Type: application/json
[ ] package_name matches android.package in app config
[ ] SHA-256 fingerprints include BOTH upload key AND Play Store signing key
[ ] autoVerify: true in intent filters
[ ] intentFilters in app.config.js with correct host and pathPrefix
[ ] New native build after config change
[ ] Tested on real device (not just emulator)
```