Learning

3.3 CORS-safe payloads: recipes that need no server setup

The JSON-as-text/plain envelope, form encoding for flat events, and a unified payload builder that measures what it sends in real bytes.

Levels: Intermediate ~13 min read

Intermediate

Knowing the safelist rule is theory; shipping telemetry through it is engineering. This page collects the two payload recipes that put the rule to work — the JSON-as-text/plain trick that needs zero server CORS and the form-encoding shape for flat events — and unifies them in one payload builder. Each recipe runs below exactly as written, with a capture harness standing in for the network so you can watch the decisions happen. Which transport carries the payload is a separate decision, and the hybrid layer later in this series makes it per call.

Recipe 1 — JSON in a text/plain envelope

The derived Content-Type for a string body is text/plain;charset=UTF-8 — safelisted, so the request stays in no-cors mode and crosses any origin with no CORS configuration at all. Nothing stops the body itself from being JSON. A collector that reads the raw body and parses it as JSON regardless of the Content-Type header accepts these beacons from any origin, forever, with zero preflight traffic. The trade is explicit: the header lies about the body's nature, so anything that routes or validates by Content-Type upstream (API gateways, WAFs, some frameworks' body parsers) must be told to read the body anyway.

// The JSON-as-text/plain send — no CORS setup needed anywhere:
const payload = JSON.stringify({ event: 'pageview', path: location.pathname });
navigator.sendBeacon('https://collector.example.com/ingest', payload);
// derived Content-Type: text/plain;charset=UTF-8  -> no-cors mode

Recipe 2 — form encoding for flat events

When events are key/value shaped, URLSearchParams is the honest encoding: the platform derives application/x-www-form-urlencoded;charset=UTF-8 — safelisted, no-cors, and readable by every server-side form parser ever written. It is also the encoding the classic image-pixel analytics era converged on, so migration paths from legacy collectors tend to line up naturally. Its limits are the limits of form encoding: no nesting without conventions (dot-keys, JSON-in-a-field), and URL-encoding overhead on dense payloads.

The payload builder, unifying both

The runnable example implements buildBeaconPayload(target, value) — one function that returns the data object, the Content-Type the platform will derive, and the mode the request will fly in, for all three targets: form, json-text, and json-blob (the cors-mode one, for same-origin collectors or CORS-configured servers). It also demonstrates the byte-measurement discipline the quota page will demand: sizes measured with Blob([s]).size in UTF-8 bytes, never string.length in UTF-16 code units:

Interactive Runnable example

Edit

// buildBeaconPayload(): choose a payload shape that keeps your
// beacon in no-cors mode AND lands as parseable data on the server.
//
// Three honest options, given that the Content-Type decides the mode:
//   'json-text'  — a JSON string sent as text/plain (safelisted).
//                  The server reads the body as JSON regardless of
//                  the Content-Type. Works cross-origin with NO
//                  CORS setup at all (no-cors, opaque response).
//   'form'       — URLSearchParams, the form-post encoding
//                  (safelisted). Best for flat key/value events.
//   'json-blob'  — a Blob typed application/json. NOT safelisted:
//                  the request flips to cors mode and the server
//                  must pass a CORS preflight. Use it only for
//                  same-origin collectors, or servers you control
//                  that answer preflights.

// A tiny capture harness so we can watch what would go on the wire.
// (In your own page you would just call navigator.sendBeacon.)
const sent = [];
const mockSendBeacon = (url, data) => {
  sent.push({ url, kind: data === null ? 'none' : data.constructor.name });
  return true;
};

const event = { type: 'pageview', path: '/checkout', ts: 1234567890 };

for (const target of ['form', 'json-text', 'json-blob']) {
  const payload = buildBeaconPayload(target, { ...event, target });
  mockSendBeacon('https://collect.example.com/ingest', payload.data);
  console.log(
    target.padEnd(10),
    'content-type:', payload.contentType,
    '| mode:', payload.mode
  );
}

console.log('captured sends:', JSON.stringify(sent));

// Sizing note: the keepalive quota counts BODY bytes only —
// 64 kibibytes across all in-flight keepalive requests of this
// fetch group. Measure a payload the way the platform does, in
// UTF-8 bytes, not UTF-16 code units:
const json = JSON.stringify({ note: ' sizes must use bytes ', emoji: '🎉' });
console.log('string .length =', json.length, '(UTF-16 units)');
console.log('byte size      =', new Blob([json]).size, '(what the quota counts)');

Ready to run.

Quick check

Your third-party collector has zero CORS configuration. Which payload reaches it?

navigator.sendBeacon('https://third-party.example.com/ingest', ?);

Key takeaways

String bodies (JSON or otherwise) fly as text/plain;charset=UTF-8 — safelisted, no-cors, zero server setup; the server must parse the body as JSON itself.
URLSearchParams gives standard form-encoding — safelisted and universally parseable, best for flat events.
Measure payload sizes with new Blob([s]).size (UTF-8 bytes), never .length (UTF-16 units) — the quota counts bytes.
Payload shaping and transport selection stay separate — these recipes fly unchanged on sendBeacon, fetch(keepalive), or fetchLater.
Separate payload shaping from transport selection; both recipes compose instead of competing.

Was this page helpful?

Yes No

Mark this learning resource complete to track your learning progress.

Suggest an edit