Remote config & remote stop

Your upload endpoint can steer the device that is talking to it. Add a long_ping object to the JSON body of any 2xx reply. The device applies it right away, even with the app in the background and no JavaScript running. No app release, no push notification.

Change settings

{
  "long_ping": {
    "config": { "movingIntervalSec": 5, "http": { "uploadIntervalSec": 15 } }
  }
}

long_ping.config is a partial Config. The device keeps your server’s values as their own layer, on top of the app’s config: objects merge, arrays and scalars replace, the result is validated, saved on the device and applied. Then the configchange event fires with the full effective config.

Because the server’s values are a separate layer, they survive the app calling configure() or setConfig() (for example on every launch) and survive restarts and reboots. They stay until your server clears them.

Typical uses:

• Live mode on demand. A dispatcher opens a job: reply with movingIntervalSec: 5 to that driver’s device; reply with reset when the job is done, and the device goes back to the app’s own settings.
• Fleet-wide tuning after you have measured battery on your phones, without waiting for app store review.
• Pointing at a new endpoint (http.url) during a backend migration.

Clear the server’s values

{ "long_ping": { "reset": true } }

Removes every value your server has set, so the device runs on the app’s own config again. reset and config can come in the same reply: the reset runs first, then the new config is applied on a clean slate.

Stop tracking

{ "long_ping": { "stop": true } }

Tracking stops as if the app called stop(), and enabledchange fires with { enabled: false }. Records still in the queue keep uploading. Tracking only starts again when the app calls start().

config and stop can be sent together; the config is applied first.

Rules

Situation	Result
Reply is not 2xx	long_ping is ignored.
Body is not JSON, or has no long_ping	Nothing happens.
remoteConfig: false in the device config	long_ping.config is ignored and not stored (logged); stored server values are not applied. reset and stop still work.
The server sends remoteConfig	Dropped and logged: only the app decides whether the server may change settings.
The app’s own configure() / setConfig() makes stored server values invalid	The app’s call wins: the server values are cleared and an error is logged.
long_ping.config fails validation	Rejected and logged; the current config stays.
Unknown keys in long_ping.config	Ignored, logged at debug.

Send it once

The device applies long_ping.config each time it sees it. Merging the same values again is harmless, but send it only when something changes, so your server stays the single source of truth and the device log stays readable.

A server example

// Express: switch a device to live mode while it has an active job.
app.post('/locations', async (req, res) => {
  await storeLocations(req.body); // see "Receiving uploads"
  const device = await devices.get(req.body.device_id);

  if (device.wantsLiveMode && !device.isInLiveMode) {
    await devices.markLiveMode(device.id, true);
    return res.json({ long_ping: { config: { movingIntervalSec: 5, http: { uploadIntervalSec: 10 } } } });
  }
  if (device.offDuty) {
    return res.json({ long_ping: { stop: true } });
  }
  res.json({});
});

Things to keep in mind

• A device only hears from you when it uploads. With uploadIntervalSec: 300, a change can take up to five minutes to land (or longer while parked with a long parked interval).
• configure() on every launch is fine: it replaces only the app’s layer, never your server’s values. state.config always shows the effective config (app layer plus server values).
• onConfigChange lets your UI reflect the new settings when JavaScript is running.