Pourquoi sendBeacon vs fetch keepalive est une décision de 64 KiB

Quelle est la différence entre sendBeacon vs fetch keepalive ?

La différence concrète entre sendBeacon vs fetch keepalive tient au contrôle : navigator.sendBeacon() met en file un POST qui survit à la page mais ne renvoie rien d'autre que true ou false, tandis que fetch() avec keepalive: true vous laisse choisir la méthode, définir des en-têtes personnalisés et lire la réponse du serveur. La spécification Beacon du W3C est explicite : "The sendBeacon() method does not provide ability to customize the request method, provide custom request headers, or change other processing properties of the request and response. Applications that require non-default settings for such requests should use the [FETCH] API with keepalive set to true." Les deux passent par la même machinerie fetch en dessous, donc une seule limite de taille les gouverne tous les deux.

Combien de données sendBeacon vs fetch keepalive peuvent-ils envoyer ?

Une requête keepalive transporte au plus 64 kibioctets de corps, soit 65 536 octets. Le standard WHATWG Fetch applique le plafond à l'intérieur de HTTP-network-or-cache fetch, avant que la requête n'atteigne le réseau :

If contentLength is non-null and httpRequest's keepalive is true, then:

1. Let inflightKeepaliveBytes be 0.
2. Let group be httpRequest's client's fetch group.
3. Let inflightRecords be the set of fetch records in group whose request's keepalive is true and done flag is unset.
4. For each fetchRecord of inflightRecords:
   1. Let inflightRequest be fetchRecord's request.
   2. Increment inflightKeepaliveBytes by inflightRequest's body's length.
5. If the sum of contentLength and inflightKeepaliveBytes is greater than 64 kibibytes, then return a network error.

La note de la spécification explique le chiffre : "The above limit ensures that requests that are allowed to outlive the environment settings object and contain a body, have a bounded size and are not allowed to stay alive indefinitely." Mesurez la charge sérialisée en octets, pas en caractères, avant de lui faire confiance pour tenir.

Le plafond de 64 KiB est-il partagé entre les requêtes keepalive en vol ?

Le plafond est partagé, pas par appel. L'étape 5 ci-dessus additionne contentLength et inflightKeepaliveBytes, la longueur totale du corps de chaque requête keepalive inachevée du groupe de fetch. La spécification Beacon dit la même chose de son côté : "Requests initiated via the Beacon API automatically set the keepalive flag, and developers can similarly set the same flag manually when using the Fetch API. All requests with this flag set share the same in-flight quota restrictions that is enforced within the Fetch API." Un appel sendBeacon() et un appel fetch(..., { keepalive: true }) se disputent un seul budget.

La marge qui reste pour votre prochain appel vaut :

remaining bytes = 65536 - (sum of body lengths of unfinished keepalive requests)

Imaginons un rapport d'erreur de 12 288 octets et un lot de clics de 8 192 octets, tous deux en vol. La marge vaut 65 536 moins 20 480, soit 45 056 octets. Un résumé de session de 50 000 octets pousse la somme à 70 480, donc fetch() renvoie une erreur réseau et sendBeacon() renvoie false. Regroupez chaque charge de suivi des événements dans un seul envoi et ce calcul cesse de mordre.

Quel Content-Type sendBeacon associe-t-il à chaque type de corps ?

sendBeacon ne vous laisse jamais définir Content-Type vous-même : le navigateur le déduit du type de corps que vous passez, et cette valeur décide si la requête reste en mode no-cors ou déclenche un preflight CORS. Le modèle de traitement de la spécification Beacon détaille l'embranchement :

If contentType is not null:

1. Set corsMode to "cors".
2. If contentType value is a CORS-safelisted request-header value for the Content-Type header, set corsMode to "no-cors".
3. Append a Content-Type header with value contentType to headerList.

Le standard Fetch définit le test de safelist pour cet en-tête : "If mimeType's essence is not application/x-www-form-urlencoded, multipart/form-data, or text/plain, then return false." Fetch fixe aussi le Content-Type que produit chaque type de corps :

La spécification Beacon énonce la conséquence : "If the request does not contain a payload, or the request Content-Type is a CORS-safelisted request-header, then the request mode is no-cors." Sinon, selon les termes de la spécification, "a CORS preflight is made and the server needs to first allow such requests by returning the appropriate set of CORS headers: Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers." Un preflight double les allers-retours sur une page qui est déjà en train de se décharger, alors envoyez le JSON sous forme de chaîne simple et parsez-le côté serveur.

Pourquoi un beacon doit-il se déclencher sur pagehide plutôt que sur unload ?

Déclenchez le beacon d'abord sur visibilitychange et ensuite sur pagehide, et laissez unload tranquille, parce que unload casse le cache avant/arrière. La page sendBeacon de MDN le dit sans détour : "the unload event is incompatible with the back/forward cache (bfcache) implemented in modern browsers. Some browsers, such as Firefox, handle this incompatibility by excluding pages from the bfcache if they contain unload handlers, thus hurting performance." MDN recommande pagehide comme repli pour les navigateurs sans visibilitychange : "Like beforeunload and unload, this event is not reliably fired, especially on mobile. However, it is compatible with the bfcache."

La spécification Beacon ajoute la raison mobile : "Developers should avoid relying on unload event because it will not fire whenever a page is in a background state (i.e. visibilityState equal to hidden) and the process is terminated by the mobile OS." L'arbitrage complet entre les événements de sortie se trouve dans beforeunload vs pagehide.

Comment écrire un appel sendBeacon qui survit au déchargement ?

Passez une chaîne simple, vérifiez le booléen renvoyé, et ne videz le tampon qu'une fois que le navigateur a accepté la file :

const endpoint = "https://collect.example.com/session";
const buffer = { sessionId: crypto.randomUUID(), events: [] };
 
function flush() {
  if (buffer.events.length === 0) return;
  const body = JSON.stringify(buffer);
  if (navigator.sendBeacon(endpoint, body)) {
    buffer.events.length = 0;
  }
}
 
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") flush();
});
 
window.addEventListener("pagehide", flush);

Le corps de type chaîne produit text/plain;charset=UTF-8, qui figure sur la safelist, donc le POST cross-origin saute le preflight. Un retour false signifie que la charge plus tout ce qui est en vol a dépassé 65 536 octets, et le tampon survit pour la tentative suivante.

Comment écrire le même appel avec fetch keepalive ?

Mettez keepalive: true, ajoutez les en-têtes que sendBeacon ne transportera pas, et acceptez que la promesse ne se résolve que si la page vit assez longtemps pour le voir :

window.addEventListener("pagehide", () => {
  fetch("https://collect.example.com/session", {
    method: "POST",
    keepalive: true,
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": apiKey,
    },
    body: JSON.stringify(buffer),
  }).catch(() => {});
});

Content-Type: application/json comme l'en-tête personnalisé X-Api-Key sortent de la safelist CORS, donc un appel cross-origin déclenche ici un preflight OPTIONS et exige Access-Control-Allow-Headers sur le serveur. Une restriction ne vaut que pour keepalive : l'algorithme extract-a-body du standard Fetch lève un TypeError pour un corps ReadableStream quand le drapeau est posé, donc le streaming à la sortie n'est pas une option. Ce moment de sortie explique pourquoi un script léger justifie sa place, et pourquoi le surcoût de performance du session replay apparaît à l'envoi, pas à l'enregistrement.

Lequel faut-il utiliser ?

Utilisez sendBeacon pour les analytics qu'on envoie et qu'on oublie, et fetch keepalive dès qu'un en-tête, une méthode ou la réponse compte.

Au-delà de 64 kibioctets, aucun des deux ne marche : échantillonnez la charge, découpez-la, ou déplacez l'agrégation vers le serveur, un choix traité dans analytics côté client et côté serveur.

Questions fréquentes

Une valeur de retour true de sendBeacon signifie-t-elle que le serveur a reçu les données ?

Non. La spécification Beacon dit qu'un retour true "implies the browser has queued the data for transfer" et que "since the actual data transfer happens asynchronously, this method does not provide any information whether the data transfer has succeeded or not." Un retour false est le seul autre signal, et il veut dire que la file a rejeté la charge.

Puis-je définir un en-tête Authorization sur sendBeacon ?

Non. La spécification Beacon indique que sendBeacon "does not provide ability to customize the request method, provide custom request headers, or change other processing properties of the request and response." Déplacez l'identifiant dans le chemin de l'URL, dans un cookie ou dans le corps, ou passez à fetch() avec keepalive: true.

Pourquoi mon Blob sendBeacon déclenche-t-il un preflight CORS ?

Parce que le type du Blob devient le Content-Type de la requête, et application/json ne figure pas sur la safelist CORS. Le standard Fetch limite cette safelist à application/x-www-form-urlencoded, multipart/form-data et text/plain, donc tout le reste force un preflight OPTIONS. Envoyez le JSON sous forme de chaîne et la requête reste en no-cors.

La limite de 64 KiB est-elle par requête ou par page ?

Par groupe de fetch, sur chaque requête keepalive inachevée qu'il contient. Le standard Fetch additionne le contentLength du nouveau corps et inflightKeepaliveBytes puis renvoie une erreur réseau au-delà de 64 kibioctets, donc un gros beacon encore en vol réduit la place pour le suivant.

Est-ce que fetch keepalive fonctionne dans un service worker ?

Oui. MDN cite la disponibilité dans les service workers comme un avantage de fetch() avec keepalive sur sendBeacon(), aux côtés des méthodes autres que POST, des propriétés de requête personnalisées et de l'accès à la réponse.

Qu'arrive-t-il à une requête keepalive si l'utilisateur ferme l'onglet immédiatement ?

Le navigateur garde la requête en vie au-delà du document qui l'a lancée, ce qui est l'objet du drapeau. Le standard Fetch décrit keepalive comme permettant "the request to outlive the environment settings object," et le plafond existe pour que ces requêtes survivantes "have a bounded size and are not allowed to stay alive indefinitely." Ce que vous perdez, c'est la réponse : la promesse n'a plus de page vivante où se résoudre.

sendBeacon peut-il utiliser une méthode autre que POST ?

sendBeacon n'envoie que des requêtes POST, comme le montre le tableau comparatif. fetch avec keepalive accepte n'importe quelle méthode, donc passez à fetch quand l'endpoint attend PUT, PATCH ou GET.

Pourquoi un corps en streaming échoue-t-il avec fetch keepalive ?

L'algorithme extract-a-body de la norme Fetch lève une TypeError pour un corps ReadableStream dès que keepalive est activé, un flux ne peut donc pas quitter la page au moment du départ. Sérialisez la charge avec JSON.stringify ou passez plutôt un corps de type chaîne.

Faut-il écouter pagehide et visibilitychange ensemble, ou choisir l'un des deux ?

Déclenchez d'abord sur visibilitychange, car cet événement capture le passage d'un onglet en arrière-plan avant que la page ne se décharge réellement, puis ajoutez pagehide comme repli pour les navigateurs où visibilitychange ne se déclenche pas de façon fiable. La fonction flush de l'exemple de l'article attache les deux écouteurs et laisse celui qui se déclenche en premier envoyer le beacon.

Que faire une fois que ma charge dépasse 64 KiB ?

Ni sendBeacon ni fetch keepalive ne peuvent transporter un corps au-delà de 65 536 octets ; la requête renvoie une erreur réseau ou un résultat false dès que le budget partagé est dépassé. Échantillonnez la charge, répartissez-la sur plusieurs envois ou déplacez l'agrégation vers le serveur.