Skip to content

API in Service Worker

Background Sync API

Published Updated

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)WICG draft

The Background Sync API lets a page register a named sync on its service worker registration; when the browser decides the device has connectivity, it fires a sync event in the service worker, even if the page that registered it has since closed. It is a Chromium feature (Chrome 49, Edge 79, Samsung Internet 5.0) and is not implemented in Firefox or Safari (BCD api.SyncManager), so provide a fallback for retries in those browsers.

Flow diagram of background sync: a request fails offline, the page queues it in IndexedDB and calls sync.register('outbox'); the browser holds the tag until connectivity returns, then fires the sync event in the service worker, which replays the queue inside event.waitUntil(). A resolved promise clears the registration, a rejection with lastChance false is retried later with backoff, and a rejection with lastChance true ends the retries.
Background sync: queue, register, replay on the sync event, and the three ways the promise can settle.
// In the page or in the service worker (needs a window client in Chromium)
const registration = await navigator.serviceWorker.ready;
await registration.sync.register(tag);
const tags = await registration.sync.getTags();
// In the service worker
self.addEventListener('sync', (event) => {
event.waitUntil(doWork(event.tag, event.lastChance));
});

register() returns a Promise<void> that fulfils once the registration is stored. Registering a tag that is already pending is a no-op, not an error, so a page may call it on every failed request without bookkeeping. getTags() returns a Promise<string[]> of tags that have not yet fired successfully.

The method takes one string argument; the event exposes two read-only attributes.

Name Type Description
tag string Identifies the registration. One pending registration exists per tag; the same tag is delivered as SyncEvent.tag. Chromium limits the tag to 10,240 characters.
SyncEvent.tag string The tag the browser is firing for. Branch on it when one worker handles several queues.
SyncEvent.lastChance boolean true when the browser will not retry this registration again if the waitUntil() promise rejects. Use it to surface the failure to the user instead of retrying.

register() rejects rather than throwing synchronously.

Exception Condition
InvalidStateError the registration has no active service worker yet. Awaiting navigator.serviceWorker.ready before calling register() avoids it (spec, “register(tag)” step 3).
InvalidAccessError in Chromium, register() was called from a service worker that has no window client, or the tag exceeds the length limit. Chromium’s message is Attempted to register a sync event without a window or registration tag too long..
NotAllowedError the “Background sync” site permission is blocked. Chromium exposes it at chrome://settings/content/backgroundSync and in the per-site permission panel; the rejection message is Permission denied..
TypeError registration.sync is undefined in Firefox and Safari, so registration.sync.register() throws before any promise exists. Feature-detect with 'sync' in registration.

A rejected waitUntil() promise is not an exception on the page: the browser schedules a retry (Chromium: up to three attempts, five minutes before the second, with a backoff factor of three) and sets lastChance to true on the final one.

Both examples assume a registered service worker at /sw.js whose scope covers the page.

Queueing a failed POST and replaying it on sync

Section titled “Queueing a failed POST and replaying it on sync”

The page writes the outgoing request to IndexedDB (here a minimal idb-keyval-style helper is assumed) and registers the tag; the worker drains the queue when the event fires. Keep the queue in storage, not in a worker variable: the browser may terminate the worker between the failed request and the sync event.

page.js
async function sendOrQueue(payload) {
try {
await fetch('/api/messages', { method: 'POST', body: JSON.stringify(payload) });
} catch {
await outbox.add(payload); // IndexedDB-backed queue
const registration = await navigator.serviceWorker.ready;
await registration.sync.register('outbox');
}
}
// sw.js
self.addEventListener('sync', (event) => {
if (event.tag !== 'outbox') return;
event.waitUntil(drainOutbox(event.lastChance));
});
async function drainOutbox(lastChance) {
for (const item of await outbox.all()) {
const response = await fetch('/api/messages', { method: 'POST', body: JSON.stringify(item.payload) });
if (!response.ok && !lastChance) throw new Error(`replay failed: ${response.status}`);
await outbox.remove(item.id);
}
}

Throwing inside drainOutbox() rejects the waitUntil() promise, which is what asks the browser for a retry. On the lastChance pass the code above stops throwing and clears the queue so the registration ends; a production app would mark those items as failed and show them to the user on the next launch.

Firefox and Safari expose no sync property on the registration. The fallback below retries once on the online event, which every browser fires, and otherwise leaves the item for the next page load.

async function deferOrRetry(tag, retryNow) {
const registration = await navigator.serviceWorker.ready;
if ('sync' in registration) {
return registration.sync.register(tag);
}
// No Background Sync: retry as soon as the page sees the network return.
window.addEventListener('online', () => retryNow(), { once: true });
}

The fallback only runs while the page is open; Background Sync can also run after it closes. Tell users when the fallback will send: “your message will send next time you open the app”.

Specifications

SpecificationStatus
Background SyncWICG draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes49highsource—
Chrome (Android)#Yes49highsource1
Edge (Desktop)#Yes79highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#Yes5.0highsource9
WebView (Android)#No—highsource10
  1. Derived by browser-compat-data mirroring from Chrome.
  2. Derived by browser-compat-data mirroring from Chrome.
  3. No Firefox support is recorded in browser-compat-data.
  4. No Firefox for Android support is recorded in browser-compat-data.
  5. Derived by browser-compat-data mirroring from Firefox.
  6. Implementation tracking: https://webkit.org/b/182565.
  7. Implementation tracking: https://webkit.org/b/182565.
  8. Derived by browser-compat-data mirroring from Safari.
  9. Derived by browser-compat-data mirroring from Chrome Android.
  10. Implementation tracking: https://crbug.com/40449796.

Source data: /compatibility/background-sync.json · Global usage: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)