first commit
This commit is contained in:
@@ -0,0 +1,245 @@
|
||||
# Geolocation Troubleshooting Guide
|
||||
|
||||
## Overview
|
||||
This guide helps resolve issues with the "Find Nearby" fuel station search feature that uses your device's location to find nearby gas stations.
|
||||
|
||||
## Quick Fixes
|
||||
|
||||
### 1. Check Browser Permissions
|
||||
**Firefox:**
|
||||
1. Click the shield/lock icon in the address bar
|
||||
2. Make sure "Location" is set to "Allow"
|
||||
3. If it shows "Blocked", click it and select "Allow"
|
||||
4. Refresh the page and try again
|
||||
|
||||
**Chrome:**
|
||||
1. Click the lock icon next to the URL
|
||||
2. Set "Location" to "Allow"
|
||||
3. Refresh the page
|
||||
|
||||
**Safari:**
|
||||
1. Go to Safari > Preferences > Websites > Location Services
|
||||
2. Find your site and set it to "Allow"
|
||||
|
||||
### 2. Enable Location Services (System Level)
|
||||
|
||||
**Windows 10/11:**
|
||||
1. Settings > Privacy & Security > Location
|
||||
2. Turn on "Location services"
|
||||
3. Turn on "Allow apps to access your location"
|
||||
|
||||
**macOS:**
|
||||
1. System Preferences > Security & Privacy > Privacy
|
||||
2. Select "Location Services"
|
||||
3. Enable Location Services
|
||||
4. Check the box for your browser
|
||||
|
||||
**Linux:**
|
||||
1. Settings > Privacy > Location Services
|
||||
2. Enable Location Services
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: "Location access was denied"
|
||||
|
||||
**Cause:** Browser permission blocked
|
||||
**Solution:**
|
||||
1. Clear site permissions and try again
|
||||
2. Check if location services are enabled system-wide
|
||||
3. Try in incognito/private browsing mode
|
||||
4. Check if browser has location permission in OS settings
|
||||
|
||||
### Issue: "Location information is unavailable"
|
||||
|
||||
**Cause:** GPS/location services disabled or poor signal
|
||||
**Solutions:**
|
||||
1. Enable GPS on mobile devices
|
||||
2. Move to an area with better signal (away from buildings)
|
||||
3. Wait a few moments for GPS to get a fix
|
||||
4. Try refreshing the page
|
||||
5. Use Wi-Fi instead of mobile data (often more accurate)
|
||||
|
||||
### Issue: "Location request timed out"
|
||||
|
||||
**Cause:** Taking too long to get GPS fix
|
||||
**Solutions:**
|
||||
1. Wait longer - GPS can take 30+ seconds for first fix
|
||||
2. Move outside or near a window
|
||||
3. The app will automatically retry with lower accuracy
|
||||
4. Use manual entry as backup
|
||||
|
||||
### Issue: "This page requires HTTPS"
|
||||
|
||||
**Cause:** Modern browsers require secure connection for location access
|
||||
**Solutions:**
|
||||
1. Access the site via `https://` instead of `http://`
|
||||
2. If running locally, use `localhost` instead of IP address
|
||||
3. Contact administrator to enable HTTPS
|
||||
|
||||
## Browser-Specific Issues
|
||||
|
||||
### Firefox
|
||||
- **Private Browsing:** Location might be blocked by default
|
||||
- **Enhanced Tracking Protection:** May interfere with location
|
||||
- **Solution:** Temporarily disable tracking protection for the site
|
||||
|
||||
### Chrome
|
||||
- **Incognito Mode:** Location access requires explicit permission
|
||||
- **Site Settings:** Check chrome://settings/content/location
|
||||
- **Solution:** Ensure site is not in "Block" list
|
||||
|
||||
### Safari
|
||||
- **Privacy Settings:** May block location by default
|
||||
- **Website Settings:** Check per-site permissions
|
||||
- **Solution:** Enable in Safari preferences
|
||||
|
||||
### Mobile Browsers
|
||||
- **App Permissions:** Browser app needs location permission
|
||||
- **Battery Saving:** May disable GPS
|
||||
- **Solution:** Check app permissions in device settings
|
||||
|
||||
## Debugging Steps
|
||||
|
||||
### 1. Check Browser Console
|
||||
1. Press F12 to open developer tools
|
||||
2. Go to Console tab
|
||||
3. Click "Find Nearby" and look for error messages
|
||||
4. Common errors and meanings:
|
||||
- `User denied geolocation` → Permission issue
|
||||
- `Position unavailable` → GPS/signal issue
|
||||
- `Timeout` → Taking too long to get location
|
||||
|
||||
### 2. Test Geolocation Manually
|
||||
1. Open browser console (F12)
|
||||
2. Type: `navigator.geolocation.getCurrentPosition(console.log, console.error)`
|
||||
3. Check if you get coordinates or an error
|
||||
|
||||
### 3. Check Permissions API
|
||||
1. In console, type: `navigator.permissions.query({name: 'geolocation'})`
|
||||
2. Should return permission state: 'granted', 'denied', or 'prompt'
|
||||
|
||||
### 4. Verify HTTPS
|
||||
1. Check if URL starts with `https://`
|
||||
2. Look for lock icon in address bar
|
||||
3. Geolocation requires secure context
|
||||
|
||||
## Alternative Solutions
|
||||
|
||||
### 1. Manual Entry
|
||||
- Click "Enter Station Details Manually" in the search modal
|
||||
- Fill in station name and address yourself
|
||||
- Useful when location services fail
|
||||
|
||||
### 2. Use Map Applications
|
||||
- Search for "gas stations near me" in Google Maps
|
||||
- Copy station name and address to TankStopp manually
|
||||
- More reliable but requires extra steps
|
||||
|
||||
### 3. Search by City/Area
|
||||
- Enter your city name in the location field
|
||||
- Add station name from memory or other sources
|
||||
- Good for frequently visited stations
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Geolocation Requirements
|
||||
- **HTTPS:** Required for security (except localhost)
|
||||
- **User Permission:** Must be explicitly granted
|
||||
- **Active Connection:** Internet required for map data
|
||||
- **GPS/Network:** Device needs location capability
|
||||
|
||||
### How It Works
|
||||
1. **Request Location:** Browser asks device for coordinates
|
||||
2. **Get Permission:** User must allow location access
|
||||
3. **Query Map Data:** Searches OpenStreetMap for fuel stations
|
||||
4. **Calculate Distance:** Sorts results by proximity
|
||||
5. **Display Results:** Shows stations with distance
|
||||
|
||||
### Accuracy Factors
|
||||
- **GPS Signal:** Better outdoors with clear sky
|
||||
- **Wi-Fi Location:** More accurate in urban areas
|
||||
- **Mobile Network:** Less accurate but faster
|
||||
- **Device Type:** Phones generally more accurate than laptops
|
||||
|
||||
## Advanced Troubleshooting
|
||||
|
||||
### Clear Browser Data
|
||||
1. Clear cookies and site data for the website
|
||||
2. Reset all permissions
|
||||
3. Try accessing the site fresh
|
||||
|
||||
### Network Issues
|
||||
- **Firewall:** May block map API requests
|
||||
- **VPN:** Can affect location accuracy
|
||||
- **Corporate Network:** May have restrictions
|
||||
|
||||
### Device Issues
|
||||
- **Low Battery:** May disable GPS
|
||||
- **Airplane Mode:** Disables all location services
|
||||
- **Location History:** Some devices need this enabled
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Collect Debug Information
|
||||
If you're still having issues, collect this information:
|
||||
1. Browser name and version
|
||||
2. Operating system
|
||||
3. Error messages from browser console
|
||||
4. Whether you're using HTTPS
|
||||
5. Location permission status
|
||||
|
||||
### Contact Support
|
||||
Include the debug information when reporting issues:
|
||||
- GitHub Issues: Link to project repository
|
||||
- Email: Include all debug information
|
||||
- Forum: Post in relevant community
|
||||
|
||||
### Workarounds
|
||||
While waiting for fixes:
|
||||
1. Use manual entry for station details
|
||||
2. Search stations beforehand using map apps
|
||||
3. Keep a list of frequently visited stations
|
||||
4. Use desktop version if mobile has issues
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
### Keep It Working
|
||||
1. **Don't Block Location:** Always allow when prompted
|
||||
2. **Use HTTPS:** Bookmark the secure URL
|
||||
3. **Update Browser:** Keep browser up to date
|
||||
4. **Enable Location Services:** Keep them on system-wide
|
||||
5. **Test Regularly:** Verify it works before you need it
|
||||
|
||||
### Best Practices
|
||||
1. **Allow Permission Once:** It will remember for future visits
|
||||
2. **Be Patient:** GPS can take time for first fix
|
||||
3. **Have Backup Plan:** Know how to enter manually
|
||||
4. **Check Signal:** Use near windows or outdoors when possible
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Why does it work sometimes but not others?**
|
||||
A: GPS accuracy varies by location, weather, and device battery. Indoor locations often have poor GPS signal.
|
||||
|
||||
**Q: Can I use it without GPS?**
|
||||
A: Yes, use the "Enter Manually" option to input station details yourself.
|
||||
|
||||
**Q: Is my location data stored?**
|
||||
A: No, your coordinates are only used for the search and not saved or transmitted to our servers.
|
||||
|
||||
**Q: Why does it need HTTPS?**
|
||||
A: Modern browsers require secure connections for location access as a security measure.
|
||||
|
||||
**Q: Can I search a different location?**
|
||||
A: Currently, it only searches near your current location. Use manual entry for stations in other areas.
|
||||
|
||||
## Success Indicators
|
||||
|
||||
You'll know it's working when:
|
||||
- ✅ Modal opens immediately when clicking "Find Nearby"
|
||||
- ✅ "Requesting your location..." message appears
|
||||
- ✅ Location is obtained within 15 seconds
|
||||
- ✅ Search results show nearby stations with distances
|
||||
- ✅ Clicking a station fills the form fields automatically
|
||||
|
||||
If any step fails, refer to the troubleshooting steps above.
|
||||
Reference in New Issue
Block a user