Web Background Synchronization

5.1. Permission

Note: Background sync SHOULD be enabled by default. Having the permission denied is considered an exceptional case.

5.2. Location Tracking

5.3. History Leaking

6.1. Extensions to the ServiceWorkerRegistration interface

partial interface ServiceWorkerRegistration {
  readonly attribute SyncManager sync;
};

The sync attribute exposes a SyncManager, which has an associated service worker registration represented by the ServiceWorkerRegistration on which the attribute is exposed.

6.2. SyncManager interface

[Exposed=(Window,Worker)]
interface SyncManager {
  Promise<undefined> register(DOMString tag);
  Promise<sequence<DOMString>> getTags();
};

The register(tag) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

1. Let serviceWorkerRegistration be the SyncManager's associated service worker registration.
2. If serviceWorkerRegistration’s active worker is null, reject promise with an InvalidStateError and abort these steps.
3. If the user has disabled background sync, reject promise with an NotAllowedError and abort these steps.
4. Let isBackground be true.
5. For each client in the service worker clients for the serviceWorkerRegistration’s origin:
   1. If client’s frame type is top-level or auxiliary, set isBackground to false.
6. If isBackground is true, reject promise with an InvalidAccessError and abort these steps.
7. Let currentRegistration be the registration in serviceWorkerRegistration’s list of sync registrations whose tag equals tag if it exists, else null.
8. If currentRegistration is not null:
   1. If currentRegistration’s registration state is waiting, set currentRegistration’s registration state to pending.
   2. If currentRegistration’s registration state is firing, set currentRegistration’s registration state to reregisteredWhileFiring.
   3. Resolve promise.
   4. If the user agent is currently online and currentRegistration’s registration state is pending, fire a sync event for currentRegistration.
9. Else:
   1. Let newRegistration be a new sync registration.
   2. Set newRegistration’s associated tag to tag.
   3. Set newRegistration’s associated service worker registration to serviceWorkerRegistration.
   4. Add newRegistration to serviceWorkerRegistration’s list of sync registrations.
   5. Resolve promise.
   6. If the user agent is currently online, fire a sync event for newRegistration.

The getTags() method when invoked, MUST return a new promise promise and run the following steps in parallel:

1. Let serviceWorkerRegistration be the SyncManager's associated service worker registration.
2. Let currentTags be a new sequence.
3. For each registration in serviceWorkerRegistration’s list of sync registrations, add registration’s associated tag to currentTags.
4. Resolve promise with currentTags.

6.3. The sync event

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onsync;
};

[Exposed=ServiceWorker]
interface SyncEvent : ExtendableEvent {
  constructor(DOMString type, SyncEventInit init);
  readonly attribute DOMString tag;
  readonly attribute boolean lastChance;
};

dictionary SyncEventInit : ExtendableEventInit {
  required DOMString tag;
  boolean lastChance = false;
};

Note: The SyncEvent interface represents a firing sync registration. If the page (or worker) that registered the event is running, the user agent will fire the sync event as soon as network connectivity is available. Otherwise, the user agent should run the event at the soonest convenience. If a sync event fails, the user agent may decide to retry it at a time of its choosing. The lastChance attribute is true if the user agent will not make further attempts to try this sync after the current attempt.

self.addEventListener('sync', event => {
  if (event.tag == 'important-thing') {
    event.waitUntil(
      doImportantThing().catch(err => {
        if (event.lastChance) {
          self.registration.showNotification("Important thing failed");
        }
        throw err;
      })
    );
  }
});

Whenever the user agent changes to online, the user agent SHOULD fire a sync event for each sync registration whose registration state is pending. The events may be fired in any order.

To fire a sync event for a sync registration registration, the user agent MUST run the following steps:

1. Assert: registration’s registration state is pending.
2. Let serviceWorkerRegistration be the service worker registration associated with registration.
3. Assert: registration exists in the list of sync registrations associated with serviceWorkerRegistration.
4. Set registration’s registration state to firing.

5. Fire Functional Event "sync" using SyncEvent on serviceWorkerRegistration with the following properties:

   ⚠MDN

   SyncEvent/tag

   In only one current engine.

   FirefoxNoneSafariNoneChrome49+

   ---

   Opera?Edge79+

   ---

   Edge (Legacy)NoneIENone

   ---

   Firefox for AndroidNoneiOS SafariNoneChrome for Android49+Android WebViewNoneSamsung Internet5.0+Opera Mobile?

   tag

   The tag associated with registration

   ⚠MDN

   SyncEvent/lastChance

   In only one current engine.

   FirefoxNoneSafariNoneChrome49+

   ---

   Opera?Edge79+

   ---

   Edge (Legacy)NoneIENone

   ---

   Firefox for AndroidNoneiOS SafariNoneChrome for Android49+Android WebViewNoneSamsung Internet5.0+Opera Mobile?

   lastChance

   False if the user agent will retry this sync event if it fails, or true if no further attempts will be made after the current attempt.

   Then run the following steps with dispatchedEvent:

   1. Let waitUntilPromise be the result of waiting for all of dispatchedEvent’s extended lifetime promises.
   2. Upon fulfillment of waitUntilPromise, perform the following steps atomically:
      1. If registration’s state is reregisteredWhileFiring:
         1. Set registration’s state to pending.
         2. If the user agent is currently online, fire a sync event for registration.
         3. Abort the rest of these steps.
      2. Assert: registration’s registration state is firing.
      3. Remove registration from serviceWorkerRegistration’s list of sync registration.
   3. Upon rejection of waitUntilPromise, or if the script has been aborted by the termination of the service worker, perform the following steps atomically:
      1. If registration’s state is reregisteredWhileFiring:
         1. Set registration’s state to pending.
         2. If the user agent is currently online, fire a sync event for registration.
         3. Abort the rest of these steps.
      2. If the lastChance attribute of dispatchedEvent is false, set registration’s registration state to waiting, and perform the following steps in parallel:
         1. Wait a user agent defined length of time.
         2. If registration’s registration state is not waiting, abort these substeps.
         3. Set registration’s registration state to pending.
         4. If the user agent is currently online, fire a sync event for registration.
      3. Else remove registration from serviceWorkerRegistration’s list of sync registrations.

A user agent MAY impose a time limit on the lifetime extension and execution time of a SyncEvent which is stricter than the time limit imposed for ExtendableEvents in general. In particular an event for which lastChance is true MAY have a significantly shortened time limit.

A user agent will retry a sync event based on some user agent defined heuristics.