Geofencing API

1518 |

1519 |

1. Introduction

1520 |

This section is non-normative.

1521 |

The Geofencing API lets webapps set up geographic boundaries around 1522 | specific locations and then receive notifications when the hosting device enters or leaves 1523 | those areas. While it would be possible to implement something similar using the 1524 | Geolocation API [GEOLOCATION-API], there are a few differences that could make this API 1525 | a better choice:

1526 |

1528 |
Because of the limited API surface of the Geofencing API, user 1529 | agents can implement the API in a more (power) efficient way than could be achieved by 1530 | regularly checking the current geographic position with the Geolocation API.
1531 |
1532 |
The Geofencing API is built around Service Workers. This makes it possible for a webapp to receive notifications from the Geofencing API even after the user has 1533 | closed the webapp.
1534 |

1535 |

1536 |

1.1. Examples

1537 |

The following code extracts illustrate how to use this API to be notified of geographic 1538 | regions being entered or left.

1539 |

1540 | Monitor a region: 1541 |

// https://example.com/webapp.js
1542 | navigator.serviceWorker
1543 |   .register('serviceworker.js')
1544 |   .then((swRegistration) => {
1545 |     let region = new CircularGeofenceRegion({
1546 |       name: 'myfence',
1547 |       latitude: 37.421999,
1548 |       longitude: -122.084015,
1549 |       radius: 1000
1550 |     });
1551 |     let options = {
1552 |       includePosition: true
1553 |     };
1554 |     swRegistration.geofencing.add(region, options)
1555 |       .then(
1556 |         // If more than just a name needs to be stored with a geofence, now
1557 |         // would be the time to store this in some storage.
1558 |         (geofence) => console.log(geofence.id),
1559 |         (error) => console.log(error)
1560 |       );
1561 | });

1562 |

1563 |

1564 | Respond to a region being entered: 1565 |

// https://example.com/serviceworker.js
1566 | self.ongeofenceenter = (event) => {
1567 |   console.log(event.geofence.id);
1568 |   console.log(event.geofence.region.name);
1569 | 
1570 |   // If this is not a geofence of interest anymore, remove it.
1571 |   if (event.geofence.region.name !== "myfence") {
1572 |     event.waitUntil(event.geofence.remove());
1573 |   }
1574 | };

1575 |

1576 |

1577 | Respond to an error condition: 1578 |

// https://example.com/serviceworker.js
1579 | self.ongeofenceerror = (event) => {
1580 |   console.log(event.geofence.id);
1581 |   console.log(event.geofence.region.name);
1582 |   console.log(event.error);
1583 | 
1584 |   // Some error condition occurred. The region is no longer monitored, and won’t
1585 |   // trigger any more events.
1586 | 
1587 |   // Try to re-monitor, although depending on the error this might fail.
1588 |   event
1589 |     .waitUntil(self.registration.geofencing.add(event.geofence.region))
1590 |     .then((geofence) => {
1591 |       // re-monitoring succeeded, new geofence will have a different ID.
1592 |     }, (error) => {
1593 |       // re-monitoring failed.
1594 |     });
1595 | };

1596 |

1597 |

1598 | Stop monitoring a region in response to some other event: 1599 |

// https://example.com/serviceworker.js
1600 | 
1601 | // Either look geofence up by name:
1602 | self.onsomeevent = (event) => {
1603 |   event
1604 |     .waitUntil(
1605 |       self.registration.geofencing.getAll({
1606 |         name: 'myfence'
1607 |       })
1608 |     )
1609 |     .then(
1610 |       geofences => geofences.forEach(fence => fence.remove())
1611 |     );
1612 | };
1613 | 
1614 | // Or look geofence up by ID:
1615 | self.onsomeotherevent = (event) => {
1616 |   let geofence_id = ''; /* somehow get the ID of a geofence */
1617 |   event
1618 |     .waitUntil(self.registration.geofencing.getById(geofence_id))
1619 |     .then(geofence => geofence.remove());
1620 | };

1621 |

1622 |

1623 |

1624 |

1625 |

2. Model

1626 |

The term webapp#webappReferenced in:1. Introduction (2) (3)3.1. 1627 | Privacy considerations for implementers of the Geofencing API 4.2. GeofenceManager interface (2) (3) refers to a Web application, i.e. an application implemented 1628 | using Web technologies, and executing within the context of a Web user agent, e.g. a 1629 | Web browser or other Web runtime environment.

1630 |

A service worker registration has an associated list of geofences#list-of-geofencesReferenced in:2. Model2.1. Implementation considerations (2)4.2. GeofenceManager interface (2) (3) (4)4.3. Geofence interface (2) whose element 1631 | type is a geofence.

1632 |

A geofence#geofence-termReferenced in:2. Model (2) (3) (4) (5) (6) (7) (8) (9) (10)3.1. 1633 | Privacy considerations for implementers of the Geofencing API (2) (3) (4)4.2. GeofenceManager interface (2) (3)4.3. Geofence interface (2) (3) (4) (5)4.6.1. 1634 | The geofenceenter and geofenceleave events 4.6.2. GeofenceErrorEvent is one specific registration of a geograhpic region as a geofence.

1635 |

A geofence has a name#geofence-nameReferenced in:2.1. Implementation considerations4.2. GeofenceManager interface (a string).

1636 |

A geofence has an associated geographic region.

1637 |

A geofence has a geofence ID#geofence-idReferenced in:4.2. GeofenceManager interface (2)4.3. Geofence interface, a string uniquely identifying it. This ID is 1638 | generated by the user agent and MUST be unique among all geofences associated with all service worker registrations at the 1639 | same origin. A user agent SHOULD NOT reuse the ID from an old geofence for a new 1640 | one.

1641 |

A geofence has an include position#include-positionReferenced in:4.2. GeofenceManager interface4.6.1. 1642 | The geofenceenter and geofenceleave events flag, a boolean indicating if events 1643 | associated with this geofence should include the exact geographic position.

1644 |

A geofence has an associated state#stateReferenced in:3.1. 1645 | Privacy considerations for implementers of the Geofencing API 4.2. GeofenceManager interface (2)4.3. Geofence interface4.6.2. GeofenceErrorEvent (2), which is one of active#activeReferenced in:2. Model3.1. 1646 | Privacy considerations for implementers of the Geofencing API 4.2. GeofenceManager interface4.6.2. GeofenceErrorEvent or inactive#inactiveReferenced in:4.2. GeofenceManager interface4.3. Geofence interface4.6.2. GeofenceErrorEvent.

1647 |

The user agent SHOULD be monitoring all active geofences for breach events.

1648 |

A geographic region#geographic-regionReferenced in:2. Model (2)4.2. GeofenceManager interface4.3. Geofence interface is a circular region defined by a geographic 1649 | coordinate representing the center of the region and a radius representing 1650 | the size of the region.

1651 |

The geographic coordinate#geographic-coordinateReferenced in:2. Model reference system used by the attributes in this API is 1652 | the World Geodetic System (2d) [WGS84]. No other reference system is supported.

1653 |

A geofence is said to be breached#breachedReferenced in:2. Model3.1. 1654 | Privacy considerations for implementers of the Geofencing API 4.2. GeofenceManager interface4.6.1. 1655 | The geofenceenter and geofenceleave events (2) (3) (4) (5) if the current geographical location 1656 | changed from being inside the geographic region to outside (a leave 1657 | event), or vice versa (an enter event).

1658 |

1659 |

2.1. Implementation considerations

1660 |

A user agent MAY impose limits#name-limitReferenced in:4.2. GeofenceManager interface on the maximum size of a geofence name. If a limit is imposed, this limit SHOULD allow for at least 100 characters.

1661 |

A user agent MAY impose limits#geofence-limitReferenced in:4.2. GeofenceManager interface on the total number of geofences that can be registered by a single origin. If a 1662 | limit is imposed, this limit SHOULD allow at least 20 geofences to be registered on a single origin.

1663 |

1664 |

1665 |

1666 |

3. Security and privacy considerations

1667 |

The same security and privacy 1668 | considerations that apply to the Geolocation API [GEOLOCATION-API] also apply to 1669 | this API. Furthermore since this API effectively gives access to geographic location 1670 | information after a user has stopped interacting with a webapp, a few other considerations 1671 | should be taken into account.

1672 |

1673 |

3.1. Privacy considerations for implementers of the Geofencing API

1674 |

User agents MUST NOT provide Geofencing API access to webapps without the express permission of the user. User agents MUST acquire consent for permission through a user 1675 | interface for each call to the add(initialRegion, options) method, unless a 1676 | previous permission grant has been persisted, or a prearranged trust relationship applies. 1677 | Permissions that are preserved beyond the current browsing session MUST be revocable.

1678 |

The user agent MAY consider the GeofenceRegion and/or the GeofenceOptions when 1679 | acquiring permission or determining the permission status.

1680 |

When a permission is revoked, all geofences added with that permission 1681 | MUST be deactivated.

1682 |

When permission is granted for unlimited use of the Geofencing API by a service worker 1683 | registration, the state of all associated geofences SHOULD 1684 | be set to active, and the user agent SHOULD start monitoring these geofences for breach events.

1685 |

When a service worker registration is unregistered, any associated geofences MUST be deactivated.

1686 |

User agents MUST allow access to the Geofencing API from secure contexts only.

1687 |

This should somehow mention how the [permissions] API is related to this.

1688 |

1689 |

1690 |

3.2. Privacy considerations for recipients of location information

1691 |

TODO

1692 |

1693 |

1694 |

3.3. Additional implementation considerations

1695 |

This section is non-normative.

1696 |

TODO

1697 |

1698 |

1699 |

1700 |

4. API Description

1701 |

1702 |

4.1. Extensions to the `ServiceWorkerRegistration` interface

1703 |

The Service Worker specification defines a ServiceWorkerRegistration interface, which 1704 | this specification extends.

1705 |

partial interface ServiceWorkerRegistration {
1706 |   readonly attribute GeofenceManager geofencing;
1707 | };
1708 |

1709 |

1710 |

1711 |

4.2. `GeofenceManager` interface

1712 |

The GeofenceManager interface defines operations that enable webapps to establish access to geofencing services.

1713 |

[NoInterfaceObject]
1714 | interface GeofenceManager#geofencemanagerReferenced in:4.1. 
1715 |       Extensions to the ServiceWorkerRegistration interface
1716 |     4.2. GeofenceManager interface (2) (3) (4) (5) {
1717 |   Promise<Geofence> add(GeofenceRegion initialRegion, optional GeofenceOptions options);
1718 |   Promise<sequence<Geofence>> getAll(optional GeofenceQueryOptions options);
1719 |   Promise<Geofence> getById(DOMString id);
1720 | };
1721 | 
1722 | dictionary GeofenceOptions#dictdef-geofenceoptionsReferenced in:3.1. 
1723 |       Privacy considerations for implementers of the Geofencing API
1724 |     4.2. GeofenceManager interface {
1725 |   boolean includePosition = false;
1726 | };
1727 | 
1728 | dictionary GeofenceQueryOptions#dictdef-geofencequeryoptionsReferenced in:4.2. GeofenceManager interface {
1729 |   DOMString? name;
1730 | };
1731 |

1732 |

A GeofenceManager has an associated service worker registration, represented by the ServiceWorkerRegistration instance on which the GeofenceManager was exposed.

1733 |

The add(initialRegion, options)#dom-geofencemanager-addReferenced in:3.1. 1734 | Privacy considerations for implementers of the Geofencing API 4.2. GeofenceManager interface method when invoked MUST return a new promise promise and run the following steps in parallel:

1735 |

Let serviceWorkerRegistration be the GeofenceManager's associated service worker registration. 1737 |
If initialRegion is not a CircularGeofenceRegion instance, reject promise with a TypeError. 1738 |
If the length of the name property of initialRegion exceeds a user agent defined limit, reject promise with a RangeError. 1739 |
If the latitude property of initialRegion is less than -90 or greater than 90, reject promise with a RangeError. 1740 |
If the longitude property of initialRegion is less 1741 | than -180 or greater than 180, reject promise with a RangeError. 1742 |
If the total number of geofences for all service worker registrations in the current origin 1743 | is more than the user agent defined limit, reject promise with a QuotaExceededError and terminate these substeps. 1744 |
Let geofence be a new geofence. 1745 |
Set the geofence ID of geofence to a newly generated value. 1746 |
Set the geographic region of geofence to a 1747 | the region represented by initialRegion. 1748 |
Set the include position flag of geofence to options.includePosition, or false if no options were 1749 | specified. 1750 |
Set the state of geofence to inactive. 1751 |
Add geofence to the list of geofences associated with serviceWorkerRegistration. 1752 |
Resolve promise with a new Geofence instance representing geofence. 1753 |
Ask the user whether they allow the webapp to monitor geofences, unless a 1754 | prearranged trust relationship applies or the user has already granted or denied 1755 | permission explicitly for this webapp to use this API. 1756 |
1757 | If permission is not granted, invoke the Handle Functional Event algorithm with serviceWorkerRegistration and the algorithm represented by 1758 | the following substeps as arguments. 1759 |
1. Let globalObject be the global object these steps are invoked with. 1761 |
2. Create a trusted event event that uses the GeofenceErrorEvent interface, with event type geofenceerror. 1762 |
3. Let the geofence atrribute of event be initialized to 1763 | a new Geofence instance representing geofence. 1764 |
4. Let the error attribute of event be initialized to PermissionDeniedError. 1765 |
5. Dispatch event at globalObject. 1766 |
1767 |
1768 | Else if permission is granted, run the following substeps: 1769 |
1. Set the state of geofence to active and start monitoring the 1771 | geofence for breach events. 1772 |
2. If the current geographic position is inside the newly added region, fire a geofenceenter event. 1773 |
1774 |

1775 |

Somehow mention that the region that is saved as part of the registration can be slightly 1776 | different from the region passed to register. An implementation may adjust parameters to 1777 | be in range of what is possible, or otherwise modify the region.

1778 |

If the includePosition#dom-geofenceoptions-includepositionReferenced in:4.2. GeofenceManager interface attribute is set to true, GeofenceEvents for this registration will have a position attribute. When set to false, the position attribute will always be undefined.

1779 |

The getAll(options)#dom-geofencemanager-getallReferenced in:4.2. GeofenceManager interface method when invoked MUST return a new promise promise and run the following steps in parallel:

1780 |

Let geofences be a new sequence. 1782 |
1783 | For each geofence geofence in the list of geofences associated 1784 | with this service worker registration, run the following substeps: 1785 |
1. If options is passed, has a non-null name attribute, 1787 | and that name is not equal to the name of the geofence, skip the rest of these substeps and continue with the next registration. 1788 |
2. Append a new Geofence instance representing geofence to geofences. 1789 |
1790 |
Resolve promise with geofences. 1791 |

1792 |

The getById(id)#dom-geofencemanager-getbyidReferenced in:4.2. GeofenceManager interface method when invoked MUST return a new promise promise and run the following 1793 | steps in parallel:

1794 |

1796 | For each geofence geofence in the list of geofences associated 1797 | with this service worker registration, run the following substeps: 1798 |
1. If the geofence ID of geofence is not equal to 1800 | the passed in id, skip the rest of these substeps and continue with 1801 | the next geofence. 1802 |
2. Resolve promise with a new Geofence instance representing geofence. 1803 |
1804 |
If promise was not resolved, resolve promise with null. 1805 |

1806 |

1807 |

1808 |

4.3. `Geofence` interface

1809 |

An instance of the Geofence interface represents a geofence.

1810 |

[Exposed=(Window,Worker)]
1811 | interface Geofence#geofenceReferenced in:4.2. GeofenceManager interface (2) (3) (4) (5) (6) (7)4.3. Geofence interface (2) (3)4.6.1. 
1812 |         The geofenceenter and geofenceleave events
1813 |        (2)4.6.2. GeofenceErrorEvent (2) {
1814 |   readonly attribute DOMString id;
1815 |   readonly attribute GeofenceRegion region;
1816 |   Promise<boolean> remove();
1817 | };
1818 |

1819 |

When getting the id#dom-geofence-idReferenced in:4.3. Geofence interface attribute, the user 1820 | agent MUST return the geofence ID of the geofence.

1821 |

When getting the region#dom-geofence-regionReferenced in:4.3. Geofence interface attribute, the user agent MUST return the geographic region of this geofence.

1822 |

The remove()#dom-geofence-removeReferenced in:4.3. Geofence interface method when invoked 1823 | MUST return a new promise promise and run the following steps in parallel:

1824 |

Let geofence be the geofence represented by this Geofence instance. 1826 |
If geofence is not currently in the list of geofences associated with a service worker registration, resolve promise with false and abort the remainder of these steps. 1827 |
Remove geofence from the list of geofences associated 1828 | with the current service worker registration. No more events related to this 1829 | geofence will be fired after this. 1830 |
Set the state of geofence to inactive, but do not trigger the steps 1831 | that are normally triggered when a geofence is deactivated. 1832 |
Resolve promise with true. 1833 |

1834 |

1835 |

1836 |

4.4. `GeofenceRegion` interface

1837 |

[Exposed=(Window,Worker)]
1838 | interface GeofenceRegion#geofenceregionReferenced in:3.1. 
1839 |       Privacy considerations for implementers of the Geofencing API
1840 |     4.2. GeofenceManager interface4.3. Geofence interface4.4. GeofenceRegion interface4.5. CircularGeofenceRegion interface {
1841 |   readonly attribute DOMString name;
1842 | };
1843 | 
1844 | dictionary GeofenceRegionInit#dictdef-geofenceregioninitReferenced in:4.4. GeofenceRegion interface4.5. CircularGeofenceRegion interface {
1845 |   DOMString? name#dom-geofenceregioninit-nameReferenced in:4.4. GeofenceRegion interface;
1846 | };
1847 |

1848 |

The name#dom-geofenceregion-nameReferenced in:4.2. GeofenceManager interface4.4. GeofenceRegion interface attribute MUST return 1849 | the value it was initialized to. When the object is created, this attribute MUST be set to the 1850 | value of the name property in the GeofenceRegionInit dictionary, or 1851 | an empty string if that property wasn’t set.

1852 |

1853 |

1854 |

4.5. `CircularGeofenceRegion` interface

1855 |

[Constructor(CircularGeofenceRegionInit init), Exposed=(Window,Worker)]
1856 | interface CircularGeofenceRegion#circulargeofenceregionReferenced in:4.2. GeofenceManager interface4.5. CircularGeofenceRegion interface (2) : GeofenceRegion {
1857 |   readonly attribute double latitude;
1858 |   readonly attribute double longitude;
1859 |   readonly attribute double radius;
1860 | };
1861 | 
1862 | dictionary CircularGeofenceRegionInit#dictdef-circulargeofenceregioninitReferenced in:4.5. CircularGeofenceRegion interface : GeofenceRegionInit {
1863 |   double latitude;
1864 |   double longitude;
1865 |   double radius;
1866 | };
1867 |

1868 |

The CircularGeofenceRegion constructor when invoked MUST initialize the properties of the 1869 | newly created object to the corresponding attributes in the initializer.

1870 |

The latitude#dom-circulargeofenceregion-latitudeReferenced in:4.2. GeofenceManager interface4.5. CircularGeofenceRegion interface attribute 1871 | MUST return the value it was intialized to. This value represents the latitude in 1872 | circular degrees of the center of the circular region.

1873 |

The longitude#dom-circulargeofenceregion-longitudeReferenced in:4.2. GeofenceManager interface4.5. CircularGeofenceRegion interface attribute MUST return the value it was intialized to. This value represents the longitude 1874 | in circular degrees of the center of the circular region.

1875 |

The radius#dom-circulargeofenceregion-radiusReferenced in:4.5. CircularGeofenceRegion interface attribute MUST 1876 | return thev value it was initialized to. This value represents the radius in meters of the 1877 | circular region.

1878 |

1879 |

1880 |

4.6. Events

1881 |

The Service Worker specification defines a ServiceWorkerGlobalScope interface, which this 1882 | specification extends.

1883 |

partial interface ServiceWorkerGlobalScope {
1884 |   attribute EventHandler ongeofenceenter;
1885 |   attribute EventHandler ongeofenceleave;
1886 |   attribute EventHandler ongeofenceerror;
1887 | };
1888 |

1889 |

The ongeofenceenter#dom-serviceworkerglobalscope-ongeofenceenterReferenced in:4.6. Events attribute is 1890 | an event handler whose corresponding event handler event type is geofenceenter#geofenceenterReferenced in:4.6.1. 1891 | The geofenceenter and geofenceleave events.

1892 |

The ongeofenceleave#dom-serviceworkerglobalscope-ongeofenceleaveReferenced in:4.6. Events attribute is 1893 | an event handler whose corresponding event handler event type is geofenceleave#geofenceleaveReferenced in:4.6.1. 1894 | The geofenceenter and geofenceleave events.

1895 |

The ongeofenceerror#dom-serviceworkerglobalscope-ongeofenceerrorReferenced in:4.6. Events attribute is 1896 | an event handler whose corresponding event handler event type is geofenceerror#geofenceerrorReferenced in:4.2. GeofenceManager interface4.6.2. GeofenceErrorEvent.

1897 |

1898 |

4.6.1. The `geofenceenter` and `geofenceleave` events

1899 |

The GeofenceEvent interface represents a geofence being breached.

1900 |

[Exposed=ServiceWorker]
1901 | interface GeofenceEvent#geofenceeventReferenced in:4.2. GeofenceManager interface4.6.1. 
1902 |         The geofenceenter and geofenceleave events
1903 |        (2) : ExtendableEvent {
1904 |   readonly attribute Geofence geofence#dom-geofenceevent-geofenceReferenced in:4.6.1. 
1905 |         The geofenceenter and geofenceleave events
1906 |       ;
1907 |   readonly attribute Position? position#dom-geofenceevent-positionReferenced in:4.2. GeofenceManager interface (2)4.6.1. 
1908 |         The geofenceenter and geofenceleave events
1909 |       ;
1910 | };
1911 |

1912 |

Upon detecting a breach of a geofence geofence, 1913 | the user agent MUST run the following steps to fire a geofence event#fire-a-geofence-eventReferenced in:4.2. GeofenceManager interface4.6.1. 1914 | The geofenceenter and geofenceleave events :

1915 |

Let serviceWorkerRegistration be the service worker registration geofence is associated with. 1917 |
1918 | Invoke the Handle Functional Event algorithm with serviceWorkerRegistration and the algorithm represented by the following substeps as arguments. 1919 |
1. Let globalObject be the global object these steps are invoked with. 1921 |
2. Let eventType be geofenceenter or geofenceleave, corresponding to the type of breach event being processed. 1922 |
3. Create a trusted event event that uses the GeofenceEvent interface, with event type equal to eventType. 1923 |
4. Let the geofence atrribute of event be initialized to 1924 | a new Geofence instance representing geofence. 1925 |
5. If the include position flag of geofence is true, set the position attribute of event to the current geographical 1926 | position. 1927 |
6. Dispatch event at globalObject. 1928 |
1929 |

1930 |

The user agent MAY delay firing a geofence 1931 | event until some time and/or distance has passed after the breach was detected to make sure that the geofence really was breached.

1932 |

1933 |

1934 |

4.6.2. `GeofenceErrorEvent`

1935 |

[Exposed=ServiceWorker]
1936 | interface GeofenceErrorEvent#geofenceerroreventReferenced in:4.2. GeofenceManager interface4.6.2. GeofenceErrorEvent (2) : ExtendableEvent {
1937 |   readonly attribute Geofence geofence#dom-geofenceerrorevent-geofenceReferenced in:4.2. GeofenceManager interface4.6.2. GeofenceErrorEvent;
1938 |   readonly attribute DOMString error#dom-geofenceerrorevent-errorReferenced in:4.2. GeofenceManager interface4.6.2. GeofenceErrorEvent;
1939 |   readonly attribute DOMString message#dom-geofenceerrorevent-messageReferenced in:4.6.2. GeofenceErrorEvent;
1940 | };
1941 |

1942 |

When a geofence geofence is deactivated#deactivatedReferenced in:3.1. 1943 | Privacy considerations for implementers of the Geofencing API (2)4.3. Geofence interface, the user agent SHOULD run the following steps:

1944 |

Let serviceWorkerRegistration be the service worker registration geofence is associated with. 1946 |
Let oldState be the state of geofence. 1947 |
Set the state of geofence to inactive. 1948 |
1949 | If oldState is active, invoke the Handle Functional Event algorithm with serviceWorkerRegistration and the algorithm represented by 1950 | the following substeps as arguments. 1951 |
1. Let globalObject be the global object these steps are invoked with. 1953 |
2. Create a trusted event event that uses the GeofenceErrorEvent interface, with event type geofenceerror. 1954 |
3. Let the geofence atrribute of event be initialized to 1955 | a new Geofence instance representing geofence. 1956 |
4. Let the error attribute of event be initialized to 1957 | an error name. 1958 |
5. Let the message attribute of event be initialized to 1959 | a descriptive message for the error that occurred. 1960 |
6. Dispatch event at globalObject. 1961 |
1962 |

1963 |

1964 |

1965 |

1966 |

1967 |

5. Exceptions

1968 |

The Geofencing API uses the new PermissionDeniedError DOMException name.

1969 |

1970 |

Conformance

Document conventions

Conformance requirements are expressed with a combination of 1977 | descriptive assertions and RFC 2119 terminology. The key words “MUST”, 1978 | “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, 1979 | “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this 1980 | document are to be interpreted as described in RFC 2119. 1981 | However, for readability, these words do not appear in all uppercase 1982 | letters in this specification.

All of the text of this specification is normative except sections 1984 | explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” 1986 | or are set apart from the normative text with class="example", 1987 | like this:

Informative notes begin with the word “Note” and are set apart from the 1993 | normative text with class="note", like this:

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as 1997 | "strip any leading space characters" or "return false and abort these 1998 | steps") are to be interpreted with the meaning of the key word ("must", 1999 | "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be 2001 | implemented in any manner, so long as the end result is equivalent. In 2002 | particular, the algorithms defined in this specification are intended to 2003 | be easy to understand and are not intended to be performant. Implementers 2004 | are encouraged to optimize.

Introduction

Examples

Model

Implementation considerations

Security and privacy considerations

270 | Privacy considerations for implementers of the Geofencing API 271 |

303 | Privacy considerations for recipients of location information 304 |

311 | Additional implementation considerations 312 |

API Description

325 | Extensions to the {{ServiceWorkerRegistration}} interface 326 |

{{GeofenceManager}} interface

{{Geofence}} interface

{{GeofenceRegion}} interface

{{CircularGeofenceRegion}} interface

Events

655 | The geofenceenter and geofenceleave events 656 |

{{GeofenceErrorEvent}}

Exceptions

Geofencing API

Editor’s Draft, 11 May 2016

Abstract

Status of this document

1. Introduction

1.1. Examples

2. Model

2.1. Implementation considerations

3. Security and privacy considerations

3.1. Privacy considerations for implementers of the Geofencing API

3.2. Privacy considerations for recipients of location information

3.3. Additional implementation considerations

4. API Description

4.1. Extensions to the ServiceWorkerRegistration interface

4.2. GeofenceManager interface

4.3. Geofence interface

4.4. GeofenceRegion interface

4.5. CircularGeofenceRegion interface

4.6. Events

4.6.1. The geofenceenter and geofenceleave events

4.6.2. GeofenceErrorEvent

5. Exceptions

Conformance

Document conventions

Conformant Algorithms

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Issues Index

655 | The `geofenceenter` and `geofenceleave` events 656 |