├── getting-a-token.md ├── completed-trials.md ├── available-trials.md ├── ship-as-trial.md ├── README.md ├── check-token.html ├── archive └── index.bs ├── LICENSE ├── explainer.md └── developer-guide.md /getting-a-token.md: -------------------------------------------------------------------------------- 1 | You can request an Origin Trials token the enable a feature by visiting the [developer console](https://developers.chrome.com/origintrials/#/trials/active). 2 | -------------------------------------------------------------------------------- /completed-trials.md: -------------------------------------------------------------------------------- 1 | # Completed Trials 2 | 3 | Information about completed trials is now found in the [developer console](https://developers.chrome.com/origintrials/#/trials/complete). 4 | -------------------------------------------------------------------------------- /available-trials.md: -------------------------------------------------------------------------------- 1 | # Current Experimental Features 2 | 3 | _For the full context on origin trials, please see the [explainer](explainer.md)._ 4 | 5 | Visit the [developer console](https://developers.chrome.com/origintrials/#/trials/active) to sign up to try out any of the current features. 6 | -------------------------------------------------------------------------------- /ship-as-trial.md: -------------------------------------------------------------------------------- 1 | # Running an origin trial for a feature 2 | 3 | _For the full context on origin trials, please see the [explainer](explainer.md)._ 4 | 5 | The instructions for running a trial (i.e. the feature author guide) now live in the Chromium project documentation: 6 | https://dev.chromium.org/blink/origin-trials/running-an-origin-trial 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Origin Trials 2 | Origin trials are an approach to enable safe experimentation with web platform features. 3 | 4 | Briefly, the web needs new features, and iteration yields the best designs and implementations for those features. However, previous efforts have seen experiments prematurely become de-facto standards, with browser vendors scrambling to implement the features, and web developers coming to rely on these features. These experimental features became burned-in, and resistant to change (or removal), even though better implementations were identified/available. 5 | 6 | One of the root causes was that experimental features were available too widely, and thus usage grew unchecked as a result. Ideally, it should be easier to expose and iterate on new features, but reliably limit the experimental population. With a test population of developers committed to providing feedback, and limits in user base size and experiment duration, iteration can happen faster, but without the risk of burn-in. 7 | 8 | The origin trial feature is still security-reviewed, tested and launched as a production feature, just time and usage limited to allow for evolving the feature with developer feedback, minimizing the risk of it prematurely becoming a defacto standard. 9 | 10 | Please see the [explainer](explainer.md) to learn more about the problem, and why origin trials is a good solution. 11 | 12 | ## Signing up for an origin trial 13 | Developers can use the [developer console](https://developers.chrome.com/origintrials/) to request a token to access a feature currently available as an Origin Trial. 14 | 15 | ## Contents 16 | In addition to describing the problem, and solution, you'll find information for implementing features as experiments, participating in experiments, and details about how it works in Chrome. 17 | 18 | * [Motivation/Explainer](explainer.md) - Detailed discussion of the problem, the history and why we think origin trials are a good solution 19 | * [Web Developer Guide](developer-guide.md) - For web developers looking to participate in a trial 20 | * [Feature Author Guide](https://dev.chromium.org/blink/origin-trials/running-an-origin-trial) - For browser engineers looking to experiment with their feature 21 | -------------------------------------------------------------------------------- /check-token.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Check an Origin Trial token 4 | 5 | 10 | 11 |

Check an Origin Trial token

12 | 13 |

14 | 17 |

18 |

19 | 22 |

23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 |
Valid?
Version
Origin
Matches Subdomains?
Matches Third-party?
Usage Restriction
Feature
Expires
34 | 35 | 40 | 41 | 182 | -------------------------------------------------------------------------------- /archive/index.bs: -------------------------------------------------------------------------------- 1 | 
  2 | Title: Origin Trials
  3 | Shortname: origintrials
  4 | Level: 1
  5 | Indent: 2
  6 | Group: personal
  7 | Editor: Marijn Kruisselbrink, Google, mek@chromium.org
  8 | Status: ED
  9 | ED: https://googlechrome.github.io/OriginTrials/
 10 | Repository: GoogleChrome/OriginTrials
 11 | Abstract: Doing Science On The Web summarizes the past
 12 |   problems in bringing new features to the web platform.
 13 |   Briefly, the web needs new features, and iteration yields the best designs and implementations for
 14 |   those features.
 15 |   However, previous efforts have seen experiments prematurely become de-facto standards, with
 16 |   browser vendors scrambling to implement the features, and web developers coming to rely on
 17 |   these features.
 18 |   These experimental features became burned-in, and resistant to change (or removal), even though
 19 |   better implementations were identified/available.
 20 | 
 21 |   One of the root causes was that experimental features were available too widely, and thus usage
 22 |   grew unchecked as a result.
 23 |   Ideally, it should be easier to expose and iterate on new features, but reliably limit the
 24 |   experimental population.
 25 |   With a test population of developers committed to providing feedback, and limits in user base size
 26 |   and experiment duration, iteration can happen faster, but without the risk of burn-in.
 27 | Boilerplate: omit conformance
 28 | Markup Shorthands: css off, markdown on
 29 |
30 | 31 | 
 32 | {
 33 |   "Doing Science On The Web": {
 34 |     "href": "https://infrequently.org/2015/08/doing-science-on-the-web/",
 35 |     "title": "Doing Science On The Web"
 36 |   }
 37 | }
 38 |
39 | 40 | 
 41 | spec: html
 42 |   type: dfn
 43 |     text: environment settings object
 44 |     text: global object; for: environment settings object
 45 |     text: initialising a new document object
 46 |     text: inserted into a document
 47 |     text: responsible document
 48 |     text: run a worker
 49 |   type: element
 50 |     text: link
 51 |     text: script
 52 | 
 53 | spec: dom
 54 |   type: interface
 55 |     text: Document
 56 | 
 57 | spec:url
 58 |   type:dfn
 59 |     for:url; text:scheme
 60 |     text: local scheme
 61 |
62 | 63 | 
 64 | spec: fetch; urlPrefix: https://fetch.spec.whatwg.org/
 65 |   type: dfn
 66 |     text: response; url: concept-response
 67 |     for: response; urlPrefix: #concept-response-
 68 |       text: header list
 69 |       text: url
 70 | 
 71 | spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
 72 |   urlPrefix: infrastructure.html
 73 |     type: dfn; text: ASCII case-insensitive match; url: ascii-case-insensitive
 74 |   urlPrefix: semantics.html
 75 |     type: element-attr; for: meta; urlPrefix: #attr-meta-
 76 |       text: content
 77 |       text: http-equiv
 78 | 
 79 | spec: rfc7230; urlPrefix: https://tools.ietf.org/html/rfc7230
 80 |   type: grammar; url: section-3.2.6
 81 |     text: quoted-string
 82 |     text: token
 83 |
84 | 85 |

Introduction

86 | 87 | This section is informative. 88 | 89 |

Model

90 | 91 | A trial is something that can be enabled or disabled. 92 | 93 | Issue: define trial and other terminology better. 94 | 95 | A trial token is a string in a user agent defined format. A trial token is somehow 96 | associated with a trial. 97 | 98 | 99 | 100 | The `Origin-Trial` HTTP response header field can be used to deliver trial tokens 101 | from a server to a client. The header's value is represented by the following 102 | ABNF: 103 | 104 | 
105 |   Origin-Trial = 1#serialized-trial-token
106 | 
107 |   serialized-trial-token = token | quoted-string
108 |
109 | 110 |
111 | 
112 |     Origin-Trial: some-token, some|other|token
113 |     Origin-Trial: yet_another_token
114 |
115 |
116 | 117 | When the user agent receives a `Origin-Trial` header field, it MUST process it as described in 118 | [[#integration]]. 119 | 120 |

The <{meta}> element

121 | 122 | A {{Document}} may specify trial tokens via one or more HTML <{meta}> elements whose 123 | <{meta/http-equiv}> attributes are an ASCII case-insensitive match for the string 124 | `"Origin-Trial"`. For example: 125 | 126 |
127 | 
128 |     <meta http-equiv="Origin-Trial" content="sometoken">
129 |
130 |
131 | 132 | Authors are strongly encouraged to place <{meta}> elements as early in the document as 133 | possible, because tokens in <{meta}> elements are not taken into account for content which precedes 134 | them. In particular, note that <{script}> executed before the <{meta}> element will not have access 135 | to trials enabled by tokens in the <{meta}> element. 136 | 137 | Issue: Another option would be to not process <{meta}> elements that occur after the first 138 | <{script}> tag. But that won't be enough, since <{link}> can allow script execution via its 139 | `load` and `error` events as well, as one example of another way to execute javascript. 140 | 141 | Note: Modifications to a <{meta}> element after the element has been parsed will be ignored. 142 | 143 |

Integration with HTML

144 | 145 | The {{Document}} and {{WorkerGlobalScope}} objects have a trial token list, which holds 146 | all the trial tokens which are active for a given context. This list is empty unless otherwise 147 | specified. 148 | 149 | A trial trial is enabled in a specific 150 | context if any of the trial tokens in context's trial token list 151 | is associated with trial. 152 | 153 |

Initialize a `Document`'s trial token list

154 | 155 | This algorithm should be executed during the initialising a new `Document` object algorithm. 156 | 157 | Given a {{Document}} (document) and a response (response), the user 158 | agent performs the following steps in order to initialize document's trial token 159 | list: 160 | 161 | 1. If response's url's scheme is a local scheme: 162 | 163 | Issue: this is about blob URLs, about:blank, and similar. We should define what to do here. It 164 | might make sense to inherit tokens from the creating document, similar to how CSP policies etc 165 | are inherited. 166 | 167 | 2. For each serialized-trial-token serializedToken resulting from parsing 168 | the Origin-Trial headers in response's header list: 169 | 170 | 1. Add the trial token represented by serializedToken to document's 171 | trial token list. 172 | 173 |

Initialize a `WorkerGlobalScope`'s trial token list

174 | 175 | This algorithm shuold be executed as part of the run a worker algorithm. 176 | 177 | Given a {{WorkerGlobalScope}} (global), response (response) and 178 | possible {{WorkerGlobalScope}} parentWorker the user agent performs the 179 | following steps in order to initialize global's trial token list: 180 | 181 | 1. If global is a {{DedicatedWorkerGlobalScope}} instance: 182 | 183 | 1. If global has a parentWorker, set global's 184 | trial token list to a copy of parentWorker's trial token list. 185 | 186 | 2. Else set global's trial token list to a copy of global's 187 | responsible document's trial token list. 188 | 189 | 2. Else: 190 | 191 | 1. For each serialized-trial-token serializedToken resulting from 192 | parsing the Origin-Trial headers in response's header list: 193 | 194 | 1. Add the trial token represented by serializedToken to global's 195 | trial token list. 196 | 197 | Issue: does this need special handling for about:blank, blob: urls etc? 198 | 199 |

Processing of a <{meta}> tag

200 | 201 | When a <{meta}> element is inserted into a document, if its <{meta/http-equiv}> attribute 202 | is present and represents a `Origin-Trial`, the user agent must run the following algorithm: 203 | 204 | 1. If the <{meta}> element is not a child of a <{head}> element, abort these steps. 205 | 206 | 2. If the <{meta}> element has no <{meta/content}> attribute, abort these steps. 207 | 208 | 3. If the <{meta}> element was created by script, abort these step. 209 | 210 | Issue: need to define what "created by script" means, and what is/isn't supported 211 | 212 | 4. Add the value of the <{meta/content}> attribute to the {{Document}}'s trial token list. 213 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /explainer.md: -------------------------------------------------------------------------------- 1 | # Motivation and Explainer 2 | 3 | This document describes why we feel it is important to enable browser vendors and standards designers to experiment on the web, and how we believe it is possible to do safely. 4 | 5 | _Note: If you’re a developer interested in how to use origin trials, see [this guide](developer-guide.md). New origin trials are announced on [developers.google.com/web/updates](https://developers.google.com/web/updates/), and a list of active trials are [posted here](https://developers.chrome.com/origintrials/#/trials/active)._ 6 | 7 | ## The problem 8 | It is well known that **iteration and fast feedback cycles are key to designing high quality software**. The process of development is one of designing interfaces and abstractions, attempting to use them or have your friends and colleagues use them, realizing they’re leaky or broken, fixing those problems, and then repeating the cycle. 9 | 10 | This works great in an environment where you can cycle through the process many times, but **this process is very challenging in some cases**, especially when: 11 | - You are not the target user of the interface or abstraction 12 | - The target user is very different from you 13 | - The target users aren’t willing or able to try it out in actual usage 14 | - Changing the interface or abstraction is difficult or costly, once shipped 15 | 16 | Interestingly, the web is approximately a worst case example of all of the above: 17 | - Browser engineers are designing abstractions and interfaces for web developers, not for browser engineers 18 | - Browser engineers often have very different backgrounds, knowledge and experiences than web developers 19 | - Web developers generally aren’t compelled to try features until they can use them to build a site and have their users interact with it 20 | - Making breaking changes to web APIs is extremely challenging; even before shipping, changes are difficult to make due to the need to drive consensus between individuals across companies 21 | 22 | The resulting situation is one in which **features shipping on the web take a long time to design, and are then frozen into standards well before they have been significantly road-tested by real web developers**. 23 | 24 | This has resulted in a number of unfortunate situations such as us spending years designing a [declarative disaster](http://alistapart.com/article/application-cache-is-a-douchebag) when we should have been iterating to design a [programmable proxy](http://www.html5rocks.com/en/tutorials/service-worker/introduction/). 25 | 26 | To summarize, we believe it would be hugely beneficial to the web if we had a safe way to enable browser vendors to iteratively develop features using feedback from web developers. 27 | 28 | ## The risks and past attempts to solve the problem 29 | This problem is difficult to solve. Browser vendors previously attempted to solve it with [vendor prefixes](https://developer.mozilla.org/en-US/docs/Glossary/Vendor_Prefix), which allowed browser vendors to ship features prior to standardization. The theory was that this would allow developers to provide early feedback and give vendors the ability to change APIs before standardizing them. The intention was that the ugly appearance of prefixes would make it obvious that developers shouldn’t depend on the features in production. 30 | 31 | Unfortunately, what actually happened was that developers didn’t consider these experimental but rather used prefixed features in production sites that have survived for years and years. As a result, the web is now full of sites that in the worst case only support some features in the browsers that happened to have a prefixed form at the time, and in the best case ship huge CSS files full of redundant vendor prefixes. 32 | 33 | This experience makes it clear that **any system to enable experimentation should also converge to eventual interoperability for successful features**. 34 | 35 | Conversely, for unsuccessful features we should ensure that any system to enable experimentation prevents designs we later regret from being baked into the web. 36 | 37 | The risks don’t stop there though. Assuming we did ship a feature experimentally, how can we prevent one large company from adopting it and relying on it at scale, making deprecation or changes to the feature much more difficult? How can we ensure experimental features maintain our high privacy and security standards? 38 | 39 | ## A sketch of a solution 40 | When reflecting on the problem we outlined earlier, it’s clear that we can’t change the fact that web browser engineers are fundamentally different people to web developers. For that reason, we focused our design efforts on coming up with a safe way to encourage web developers to try new features and provide us feedback while maintaining our ability to modify designs, ensure successful experiments result in eventual interoperability and ensure unsuccessful experiments are not baked into production websites. 41 | 42 | We believe these constraints are solvable with ‘origin trials’. **In summary, with origin trials**: 43 | - Developers are able to register for an experimental feature to be enabled on their origin for a fixed period of time measured in months. In exchange, they provide us their email address and agree to give feedback once the experiment ends. 44 | - Usage of these experiments is constrained to remain below Chrome’s deprecation threshold (< 0.5% of all Chrome page loads) by a system which automatically disables the experiment on all origins if this threshold is exceeded. 45 | 46 | This design is expanded in detail later, but first consider how this satisfies the constraints we outlined earlier: 47 | - **Encouraging developers to try features and provide feedback:** This system allows us to effectively communicate with these developers for the first time, and we believe the ability to use new features to build demos and prototypes that can be shared with friends, Twitter and beta testers will compel developers to try out these features. Production sites could run limited experiments to gauge the impact of a feature and provide that data as part of the feedback to the feature teams. 48 | - **Maintaining our ability to change our implementation:** The time-limited nature of an origin trial means that these features will self destruct after a few months whatever happens. This gives us clear cover for making breaking changes. Additionally, no large site can rely on these features for their full production traffic thanks to the usage constraint, so there is minimal risk in causing it to become a defacto-standard prematurely. 49 | - **Ensuring successful experiments result in eventual interoperability:** Developers will be very aware that the trial they signed up for will end soon, and that their site must therefore rely on proper feature detection (and degrade gracefully without the feature). Assuming the feature is a success we can then communicate any breaking changes to these developers, who can then make the changes and have the feature work with the finalized syntax. 50 | - **Ensuring unsuccessful experiments are not baked into production websites:** These experimental APIs will all stop working within a few months and developers will be very aware of this when they sign up. 51 | 52 | And when considering those additional risks we were worried about: 53 | - **Preventing premature production use from forcing us to keep an experimental feature available:** The automatic usage limiting minimizes the ability for major properties to rely on a feature before it is shipped, and the time-limited design means that inaction results in the feature reverting. 54 | - **Maintaining our high privacy and security standards:** Features launched as origin trials are only experimental in terms of their syntax and semantics. Otherwise these are features going out to actual end users, and as such will go through Chrome’s standard launch process the same as any other feature to ensure a high bar for privacy and security is maintained. 55 | 56 | This design also has the additional benefit that developers cannot simply copy paste code using experimental APIs from Stack Overflow as was possible with prefixes. 57 | 58 | To summarize this document so far: in order to design good features on the web, the web developer feedback needs to be the most important voice in the standards process. We have been very careful in designing origin trials and are tentatively declaring we believe it is safe way to make that possible. 59 | 60 | ## High-level design of the solution 61 | 62 | Earlier, we outlined two key aspects of the origin trials solution. First, using registration to establish a communication channel with developers. Second, using automated usage limits to prevent burn-in of experimental features and maintain flexibility in implementation. Here, we describe the high-level design of the solution. For more details on the design, see [Origin Trials Framework Design Outline](https://docs.google.com/document/d/1qVP2CK1lbfmtIJRIm6nwuEFFhGhYbtThLQPo3CSTtmg/). 63 | 64 | The high-level process for experimental features is: 65 | - An experimental feature is implemented in Chrome. 66 | - This follows the established [launch process](http://www.chromium.org/blink#launch-process) for web platform features, with the addition of an "Intent to Experiment" and other steps for experiments. 67 | - Feature authors (i.e. browser engineers) can refer to [this guide](https://dev.chromium.org/blink/origin-trials/running-an-origin-trial) for more details. 68 | - The feature author publishes an origin trial (i.e. experiment) for this feature. The trial must include an end date, to limit the duration. 69 | - Currently, this is a manual process where a feature is made available for registrations 70 | - We expect to automate this process, as part of a self-service developer console 71 | - Web developers register their origin to participate in the trial, and receive a trial token. 72 | - Registrations will be collected via the [developer console](https://developers.chrome.com/origintrials/). 73 | - More details are available in the [developer guide](developer-guide.md). 74 | - Web developers change their origin to embed the trial token. 75 | - The token must be embedded in their origin (via \ tag or HTTP header) 76 | - Again, details are available in the [developer guide](developer-guide.md). 77 | - Users visit the registered origin, and the Origin Trials Framework exposes the new feature, but only if a valid trial token is found. 78 | - In Chrome, the framework will extract any token found in the page. The token is checked for origin, feature and expiry date. Only if all the token data is valid, the framework will then allow the feature to be exposed via JavaScript. 79 | - The end date of the trial passes, all issued trial tokens expire, and the framework automatically prevents further access to the feature. 80 | - Feedback on the feature is requested from all registered developers 81 | - Feedback may also be solicited earlier, during the trial. 82 | 83 | ### Trial tokens 84 | 85 | After considering other mechanisms, we settled on using trial tokens to provide limited access to experimental features. We wanted a mechanism that provided a few important capabilities: 86 | - Features are disabled/off by default, but can be enabled/turned on (almost) immediately after a developer registers their origin 87 | - Features can be enabled with minimal performance impact, and without internet connectivity for every page load 88 | - Developers can control which individual pages have access to a feature, and/or which users have access to a feature 89 | 90 | Trial tokens are self-contained, verifiable blobs of text, which can safely be embedded in web pages. Each token is issued for a specific combination of origin and feature. It is not possible for a developer to use one token to enable multiple experimental features on their origin. As well, a token issued for a given origin and feature cannot be used to enable that same feature on a different origin. 91 | 92 | ### Monitoring and limiting usage 93 | 94 | As above, we've defined a cap that usage of a single experimental feature cannot exceed 0.5% of all Chrome page loads 95 | 96 | To enforce these limits, usage for each feature with an active origin trial will be monitored regularly. The primary source of data will be anonymous usage statistics collected by Chrome (i.e. [UseCounter](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/frame/use_counter.h)). With these usage statistics, we can determine if the limit is exceeded for each feature. 97 | 98 | When the usage limits are exceeded for a feature, the feature will be disabled for future use. As features are enabled by self-contained trial tokens, a separate mechanism is needed to revoke/override the access provided by otherwise valid tokens. In general we intend to use: 99 | - Feature-implemented Finch switches, that we require them to implement, or 100 | - If the API is permissioned, the global permissions kill switch which effectively denies permission to access the new API 101 | 102 | There are further steps we can take if there is some unforseen issue with the above kill switches, for example: 103 | - Remotely replace the token signing key on clients (effectively invalidates all tokens signed with the previous 104 | key). 105 | - Remotely disable the entire Origin Trials framework (disables all features exposed via trials). 106 | 107 | All the above mechanisms make use of the existing infrastructure in Chrome to push out information to installed browsers. For the feature-implemented switches, this makes use of the [field trials](https://cs.chromium.org/chromium/src/base/metrics/field_trial.h) infrastructure. For the origin trials revocation lists/signing key replacement, this makes use of the infrastructure for component updates. 108 | 109 | Different mechanisms will be used to disable a feature, depending on how the 110 | usage limits were exceeded. Initially, the feature-implemented switch will most 111 | commonly be used to disable the specific overused feature. 112 | 113 | ### Collecting developer feedback 114 | One of the main goals of origin trials is to enable browser vendors to collect developer feedback to help iterate on new features. With the registration process, we will be able to establish a communication channel with developers. We hope that developers will participate in the community around each experimental feature. Feedback is always valuable, so we'll encourage developers to provide informal/adhoc feedback during the trial, or join the mailing list/GitHub repo/etc. for each feature. 115 | 116 | ## FAQ 117 | 118 | *Why does this project exist?* 119 | - Sometimes we, the web standards community, spend years designing an API that turns out to be fundamentally flawed and then have to go back to the drawing board for a few more years before we can ship the right thing. We believe letting developers safely try experiments in production early will allow us to realize these mistakes earlier, increasing our ability to learn and ship the right things sooner. 120 | 121 | *Will all of these experiments ship eventually?* 122 | - Remember that these are only experiments. There is a good chance that some of them will never ship as standardized APIs on the web. These experimental features are essentially very similar to Chrome flags: an exciting glimpse into one possible future that you can play around with today, and provide feedback for. 123 | 124 | *What happens if a large site such as a Google service starts depending on an experimental API?* 125 | - Origin trials have a built-in safeguard that automatically disables an experimental API globally if its usage exceeds 0.5% of all Chrome page loads. This is to keep usage limited to developers experimenting and below Chrome’s threshold whereby features used on less than 0.5% of all page loads (as measured by Chrome Status) may be deprecated. 126 | 127 | *Isn’t this just vendor prefixing all over again?* 128 | - This topic has been explored in great depth in Alex Russell’s Medium post [Doing Science on the Web](https://medium.com/@slightlylate/doing-science-on-the-web-af26d9be2faa). A couple of key differences include the fact that these features automatically stop working before they become too broadly adopted and that developers cannot simply copy-paste code using an experimental API from the web since they would need to go through the experimental API signup process and accept that the feature is going to shortly stop working. 129 | 130 | *Does this change impact how we think about security or privacy on the web?* 131 | - No, these experimental APIs will all be approved as safe by Chrome’s privacy and security teams. 132 | 133 | *Is there any restriction on which websites can sign up to use experimental APIs?* 134 | - No, any website can sign up to use an experimental API. The only thing to note is that an experiment will be automatically shut off for all domains if it becomes used on more than 0.5% of all Chrome page loads, which means, unsurprisingly, experimental APIs aren’t suitable for full-production use on very large production sites such as the Google home page. Limited experimental use on very large production sites is encouraged, just not a full launch until the feature itself is no longer experimental. 135 | 136 | *Is there any review process for signing up a website to access an experimental API?* 137 | - No. We do not review domain content before generating a token. 138 | 139 | *Can one large website prevent anyone from accessing an origin trial (either maliciously or inadvertently)?* 140 | - We automatically disable any experiment that becomes used too broadly to prevent features from being used in production such that we wouldn't feel OK about breaking them. This does make it possible for a site to maliciously or inadvertently disable an experiment although in that case no developers will be depending on the feature in production since it is experimental so the harm is mitigated. 141 | 142 | *What is the structure of trial tokens?* 143 | - The properties and structure of trials tokens are discussed in detail in the [design document](https://docs.google.com/document/d/1qVP2CK1lbfmtIJRIm6nwuEFFhGhYbtThLQPo3CSTtmg/edit#bookmark=id.jtr9rupl4osm). 144 | 145 | *Why shouldn't browsers just use A/B experimentation techniques to test out web platform features* 146 | - It's common in software to rely on A/B experiments to compare one design to another. This isn't appropriate when experimenting with platform API surface area because it would make it extremely difficult for developers to reason about the behavior they're seeing from the platform (making the platform much less predictable). For example, when a user reports an issue, developers try to match the exact browser version and OS when attempting to reproduce the problem. When there's some other variable they don't know about (eg. rarely a user will have a special browser flag enabled), it inevitably causes a ton of frustration and confusion. 147 | -------------------------------------------------------------------------------- /developer-guide.md: -------------------------------------------------------------------------------- 1 | # Origin Trials Guide for Web Developers 2 | 3 | Origin trials allow developers to try out new features and give feedback on usability, practicality, and effectiveness to the web standards community. Your feedback is valuable input into the final decision about the feature design, or even whether we want to proceed with standardizing and enabling the feature by default. When a feature is available as an origin trial, you are able to register to have it enabled for all users on your origin for a fixed period of time. 4 | 5 | Once your origin has opted into a trial of an experimental feature you can then build demos and prototypes that your friends and beta testing users can try for the duration of the trial without them needing to flip special flags in Chrome. 6 | 7 | You can also run limited production experiments to evaluate the effectiveness of a feature at scale. You must be careful to limit the amount of traffic using the feature, as the trial will automatically disable if is used in more than 0.5% of Chrome page loads (across all sites). This is part of the protections in place to prevent the feature from becoming a defacto standard before the experimentation and standards work have completed. 8 | 9 | ## How do I enable an experimental feature on my origin? 10 | 11 | You can opt any page on your origin into the trial of an experimental feature by [requesting a token for your origin](https://developers.chrome.com/origintrials/). After signing up for a trial, we will generate a token for your origin. 12 | 13 | There are two ways to provide this token on any pages in your origin: 14 | 15 | - Add an `origin-trial` \ tag to the head of any page. For example this may look something like: 16 | 17 | ``` 18 | 19 | ``` 20 | 21 | - If you can configure your server, you can also provide the token on pages using an `Origin-Trial` HTTP header. The resulting response header should look something like: 22 | 23 | ``` 24 | Origin-Trial: **token as provided in the developer console** 25 | ``` 26 | 27 | **NOTE:** 28 | 29 | - You can provide multiple tokens for a given page. See [Can I provide multiple tokens on a page?](developer-guide.md#15-can-i-provide-multiple-tokens-on-a-page). 30 | - You can provide tokens programmatically, via script. See [Can I provide tokens by running script?](developer-guide.md#16-can-i-provide-tokens-by-running-script). 31 | 32 | If you have trouble configuring pages with your token, or need other help, please contact us at origin-trials-support@google.com. 33 | 34 | ## How can I experiment with the new feature locally? 35 | 36 | Each feature that is available as an origin trial can alternatively be enabled on individual machines by flipping the corresponding flag in about:flags. The correct flag depends on the feature, and should be mentioned in the blog post about that specific feature. 37 | 38 | You can get started experimenting with the new feature on `localhost` either by flipping the flag locally or requesting an origin trial token for `localhost`. 39 | 40 | For automated tests, you can enable the feature flag using a Chrome command-line parameter: ```--enable-blink-features=xxxxx```. 41 | 42 | ## What is the thinking behind origin trials? 43 | An exploration of the motivations and reasoning behind origin trials is provided in [the explainer](explainer.md). The TL;DR is that we strongly value the feedback of real web developers (that means you!) during the process of designing and standardizing new features. We believe origin trials provide a good way of encouraging that feedback, while being extremely careful that the experiments aren’t used by sites in production-critical roles or as if they’re finalized features. 44 | 45 | ## What experimental features are currently available? 46 | The [developer console](https://developers.chrome.com/origintrials/#/trials/active) lists all of the currently available features. 47 | 48 | ## FAQ 49 | 50 | ### 1. How can I find out about new experiments when they become available? 51 | 52 | - When you register for an origin trial token you will be automatically added to a mailing list. We'll use this list to send high level updates about the origin trials system, including announcing new features. 53 | - Additionally, we will be posting updates to [developers.google.com/web/updates/](http://developers.google.com/web/updates/) about each new feature that becomes available as an origin trial. 54 | 55 | ### 2. Will all of these experiments ship eventually? 56 | 57 | These are only experiments and there is a good chance that some of them will never ship as standardized features on the web. These experimental features are essentially very similar to Chrome flags: an exciting glimpse into one possible future that you can play around with today, and provide feedback for. 58 | 59 | ### 3. What happens if a large site such as a Google service starts depending on an experimental feature? 60 | 61 | Origin trials have a built-in safeguard that automatically disables an experimental feature globally if its total usage exceeds 0.5% of all Chrome page loads. This is to keep usage limited to developers experimenting and below Chrome’s threshold whereby features used on less than 0.5% of all page loads (as measured by [Chrome Status](https://www.chromestatus.com/metrics/feature/popularity)) may be deprecated. 62 | 63 | For very popular sites it is important to only experiment with a small portion of your traffic when participating in a trial. 64 | 65 | ### 4. Isn’t this just vendor prefixing all over again? 66 | 67 | This topic has been explored in depth in Alex Russell’s Medium post [Doing Science on the Web](https://medium.com/@slightlylate/doing-science-on-the-web-af26d9be2faa#.94pf1lwmp). A couple of key differences include: 68 | 69 | - These features automatically stop working before they become too broadly adopted. 70 | - Developers cannot simply copy-paste sample code using an experimental feature, as they must provide a unique trial token obtained via the experimental feature registration signup process (and accept that the feature is going to shortly stop working). 71 | 72 | ### 5. Does this change impact how we think about security or privacy on the web? 73 | 74 | No, these experimental features have all been held to the same high privacy and security standards as any Chrome platform feature. 75 | 76 | ### 6. Is there any restriction on which websites can sign up to use experimental features? 77 | 78 | Origin trials are available to any website served over HTTPS. Note that there is no policy against specific large sites opting into origin trials, but the system is designed to prevent large populations of the web depending on experimental features. To achieve that, origin trials have a built-in safeguard that automatically limits it globally if its usage exceeds 0.5% of all Chrome page loads. This means that experimental features aren’t suitable for full production use on large production sites such as the Google home page, though experiments with limited usage on large sites is encouraged. 79 | 80 | ### 7. Is there any review process for signing up a website to access an experimental feature? 81 | 82 | In most cases, no. We do not review domain content before generating a token. 83 | 84 | Participation in a trial may require additional criteria to be met before a token is generated. During the registration process, a link to the trial's participation criteria will be available before submission. Once your registration request is submitted, you will be provided with a link to your petition for participation. Additional information may be needed to verify your participation criteria is met. You will be notified by email of any updates to your origin trial participation request. 85 | 86 | ### 8. Is there a way to only enable an origin trial for some of my users or only some pages on my site? 87 | 88 | Yes, origin trials are enabled on a per-page basis. 89 | 90 | ### 9. Will these experiments work in Opera or other web browsers? 91 | 92 | Not today, but if this model proves to work well then it’s possible that other web browsers may build their own origin trials system. The experimental feature implementations likely won’t be compatible between browsers due to the nature of them being experimental. 93 | 94 | ### 10. Can I request a token for an origin that I don't own? 95 | 96 | Yes, you can technically request a token for an origin that you don't own. However, generating the token won't cause the feature to be enabled on that origin - unless it is served in the pages on that origin (either in the \ or as an HTTP header). Also note that these features have held up to the same high security and privacy standards as any other feature in Chrome. 97 | 98 | 99 | ### 11. Why do tokens expire before the trial ends? 100 | 101 | - The trial may have been extended after your last registration. Each token contains the 102 | expiration date and cannot be updated, so you must renew to generate a new token in this 103 | case. We'll also send you an email to invite you to renew and continue participating in the 104 | trial. 105 | - Prior to February 3, 2021, tokens were issued to be short-lived, lasting 6 weeks until they expire. 106 | Please see [How do I renew a token that is about to expire/has expired?](#renew) for how to renew your tokens 107 | to continue participating in the trial. 108 | 109 | 110 | ### 12. How do I renew a token that is about to expire/has expired? 111 | 112 | - You should receive a reminder email to renew the token before it expires. That email includes a 113 | link to the registration page in the [developer console](https://developers.chrome.com/origintrials/#/trials/active). 114 | You can also go directly to the page in the console, by finding the trial in the list on 115 | [My Registrations](https://developers.chrome.com/origintrials/#/trials/my). 116 | - On the registration page, use the Renew button to generate a new token. 117 | 118 | ### 13. I have multiple testing/staging domains, or subdomains that are programmatically generated. Do I need to request a token for every subdomain? 119 | 120 | - No, we can issue a single token that will match multiple subdomains. These tokens will behave similarly to wildcard matching (like specifying "\*.\"). For example, you can request a token for "example.com", and it will enable the feature on all origins whose suffix matches "example.com", including: 121 | - a.example.com 122 | - b.example.com 123 | - a.b.example.com 124 | - example.com 125 | - To ensure that an experimental feature is not enabled too broadly, there are some additional checks on requests for subdomain-matching tokens. Specifically, subdomain-matching tokens will not be issued for origins found in the [Public Suffix List](https://publicsuffix.org/). This restriction does not apply to deprecation trials, where subdomain-matching tokens are issued for all origins, regardless if they are found in the Public Suffix List. 126 | - Subdomains do not apply to IP addresses. Tokens issued for IP addresses will only allow exact matching on origin, as before. 127 | - You can request a subdomain token by filling out the appropriate field on the trial signup form. 128 | 129 | ### 14. Are there different types of trials? 130 | 131 | Yes, we've started using the origin trial infrastructure and console to allow developers to temporarily control Chrome's behavior in different ways. For example, to register for a [temporary extension to Web Components V0 deprecation](https://developers.chrome.com/origintrials/#/view_trial/2431943798780067841). We're also planning to have trials to allow developers to opt-in or opt-out of some Chrome interventions (especially those based on heuristics). Some aspects of these trials may be different, such as the expiry period for tokens. However, all types of trials will be limited in duration - this is not meant as a new mechanism for permanent configuration. 132 | 133 | ### 15. Can I provide multiple tokens on a page? 134 | 135 | Yes, you can provide multiple tokens for a given page. Only one valid token is required to enable a trial, any other invalid tokens or non-matching tokens are ignored. You may want to provide multiple tokens if the same page is served to different origins (e.g. example.com, example.ca, etc.). You can add multiple tokens in different ways: 136 | - Add multiple \ tags to the page, where each tag contains a single token. 137 | - Include multiple `Origin-Trial` response headers, where each header contains a single token. 138 | - Include a single `Origin-Trial` response header, with comma-separated tokens. 139 | 140 | ### 16. Can I provide tokens by running script? 141 | 142 | Yes, you can provide tokens programmatically, from a script running on a given page. A token 143 | can be provided by creating and injecting a \ tag into the head of the page, in the same 144 | format as would be provided in HTML markup. For example, using a function like: 145 | 146 | ``` 147 | function addTrialToken(tokenContents) { 148 | const tokenElement = document.createElement('meta'); 149 | tokenElement.httpEquiv = 'origin-trial'; 150 | tokenElement.content = tokenContents; 151 | document.head.appendChild(tokenElement); 152 | } 153 | ``` 154 | 155 | Limitations for tokens injected via script include: 156 | 157 | - The token must match the origin of the page containing the script (i.e. the *first-party* 158 | origin). For external scripts (e.g. included as `