# Deep Linking Setup Guide

## Overview

This guide explains how to configure universal links (iOS) and App Links (Android) so that shared post links open directly in the mobile app instead of the browser.

## Current Status

✅ App configuration files are set up:
- iOS: `Info.plist` configured for universal links
- Android: `AndroidManifest.xml` configured for App Links
- Server files created: `.well-known/apple-app-site-association` and `.well-known/assetlinks.json`
- Laravel routes added to serve files with correct content-type

⚠️ **Action Required**: You need to complete the configuration below.

**IMPORTANT**: Universal links will NOT work until you:
1. Replace `TEAM_ID` with your actual Apple Team ID
2. Replace `YOUR_APP_SHA256_FINGERPRINT_HERE` with your app's SHA256 fingerprint
3. Rebuild the iOS and Android apps
4. Test on a physical device (universal links don't work in simulators)

## Step 1: Install Capacitor App Plugin

The App plugin is needed to handle deep links. Install it:

```bash
cd mobile
npm install @capacitor/app
npx cap sync
```

## Step 2: Configure iOS Universal Links

1. **Get your Apple Team ID**:
   - Go to https://developer.apple.com/account
   - Your Team ID is shown in the top right (e.g., `ABC123DEF4`)

2. **Update `public/.well-known/apple-app-site-association`**:
   - Replace `TEAM_ID` with your actual Team ID
   - Example: `"appID": "ABC123DEF4.com.ashlarclub.app"`

3. **Verify the file is accessible**:
   - Visit: `https://ashlar.club/.well-known/apple-app-site-association`
   - It should return JSON (not HTML)
   - Content-Type should be `application/json`

4. **Server Configuration** (if using Nginx):
   ```nginx
   location /.well-known/apple-app-site-association {
       default_type application/json;
       add_header Content-Type application/json;
   }
   ```

## Step 3: Configure Android App Links

1. **Get your app's SHA256 fingerprint**:
   ```bash
   keytool -list -v -keystore path/to/your-keystore.jks -alias your-alias
   ```
   Look for "SHA256:" in the output.

2. **Update `public/.well-known/assetlinks.json`**:
   - Replace `YOUR_APP_SHA256_FINGERPRINT_HERE` with your actual SHA256 (without colons)
   - Example: `"sha256_cert_fingerprints": ["A1:B2:C3:..."]`

3. **Verify the file is accessible**:
   - Visit: `https://ashlar.club/.well-known/assetlinks.json`
   - It should return JSON (not HTML)
   - Content-Type should be `application/json`

## Step 4: Test Universal Links

### iOS Testing:
1. Build and install the app on a device
2. Long-press a shared link in Messages/WhatsApp
3. You should see "Open in Ashlar" option
4. Tap it - the app should open directly

### Android Testing:
1. Build and install the app on a device
2. Click a shared link in WhatsApp/Messages
3. The app should open directly (not browser)

## Troubleshooting

### Links still open in browser:
- Verify server files are accessible with correct content-type
- Check that Team ID and SHA256 are correct
- Rebuild the app after configuration changes
- On iOS, universal links only work on physical devices (not simulator)

### App opens but shows login:
- This means universal links are working!
- The issue is authentication - the app should use stored token
- Check that `AuthenticateMobileApp` middleware is working
- Verify token is stored in localStorage

## How It Works

1. User shares a post → generates URL: `https://ashlar.club/dashboard?category=X&post_id=Y`
2. Someone clicks the link
3. If app is installed: Universal link opens the app directly
4. If app not installed: Opens in browser (expected behavior)
5. App uses stored auth token to authenticate
6. Dashboard navigates to the correct category and scrolls to the post

## Notes

- Universal links require HTTPS
- The files must be served from the root domain (ashlar.club)
- After configuration, rebuild both iOS and Android apps
- Universal links are verified by Apple/Google servers, so changes may take time to propagate