kyle/vip-coordinator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: optimize Traccar Client QR code with iOS background GPS settings

Browse Source 
QR enrollment was only setting id and interval, causing iOS to default
to medium accuracy with stop_detection enabled — which pauses GPS
updates when the phone appears stationary, causing 5-30 min gaps.

Now sets accuracy=highest, stop_detection=false, distance=0, angle=30,
heartbeat=300, buffer=true. Also updates driver instructions with
required iPhone settings (Always location, Background App Refresh).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kyle
2026-02-09 18:51:42 +01:00
parent 53eb82c4d2
commit 14c6c9506f
1 changed files with 24 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
backend/src/gps/gps.service.ts
View File

@@ -198,14 +198,20 @@ export class GpsService implements OnModuleInit {
const settings = await this.getSettings();
// Build QR code URL for Traccar Client app
// Format: https://server:5055?id=DEVICE_ID&interval=SECONDS
// The Traccar Client app parses this as: server URL (origin) + query params (id, interval, etc.)
// All supported params: id, interval, accuracy, distance, angle, heartbeat, buffer, stop_detection, wakelock
// Key iOS settings: accuracy=highest + stop_detection=false prevents iOS from pausing GPS updates
const devicePort = this.configService.get<number>('TRACCAR_DEVICE_PORT') || 5055;
const traccarPublicUrl = this.traccarClient.getTraccarUrl();
const qrUrl = new URL(traccarPublicUrl);
qrUrl.port = String(devicePort);
qrUrl.searchParams.set('id', actualDeviceId);
qrUrl.searchParams.set('interval', String(settings.updateIntervalSeconds));
qrUrl.searchParams.set('accuracy', 'highest'); // iOS: kCLDesiredAccuracyBestForNavigation
qrUrl.searchParams.set('distance', '0'); // Disable distance filter — rely on interval
qrUrl.searchParams.set('angle', '30'); // Send update on 30° heading change (turns)
qrUrl.searchParams.set('heartbeat', '300'); // 5 min heartbeat when stationary
qrUrl.searchParams.set('stop_detection', 'false'); // CRITICAL: prevent iOS from pausing GPS
qrUrl.searchParams.set('buffer', 'true'); // Buffer points when offline
const qrCodeUrl = qrUrl.toString();
this.logger.log(`QR code URL for driver: ${qrCodeUrl}`);
@@ -217,15 +223,21 @@ GPS Tracking Setup Instructions for ${driver.name}:
- iOS: https://apps.apple.com/app/traccar-client/id843156974
- Android: https://play.google.com/store/apps/details?id=org.traccar.client
2. Open the app and configure:
2. Open the app and scan the QR code (or configure manually):
- Device identifier: ${actualDeviceId}
- Server URL: ${serverUrl}
- Location accuracy: Highest
- Frequency: ${settings.updateIntervalSeconds} seconds
- Location accuracy: High
- Distance: 0
- Angle: 30
3. Tap "Service Status" to start tracking.
3. IMPORTANT iPhone Settings:
- Settings > Privacy > Location Services > Traccar Client > "Always"
- Settings > General > Background App Refresh > ON for Traccar Client
- Do NOT swipe the app away from the app switcher
- Low Power Mode should be OFF while driving
Note: GPS tracking is only active during shift hours (${settings.shiftStartHour}:00 - ${settings.shiftEndHour}:00).
4. Tap "Service Status" to start tracking.
`.trim();
let signalMessageSent = false;
@@ -286,6 +298,12 @@ Note: GPS tracking is only active during shift hours (${settings.shiftStartHour}
qrUrl.port = String(devicePort);
qrUrl.searchParams.set('id', device.deviceIdentifier);
qrUrl.searchParams.set('interval', String(settings.updateIntervalSeconds));
qrUrl.searchParams.set('accuracy', 'highest');
qrUrl.searchParams.set('distance', '0');
qrUrl.searchParams.set('angle', '30');
qrUrl.searchParams.set('heartbeat', '300');
qrUrl.searchParams.set('stop_detection', 'false');
qrUrl.searchParams.set('buffer', 'true');
return {
driverName: device.driver.name,