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.
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.
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.
You can opt any page on your origin into the trial of an experimental feature by requesting a token for your origin. After signing up for a trial, we will generate a token for your origin.
There are two ways to provide this token on any pages in your origin:
-
Add an
origin-trial<meta> tag to the head of any page. For example this may look something like:<meta http-equiv="origin-trial" content="**insert your token as provided in the developer console**"> -
If you can configure your server, you can also provide the token on pages using an
Origin-TrialHTTP header. The resulting response header should look something like:Origin-Trial: **token as provided in the developer console**
NOTE:
- You can provide multiple tokens for a given page. See Can I provide multiple tokens on a page?.
- You can provide tokens programmatically, via script. See Can I provide tokens by running script?.
If you have trouble configuring pages with your token, or need other help, please contact us at [email protected].
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.
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.
For automated tests, you can enable the feature flag using a Chrome command-line parameter: --enable-blink-features=xxxxx.
An exploration of the motivations and reasoning behind origin trials is provided in the explainer. 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.
The developer console lists all of the currently available features.
- 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.
- Additionally, we will be posting updates to developers.google.com/web/updates/ about each new feature that becomes available as an origin trial.
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.
3. What happens if a large site such as a Google service starts depending on an experimental feature?
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) may be deprecated.
For very popular sites it is important to only experiment with a small portion of your traffic when participating in a trial.
This topic has been explored in depth in Alex Russell’s Medium post Doing Science on the Web. A couple of key differences include:
- These features automatically stop working before they become too broadly adopted.
- 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).
No, these experimental features have all been held to the same high privacy and security standards as any Chrome platform feature.
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.
In most cases, no. We do not review domain content before generating a token.
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.
8. Is there a way to only enable an origin trial for some of my users or only some pages on my site?
Yes, origin trials are enabled on a per-page basis.
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.
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 <head> 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.
- The trial may have been extended after your last registration. Each token contains the expiration date and cannot be updated, so you must renew to generate a new token in this case. We'll also send you an email to invite you to renew and continue participating in the trial.
- Prior to February 3, 2021, tokens were issued to be short-lived, lasting 6 weeks until they expire. Please see How do I renew a token that is about to expire/has expired? for how to renew your tokens to continue participating in the trial.
- You should receive a reminder email to renew the token before it expires. That email includes a link to the registration page in the developer console. You can also go directly to the page in the console, by finding the trial in the list on My Registrations.
- On the registration page, use the Renew button to generate a new token.
13. I have multiple testing/staging domains, or subdomains that are programmatically generated. Do I need to request a token for every subdomain?
- No, we can issue a single token that will match multiple subdomains. These tokens will behave similarly to wildcard matching (like specifying "*.<some domain>"). 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:
- a.example.com
- b.example.com
- a.b.example.com
- example.com
- 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. 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.
- Subdomains do not apply to IP addresses. Tokens issued for IP addresses will only allow exact matching on origin, as before.
- You can request a subdomain token by filling out the appropriate field on the trial signup form.
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. 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.
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:
- Add multiple <meta> tags to the page, where each tag contains a single token.
- Include multiple
Origin-Trialresponse headers, where each header contains a single token. - Include a single
Origin-Trialresponse header, with comma-separated tokens.
Yes, you can provide tokens programmatically, from a script running on a given page. A token can be provided by creating and injecting a <meta> tag into the head of the page, in the same format as would be provided in HTML markup. For example, using a function like:
function addTrialToken(tokenContents) {
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = tokenContents;
document.head.appendChild(tokenElement);
}
Limitations for tokens injected via script include:
- The token must match the origin of the page containing the script (i.e. the first-party
origin). For external scripts (e.g. included as
<script src="some origin">), the token validation ignores the origin of the script. This does not apply to third-party tokens. - The token can usually be injected later in the page lifecycle (e.g. after loading), but must be injected before any attempt to use the experimental feature, including feature detection. For experimental features that are exposed to JavaScript, once the token is injected, you'll be able to test for API presence as expected.
- There may be experimental features that are not compatible with token injection via script. For example, features that affect the initial loading of a page or require configuration via HTTP response headers.
Not by default — iframes in a page do not inherit the experimental features that are enabled from their containing page. When the page provides a token to enable an experimental feature, that only applies to the top-level document. Each iframe is considered a separate document, and must independently provide a valid token to enable an experimental feature. As well, each iframe must provide a token that matches its own origin, not the origin of the containing page. Finally, this applies to all nested iframes.
The behavior is different when the origin trial enables an experimental feature that is also controlled by Permission Policy. Some policy-controlled features must be delegated to an iframe from its parent (see How is a Policy Specified? in the explainer). For delegation to work, both the parent and the iframe must provide a valid token to enable the experimental feature.
-
You can enable an experimental feature as embedded content, as long as you have third-party script running in the containing page.
-
To enable as embedded content, there are two options to request the appropriate tokens(s):
- Register for a token for each target origin.
- Available for all trials.
- May be feasible if you have a known, short list of the domains that embed your content.
- Requires you to provide the correct token from your script, which matches the containing page.
- Register once for a third-party token for your own origin.
- Currently, available on a limited basis for some trials.
- Requests are subject to verification to prevent misuse.
- Allows you to use a single token on any embedding page, regardless of its origin.
- Requires you to provide the token from a script served from your origin. Inline scripts are not supported.
- Register for a token for each target origin.
-
Your third-party script must provide the appropriate token as described in Can I provide tokens by running script?.
Origin trials have a built-in safeguard that automatically disables an experimental feature if its usage exceeds a small percentage of all Chrome page loads. This is designed to prevent individual web sites, and large populations of the web, from depending on experimental features.
Deprecation trials are not subject to such limits as they are not introducing a new feature and therefore there is no risk of depending on experimental features. Similarly, trials where existing functionality is removed are not constrained as the same risk doesn not apply.
The standard usage limit for a trial is 0.5% of all Chrome page loads, based on the same statistics as in Chrome Status. The usage is measured in a way to allow for temporary spikes of higher usage. In rare exceptions, a trial may be approved for a higher usage limit, only when necessary to allow for more effective experimentation (e.g. statistical significance requires a larger sample size of page loads).
This means that large production sites can try out experimental features, but they must take care to limit usage to a suitable portion of their traffic.
By default, tokens are issued without any usage restriction. This means that when a token is valid for a page, the experimental feature will always be enabled on that page (assuming it hasn't been disabled for exceeding usage limits).
For some trials, there will be options for different usage restrictions when registering for a token. If available, the choices are:
- Standard Limit: This is the default behavior, where the global usage limit is the only restriction (described above).
- User Subset: A small percentage of Chrome users will always be excluded from the trial, even when a valid token is provided. The exclusion percentage varies for each trial, but is typically less than 5%.
Tokens are considered valid by Chrome up to the expiry date. The expiry date is usually the same as the end date of the origin trial. See Question 11.
As of February 12, 2024, submitting feedback for a trial is optional, but encouraged. Over the course of your participation in the trial, you may receive notifications to ask for your feedback on the feature.
Tokens are self-contained and verified by Chrome on-device, without any server calls or network access.
Verifying a token requires some parsing/decoding of the token, and a crypto call, but the performance impact is unlikely to be observable on any page.