1. Introduction
A device-class signal is used for several reasons, including:
-
Serving a light version of the site or specific components: This is useful to customize a site for low-end devices. Examples include:
-
Serve “search lite” - a 10KB search results page used for low-end devices.
-
Serve a light version of video player in a social media web application.
-
Serve lightweight tile images in a map web application.
-
-
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 identification and classification based on advertised User, 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 (Client Hint) Header Field and a JavaScript API which exposes the approximate device memory (RAM) to address these needs without needing to use a device database.
2. Computing device memory value
-
Let physicalDeviceMemory be the amount of physical memory in bytes.
-
Let minimumLowerBound be an implementation-defined minimum bound.
-
Let maximumUpperBound be an implementation-defined maximum bound.
-
Let deviceMemory be physicalDeviceMemory / 1024.0.
-
Let power be 0.
-
While deviceMemory is greater than 1:
-
Bitwise shift deviceMemory right 1 place.
-
Increment power by 1.
-
-
Let lowerBound be 2 to the power of power.
-
Let upperBound be 2 to the power of |power + 1|.
-
If physicalDeviceMemory − lowerBound ≤ upperBound − physicalDeviceMemory, then deviceMemory’s value is lowerBound.
-
Otherwise deviceMemory’s value is upperBound.
-
If deviceMemory < minimumLowerBound, then deviceMemory is minimumLowerBound.
-
If deviceMemory > maximumUpperBound, then deviceMemory is maximumUpperBound.
-
Return deviceMemory.
The algorithm includes the ability for implementation-defined upper bound and a lower bounds. The range between the upper and the lower bounds should include the majority of device memory values but exclude rare device memory values to mitigate device fingerprinting. Implementations may adjust these bounds over time. These bounds may differ on different device types.
3. Sec- CH- Device- Memory (Client Hint) Header Field
The Sec header field is a HTTP Client Hint header.
It is a structured header value containing an item which value is a decimal that indicates the client’s approximate amount of device memory (RAM) in GiB.
If `Sec` header field occurs in a message more than once, the last value overrides all previous occurrences.
The ABNF (Augmented Backus-Naur Form) syntax for the `Sec` header field is as follows:
Sec-CH-Device-Memory = sf-decimal
The `Sec`'s value should be set to the user agent’s deviceMemory.
3.1. Client Hint examples
Sec- CH- Device- Memory` HTTP Client Hint using the Accept- CH header field, or an equivalent HTML meta element with http-equiv attribute:
Accept-CH: Sec-CH-Device-Memory
In turn, on receiving the above preferences from the server, a compatible user agent would then advertise the device capability for memory, via the `Sec` request header field:
GET /example HTTP / 1.1 Sec-CH-Device-Memory : 8 ...
4. Device Memory JavaScript API
[
SecureContext ,
Exposed =(Window ,Worker )
] interface mixin NavigatorDeviceMemory readonly attribute double deviceMemory Navigator includes NavigatorDeviceMemory ;
WorkerNavigator includes NavigatorDeviceMemory ;
The NavigatorDeviceMemory’s deviceMemory getter steps are to return the user agent’s deviceMemory.
4.1. JavaScript examples
A web application can either enable or disable features based on device memory.
Note: The web application should consider how to handle browsers that do not support the API: either by enabling by default, or disabling by default.
const mem= navigator. deviceMemory; // Either disable features if it is known to be a low-memory device if ( mem&& mem< 2 ) { // disable features to provide a better experience } // Or, alternatively only enable features if the device memory is // either not provided, or known to be above minimum requirements if ( ! mem|| mem> 4 ) { // enable features to provide a better experience }
navigator. deviceMemory API and include this in performance beacons as additional information to help explain or segment the data.
const mem= navigator. deviceMemory; const analyticsData= { memory: mem, // Add other metrics here. }; navigator. sendBeacon( "/endpoint" , JSON. stringify( analyticsData));
5. Security & privacy considerations
`Sec` Client Hint header and JavaScript API will only be available to HTTPS secure contexts.
To reduce fingerprinting risk, the reported value is rounded to a single significant bit, as opposed to reporting the exact value. In addition, an implementation-specific upper and lower bound is placed on the reported values. These bounds should be reviewed over time as commonly used device memory characteristics change. Device type should be taken into account when defining these bounds since mobile devices typically have different characteristics than desktops and laptops.
6. IANA considerations
This document defines the `Sec` HTTP request header field, and registers them in the permanent message header field registry ([RFC3864]).
6.1. Sec- CH- Device- Memory header field
- Header field name
-
Sec-CH-Device-Memory
- Applicable protocol
-
http
- Status
-
standard
- Author/Change controller
-
IETF
- Specification document
-
This specification (§ 3 Sec-CH-Device-Memory (Client Hint) Header Field)
7. Acknowledgements
Special thanks to the previous editor Shubhie Panicker and all the contributors for their technical input and suggestions that led to improvements to this specification.