HTTP Posting & Offline Buffer

How It Works

1. Each location update triggers a native HTTP POST to your configured URL.
2. iOS uses URLSession, Android uses HttpURLConnection — both run natively without waking the JS runtime.
3. If the request fails (no network, server error), the location is stored in a local SQLite database.
4. On the next successful request, buffered locations are flushed automatically in FIFO order.
5. The onHttp event is emitted for every attempt, letting you monitor delivery in JavaScript.

Configuration

interface HttpConfig {
  url: string;                           // POST endpoint
  headers?: Record<string, string>;      // custom headers
  buffer?: {
    maxSize?: number;                    // max offline entries (default: 1000)
  };
}

POST Body Format

Each POST sends a single location object as JSON. The Content-Type header is set to application/json automatically.

{
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122,
    "accuracy": 5.0,
    "speed": 1.2,
    "heading": 180.0,
    "altitude": 110.5,
    "timestamp": 1700000000000,
    "isMoving": true,
    "isMock": false
  }
}

HttpEvent

interface HttpEvent {
  statusCode: number;       // HTTP status code (0 if network error)
  success: boolean;         // true if 2xx
  responseText: string;     // response body
  error?: string;           // error message on network failure
  bufferedCount?: number;   // locations waiting in offline buffer
}

Offline Buffer & Retry

When a POST fails (network offline, server 5xx, timeout), the location is pushed to a local SQLite buffer. On the next successful delivery, the plugin flushes buffered entries automatically in chronological order.

• Buffer capacity is controlled by buffer.maxSize (default: 1000).
• When the buffer is full, the oldest entries are evicted to make room for new locations.
• The bufferedCount field in HttpEvent shows how many locations are waiting.
• Retry happens automatically — no manual intervention needed.

Complete Example with Authentication

import { addListener, configure, start } from '@bglocation/react-native';

await configure({
  distanceFilter: 15,
  desiredAccuracy: 'high',
  heartbeatInterval: 15,
  http: {
    url: 'https://api.example.com/locations',
    headers: {
      Authorization: 'Bearer YOUR_TOKEN',
      'X-Device-Id': 'device-123',
    },
    buffer: {
      maxSize: 1000, // store up to 1000 locations offline
    },
  },
});

// Monitor HTTP delivery
addListener('onHttp', (event) => {
  if (event.success) {
    console.log('✅ Delivered, status:', event.statusCode);
  } else {
    console.warn('❌ Failed:', event.error ?? event.statusCode);
    console.warn('   Buffered:', event.bufferedCount);
  }
});

await start();