-
Notifications
You must be signed in to change notification settings - Fork 17
/
Copy pathindex.bs
163 lines (126 loc) · 6.27 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<pre class='metadata'>
Title: Device Memory
Shortname: device-memory
Level: 1
Group: webperf
Status: ED
ED: https://www.w3.org/TR/device-memory/
TR: https://www.w3.org/TR/device-memory/
Editor: Shubhie Panicker, Google https://google.com, [email protected], w3cid 92587
Repository: w3c/device-memory
Abstract: This document defines a HTTP Client Hint header to surface device capability for memory i.e. device RAM, in order to enable web apps to customize content depending on device memory constraints.
Required IDs: sec-device-memory-client-hint-header
Default Highlight: js
</pre>
<pre class=biblio>
{
"CLIENT-HINTS": {
"authors": [
"Ilya Grigorik",
"Yoav Weiss"
],
"href": "https://httpwg.org/http-extensions/client-hints.html",
"publisher": "IETF HTTP-WG",
"title": "Client Hints",
"status": "ID"
},
"I-D.ietf-httpbis-header-structure": {
"authors": [ "Mark Nottingham", "Poul-Henning Kamp" ],
"href": "https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html",
"title": "Structured Field Values for HTTP",
"status": "ID",
"publisher": "IETF HTTP-WG"
}
}
</pre>
<pre class="anchors">
urlPrefix: https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html; spec: I-D.ietf-httpbis-header-structure
type: dfn
text: structured header value; url: #
for: structured header value
type: dfn
text: decimal; url: #name-decimals
text: item; url: #name-items
</pre>
Introduction {#intro}
=====================
Developers need device-class signal for:
1. Serving light version of the site or specific components, for low-end devices. Egs:
* Serve Google "search lite" - a 10KB search results page used in EM.
* Serve a light version of video player in Facebook.
* Serve lightweight tile images in Google Maps.
2. Normalizing Metrics: analytics need to be able to normalize their metrics against the device-class. For instance, a 100ms long task on a high end device is a more severe issue compared to a low-end device.
Device memory is an especially useful signal for determining “device-class”. Low memory devices devices (under 512MB, 512MB - 1GB) are widely used in emerging markets.
Usage Example {#example}
------------------------
A server opts-in to receive a `Device-Memory` client hint [[!CLIENT-HINTS]] using the `Accept-CH` header field, or an equivalent HTML meta element with http-equiv attribute:
<pre class="highlight">
Accept-CH: Device-Memory
</pre>
In turn, on receiving the above preferences from the server, a compatible user agent would then advertise the device capability for memory, via the `Device-Memory` request header field:
<pre class="highlight">
GET /example HTTP/1.1
Device-Memory: 0.5
...
</pre>
Device Memory (Client Hint) Header Field {#sec-device-memory-client-hint-header}
=======================================
The Device Memory header field is a [[CLIENT-HINTS]] header.
It is a [=structured header value=] containing an [=item=] which value is a [=decimal=] that indicates the client’s device memory, i.e. the approximate amount of RAM in GiB.
The ABNF (Augmented Backus-Naur Form) syntax for the `Device-Memory` header field is as follows:
~~~ abnf
Device-Memory = sf-decimal
~~~
<h3 dfn>Computing Device Memory Value</h3>
The value is calculated by using the actual device memory in MiB then rounding it to the nearest number where only the most signicant bit can be set and the rest are zeros (nearest power of two). Then dividing that number by 1024.0 to get the value in GiB.
An upper bound and a lower bound should be set on the list of values.
NOTE: While implementations may choose different values, the recommended upper bound is 8GiB and the recommended lower bound is 0.25GiB (or 256MiB).
If Device-Memory header field occurs in a message more than once, the last value overrides all previous occurrences.
<h3 dfn>Examples</h3>
512 MiB will be reported as:
<pre class="highlight">
Device-Memory: 0.5
</pre>
1000 MiB will be reported as:
<pre class="highlight">
Device-Memory: 1
</pre>
A full list of possible values should be as follows: 0.25, 0.5, 1, 2, 4, 8
Device Memory JS API {#sec-device-memory-js-api}
=======================================
<pre class="idl">
[
SecureContext,
Exposed=(Window,Worker)
] interface mixin NavigatorDeviceMemory {
readonly attribute double deviceMemory;
};
Navigator includes NavigatorDeviceMemory;
WorkerNavigator includes NavigatorDeviceMemory;
</pre>
NOTE: self.navigator.deviceMemory Returns the amount of ram in GiB as described in [[#computing-device-memory-value]]
Security Considerations {#sec-security-considerations}
=======================================
Device-Memory Client Hint header and JS API will only be available to HTTPS secure contexts.
Device identification and classification (e.g. device type and class) based on advertised User-Agent, and other characteristics of the client, are commonly used to select and provide optimized content. Such solutions frequently rely on commercial device databases, which are costly, hard to integrate, and hard to maintain. This specification defines a mechanism to obtain device memory capability that addresses these technical challenges.
To reduce fingerprinting risk, reported value is rounded to single most significant bit, as opposed to reporting the exact value. In addition, an upper and lower bound is placed on the reported values.
IANA considerations {#iana}
===================
This document defines the `Device-Memory` HTTP request header field, and registers them in the permanent message header field registery ([[RFC3864]]).
Device-Memory Header field {#iana-device-memory}
---------------------------------
: Header field name
:: Device-Memory
: Applicable protocol
:: http
: Status
:: standard
: Author/Change controller
:: IETF
: Specification document
:: this specification ([[#sec-device-memory-client-hint-header]])
<!-- ============================================================ -->
<h2 id=acknowledgements>Acknowledgements</h2>
<!-- ============================================================ -->
Special thanks to <a href="https://github.com/w3c/device-memory/graphs/contributors">all the contributors</a> for their technical input and suggestions that led to improvements to this
specification.