Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an HTTP-based mechanism for JavaScript monitoring code which leverages other performance APIs (like Resource Timing).
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 http://www.w3.org/TR/.
This is a work in progress and may change without any notices.
Please send comments to public-web-perf@w3.org (archived) with [JSPreflight] at the start of the subject line.
This document is produced by the Web Performance Working Group. The Web Performance Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.
Publication as a Working 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 5 February 2004 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 section is non-normative.
Performance data collection is well supported by Navigation Timing, Resource Timng and Navigation Error Logging. The collection, processing of the data as well as the data transfer to a monitoring server is left to application owners. The currently used approach is to add a script to the page which then takes care of the above tasks as shown below.
For example, an HTML page that wants to load a JavaScript file which processes and sends Performance Timeline data will be integrated into a page using a JavaScript tag in the head section of the page.
<html>
<head>
<script type="text/javascript" src="./monitoring.js" ></script>
</head>
....
To address the need for a better mechanism to add analytics logic to web pages the Javascript Preflight Injection specification defines a standardized and reliable approach to load JavaScript for analytics purposes without impacting the loading of the actual web page.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.
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.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may 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 follow, and not intended to be performant.)
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]
The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of
the more accurate "an object implementing the interface Foo".
The term "navigation" refers to the act of navigating.
The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.
This section is non-normative.
This specification defines the main steps involved in JavaScript Preflight Injection. The mechanism is heavily based on the behaviour of cookies.
The first interaction between browser and server is part of the HTTP request. The browser has to communicate that it supports PreFlight Injection.
The Accept-Preflight header is set indicating that the browser supports preflight JavaScript injection.
GET /index.html HTTP/1.1
Host: www.example.com
Accept-Preflight: true
The server sets a preflight JavaScript Cookie for the domain www.example.com
HTTP/1.1 200 OK
Date: Thu, 24 Jan 2013 05:46:54 GMT
Content-Length: 2291
Content-Type: text/html
Set-Preflight-Cookie: /monitoring.js;domain=www.example.com;path=/;max-age=250000
The Preflight Cookie header is sent back to indicate that the browser has set a preflight JavaScript file.
GET /index.html HTTP/1.1
Host: www.example.com
Preflight-Cookie: /monitoring.js
The Set-PreflightCookie: is set to remove a script from preflight injection.
GET /index.html HTTP/1.1
Host: www.example.com
Set-Preflight-Cookie: /monitoring.js;delete
Preflight scripts are executed when the document object is created or when the page load has failed and a Navigation Error has been created.
Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed, e.g., for experimental purposes, vendors MUST use the following extension mechanisms:
This section is non-normative.
Note: Possibly we need a flag where a preflight script can specify an async attribute indicating it does not need to be executed before any JavaScript on the page.
This section is non-normative.
This specification utilizes current standard building blocks of web communication - specifically the HTTP Cookie mechanism. This implies that no additional security and pricacy threats are introduced.