crowd-funder-for-time-pwa/doc/deep-link-debugging-guide.md

# Deep Link Debugging Guide for TimeSafari

This guide helps you debug and fix deep link issues in the TimeSafari Capacitor application.

## Quick Start

1. **Check logs**: Use browser dev tools or device console to see detailed logging
2. **Test manually**: Use the testing script or browser console commands
3. **Verify configuration**: Ensure all platform configurations are correct

## Common Issues and Solutions

### Issue 1: App opens but doesn't navigate to the correct page

**Symptoms:**
- Deep link opens the app
- App stays on home screen or current page
- No error messages visible

**Debugging Steps:**

1. **Check console logs** in browser dev tools or device console:
   ```bash
   # Android
   adb logcat | grep -E "(TimeSafari|DeepLink|appUrlOpen)"
   
   # iOS Simulator
   xcrun simctl spawn booted log stream --predicate 'process == "TimeSafari"'
   ```

2. **Verify listener registration**:
   Look for these log messages:
   ```
   [DeepLink] Registering appUrlOpen listener...
   [DeepLink] Listener registered successfully
   ```

3. **Check for event reception**:
   Look for:
   ```
   [DeepLink] ========== DEEP LINK EVENT RECEIVED ==========
   [DeepLink] URL: timesafari://your/url/here
   ```

4. **Verify URL parsing**:
   Check if URL components are parsed correctly:
   ```
   [DeepLinkHandler.parseDeepLink] Parse result: {"path":"claim","params":{"id":"123"},"query":{}}
   ```

### Issue 2: Listener not receiving events

**Symptoms:**
- No deep link logs appear
- App opens but no event processing

**Solutions:**

1. **Rebuild and reinstall** the app completely:
   ```bash
   npm run build:capacitor
   npx cap sync
   npx cap run android  # or ios
   ```

2. **Check capacitor.config.json**:
   ```json
   {
     "plugins": {
       "App": {
         "appUrlOpen": {
           "handlers": [
             {
               "url": "timesafari://*",
               "autoVerify": true
             }
           ]
         }
       }
     }
   }
   ```

3. **Verify native configuration**:
   - **Android**: Check `android/app/src/main/AndroidManifest.xml`
   - **iOS**: Check `ios/App/App/Info.plist`

### Issue 3: URL scheme not recognized by OS

**Symptoms:**
- "No app found to handle this link" error
- OS doesn't open your app

**Solutions:**

1. **Android**: Verify intent filter in AndroidManifest.xml:
   ```xml
   <intent-filter>
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:scheme="timesafari" />
   </intent-filter>
   ```

2. **iOS**: Verify URL types in Info.plist:
   ```xml
   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLName</key>
           <string>app.timesafari</string>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>timesafari</string>
           </array>
       </dict>
   </array>
   ```

## Testing Tools

### 1. Automated Testing Script

Use the provided testing script:

```bash
# Test all URLs on Android
./scripts/test-deep-links.sh android

# Test specific URL on iOS
./scripts/test-deep-links.sh ios "timesafari://claim/test123"

# Monitor logs
./scripts/test-deep-links.sh android-logs
```

### 2. Manual Testing Commands

**Android Emulator:**
```bash
adb shell am start -W -a android.intent.action.VIEW -d "timesafari://claim/test123" app.timesafari
```

**iOS Simulator:**
```bash
xcrun simctl openurl booted "timesafari://claim/test123"
```

### 3. Browser Console Testing

For web/PWA testing, use the browser console:

```javascript
// Test deep link processing directly
window.testSingleDeepLink("timesafari://claim/test123");

// Run all test URLs
window.testDeepLinks();
```

## Debugging Steps Checklist

### Pre-Testing Setup

- [ ] App is installed on device/emulator
- [ ] App has been launched at least once
- [ ] Device/emulator is properly connected
- [ ] Debugging tools are accessible

### During Testing

- [ ] Check console for initialization logs
- [ ] Verify listener registration
- [ ] Test with simple URL first (e.g., `timesafari://claim/test`)
- [ ] Monitor URL parsing logs
- [ ] Check router navigation logs

### Post-Testing Analysis

- [ ] Review complete log sequence
- [ ] Identify where process fails
- [ ] Check error messages for clues
- [ ] Test with different URL formats

## Common Log Patterns

### Successful Deep Link Flow

```
[DeepLink] Registering appUrlOpen listener...
[DeepLink] Listener registered successfully
[DeepLink] ========== DEEP LINK EVENT RECEIVED ==========
[DeepLink] URL: timesafari://claim/test123
[DeepLinkHandler] Starting handleDeepLink with URL: timesafari://claim/test123
[DeepLinkHandler.parseDeepLink] Parse result: {"path":"claim","params":{"id":"test123"},"query":{}}
[DeepLinkHandler.validateAndRoute] Route validation passed. Route name: claim
[DeepLinkHandler.validateAndRoute] Router navigation completed successfully
[DeepLink] Deep link handled successfully
```

### Failed URL Parsing

```
[DeepLinkHandler.parseDeepLink] Route not found: invalid-route
[DeepLinkHandler.parseDeepLink] Available routes: ["claim","project","contact-import",...]
[DeepLinkHandler.validateAndRoute] Redirecting to deep-link-error page
```

### Router Navigation Issues

```
[DeepLinkHandler.validateAndRoute] Error routing to route name claim
[DeepLinkHandler.validateAndRoute] Navigation params: {"name":"claim","params":{"id":"test123"}}
```

## Platform-Specific Issues

### Android

**Issue**: Deep links work in development but not in production build
- **Solution**: Ensure `android:exported="true"` in MainActivity

**Issue**: App doesn't respond to links when running in background
- **Solution**: Check `android:launchMode="singleTask"` in AndroidManifest.xml

### iOS

**Issue**: Deep links don't work in iOS simulator
- **Solution**: Use `xcrun simctl openurl` instead of opening URLs in Safari

**Issue**: App launches but doesn't process URL
- **Solution**: Check for Associated Domains if using universal links

## Advanced Debugging

### Enable Capacitor Native Logging

Add to `capacitor.config.json`:

```json
{
  "ios": {
    "loggingBehavior": "debug"
  },
  "android": {
    "loggingBehavior": "debug"
  }
}
```

### Add Custom Debug Points

Insert additional logging in your deep link handler:

```typescript
// Add at strategic points in DeepLinkHandler
console.log('[DEBUG] Custom checkpoint:', { data: yourData });
```

### Network Debugging

If deep links involve network requests:

```bash
# Monitor network traffic (Android)
adb shell dumpsys connectivity

# Monitor network traffic (iOS)
# Use Xcode Network Debugger
```

## Recovery Strategies

### If deep links stop working completely:

1. **Clean rebuild**:
   ```bash
   rm -rf node_modules
   npm install
   npm run build:capacitor
   npx cap sync
   ```

2. **Reset device/emulator**:
   - Clear app data
   - Uninstall and reinstall
   - Restart emulator

3. **Verify basic functionality**:
   - Test simple navigation within app
   - Test URL schemes with minimal URLs
   - Gradually increase complexity

## Support Resources

- [Capacitor Deep Links Documentation](https://capacitorjs.com/docs/guides/deep-links)
- [Android Intent Filter Guide](https://developer.android.com/guide/components/intents-filters)
- [iOS URL Scheme Guide](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)

## Contact and Feedback

If you encounter issues not covered in this guide:

1. Check the project's issue tracker
2. Review recent commits for deep link changes
3. Test with minimal reproduction case
4. Document exact steps and environment details