Sync & your backend

Beekon stores every fix on the device. Sync is how those fixes reach a backend you run: Beekon batches the stored history, POSTs it as a small JSON envelope, and deletes the rows your server acknowledges. It’s opt-in — pass a SyncConfig with a url. Without one, nothing ever leaves the device (local-only mode).

Turn on sync

Add a sync block to your config — the only required field is url.

Android

Beekon.configure(
  BeekonConfig.Custom(
    sync = SyncConfig(
      url = "https://api.example.com/locations",
      headers = mapOf("Authorization" to "Bearer <static-token>"), // optional
      intervalSeconds = 300,
      batchSize = 100,
    ),
  ),
)

iOS

try await Beekon.shared.configure(
  BeekonConfig.custom(
    sync: SyncConfig(
      url: URL(string: "https://api.example.com/locations")!,
      headers: ["Authorization": "Bearer <static-token>"], // optional
      intervalSeconds: 300,
      batchSize: 100
    )
  )
)

Flutter

await Beekon.instance.configure(
  BeekonConfig.custom(
    sync: SyncConfig(
      url: 'https://api.example.com/locations',
      headers: {'Authorization': 'Bearer <static-token>'}, // optional
      intervalSeconds: 300,
      batchSize: 100,
    ),
  ),
);

React Native

await Beekon.configure({
  mode: 'custom',
  sync: {
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer <static-token>' }, // optional
    intervalSeconds: 300,
    batchSize: 100,
  },
});

url is used verbatim — Beekon adds no path. Set static credentials with headers (e.g. an API key); for rotating bearer tokens use auth instead, so the SDK refreshes them for you even in the background.

When uploads happen

Once a SyncConfig is set, uploads are woken by a set of triggers; whichever fires first uploads, and they all feed the same batched drain:

Trigger	When it fires
A geofence event is recorded	Immediately — geofence events are sparse and high-signal
A session stops with fixes pending	Immediately — flushes the trip tail
Every intervalSeconds (floored per platform)	The staleness backstop
sync() is called	Immediately
A regular fix is persisted	Only when syncThreshold: N ≥ 1 and ≥ N fixes are pending

The first four are unconditional. syncThreshold governs only the last — an early upload of regular fixes while moving; 0 (the default) means regular fixes ride the intervalSeconds schedule. A batch carries exactly one session — the oldest pending, oldest fixes first — so your server can stitch a tracking run back together.

SyncConfig

Field	Default	What it does
url	(required)	Your ingest endpoint, used verbatim.
headers	{}	Static headers on every POST. Where a fixed API key lives. (Auth’s Authorization, if set, wins over a static one.)
intervalSeconds	300	Scheduled upload cadence. iOS runs an in-process loop with a 60 s floor; Android background uploads run through WorkManager, whose periodic minimum is ~15 min.
batchSize	100	Max locations per POST (clamped 1…1000). A triggered upload still drains in batchSize chunks.
syncThreshold	0	Pending-fix count that triggers an early upload of regular fixes. 0 disables it.

The two time/count knobs bound different things: intervalSeconds bounds staleness; syncThreshold bounds latency while moving (you’re never more than N regular fixes behind, without the Android 15-min floor).

Goal	Config
Default — periodic batching, prompt geofence/stop flush	syncThreshold: 0
Live map / fleet tracking	syncThreshold: 10
Per-point realtime	syncThreshold: 1
Backend accepts one point per request	batchSize: 1 (pair with a threshold)

Observing sync

The syncStatus stream reports upload progress and outcomes (in flight, success, auth failure, retry). Poll pendingUploadCount() for rows still waiting, and call sync() to trigger an immediate cycle.

Tip

Set opaque per-batch metadata with setExtras({ ... }) — the map rides along in the envelope’s extras on the next upload (e.g. a trip tag). It’s omitted entirely when empty. For a stable per-user id, use setUserId(...) — it’s bound to fixes at record time and rides as each segment’s user_id (and drives Beekon Cloud MTU metering).

The upload payload

Each upload is a single JSON object at schema_version: 1; new fields only ever arrive as must-ignore additions. Fixes ride in identity segments: each segment carries the user_id that was active when its rows were recorded, so an account switch while offline can never attribute one user’s points to another. The wire shape is normative in the sync spec.

{
  "schema_version": 1,
  "batch_id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e1f",
  "session_id": "0190d4e0-1234-7000-8000-aabbccddeeff",
  "sent_at": "2026-06-15T12:34:56.789Z",
  "device": {
    "install_id": "0190c1a4-aaaa-7bbb-8ccc-ddddeeeeffff",
    "platform": "ios",
    "sdk_version": "0.4.0",
    "model": "iPhone15,3"
  },
  "extras": {
    "trip": "morning-commute"
  },
  "segments": [
    {
      "user_id": "app-user-123",
      "locations": [
        {
          "id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e20",
          "timestamp": "2026-06-15T12:34:10.000Z",
          "trigger": "interval",
          "motion": "moving",
          "is_mock": false,
          "latitude": 37.7749,
          "longitude": -122.4194,
          "accuracy": 5.2,
          "speed": 2.5,
          "bearing": 180,
          "altitude": 14.3,
          "activity": "walking",
          "battery_percent": 87,
          "is_charging": false,
          "power_save_mode": false
        }
      ],
      "geofence_events": [
        {
          "id": "0190d4e2-7b1a-7c3e-9f10-2a4b6c8d0e21",
          "geofence_id": "home",
          "type": "exit",
          "timestamp": "2026-06-15T12:34:05.000Z"
        }
      ]
    }
  ]
}

Root fields

Field	Type	Always present	Meaning
schema_version	integer	yes	1 for this format. Branch on it to be future-proof.
batch_id	string (UUIDv7)	yes	Fresh per POST attempt. Tracing only — never dedupe on it; a retried batch may be rebuilt with a fresh batch_id. Dedupe on the row ids.
session_id	string	yes	One tracking run (start()→stop()), stable across relaunch. Stitch a trip with it.
sent_at	string	yes	When the device assembled the batch (fresh per attempt).
device	object	yes	Constant per install.
extras	object	no	Your opaque string → string map from setExtras(...). Omitted when empty. Never carries identity.
reported_state	object	no	Cloud-mode device health/config report. Never sent to custom backends’ concern — ignore it if present.
segments	array	yes	Identity segments in chronological order. Each is {user_id?, locations[], geofence_events[]} — user_id omitted means the segment is anonymous (attribute to device.install_id). Consecutive segments never share an identity.

device carries install_id (UUIDv7, stable per app install), platform ("android" / "ios"), sdk_version, and model (omitted when blank).

segments[].locations[]

Field	Type	Always	Meaning
id	string (UUIDv7)	yes	Fix id. The dedup key — dedupe on it.
timestamp	string	yes	When the fix was recorded.
trigger	string	yes	interval · motion · check_in · geofence · manual
motion	string	yes	moving · stationary · unknown
is_mock	boolean	yes	OS flagged the fix as mock.
latitude, longitude	number	yes	Degrees.
accuracy	number	no	Horizontal accuracy, metres. Omitted when absent.
speed	number	no	Metres/second. Omitted when absent.
bearing	number	no	Course, degrees. Omitted when absent.
altitude	number	no	Metres. Omitted when absent.
activity	string	no	stationary · walking · running · cycling · automotive · unknown. Omitted when activity detection is off.
quality	string	no	low_accuracy · implausible_speed. Omitted when the fix is good — absence means OK.
battery_percent	integer	no	Battery level when the fix was recorded. Omitted when unknown.
is_charging	boolean	no	Charging at record time. Omitted when unknown.
power_save_mode	boolean	no	OS power saver active at record time. Omitted when unknown.

segments[].geofence_events[]

Field	Type	Meaning
id	string (UUIDv7)	Event id. Dedupe on it.
geofence_id	string	The geofence that fired (your id).
type	string	enter or exit.
timestamp	string	When the crossing occurred.

Encoding rules

You can rely on:

• Transport — POST, Content-Type: application/json, Content-Encoding: gzip (the body is always gzipped).
• Timestamps — ISO-8601 UTC with exactly three fractional digits and a literal Z: YYYY-MM-DDTHH:MM:SS.mmmZ.
• Enums — always lowercase snake_case (check_in, low_accuracy).
• Numbers — an integral value renders without a decimal (180, not 180.0).
• Optionals are omitted, never null — an absent accuracy/speed/bearing/altitude means “the OS didn’t report it.” Treat missing as unknown, never 0.
• Bad rows are dropped at the source — a fix with a non-finite latitude/longitude is removed before it’s sent; the rest still arrive.

Note

user_id lives on the segment, bound at record time via setUserId(...) — used by Beekon Cloud for MTU metering (an omitted segment user_id means anonymous, attributed to device.install_id). extras is a fully opaque map with no reserved keys — the SDK never reads identity out of it. In a self-managed backend, read segment user_id if you want it, or ignore it.

Build your ingest endpoint

Your endpoint receives the upload and answers with a status code that tells the SDK what to do with the batch. Every Beekon backend does four things:

1. Gunzip and parse the body (Content-Encoding: gzip, JSON inside).
2. Dedupe on the row ids (INSERT … ON CONFLICT DO NOTHING) so retries are harmless — never on batch_id, which is tracing-only and may change on a retry.
3. Store each segment’s locations and geofence events with its user_id.
4. Answer with the right status code — 2xx means “I durably have it; delete your copy.” An empty 2xx body is a fully conforming response.

A complete receiver

import express from 'express';
import zlib from 'node:zlib';

const app = express();

// Beekon sends gzipped JSON. Take the raw bytes; don't let a JSON body-parser touch them.
app.use('/ingest', express.raw({ type: '*/*', limit: '12mb' }));

// Stand-in for your database. In production use a table with a UNIQUE index
// on each row id, and INSERT ... ON CONFLICT DO NOTHING — the row id is the
// dedup key (batch_id is tracing-only and may change on a retry).
const fixes = new Map(); // id -> row

app.post('/ingest', (req, res) => {
  // 1. Gunzip + parse.
  let envelope;
  try {
    const raw = req.headers['content-encoding'] === 'gzip'
      ? zlib.gunzipSync(req.body)
      : req.body;
    envelope = JSON.parse(raw.toString('utf8'));
  } catch {
    return res.sendStatus(400); // unparseable — the SDK drops it and won't retry
  }

  // 2. (Optional) authenticate. Return 401 to make the SDK refresh its token and retry.
  //    if (!authorized(req)) return res.sendStatus(401);

  // 3. Idempotent ingest — dedupe on each row's id; replays are no-ops.
  for (const segment of envelope.segments ?? []) {
    for (const loc of segment.locations ?? []) {
      if (fixes.has(loc.id)) continue;
      fixes.set(loc.id, {
        ...loc,
        sessionId: envelope.session_id,
        installId: envelope.device.install_id,
        userId: segment.user_id ?? null, // record-time identity
      });
    }
    // ...store segment.geofence_events the same way (dedupe on their id too)...
  }

  // 4. Acknowledge — only after the data is durably written.
  return res.sendStatus(200);
});

app.listen(8080, () => console.log('ingest listening on :8080'));

What your status code means

The SDK reads your HTTP status and acts on the batch — it never deletes data it isn’t sure you have:

You return	SDK treats it as	What the SDK does
2xx	accepted	Deletes those rows. ✅
400, 422	rejected	Drops the batch — won’t retry. Use only for a permanently bad payload.
401, 403	auth	Keeps the rows, refreshes the token (if configured), retries once.
408, 429	transient	Keeps the rows, backs off, retries. Retry-After is honored on 429.
5xx, timeout, network error	transient	Keeps the rows, retries with backoff. Retry-After is honored on 503.
413	too large	Keeps the rows, halves the batch and retries, down to a single row; a single row that still gets 413 is dropped as poison so the queue can’t wedge.
404, 3xx, any other 4xx	permanent	Keeps the rows. Fix the endpoint.

Caution

Three SDK-side rules to design around:

• The body is always gzipped (Content-Encoding: gzip) — your app can’t change this.
• Redirects are refused. A 3xx is never followed (it would leak the Authorization header). Serve /ingest directly — no 301/302 to a CDN or trailing-slash variant.
• Requests time out at 30 s. Do durable work fast, or accept-then-process asynchronously and return 2xx once the batch is safely queued.

A 2xx that never reaches the device (dropped connection, a timeout after you committed) leaves the SDK believing the upload failed — so it retries the rows, possibly regrouped under a fresh batch_id. Dedupe on each row id and even a partial write is safe to replay.

The optional response body

Your 2xx may carry a JSON body — every field optional, unknown fields ignored. This is the down-channel Beekon Cloud rides (a config_revision staleness signal, a geofence_halo slice, pending device commands); a custom backend can implement any subset or, most commonly, none. Returning a bare 200 with no body is the complete, conforming contract. A malformed body never un-accepts an upload — the rows stay deleted on the device.

Auth & token refresh

There are two ways to authenticate uploads:

• Static header — a fixed API key in SyncConfig.headers. Simple, but it never rotates and it’s stored in plaintext on the device.
• Declarative refresh — an AuthConfig recipe. The SDK attaches a bearer token and refreshes it itself against your token endpoint, proactively before it expires and reactively on a 401/403. This runs headless, in the background, across a cold launch — no callback from your app code.

Use the static header for low-stakes keys; use AuthConfig for anything that should rotate.

Configure declarative refresh

Android

SyncConfig(
  url = "https://api.example.com/locations",
  auth = AuthConfig(
    accessToken = "<initial access token>",      // seed, optional
    refreshToken = "<initial refresh token>",     // seed
    expiresAt = System.currentTimeMillis() / 1000 + 3600, // epoch seconds
    refreshUrl = "https://auth.example.com/oauth/token",
    refreshPayload = mapOf(
      "grant_type" to "refresh_token",
      "refresh_token" to "{refreshToken}",        // substituted at refresh time
    ),
    // strategy = AuthStrategy.Bearer, refreshBodyFormat = AuthBodyFormat.Form,
    // skewMarginSeconds = 60 — all defaults
  ),
)

iOS

SyncConfig(
  url: URL(string: "https://api.example.com/locations")!,
  auth: AuthConfig(
    accessToken: "<initial access token>",        // seed, optional
    refreshToken: "<initial refresh token>",       // seed
    expiresAt: Date().timeIntervalSince1970 + 3600, // epoch seconds
    refreshUrl: URL(string: "https://auth.example.com/oauth/token")!,
    refreshPayload: [
      "grant_type": "refresh_token",
      "refresh_token": "{refreshToken}",           // substituted at refresh time
    ]
    // strategy: .bearer, refreshBodyFormat: .form, skewMarginSeconds: 60 — defaults
  )
)

Flutter

SyncConfig(
  url: 'https://api.example.com/locations',
  auth: AuthConfig(
    accessToken: '<initial access token>',        // seed, optional
    refreshToken: '<initial refresh token>',       // seed
    expiresAt: DateTime.now().millisecondsSinceEpoch / 1000 + 3600, // epoch seconds
    refreshUrl: 'https://auth.example.com/oauth/token',
    refreshPayload: {
      'grant_type': 'refresh_token',
      'refresh_token': '{refreshToken}',           // substituted at refresh time
    },
    // strategy: AuthStrategy.bearer, refreshBodyFormat: AuthBodyFormat.form,
    // skewMarginSeconds: 60 — defaults
  ),
)

React Native

{
  url: 'https://api.example.com/locations',
  auth: {
    accessToken: '<initial access token>',        // seed, optional
    refreshToken: '<initial refresh token>',       // seed
    expiresAt: Math.floor(Date.now() / 1000) + 3600, // epoch seconds
    refreshUrl: 'https://auth.example.com/oauth/token',
    refreshPayload: {
      grant_type: 'refresh_token',
      refresh_token: '{refreshToken}',             // substituted at refresh time
    },
    // strategy: 'bearer', refreshBodyFormat: 'form', skewMarginSeconds: 60 — defaults
  },
}

The supplied tokens are a seed: the SDK adopts them once, then owns and rotates the live token set in encrypted storage (Keychain / Keystore). Rotations surface on the authChanges stream — mirror them into your own session store if you need to.

The recipe

Field	Default	Meaning
accessToken	—	Seed access token (optional).
refreshToken	—	Seed refresh token / long-lived credential.
expiresAt	—	Seed expiry, epoch seconds. Null ⇒ no proactive refresh (reactive only).
strategy	Bearer	How the token attaches: Bearer → Authorization: Bearer <token>; Raw → Authorization: <token>.
refreshUrl	—	Token endpoint. Null ⇒ seed-only, no refresh.
refreshPayload	{}	Request body fields. {accessToken} / {refreshToken} are substituted with the current tokens.
refreshHeaders	Authorization: Bearer {accessToken}	Request headers, same templating.
refreshBodyFormat	Form	Form (application/x-www-form-urlencoded) or Json.
responseMapping	—	Override the keys Beekon reads from the response (supports dot-paths like data.access_token).
skewMarginSeconds	60	Refresh this many seconds before expiresAt.

Your refresh endpoint

When the SDK refreshes, it sends a POST to refreshUrl (15 s timeout) with the templated payload, and parses the response for the new token. Respond 2xx with JSON:

{ "access_token": "<new token>", "expires_in": 3600 }

Beekon reads, in order, responseMapping.accessToken → access_token → accessToken → token; expiry from expiresAt / expiresIn / expires_at / expires_in (relative is now + value). A numeric string like "3600" is fine.

Refresh returns	Outcome
2xx with a token	Adopt the new token set, retry the upload.
2xx without a token	Dead credentials — stop refreshing until you re-seed.
408, 429, 5xx, network/timeout	Transient — back off and retry.
3xx or any other 4xx	Dead credentials — stop refreshing until you re-seed.

After 3 consecutive refresh failures the SDK opens a circuit breaker (exponential backoff) so it never hammers your token endpoint. To recover from a dead-credential state, supply a fresh accessToken via configure().

How it behaves

• Proactive — when expiresAt is set, refresh fires at expiresAt − skewMarginSeconds, before a request ever fails.
• Reactive — a 401/403 triggers one refresh, then the upload retries once.
• Single-flight — concurrent callers share one in-flight refresh; a burst can’t stampede your endpoint.
• Persisted & encrypted — rotated tokens survive process death; the upload backlog is kept across a failed-auth window so nothing is lost.

Caution

The recipe itself (URLs, header/payload templates) is stored in plaintext. Put only the {accessToken} / {refreshToken} templates in it — never a static client secret. The secret is the rotating refresh token, which Beekon holds encrypted.

Local-only mode

With no sync block, Beekon is local-only: it tracks, persists fixes and geofence events on the device, and serves history reads and geofencing — but makes no network request at all. Nothing leaves the device.

One difference worth knowing: in local-only the 7-day age prune applies, so old fixes drop on schedule. With sync set, the full backlog is kept (bounded only by the 100,000-row cap) so an offline device can drain a long catch-up when it reconnects.

Backend checklist

• Accept POST at the exact url in SyncConfig (no redirect).
• Gunzip the body, then JSON.parse.
• Dedupe on each row id (segments[].locations[].id / segments[].geofence_events[].id) — never on batch_id.
• Store fixes + geofence events with each segment’s user_id; session_id stitches a run, device.install_id identifies the device.
• Return 2xx only after the data is durably stored (empty body is fine); 400/422 for permanently bad payloads; 5xx to ask for a retry.
• Serve over HTTPS for any non-loopback URL.