index.bs

<pre class='metadata'>
Title: Device Memory API
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: Barry Pollard, Google https://google.com, barrypollard@google.com, w3cid 138839
Editor: Guohui Deng, Microsoft https://microsoft.com, guohuideng@microsoft.com, w3cid 158258
Former Editor: Shubhie Panicker, Google https://google.com
Repository: w3c/device-memory
Abstract: This document defines a HTTP Client Hint header and a JavaScript API to surface device capability for memory (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
Markup Shorthands: markdown yes
</pre>

<pre class="anchors">
urlPrefix: https://datatracker.ietf.org/doc/html/rfc8941; spec: rfc8941
    type: dfn
        text: structured header value; url: #name-introduction
    type: dfn
        text: decimal; url: #name-decimals
        text: item; url: #name-items
urlPrefix: https://datatracker.ietf.org/doc/html/rfc8941; spec: rfc8942
    type: dfn
        text: HTTP Client Hint; url: #name-introduction
</pre>
 
# Introduction # {#intro}

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-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 [(Client Hint) Header Field](#sec-device-memory-client-hint-header) and a [JavaScript API](#device-memory-js-api) which exposes the approximate device memory (RAM) to address these needs without needing to use a device database.

# Computing device memory value # {#computing-device-memory}

<div algorithm>
    The [=user agent=]'s <dfn>deviceMemory</dfn> is calculated by these steps:

    1.  Let |physicalDeviceMemory| be the amount of physical memory in bytes.
    2.  Let |minimumLowerBound| be an [=implementation-defined=] minimum bound.
    3.  Let |maximumUpperBound| be an [=implementation-defined=] maximum bound.
    4.  Let |deviceMemory| be |physicalDeviceMemory| / 1024.0.
    5.  Let |power| be 0.
    6.  [=iteration/While=] |deviceMemory| is greater than 1:
            1.  Bitwise shift |deviceMemory| right 1 place.
            2.  Increment |power| by 1.
    7.  Let |lowerBound| be 2 to the power of |power|.
    8.  Let |upperBound| be 2 to the power of |power + 1|.
    9.  If |physicalDeviceMemory| − |lowerBound| &le; |upperBound| − |physicalDeviceMemory|, then |deviceMemory|'s value is |lowerBound|.
    10.  Otherwise |deviceMemory|'s value is |upperBound|.
    11.  If |deviceMemory| < |minimumLowerBound|, then |deviceMemory| is |minimumLowerBound|.
    12.  If |deviceMemory| > |maximumUpperBound|, then |deviceMemory| is |maximumUpperBound|.
    13.  Return |deviceMemory|.
</div>

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.

# `Sec-CH-Device-Memory` (Client Hint) Header Field # {#sec-device-memory-client-hint-header}

The <dfn http-header>`Sec-CH-Device-Memory`</dfn> 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-CH-Device-Memory:] 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-CH-Device-Memory:] header field is as follows:

```abnf
Sec-CH-Device-Memory = sf-decimal
```

The [:Sec-CH-Device-Memory:]'s value should be set to the [=user agent=]'s [=deviceMemory=].

## Client Hint examples ## {#client-hint-examples}

<div class="example">
    A server opts in to receive a [:Sec-CH-Device-Memory:] [=HTTP Client Hint=] using the `Accept-CH` header field, or an equivalent HTML meta element with http-equiv attribute:

    ```http
        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-CH-Device-Memory:] request header field:

    ```http
        GET /example HTTP/1.1
        Sec-CH-Device-Memory: 8
        ...
    ```
</div>

# Device Memory JavaScript API # {#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>

The {{NavigatorDeviceMemory}}'s {{NavigatorDeviceMemory/deviceMemory}} getter steps are to return the [=user agent=]'s [=deviceMemory=].

## JavaScript examples ## {#javascript-examples}

<div class="example">

    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.

    ```javascript
        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
        }
    ```
</div>

<div class="example">
    A RUM solution can query the device memory using `navigator.deviceMemory` API and include this in performance beacons as additional information to help explain or segment the data.

    ```javascript
        const mem = navigator.deviceMemory;
        const analyticsData = {
            memory: mem;
            ... other metrics
        }
        navigator.sendBeacon("/endpoint", analyticsData);
    ```
</div>

# Security & privacy considerations # {#security-and-privacy}

[:Sec-CH-Device-Memory:] 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.

# IANA considerations # {#iana}

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

## `Sec-CH-Device-Memory` header field ## {#iana-device-memory}

: Header field name
:: Sec-CH-Device-Memory

: Applicable protocol
:: http

: Status
:: standard

: Author/Change controller
:: IETF

: Specification document
:: This specification ([[#sec-device-memory-client-hint-header]])

# Acknowledgements # {#acknowledgements}

Special thanks to the previous editor Shubhie Panicker and [all the contributors](https://github.com/w3c/device-memory/graphs/contributors) for their technical input and suggestions that led to improvements to this specification.