02 Service Worker

Service Worker & Offline Queue

OnTheGo uses a Service Worker to enable Progressive Web App (PWA) features like offline support and background sync. Push notifications are planned and may be limited by browser/device support.

What is a Service Worker?

A service worker is a script that runs in the background, separate from your main browser tab. It enables:

How Offline Queue Works

When you lose internet connection, OnTheGo automatically queues your write actions:

What Gets Queued

What Doesn't Queue

Queue Indicators

When you're offline, you'll see a banner at the top:

Automatic Sync

When you regain connection:

1. The banner turns blue ("Syncing...")
2. Queued actions are sent to the server (oldest first)
3. Completed actions are removed from queue
4. Banner disappears when sync is complete

Sync Priority

Actions are processed in priority order:

1. High priority - Urgent status changes
2. Normal priority - Standard updates (default)
3. Low priority - Non-critical updates

Within each priority, older actions sync first.

PWA Installation

Installing OnTheGo as an app provides the best experience:

How to Install

1. Open OnTheGo in your mobile browser
2. Look for the "Install" or "Add to Home Screen" prompt
3. Tap to install
4. OnTheGo appears as an app icon

Benefits of Installing

Troubleshooting

"You're Offline" Banner Won't Go Away

Cause: No internet connection or sync stuck

Solutions:

1. Check your device's internet connection
2. Wait 30 seconds - sync has a fail-safe timeout
3. Refresh the page (pull down on order list)
4. If persistent, clear the cache (see below)

Changes Not Syncing

Cause: Network error, server issue, or conflict

Solutions:

1. Check you have internet connection
2. Look for error messages in browser console
3. Try refreshing the page
4. If conflict detected, you may need to manually resolve

App Not Updating

Cause: Service worker cache is stale

Solutions:

1. Close all OnTheGo tabs
2. Wait 30 seconds
3. Reopen OnTheGo
4. Or force refresh: Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)

Clear Service Worker Cache

If you're experiencing persistent issues:

1. Open browser DevTools (F12)
2. Go to Application tab
3. Click Service Workers in sidebar
4. Click Unregister next to OnTheGo service worker
5. Click Clear storage > Clear site data
6. Refresh the page

Check Service Worker Health

View service worker status and logs:

1. Open browser DevTools (F12)
2. Go to Application tab
3. Click Service Workers in sidebar
4. View status and log entries

Or use the health endpoint:

/onthego/sw-health

Returns:

{
  "version": "2.3",
  "uptime": 1234567,
  "cacheSize": 42,
  "metrics": {
    "fetchCount": 150,
    "cacheHitCount": 120,
    "cacheMissCount": 30,
    "errorCount": 0
  },
  "logs": [...]
}

Conflict Resolution

If multiple people edit the same order while one is offline:

1. You'll see a conflict notification
2. Check the order for current state
3. Re-apply your changes if needed
4. Contact support if data appears incorrect

Browser Compatibility

Technical Details

For developers or advanced users:

Cache Strategy

Cache Duration

• Cached pages expire after 24 hours
• Service worker checks for updates on each navigation
• Max 100 entries in cache (oldest removed first)

Idempotency Keys

Each queued request includes an idempotency key that prevents duplicate execution if the request is sent multiple times during sync.

Data Persistence

• Cache timestamps stored in IndexedDB (survives SW restart)
• Queue persisted in IndexedDB (survives page refresh)
• Metrics tracked in SW memory (reset on SW restart)

See Also

• Push Notifications - Setting up alerts
• OnTheGo - Mobile field platform
• User Profile - Account settings