Background Location

Overview

Background location tracking enables your app to monitor device location in real-time, even when the app is minimized or the phone is locked. This feature is essential for delivery apps, fitness trackers, fleet management, and any application requiring continuous location monitoring.

Prerequisites

Despia Configuration

1. Open your Despia project

2. Navigate to Add-ons

3. Enable Background location tracking

   

4. Rebuild and republish your application (required for initial setup only)

5. Wait for the app to appear in TestFlight or Android Beta

WeWeb Setup

1. Install the Despia plugin from WeWeb Marketplace

2. Verify installation: Assets → Library → check for "Despia Provider"

Implementation Steps

Step 1: Add Despia Plugin Component

1. Click Add in WeWeb editor

2. Navigate to Assets panel

3. Drag Despia plugin to the top of your page

Step 2: Create Location Variable

1. Create a new variable named "location"

2. Set type to Object

3. Set example structure / or leave empty

   Copy{
     "latitude": null,
     "longitude": null,
     "accuracy": null,
     "altitude": null,
     "altitudeAccuracy": null,
     "heading": null,
     "speed": null,
     "timestamp": null,
     "watchId": null
   }
   

   

Step 3: Add Start Tracking Button

1. Add a button element labeled "Start Background Location"

2. Go to Workflows → Add "On click" workflow

3. Add action: Execute component action

   • Component: Despia plugin

   • Action: "Start background location tracking"

   • Enable GPS: Yes (for higher accuracy)

   • Timeout: 5000 milliseconds (recommended default)

Step 4: Add Stop Tracking Button

1. Add another button labeled "Stop Background Location"

2. Go to Workflows → Add "On click" workflow

3. Add action: Execute component action

   • Component: Despia plugin

   • Action: "Stop background location tracking"

Step 5: Handle Location Updates

1. Select the Despia plugin component

2. Go to Workflows → Add new workflow

3. Change trigger to "On location change"

4. Add action: Change variable value

   • Variable: Select "location"

   • Value: Bind to Event (contains all location data)

Location Data Structure

The location event provides comprehensive data:

Copy{
  "latitude": 33.123456,
  "longitude": -117.123456,
  "altitude": 100.5,
  "accuracy": 5,           // meters
  "altitudeAccuracy": 10,  // meters
  "heading": 180,          // degrees
  "speed": 15.5,           // meters/second
  "timestamp": 1234567890,
  "watchId": "abc123"
}

Performance Considerations

Update Frequency

• Location updates fire with high frequency (every slight movement)

• Consider implementing debouncing for API calls

• Cache updates for batch processing

Backend Integration Options

API with Debouncing (Recommended for most apps):

WebSockets (Best for real-time requirements):

• Native WebSocket support in WeWeb

• Works with Xano, Supabase real-time features

• Ideal for live tracking applications

Battery Optimization

• High GPS accuracy impacts battery life

• Consider adjustable accuracy based on use case

• Implement smart tracking intervals

Background Behavior

• App minimized: Tracking continues

• Phone locked: Tracking continues

• App in background: Tracking continues

• App force-closed: Tracking stops

Note: Background tracking requires the add-on enabled in Despia, not just WeWeb configuration.

Publishing & Updates

• Initial setup requires app rebuild (for enabling add-on)

• Subsequent changes in WeWeb use over-the-air updates

• No App Store resubmission for tracking logic changes

• Updates available immediately to all users

Common Use Cases

Delivery & Logistics

• Real-time driver tracking

• Route optimization

• Delivery confirmation

Fitness & Health

• Running/cycling route tracking

• Distance and speed calculation

• Workout history

Field Services

• Employee location monitoring

• Time tracking at job sites

• Route verification

Transportation

• Ride-sharing driver tracking

• Public transit tracking

• Fleet management

Best Practices

1. User Consent: Always request explicit permission

2. Privacy Policy: Clearly explain location data usage

3. Battery Warnings: Inform users about battery impact

4. Selective Tracking: Only track when necessary

5. Data Security: Encrypt location data transmission

6. Compliance: Follow GDPR, CCPA regulations

Troubleshooting

Location not updating:

• Verify background location is enabled in Despia

• Check device location permissions

• Ensure GPS is enabled on device

Too many updates:

• Implement debouncing

• Adjust timeout settings

• Consider using WebSockets

Battery drain:

• Reduce GPS accuracy when high precision not needed

• Implement smart tracking schedules

• Stop tracking when not needed