change the android build such that Play Store isn't required (also removed android/google-services.json)

2026-06-21 18:01:04 -06:00
parent ec41dd52d5
commit 15c9088736
6 changed files with 409 additions and 4 deletions
@@ -0,0 +1,308 @@
+# 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