Permissions & Location

This article documents how location and related permissions are used in Creative Job Hub, how technician presence is surfaced, background location requirements, privacy guidance, and troubleshooting steps for admin/implementers.

High-level behavior

• Live technician locations are shown on the Jobs Map when technicians are active/clocked in. Locations update frequently to support real-time tracking (technician locations update ~every 15 seconds; jobs data refreshes ~every 30 seconds). Ensure the implementation tolerates gaps and intermittent connectivity. :contentReference[oaicite:14]{index=14} :contentReference[oaicite:15]{index=15}

• Clock-in requirement: Technicians must be clocked in to appear on the Jobs Map. If a technician is not clocked in, location should not display. This is enforced in the UI and data flow. :contentReference[oaicite:16]{index=16}

Required permissions & platform considerations

Core permissions

• Location (foreground): Required to capture and report location while the app is in use.
• Background location (optional): Required if continuous tracking when the app is backgrounded is part of your workflow. On iOS this requires the Always authorization and background mode entitlements; on Android this requires ACCESS_BACKGROUND_LOCATION and appropriate runtime prompts.
• Camera: For in-app photo capture.
• Notifications: For push alerts.

Platform notes

• iOS (PWA vs native): PWAs on iOS have limited background execution and limited or no support for background location. For reliable background tracking and push, use a native iOS app and declare the location background mode and appropriate Info.plist permission descriptions.
• Android: Background location requires ACCESS_BACKGROUND_LOCATION runtime permission and a clear app use-case in the Play Store listing. Android vendors’ battery optimizations may block background updates; instruct users to whitelist the app for background activity when continuous tracking is required.

Implementation hint

• The client uses Capacitor geolocation in native builds (@capacitor/geolocation) to capture location updates; ensure required plugin versions are installed and permissions are declared. Confirm matching Capacitor versions in package.json when adjusting plugins. :contentReference[oaicite:17]{index=17}

Map and geocoding notes

• Map rendering uses Mapbox; per-tenant Mapbox public tokens are configured in Settings → Integrations. Configure a per-tenant token for production to avoid demo token rate limits. Mapbox tokens are used for map tiles and (separately) geocoding on property creation. :contentReference[oaicite:18]{index=18}
• Property creation performs server-side geocoding (Mapbox) to obtain lat/lng. If geocoding fails, the property is saved without coordinates and the UI surfaces this behavior. See PropertyDialog for the geocoding call. :contentReference[oaicite:19]{index=19}

Privacy & legal considerations

• Minimize collection: Only collect location when necessary; ensure legal and regulatory compliance for your service area.
• Transparent notice: Provide clear in-app and onboarding text that explains why location is collected and how it will be used. For background location, explain why “Always” permission is needed.
• Data scoping & security: All API calls are authenticated and data is scoped to the user’s organization; Row Level Security (RLS) enforces tenant boundaries. Ensure admin roles and access controls are correctly configured. :contentReference[oaicite:20]{index=20}

Battery & reliability best practices

• Adaptive sampling: If you implement custom location sampling, reduce sampling frequency when not actively dispatching to reduce battery usage.
• Whitelist for background: Document how users can exempt the app from battery optimizers (Android) or enable Background App Refresh (iOS) if continuous tracking is required.
• Network-aware behavior: Buffer and queue location updates when offline and sync when connectivity returns.

Troubleshooting checklist

Technician not visible on Jobs Map

1. Is the technician clocked in? Technicians must be clocked in to appear. :contentReference[oaicite:21]{index=21}
2. Are location permissions granted (foreground/minimally)?
3. On mobile, is background location required and has it been granted (Always on iOS or ACCESS_BACKGROUND_LOCATION on Android)?
4. Is the device prevented from background execution by battery optimizers? If so, ask the user to whitelist the app.

Inaccurate or no location updates

• Check device location settings and GPS signal.
• Confirm the app can reach the backend (network). Location updates are typically synced frequently; server logs and client sync diagnostics can show failed attempts.
• Verify plugin and runtime permission declarations on the native project if using native builds.

Map tiles or geocoding failing

• Confirm per-tenant Mapbox token is configured and valid (Settings → Integrations → Mapbox Configuration). Demo tokens are rate-limited and intended for testing only. :contentReference[oaicite:22]{index=22}

Operational checklist for admins / implementers

• [ ] Ensure tenant has a valid Mapbox public token configured for production. :contentReference[oaicite:23]{index=23}
• [ ] Decide whether background tracking is required; if yes, update native apps’ manifest/Info.plist with the correct permissions and provide guidance text.
• [ ] Add a privacy notice describing location usage and retention and obtain any required legal approvals.
• [ ] Provide technicians with instructions for granting permissions and whitelisting the app on devices with aggressive battery management.

References & implementation pointers

• Jobs Map View — update cadence, technician visibility and per-tenant Mapbox configuration. :contentReference[oaicite:24]{index=24} :contentReference[oaicite:25]{index=25}
• PropertyDialog geocoding implementation (mapbox-geocode invocation). :contentReference[oaicite:26]{index=26}
• Capacitor geolocation & related plugin versions (package.json). :contentReference[oaicite:27]{index=27}

Updated on: 10/01/2026