Explainer: Prefetch Activation Beacon API

• Jiacheng Guo (gjc@google.com)

• https://github.com/explainers-by-googlers/prefetch-activation-beacon/issues

• Introduction
• Goals
• Non-goals
• User research
• Use cases
• Proposed Solution
  • Header Syntax
  • Browser Mechanism
  • Non-Interceptable Execution
  • Examples
• Detailed design discussion
  • Activation Definition
  • Post-Commit Dispatch
  • Endpoint Lifetime
• Considered alternatives
  • Client-side JavaScript reporting
• Security and Privacy Considerations
  • The "Echo Back" Principle
  • Static & Non-Modifiable
  • Origin Boundaries (Target-Origin Restriction)
  • Credentialless Beacons
• Stakeholder Feedback / Opposition

This proposal introduces the on-prefetch-activation HTTP response header, which allows a server to specify a telemetry endpoint for prefetched resources. This provides web developers with a reliable signal to accurately measure the precision and performance impact of their prefetch strategies. Because the activation beacon is dispatched directly by the browser's navigation stack when a prefetch is consumed, it is significantly more accurate than client-side scripts, which are susceptible to cache filtering, duplicate events, and aborted navigation.

• Reliable Activation Reporting: Provide a robust, browser-level channel for servers to confirm exactly when a prefetched resource is presented to a user.
• Declarative Integration: Enable servers to specify telemetry reporting endpoints directly within the HTTP response headers of speculative loads, simplifying the implementation for developers.
• Privacy-First Design: Ensure that the telemetry mechanism does not leak additional client-side information or create new vectors for user fingerprinting.

• Legacy API Support: This API will not trigger for <link rel=prefetch> or <link rel=prerender>, as these are being deprecated in favor of the Speculation Rules API.
• Subresource Measurement: This is not intended for subresource prefetches (e.g., images, scripts). "Prewarm" mechanisms or other specialized APIs are the preferred path for measuring subresource usage.
• Dynamic Data Channel: This is not a general-purpose channel for sending arbitrary client-side states. It is strictly limited to reporting the server-defined activation event.

Measuring prefetch activation is essential for web developers to:

• Evaluate the precision of their prefetch rules and optimize them for better performance and resource efficiency.
• Accurately measure the actual visits to prefetched pages to understand user behavior and feature impact.

The core of this proposal is the on-prefetch-activation HTTP response header.

When responding to a prefetch request, a server can include the following header:

on-prefetch-activation: <relative-endpoint-path>

The <relative-endpoint-path> value is the relative URL of the telemetry endpoint that the browser should notify upon activation. The reported URL is always the same-origin as the prefetched page.

The browser process consumes this header from the prefetch response and associates the provided URL with the prefetched document in its internal cache.

The activation beacon is triggered when the navigation utilizing the cached content is successfully committed in a non-prerender context. At this point, the browser sends a credentialless HTTP HEAD request to the specified endpoint.

Because the activation beacon is handled directly by the browser's navigation stack, it does not pass through the origin's Service Worker, is not interceptable by client-side JavaScript, and cannot be blocked or modified by browser extensions. This ensures:

• High Reliability: The signal cannot be blocked, delayed, or tampered with by faulty or malicious scripts, nor by browser extensions.
• Zero Script Execution: The dispatch of the beacon does not boot up a Service Worker or run any page scripts, keeping the activation path as fast and lightweight as possible.

The user navigates to a.com/ and the loaded page prefetches a.com/target. The beacon will be sent when the user navigates to a.com/target afterwards.

The user navigates to a.com/ and the loaded page prefetches b.com/target. The beacon will be sent when the user navigates to b.com/target afterwards.

The user navigates to a.com/ and the loaded page prefetches a.com/target. Then the user navigates to c.com. The beacon will not be sent when the user navigates to a.com/target afterwards.

Activation is defined as the point at which a document loaded via a speculative trigger transitions to the active state in its browsing context. This typically occurs when a user initiates a navigation that the browser satisfies using a previously prefetched response.

To ensure that the beacon accurately reflects a page being shown to the user, the browser dispatches the beacon after the navigation has been committed.

To maintain privacy and prevent "zombie" beacons from unrelated navigations, the following lifetime rules apply:

• One-Time Use: The activation trigger is valid for a single activation event. Once the beacon is fired, the trigger is devalidated for the page.
• Referrer-Bound: The activation trigger is tied to the speculative context of the triggering (referrer) document. If the user navigates away from the referrer page to an unrelated destination, the speculative load's activation metadata is discarded.
• No General Cache Persistence: The beacon does not fire for general navigations that happen to hit the disk cache long after the original speculative context has expired. It only fires when the browser's speculative loading logic explicitly consumes the response to satisfy a predicted navigation.

One alternative is to continue relying on client-side JavaScript to report activation. For example, a site might inject a small script into a prefetched page that fires a sendBeacon request when the page becomes visible.

However, this approach was rejected due to several fundamental reliability issues:

• Cache Ambiguity: Telemetry often filters back/forward navigations to avoid double-counting. However, back/forward navigation to prefetched pages will be missed.
• Duplicate Reporting: Cache restores can re-run scripts, leading to duplicate activation signals and inaccurate attribution.
• Race Conditions: Scripts often fail to execute early enough to capture rapid page transitions.

The API is designed to avoid creating new tracking vectors. The browser conveys no new client-side information to the server; it simply "echoes back" the URL and parameters that the server itself provided in the initial response. This confirms the activation event without exposing dynamic client state.

Because the activation URL is defined in the HTTP header, it is inaccessible to and cannot be modified by third-party JavaScript. This prevents malicious scripts from injecting tracking identifiers into the beacon URL.

To prevent the API from being used for cross-site tracking, the reporting endpoint must be same-origin with the prefetched page.

• If the browser initiatively prefetches target.com, the beacon can only be sent to an endpoint on target.com.
• If referer.com prefetches target.com, the beacon can only be sent to an endpoint on target.com.
• Reporting to the referrer referer.com or any third party other.com is prohibited.

This ensures that only the site being prefetched—which already knows the user is visiting—receives the signal.

Security boundaries are strictly enforced during redirects in both the speculative navigation phase and the activation beacon request itself:

1. Speculative Navigation Redirects:

   • If the speculative request (prefetch or prerender) is redirected, only the on-prefetch-activation header specified in the final response is processed.
   • Any on-prefetch-activation headers encountered in intermediate redirect responses are ignored and dropped.
   • The same-origin validation for the activation beacon endpoint is checked against the final response's URL, not the initial request URL.

2. Activation Beacon Request Redirects:

   • The activation beacon request (sent as an HTTP HEAD request) must only redirect to same-origin URLs (same-origin with the original beacon URL).
   • If the beacon request is redirected to a cross-origin URL, the browser will immediately block and discard the request.
   • The HTTP method of the beacon request must remain HEAD during redirection. If a redirect attempts to change the request method (e.g., a 302 redirect that changes HEAD to GET), the request is blocked.

Activation beacons are sent without cookies, authentication headers, or other stored credentials. This ensures the beacon cannot be used to join user sessions across different security contexts.

For a more detailed analysis, see the Security and Privacy Questionnaire.