Developer guide · Nevar Bridge

This is a protocol specification, not a hosted endpoint. The example addresses and token below are placeholders. Issue unique device tokens and implement authentication, durable acknowledgments and appropriate access controls on your server.

A receiver can be implemented in any server framework. The app knows no map format and requires no Nevar-hosted account. A destination is an HTTPS base URL, for example https://receiver.example/bridge. Up to three independently enabled destinations are supported. Its optional alternate base URL must reach the same receiver and device credential. Redirects are not followed; credentials are never forwarded to an unconfigured host. Normal platform certificate validation is mandatory.

All requests are authenticated POSTs with Authorization: Bearer <device-token> and Content-Type: application/json. Tokens belong to one phone/receiver enrollment, not a username or hardware identifier. The iPhone keeps each destination token in its device-only Keychain; credentials are not placed in URL query strings, queue records or ordinary settings. Local HTTPS requires a correctly installed/trusted CA certificate. A local-network address and a remote address may be alternate routes to the same receiver, rather than separate destinations.

Connection test

POST {base}/v1/test

{"api_version":1,"device_id":"a8f342b1-2854-4915-b4bb-8b193f274110"}

{"api_version":1,"ok":true,"receiver_id":"Example Receiver"}

This sends no coordinates. Return an operator-chosen receiver label. Issue a separate token per installation and optionally bind it to the install UUID on first successful authentication. Keep authentication independent of the display name; names are not verified identities. Define replacement-device enrollment and revocation procedures.

Location upload

POST {base}/v1/positions

{
  "api_version": 1,
  "samples": [{
    "sample_id": "18135efb-4c7a-4873-ad45-9914d4841e57",
    "device_id": "a8f342b1-2854-4915-b4bb-8b193f274110",
    "username": "Ranger-12",
    "latitude": 38.4821,
    "longitude": -90.3764,
    "accuracy_m": 5.2,
    "speed_mps": 1.8,
    "course_deg": 247,
    "heading_deg": 243,
    "timestamp": "2026-10-24T12:00:00Z"
  }]
}

sample_id, device_id, username, coordinates, accuracy and timestamp are required. Unknown speed/course/heading are omitted or null. UUIDs identify an installation and a sample; they are not advertising IDs. Timestamps include a timezone and refer to GPS measurement time, not upload time. course_deg is travel direction; heading_deg is available true-north compass heading. Units are meters, meters/second and degrees. Display names are 1–60 characters with no control characters. Latitude/longitude must be finite, within ±90/±180. Accuracy is a nonnegative horizontal estimate, not a quality guarantee. Batches contain 1–100 samples from one device, each with a unique sample ID.

On successful durable acceptance, return HTTP 200 or 202:

{"api_version":1,"accepted_sample_ids":["18135efb-4c7a-4873-ad45-9914d4841e57"],"receiver_id":"Example Receiver"}

Only explicitly acknowledged sample IDs are removed from that destination's queue. Partial acknowledgments are supported. Duplicate retries must acknowledge the original IDs without creating duplicate records. Reusing an ID for different content must be rejected. The app does not treat an empty/malformed body or a generic 2xx status as proof of acceptance. Receiver-side acknowledgment means storage/acceptance, not delivery to another person's device.

Errors and retry

401/403 pause that destination until its token/configuration is corrected and tested. TLS certificate errors also pause it; they are never bypassed. Other permanent 4xx responses indicate a configuration/protocol problem. HTTP 408, 425, 429 and 5xx are retried with bounded exponential backoff and jitter. Numeric Retry-After is respected up to one hour; the current client does not parse HTTP-date-form Retry-After. Connection failures try the configured alternate route, then retain the queue. A restored network triggers another attempt unless a server cooldown is still active. One failed destination does not prevent the other two from working.

Choose appropriate server-side rate and payload limits. Return 429 and a numeric Retry-After when throttling. Support batches of up to 100 samples and avoid logging bearer tokens or coordinates in routine access/error logs. Do not return credentials in responses.

POST {base}/v1/stop with the same body as the test request. Acknowledge with the same {api_version,ok,receiver_id} structure. Receivers should stop presenting the device as actively sharing and prevent older in-flight reports from restoring its live status. Define a stale-position expiry appropriate to your application. Stopping is best effort if disconnected; the server cannot immediately learn about an offline stop. Stop on the phone pauses GPS and queue uploads; queued history remains until explicitly resumed, cleared or expired. An already transmitted request cannot be recalled.

Fresh positions versus history

The client sends its newest queued sample first, then drains historical samples in batches. A timestamp is never changed to the reconnect time. Keep history separate from live state. Only monotonically newer measurements inside your application's freshness window should update a live marker. Historical uploads must not synthesize current geofence crossings or overwrite a newer position. Define and document your server's retention, access controls, storage limits and stale-gap behavior independently of the phone queue.

Phone queues are separate per destination: seven days / 20,000 deliveries each, surviving app restarts. Oldest entries are discarded on reaching these limits and the app exposes a removal counter. Those limits can be reached in about 28 hours at a continuous five-second target. No exact collection/upload interval or OS relaunch guarantee is made. The queue is excluded from device backups; reinstall/device loss can lose it. Background location, full-offline recovery and battery behavior require physical-device testing.

Optional per-destination presentation (v1 compatible)

A sample may include color, a #RRGGBB string. Receivers may use it to display that device. username is the name chosen for that destination, falling back to the main sharing name. Connection-card names remain local labels and are not sent. Existing configurations and samples without these optional settings still work. Queued samples retain their original name/color; edits apply to new fixes.

Optional configuration import

Administrators may privately provide a JSON file for Import pairing:

{
  "api_version": 1,
  "name": "My server",
  "primary_url": "https://receiver.example/bridge",
  "alternate_url": "https://receiver.local/bridge",
  "interval": 30,
  "token": "REPLACE_WITH_A_UNIQUE_DEVICE_TOKEN"
}

alternate_url and interval are optional; interval defaults to 30 seconds. Supported targets are 5, 10, 30 and 60 seconds. The label is a connection name, not the user's sharing name. Imported files contain credentials: transfer them privately and remove temporary copies after import. The app reviews configuration before saving and does not start sharing on import. Neither the format nor the app requires a particular host, VPN, hardware platform, map or cloud provider.