Network Information API: A Fallback-First Guide

The WICG Network Information API and MDN describe navigator.connection as an optional, coarse browser hint, not a bandwidth test or identity signal. BotBrowser can configure reported Network Information values such as RTT and downlink in a profile, but it cannot guarantee the route's real throughput or make the API universally available. The safe answer is to render a complete baseline first, feature-detect every hint, and make optional changes reversible.

TL;DR

• Treat effectiveType, rtt, downlink, and saveData as estimates and preferences, not facts about a person or route.
• Keep required content, permissions, and account decisions independent of the API.
• Choose baseline or reduced, measure request outcomes, and provide recovery.
• Explain transfer changes, honor explicit user choices, and avoid retaining raw values.
• BotBrowser can set profile-reported values for testing; it does not simulate physical bandwidth.

Contents

• What the API exposes
• A reversible decision rule
• Changes, privacy, and fallback
• Testing and BotBrowser boundaries
• Conclusion

What the API exposes

NetworkInformation may expose effectiveType, rtt, downlink, saveData, and, in some implementations, type. The first groups observed conditions into values such as slow-2g, 2g, 3g, and 4g; the next two are browser estimates; and saveData records a request to reduce data use. W3C/WICG defines the interface while MDN documents runtime availability. Values can be rounded, stale, missing, or changed by the browser.

Use the API only as an optional capability. A missing object, undefined property, unknown type, or unexpected value must leave required text, controls, and navigation usable. Do not infer country, device class, identity, or guaranteed network performance from one bucket.

A reversible decision rule

Start with a policy that works without hints. Use a behavior name, not a guessed device label, and let explicit user choices win.

const connection = navigator.connection;
const reduced = Boolean(
  connection && (connection.saveData || connection.effectiveType === 'slow-2g' || connection.effectiveType === '2g')
);
const policy = reduced ? 'reduced' : 'baseline';
// Apply only reversible, optional work; required content still renders.

Product question	Choice rule	Expected fallback
Prefetch an optional article?	Use saveData or a conservative type temporarily.	Skip prefetch; keep the link.
Start an autoplay preview?	Combine policy with playback preference and page state.	Show a poster and play control.
Deliver a required document?	Never gate delivery on this API.	Load it and explain optional upgrades.

4g does not guarantee a large transfer will succeed, and a missing value does not prove a slow connection. Observe completion, decode errors, cancellation, input delay, and recovery for the actual request. Keep the policy stable briefly so noisy estimates do not trigger repeated downloads.

Changes, privacy, and fallback

The connection object may dispatch change. Use it to pause or cancel queued enhancement work, not to remove content already available. Debounce changes, bound retries, remove listeners on teardown, and offer a clear retry after an optional failure. Preserve form input, layout space, keyboard access, and accessible loading status while a resource is delayed.

Network hints can add to a fingerprint when combined with other signals. Use them ephemerally and prefer a policy label such as reduced over raw rtt, downlink, or effectiveType in account identifiers, long-lived logs, or analytics. A lower-quality image or deferred prefetch is a product decision, not permission to collect more data. Required requests, permissions, authorization, and account decisions remain independent. For a closer look at what these hints reveal and how to fall back without them, see Network Information API: Hints, Privacy Limits, and Fallbacks.

Responsive images, lazy loading, streaming backpressure, bounded caches, cancellation, and server-rendered baseline HTML remain useful when the API is absent or blocked. Explain a material transfer choice before starting it, and let a person request full resolution even when a conservative hint suggests otherwise.

Testing and BotBrowser boundaries

Test no navigator.connection, partial properties, saveData: true, and a change event during an interrupted optional transfer. Also test an API that reports unknown. Assert behavior: required content remains readable, controls remain keyboard-accessible, and optional work recovers without an infinite loop.

BotBrowser supports profile policies for reported Network Information values, including custom RTT and downlink, so a team can review application handling of declared hints. That changes browser-reported values in the test context; it does not change proxy throughput, measure the physical route, guarantee API availability, or decide how a site classifies a session.

The Network Information API specification, MDN NetworkInformation reference, and MDN API overview are the standards and browser sources. See the Network Information fingerprinting guide and Client Hints fingerprinting guide for adjacent privacy boundaries.

Conclusion

Use Network Information as a temporary input to a reversible resource policy. Keep a complete baseline, honor user intent, measure the request you actually made, and retain only minimum evidence. Next, implement the guarded fixture above and run it once with the API absent before enabling adaptive enhancement.

FAQ

Is downlink a speed test?

No. It is a browser estimate that can be rounded, stale, or affected by other traffic. The request's own completion and failure behavior is better evidence.

Should a missing API force reduced content?

No. Missing support is unknown. Keep the baseline usable and choose a conservative optional policy only when it can be explained and reversed.

Can BotBrowser guarantee a slow or fast route?

No. It can configure reported profile values for controlled testing, not physical throughput, proxy behavior, universal API availability, or a site's response.

What should be logged?

Prefer policy outcomes, workload version, completion, cancellation, and recovery. Avoid raw values and remove temporary diagnostics after review.

How should a team review a policy change?

Compare the same task before and after the change with the same browser release, profile, media set, and viewport. Change only the policy under review. Confirm that required records, permissions, submitted values, keyboard paths, and screen-reader names are unchanged. Then compare optional completion, cancellation, input delay, and recovery. A policy is ready only when the visible improvement is repeatable and the fallback remains clear.

What is the next safe action?

Add feature detection, a baseline fixture, and one bounded retry test. Have accessibility and privacy reviewers approve the policy before collecting metrics.

A complete implementation checklist

Start by writing down which representations are required for the task. A required document, heading, label, form value, or primary action belongs in the baseline. A poster, related row, animation, prefetch, or high-resolution image may be optional if the interface explains what is waiting and how to request it. This classification is more durable than a rule that says every 2g visitor gets the same page, because the same hint can lead to different product decisions on a reading page and a transactional page.

Keep the policy at page or task scope. If every component reads navigator.connection and applies its own thresholds, a header can choose a reduced image while a video immediately starts an enhancement, causing competing downloads. Pass one named policy to child components and include a reason category such as user-preference, conservative-fallback, or hint-unavailable. The category explains the visible behavior without exposing raw browser values. A policy owner should record its maximum optional transfer, concurrency limit, retry budget, and rollback condition.

The baseline must also be stable during server rendering and hydration. Do not make the initial HTML depend on a property that exists only after page script runs. When a service uses Client Hints or a response preference, the server still needs a complete response when no hint arrives, when an origin has not opted in, or when a browser withholds the value. Cache keys should reflect an explicit product variant only when necessary. A reduced response must not replace a complete response for a later request where the person has asked for more.

Accessibility is part of every branch. A delayed image needs equivalent text and reserved dimensions; a deferred video needs a title, poster, and keyboard-accessible play control; a smaller table must not hide the only path to a required record. Announce waiting, decoding, retrying, and failure states without repeatedly moving focus. Preserve typed form data while an enhancement is paused. If the person navigates away, cancel optional work and release temporary buffers; if the person returns, begin one fresh bounded attempt.

Use real outcomes to tune thresholds. Time to first useful content, completion of an optional download, cancellation rate, input delay, and recovery after failure describe the experience more clearly than a hardware or carrier label. Aggregate those measures by policy and workload version, keep retention short, and remove incident-only diagnostic fields when the review ends. If a raw value is necessary for a narrowly scoped investigation, restrict access and retention, then convert the result to a policy-level finding.

Plan for changes during a task. A browser may report a new estimate while a request is already downloading, or a person may switch from reduced data to full resolution. Do not replace a resource after most bytes have arrived unless the remaining cost justifies it. Do not upgrade automatically while someone is interacting with a control. If a request is partially complete, keep the completed baseline, describe what remains, and let the person retry once. This avoids turning adaptation into a source of extra traffic.

The API may be unavailable because of browser support, context, privacy policy, or an implementation decision. Those states are not equivalent to a slow connection. Test them separately, and record the observed behavior rather than a guessed reason. A successful fixture proves only that one browser context exposed one value under one profile; it does not prove a site will grant access, that a proxy will deliver the same speed, or that a future release will retain the same rounding rules.

When documenting a policy, include the standards link, the supported property names, the fallback, the user-visible explanation, and the owner for review. Keep the example guarded and copyable. Avoid device labels such as old-phone or slow-user; reduced tells readers what the application will do without pretending that the browser established a personal fact. This vocabulary also makes logs safer and lets a team change thresholds without changing the public contract.

For an operational rollout, ship the baseline first, then enable one optional branch behind a measurable flag. Compare the same journey on a stable and metered connection, with the API present and absent. Confirm that keyboard paths, screen-reader labels, submitted values, authorization checks, and required records are identical. Only then add a second optional branch. If evidence worsens, roll back the branch while retaining the baseline and its user controls.

Readers can turn this guidance into a small review record. Write the product question, required baseline, optional branch, policy name, and expected fallback. Note whether the API object and each property were present, but do not copy raw values into a durable profile. Record what loaded first, what waited, which control appeared, and whether a retry recovered without a loop. Add the browser release and workload version so a later run can distinguish a product change from an implementation change.

If a result is surprising, separate four possibilities before changing code: the browser did not expose the API; it exposed an unknown or rounded value; the optional request failed for an ordinary application reason; or the policy removed a useful fallback. Reproduce one possibility at a time with a fresh context. BotBrowser profile values can exercise the first two application branches, but they do not prove the third or fourth. The page still needs normal request error handling, authorization checks, and user controls.

Keep product language honest. Say “optional preview paused to save data” when that is what the policy did. Do not say “the network is unsuitable,” “this is an old device,” or “the visitor is slow” when the browser supplied only a coarse hint. Clear language gives a person a choice and prevents a temporary estimate from becoming a permanent label.

Before launch, ask a reviewer to follow the page with the API removed, with only saveData present, and with an unknown connection type. The reviewer should be able to finish the primary task in each case, understand why an optional resource is waiting, and activate a retry without losing context. Inspect the network panel only to confirm that optional work is bounded; do not turn a development trace into a user profile. After launch, sample policy-level outcomes for a short retention period, compare them with the baseline, and remove the sample when the decision is complete. This keeps the implementation accountable while preserving the distinction between a browser hint, a product policy, and a real network measurement.

A practical rollout sequence

Begin with a baseline that serves the same semantic document, labels, and primary action on every browser. Add one optional enhancement at a time, such as selecting an existing responsive image candidate or deferring a non-essential preview. Record the policy name and workload version, not the browser's raw connection values. Compare completion, cancellation, input delay, and recovery for the same journey on a stable connection and a metered connection. Keep the baseline until the evidence shows that the enhancement improves the intended experience without creating extra retries or layout movement.

When a request is interrupted, keep the trigger visible and preserve any entered data. A retry should create one new bounded request with backoff, not attach another change listener or restart every component on the page. If a person chooses a full-resolution file, present the approximate cost before starting and let that choice override a conservative hint for the current task. If the person chooses reduced data, keep that preference stable until they change it. The API can inform the first choice, but it should not silently undo an explicit choice when the browser reports a new estimate.

For server-rendered pages, return complete baseline HTML before client enhancement. A server should have a valid response when no Client Hint or JavaScript value arrives, and a cache key should represent an explicit product variant rather than a detailed network fingerprint. Coordinate one page-level policy so an image, video, and prefetch component do not interpret the same hint differently and start competing transfers. Name recovery states clearly: waiting for a response, decoding received bytes, retrying once, or using the baseline. This makes the interface understandable to keyboard and assistive-technology users as well as to people on unstable connections.

Review the policy after a browser release, a media-set change, or a workload change. A browser may alter rounding or expose a new connection type without changing the application contract. Re-run the missing-object, partial-property, unknown, saveData, and interrupted-transfer fixtures, then remove temporary diagnostic fields. The durable result should be a bounded product rule that remains useful when the Network Information API is withheld, unsupported, stale, or deliberately ignored.

That distinction is the acceptance criterion for the feature: a browser hint informs a bounded choice, while the baseline remains the product promise.

Sources

• W3C/WICG Network Information API
• MDN: NetworkInformation
• MDN: Network Information API