Device Memory (original) (raw)

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

Table of Contents

  1. 1 Introduction
    1. 1.1 Usage Example
  2. 2 Device Memory (Client Hint) Header Field
    1. 2.1 Computing Device Memory Value
    2. 2.2 Examples
  3. 3 Device Memory JS API
  4. 4 Security Considerations
  5. 5 IANA considerations
    1. 5.1 Device-Memory Header field
  6. 6 Acknowledgements
  7. Conformance
    1. Document conventions
    2. Conformant Algorithms
  8. Index
    1. Terms defined by this specification
    2. Terms defined by reference
  9. References
    1. Normative References
    2. Informative References
  10. IDL Index

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 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:

Accept-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 `Device-Memory` request header field:

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

Headers/Device-Memory

In only one current engine.

Firefox?SafariNoneChrome61+

Opera?Edge79+

Edge (Legacy)NoneIE?

Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

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:

Device-Memory = sf-decimal

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 should be as follows: 0.25, 0.5, 1, 2, 4, 8

3. Device Memory JS API

Navigator/deviceMemory

In only one current engine.

FirefoxNoneSafariNoneChrome63+

Opera?Edge79+

Edge (Legacy)?IENone

Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

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

Navigator includes NavigatorDeviceMemory; WorkerNavigator includes NavigatorDeviceMemory;

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. IANA considerations

This document defines the `Device-Memory` HTTP request header field, and registers them in the permanent message header field registery ([RFC3864]).

5.1. Device-Memory Header field

Header field name

Device-Memory

Applicable protocol

http

Status

standard

Author/Change controller

IETF

Specification document

this specification (§ 2 Device Memory (Client Hint) Header Field)

6. Acknowledgements

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

Conformance

Document conventions

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

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

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

This is an example of an informative example.

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

Note, this is an informative note.

Conformant Algorithms

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

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

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CLIENT-HINTS]

Ilya Grigorik; Yoav Weiss. Client Hints. ID. URL: https://httpwg.org/http-extensions/client-hints.html

[HTML]

Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/

Mark Nottingham; Poul-Henning Kamp. Structured Field Values for HTTP. ID. URL: https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119

[WEBIDL]

Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[RFC3864]

G. Klyne; M. Nottingham; J. Mogul. Registration Procedures for Message Header Fields. September 2004. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc3864

IDL Index

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

Navigator includes NavigatorDeviceMemory; WorkerNavigator includes NavigatorDeviceMemory;