OriginTrials

Origin Trials Guide for Web Developers

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. Note that when the trial finishes we will contact you with a request to provide this feedback.

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.

How do I enable an experimental feature on my origin?

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:

NOTE:

If you have trouble configuring pages with your token, or need other help, please contact us at origin-trials-support@google.com.

How can I experiment with the new feature locally?

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.

What is the thinking behind origin trials?

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.

What experimental features are currently available?

The developer console lists all of the currently available features.

FAQ

1. How can I find out about new experiments when they become available?

2. Will all of these experiments ship eventually?

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 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.

4. Isn’t this just vendor prefixing all over again?

This topic has been explored in depth in Alex Russell’s Medium post Doing Science on the Web. A couple of key differences include:

5. Does this change impact how we think about security or privacy on the web?

No, these experimental features have all been held to the same high privacy and security standards as any Chrome platform feature.

6. Is there any restriction on which websites can sign up to use experimental features?

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 use on large production sites such as the Google home page.

7. Is there any review process for signing up a website to access an experimental feature?

No. We do not review domain content before generating a token.

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.

9. Will these experiments work in Opera or other web browsers?

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.

10. Can I request a token for an origin that I don’t own?

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.

11. Why do tokens expire before the trial ends?

12. How do I renew a token that is about to expire/has expired?

13. I have multiple testing/staging domains, or subdomains that are programmatically generated. Do I need to request a token for every subdomain?

14. Are there different types of trials?

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.

15. Can I provide multiple tokens on a page?

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:

16. Can I provide tokens by running script?

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:

17. Are experimental features enabled in iframes?

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.

18. How can I enable an experimental feature as embedded content on different domains?

19. Are there any usage limits on experimental features?

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.

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.

20. What are the options for usage restrictions on tokens?

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:

21. What does the Valid Until date mean for my tokens?

22. How do I keep my tokens active for the entire trial?

23. How are tokens verified?

Tokens are self-contained and verified by Chrome on-device, without any server calls or network access.

24. Does token verification have a performance impact?

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.