HttpConfig¶

public classHttpConfig

HTTP and networking configuration for the background geolocation SDK.

HttpConfig controls how recorded locations are uploaded to your server — the endpoint, HTTP verb, headers, params, batching behaviour, and request timeouts.

Contents¶

Overview
Upload lifecycle
Payload composition
Sync strategy
Error handling
Remote control
Logging
Examples

Overview¶

The SDK persistently stores each recorded location in an internal SQLite database before attempting to upload it. The HTTP service continuously consumes this queue in the background, surviving app termination and device reboot. When connectivity returns it resumes automatically.

Category	Properties	Notes
Destination	`url`, `method`	`method` defaults to `POST`.
Payload	`rootProperty`, `params`, `headers`	Controls JSON body and headers.
Sync cadence	`autoSync`, `autoSyncThreshold`, `batchSync`, `maxBatchSize`	Immediate vs batched uploads.
Network policy	`disableAutoSyncOnCellular`, `timeout`	Conserve bandwidth and battery.

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://example.com/locations"
    config.http.autoSync = true
    config.http.params = ["user_id": 1234]
}

Upload lifecycle¶

Each location follows this path from recording to delivery:

A location is recorded and immediately rendered to JSON — using the default schema or PersistenceConfig.locationTemplate if configured — then written to SQLite.
A record-level lock is acquired to prevent duplicate uploads.
The stored JSON is read from SQLite and posted to url.
A 2xx response marks the record as delivered — it is deleted from the database.
On failure, the lock is released and the record is retried later.

The SQLite buffer acts as a rolling queue and is normally empty. Records are removed when: - your server returns a 2xx (see HttpEvent) - BGGeo.destroyLocations is called - TTL from PersistenceConfig.maxDaysToPersist expires - PersistenceConfig.maxRecordsToPersist is exceeded

Inspect queue size with BGGeo.getCount or fetch records with BGGeo.getLocations.

Payload composition¶

Body: JSON. If batchSync is true, an array of records is sent. If rootProperty is set, the payload becomes { "<rootProperty>": [...] }.
Headers: Merged from headers plus any authorization headers injected by AuthorizationConfig.
Params: Merged into every payload at the root level, or under rootProperty if configured.

Uploads use application/json. Authorization refresh requests use application/x-www-form-urlencoded.

Sync strategy¶

Option	Behaviour
`autoSync`	Upload immediately after each recorded location.
`autoSyncThreshold`	Wait until N records are queued before uploading.
`batchSync`	Bundle all queued records into a single HTTP request.
`maxBatchSize`	Cap the number of records per batch request.
`disableAutoSyncOnCellular`	Defer uploads until Wi-Fi is available.
`timeout`	Abort requests exceeding this duration (ms).

Error handling¶

On a non-2xx response or network failure, records remain locked in the queue and are retried when: - new locations are recorded - the app resumes or the device reboots - BGGeo.onConnectivityChange fires - BGGeo.onHeartbeat fires - iOS background fetch runs

To trigger a manual upload at any time:

Remote control¶

Your server can instruct the SDK to execute commands by including a background_geolocation key in any HTTP response body.

Command	Arguments	Effect
`"start"`	—	BGGeo.start
`"stop"`	—	BGGeo.stop
`"startGeofences"`	—	BGGeo.startGeofences
`"changePace"`	`boolean`	BGGeo.changePace
`"setConfig"`	`{Config}`	BGGeo.setConfig
`"addGeofence"`	`{Geofence}`	BGGeo.addGeofence
`"addGeofences"`	`[{Geofence}, ...]`	BGGeo.addGeofences
`"removeGeofence"`	`identifier: string`	BGGeo.removeGeofence
`"removeGeofences"`	list or none	Remove some or all geofences.
`"uploadLog"`	`url: string`	Upload the plugin log.
`"destroyLog"`	—	Delete the plugin log.

Logging¶

The SDK log provides a trace of the full HTTP lifecycle.

#	Entry	Meaning
1	Location	Raw location recorded
2	INSERT	Persisted to SQLite
3	Locked	Marked for upload
4	HTTP POST/PUT	Upload attempted
5	Response	Server status code
6	DESTROY / UNLOCK	Delivered / failed, queued for retry

Examples¶

Manual sync¶

let bgGeo = BGGeo.shared

Task {
    do {
        let records = try await bgGeo.store.sync()
    } catch {
        print("[sync] error: \(error)")
    }
}

New compound Config¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://api.example.com"
    config.http.autoSync = true
    config.http.headers = ["Authorization": "Bearer ..."]
}

Simple upload¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://api.example.com/locations"
    config.http.method = .post
    config.http.autoSync = true
    config.http.headers = ["Authorization": "Bearer secret"]
    config.http.params = ["device_id": "abc-123"]
}

Batched uploads¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://api.example.com/locations/bulk"
    config.http.autoSync = true
    config.http.batchSync = true
    config.http.maxBatchSize = 25
    config.http.autoSyncThreshold = 10
    config.http.rootProperty = "locations"
}

Conserve cellular data¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://api.example.com/locations"
    config.http.autoSync = true
    config.http.disableAutoSyncOnCellular = true
}

Manual sync¶

let bgGeo = BGGeo.shared

bgGeo.config.batchUpdate { config in
    config.http.url = "https://api.example.com"
    config.http.autoSync = false
}

Task {
    do {
        let records = try await bgGeo.store.sync()
    } catch {
        print("[sync] error: \(error)")
    }
}

Members¶

autoSync¶

public var autoSync: Bool

Uploads each recorded location to url immediately after it is recorded.

Defaults to true. When a url is configured, the SDK attempts to upload each location as soon as it is written to SQLite. All recorded locations are persisted in the internal database until successfully delivered, regardless of this setting.

When autoSync is false, call BGGeo.sync to trigger uploads manually.

Note

With autoSync: false, the queue grows until you call BGGeo.sync or until uploads succeed automatically on the next retry trigger.

See also - autoSyncThreshold - batchSync - maxBatchSize

autoSyncThreshold¶

public var autoSyncThreshold: Int

Minimum number of queued records required before an automatic upload fires.

Defaults to 0 (no threshold — upload after every recorded location).

When set above 0, the SDK waits until at least this many locations are queued before uploading. Combining autoSyncThreshold with batchSync significantly reduces battery consumption by minimizing the number of HTTP requests.

Warning

autoSyncThreshold is ignored during BGGeo.onMotionChange transitions. When the device enters the moving state, any queued locations are uploaded immediately. When it enters the stationary state, all remaining queued locations are flushed before the SDK goes idle.

See also - autoSync - batchSync

batchSync¶

public var batchSync: Bool

Bundles all queued locations into a single HTTP request.

Defaults to false. When true, the SDK sends all records currently in the SQLite queue in one HTTP request rather than one request per location. Use maxBatchSize to cap the number of records per request.

Batching is most effective when combined with autoSyncThreshold to reduce upload frequency and conserve power.

See also - autoSync - autoSyncThreshold - maxBatchSize

disableAutoSyncOnCellular¶

public var disableAutoSyncOnCellular: Bool

Defers automatic uploads until the device is on Wi-Fi.

Defaults to false. When true, autoSync uploads occur only when a Wi-Fi connection is active. Locations continue to be recorded and queued while on cellular — they are uploaded once Wi-Fi becomes available.

Warning

This setting is ignored when calling BGGeo.sync manually. Manual syncs always proceed regardless of connection type.

See also - autoSync - BGGeo.sync

headers¶

public var headers: [String: Any]

HTTP headers applied to every outbound upload request.

The supplied headers are merged with the SDK's automatically applied headers (including "content-type": "application/json"). When AuthorizationConfig is configured, the SDK also injects an Authorization header automatically.

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://my.server.com"
    config.http.headers = [
        "Authorization": "Bearer <a secret key>",
        "X-FOO": "BAR"
    ]
}

Incoming request headers at your server:

POST /locations
{
  "host": "tracker.transistorsoft.com",
  "content-type": "application/json",
  "content-length": "456",
  ...
  "authorization": "Bearer <a secret key>",
  "X-FOO": "BAR"
}

See also - AuthorizationConfig

maxBatchSize¶

public var maxBatchSize: Int

Maximum number of records included in each batched HTTP request.

Defaults to -1 (no limit — all queued records in one request).

When batchSync is true and the queue exceeds maxBatchSize, the SDK generates multiple requests until the queue is fully drained. This prevents excessively large request bodies after the device has been offline for an extended period.

See also - batchSync

method¶

public var method:HttpMethod

The HTTP method used when uploading locations to url.

Defaults to POST. Valid values: POST, PUT, PATCH.

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://my-server.com/locations"
    config.http.method = .put
}

params¶

public var params: [String: Any]

Key/value pairs merged into the JSON body of every outbound upload request.

Params are merged at the root level of the payload, or nested under rootProperty when that is configured.

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.url = "https://my-server.com/locations"
    config.http.params = [
        "user_id": 1234,
        "device_id": "abc123"
    ]
}

Request body received by your server:

{
  "location": {
    "coords": {
      "latitude": 45.51927,
      "longitude": -73.61650
    }
  },
  "user_id": 1234,
  "device_id": "abc123"
}

See also - rootProperty

rootProperty¶

public var rootProperty: String

Wraps the location payload under a named root key in the JSON body.

Defaults to "location". When set, outgoing payloads nest the serialized

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.http.rootProperty = "myData"
    config.http.url = "https://my.server.com"
}

Produces:

{
  "myData": {
    "coords": {
      "latitude": 23.232323,
      "longitude": 37.373737
    }
  }
}

Set to "." to place the location data directly at the root of the JSON body:

{
  "coords": {
    "latitude": 23.232323,
    "longitude": 37.373737
  }
}

timeout¶

public var timeout: Int

HTTP request timeout in milliseconds.

Defaults to 60000 ms (60 seconds). When a request exceeds this duration, the SDK fires BGGeo.onHttp with a failure event and the record is unlocked for retry.

let bgGeo = BGGeo.shared

let sub = bgGeo.onHttp { response in
    if !response.isSuccess {
        print("[onHttp] FAILURE: \(response)")
    }
}

bgGeo.ready { config in
    config.http.url = "https://my-server.com/locations"
    config.http.timeout = 3000   // 3-second timeout
}

url¶

public var url: String

The server URL where the SDK posts recorded locations.

The SDK hosts a robust HTTP service that continuously uploads recorded locations to your server in the background, surviving app termination and device reboot.

Warning

Use the SDK's built-in HTTP service rather than posting locations from your own code. When AppConfig.stopOnTerminate is false, your app component terminates but the native background service continues recording and uploading. The SDK automatically retries on failure — ad-hoc HTTP requests from application code cannot provide the same reliability.

let bgGeo = BGGeo.shared

// Listen to HTTP events.
let sub = bgGeo.onHttp { event in
    print("[onHttp] \(event)")
}

bgGeo.ready { config in
    config.http.url = "https://my-server.com/locations"
    config.http.params = ["user_id": 1234]
    config.http.headers = ["Authorization": "Basic my-secret-key"]
    config.http.autoSync = true
    config.http.method = .post
    config.app.stopOnTerminate = false
}