W3C

Device Memory 1

Editor’s Draft,

This version:
https://w3c.github.io/device-memory/
Latest published version:
https://www.w3.org/TR/device-memory/
Issue Tracking:
GitHub
Editor:
(Google)

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.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Performance Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

Feedback and comments on this specification are welcome, please send them to public-web-perf@w3.org (subscribe, archives) with [device-memory] at the start of your email’s subject.

Publication as an Editors Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

1. Introduction

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.

1.1. Usage Example

A server advertises support for `Device-Memory` client hint using the `Accept-CH` header field, or an equivalent HTML meta element with http-equiv attribute. Optionally, the server can also express a preference for the user agent to persist the opt-in, by using the `Accept-CH-Lifetime` header to communicate the amount of time to remember the opt-in:
Accept-CH: Device-Memory
Accept-CH-Lifetime: 86400

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:

GET /example HTTP/1.1
Device-Memory: 0.5
...

2. Device Memory (Client Hint) Header Field

The Device Memory header field is a number that indicates the client’s device memory i.e. approximate amount of ram in GiB. The ABNF (Augmented Backus-Naur Form) syntax for the `Device-Memory` header field is as follows:

Device-Memory         = "Device-Memory" ":" #memory-value
memory-value   = 1*DIGIT [ "." 1*DIGIT ]

2.1. Computing Device Memory Value

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.

2.2. Examples

512 MiB will be reported as:

Device-Memory: 0.5

1000 MiB will be reported as:

Device-Memory: 1

A full list of possible values is as follows: 0.25, 0.5, 1, 2, 4, 8

3. Device Memory JS API

[
    NoInterfaceObject,
    SecureContext,
    Exposed=(Window,Worker)
] interface NavigatorDeviceClass {
    readonly attribute double deviceMemory;
};

NOTE: self.navigator.deviceMemory Returns the amount of ram in GiB as described in §2.1 Computing Device Memory Value

4. 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.

5. Acknowledgements

Special thanks to all the contributors for their technical input and suggestions that led to improvements to this specification.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[
    NoInterfaceObject,
    SecureContext,
    Exposed=(Window,Worker)
] interface NavigatorDeviceClass {
    readonly attribute double deviceMemory;
};