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:

   # 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:

   npm run build:capacitor
   npx cap sync
   npx cap run android  # or ios
   

2. Check capacitor.config.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:

   <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:

   <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:

# 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:

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

iOS Simulator:

xcrun simctl openurl booted "timesafari://claim/test123"

3. Browser Console Testing

For web/PWA testing, use the browser console:

// 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:

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

Add Custom Debug Points

Insert additional logging in your deep link handler:

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

Network Debugging

If deep links involve network requests:

# 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:

   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
• Android Intent Filter Guide
• iOS URL Scheme Guide

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