doImportantThing is a developer-defined function.
function sendChatMessage(message) { +function sendChatMessage(message) { return addChatMessageToOutbox(message).then(() => { // Wait for the scoped service worker registration to get a // service worker with an active state @@ -1483,10 +1496,11 @@+} +}).catch(() => { console.log('Sync registration failed :('); }); -}
In the above example addChatMessageToOutbox is a developer-defined function.
Reacting to a sync event within a service worker:
-self.addEventListener('sync', event => { +self.addEventListener('sync', event => { if (event.tag == 'send-chats') { event.waitUntil( getMessagesFromOutbox().then(messages => { @@ -1507,21 +1521,22 @@+}); +}) ); } -});
In the above example getMessagesFromOutbox and removeMessagesFromOutbox are developer-defined functions.
The sync event is considered to run in the background#in-the-backgroundReferenced in:1. Introduction4.2. Location Tracking4.3. History Leaking if no service worker clients whose frame type is top-level or auxiliary exist for the origin of the corresponding service worker registration.
-The user agent is considered to be online#onlineReferenced in:2. Concepts5.2. SyncManager interface (2)5.3. The sync event (2) (3) (4) if the user agent has established a network connection. A user agent MAY use a stricter definition of being online. Such a stricter definition MAY take into account the particular service worker or origin a sync registration is associated with.
+The sync event is considered to run in the background if no service worker clients whose frame type is top-level or auxiliary exist for the origin of the corresponding service worker registration.
+The user agent is considered to be online if the user agent has established a network connection. A user agent MAY use a stricter definition of being online. Such a stricter definition MAY take into account the particular service worker or origin a sync registration is associated with.
A sync registration#sync-registrationReferenced in:2. Concepts3. Constructs (2) (3) (4) (5)5.2. SyncManager interface (2)5.3. The sync event (2) is a tuple consisting of a tag and a state.
-A sync registration has an associated tag#tagReferenced in:3. Constructs (2)5.2. SyncManager interface (2) (3)5.3. The sync event, a DOMString.
-A sync registration has an associated registration state#registration-stateReferenced in:3. Constructs5.2. SyncManager interface (2) (3) (4) (5)5.3. The sync event (2) (3) (4) (5) (6) (7), which is one of pending#pendingReferenced in:3. Constructs5.2. SyncManager interface (2)5.3. The sync event (2) (3) (4) (5), waiting#waitingReferenced in:5.2. SyncManager interface5.3. The sync event (2), firing#firingReferenced in:5.2. SyncManager interface5.3. The sync event (2), or reregisteredWhileFiring#reregisteredwhilefiringReferenced in:5.2. SyncManager interface5.3. The sync event (2). It is initially set to pending.
+ A service worker registration has an associated list of sync registrations whose element type is a sync registration. +A sync registration is a tuple consisting of a tag and a state.
+A sync registration has an associated tag, a DOMString.
+A sync registration has an associated registration state, which is one of pending, waiting, firing, or reregisteredWhileFiring. It is initially set to pending.
A sync registration has an associated service worker registration. It is initially set to null.
Within one list of sync registrations each sync registration MUST have a unique tag.
ServiceWorkerRegistration interfacepartial interface ServiceWorkerRegistration { - readonly attribute SyncManager sync; +partial interface ServiceWorkerRegistration { + readonly attribute SyncManager sync; };The
syncattribute exposes aSyncManager, which has an associated service worker registration represented by theServiceWorkerRegistrationon which the attribute is exposed.
SyncManager interface[Exposed=(Window,Worker)] -interface SyncManager#syncmanagerReferenced in:5.1. Extensions to the ServiceWorkerRegistration interface (2)5.2. SyncManager interface (2) (3) { - Promise<void> register(DOMString tag); - Promise<sequence<DOMString>> getTags(); +[Exposed=(Window,Worker)] +interface SyncManager { + Promise<void> register(DOMString tag); + Promise<sequence<DOMString>> getTags(); };-The
+register(tag)#dom-syncmanager-registerReferenced in:5.2. SyncManager interfacemethod, when invoked, MUST return a new promise promise and run the following steps in parallel:The
register(tag)method, when invoked, MUST return a new promise promise and run the following steps in parallel:-
- Let serviceWorkerRegistration be the
SyncManager's associated service worker registration.- @@ -1598,7 +1613,7 @@
If the user agent is currently online, fire a sync event for newRegistration.
The
+getTags()#dom-syncmanager-gettagsReferenced in:5.2. SyncManager interfacemethod when invoked, MUST return a new promise promise and run the following steps in parallel:The
getTags()method when invoked, MUST return a new promise promise and run the following steps in parallel:
- Let serviceWorkerRegistration be the
SyncManager's associated service worker registration.- Let currentTags be a new
sequence. @@ -1607,26 +1622,26 @@
partial interface ServiceWorkerGlobalScope { - attribute EventHandler onsync; +5.3. The sync event
+partial interface ServiceWorkerGlobalScope { + attribute EventHandler onsync; }; -[Constructor(DOMString type, SyncEventInit init), Exposed=ServiceWorker] -interface SyncEvent#synceventReferenced in:5.3. The sync event (2) (3) : ExtendableEvent { - readonly attribute DOMString tag#dom-syncevent-tagReferenced in:5.3. The sync event; - readonly attribute boolean lastChance#dom-syncevent-lastchanceReferenced in:5.3. The sync event (2) (3) (4) (5) (6); +[Constructor(DOMString type, SyncEventInit init), Exposed=ServiceWorker] +interface SyncEvent : ExtendableEvent { + readonly attribute DOMString tag; + readonly attribute boolean lastChance; }; -dictionary SyncEventInit#dictdef-synceventinitReferenced in:5.3. The sync event : ExtendableEventInit { - required DOMString tag; - boolean lastChance = false; +dictionary SyncEventInit : ExtendableEventInit { + required DOMString tag; + boolean lastChance = false; };-Note: The
+SyncEventinterface 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 at the soonest convenience. If a sync event fails, the user agent may decide to retry it at a time of its choosing. ThelastChanceattribute is true if the user agent will not make further attempts to try this sync after the current attempt.Note: The
SyncEventinterface 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. ThelastChanceattribute is true if the user agent will not make further attempts to try this sync after the current attempt.Reacting to-lastChance: -self.addEventListener('sync', event => { +self.addEventListener('sync', event => { if (event.tag == 'important-thing') { event.waitUntil( doImportantThing().catch(err => { @@ -1637,12 +1652,13 @@+}); +}) ); } -});
The above example reacts to
lastChanceby showing a notification to the user. This requires the origin to have permission to show notifications.In the above example
doImportantThingis a developer-defined function.Whenever the user agent changes to online, the user agent SHOULD fire a sync event for each sync registration whose registration state is pending.
-To fire a sync event#fire-a-sync-eventReferenced in:5.2. SyncManager interface (2)5.3. The sync event (2) (3) (4) for a sync registration registration, the user agent MUST run the following steps:
+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:
- Assert: registration’s registration state is pending.
- Let serviceWorkerRegistration be the service worker registration associated with registration. @@ -1651,7 +1667,7 @@
Invoke the Handle Functional Event algorithm with registration and the following substeps as arguments.
-
- Let globalObject be the global object these steps are called with. +
- Let globalObject be the global object these steps are called with.
- Create a trusted event e that uses the
SyncEventinterface, with the event type sync, which does not bubble and has no default action.- Let the
tagattribute of e be initialized to the tag associated with registration.- Let the
lastChanceattribute of e be initialized to 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. @@ -1693,7 +1709,7 @@
A user agent MAY impose a time limit on the lifetime extension and execution time of a
-SyncEventwhich is stricter than the time limit imposed forExtendableEvents in general. In particular an event for whichlastChanceis true MAY have a significantly shortened time limit.A user agent will retry#will-retryReferenced in:5.3. The sync event a sync event based on some user agent defined heuristics.
+A user agent will retry a sync event based on some user agent defined heuristics.
partial interface ServiceWorkerRegistration { - readonly attribute SyncManager sync; +partial interface ServiceWorkerRegistration { + readonly attribute SyncManager sync; }; -[Exposed=(Window,Worker)] -interface SyncManager { - Promise<void> register(DOMString tag); - Promise<sequence<DOMString>> getTags(); +[Exposed=(Window,Worker)] +interface SyncManager { + Promise<void> register(DOMString tag); + Promise<sequence<DOMString>> getTags(); }; -partial interface ServiceWorkerGlobalScope { - attribute EventHandler onsync; +partial interface ServiceWorkerGlobalScope { + attribute EventHandler onsync; }; -[Constructor(DOMString type, SyncEventInit init), Exposed=ServiceWorker] -interface SyncEvent : ExtendableEvent { - readonly attribute DOMString tag; - readonly attribute boolean lastChance; +[Constructor(DOMString type, SyncEventInit init), Exposed=ServiceWorker] +interface SyncEvent : ExtendableEvent { + readonly attribute DOMString tag; + readonly attribute boolean lastChance; }; -dictionary SyncEventInit : ExtendableEventInit { - required DOMString tag; - boolean lastChance = false; +dictionary SyncEventInit : ExtendableEventInit { + required DOMString tag; + boolean lastChance = false; };-