For the full context on origin trials, please see the explainer. This is the feature author guide for Blink contributors.
Here, we describe what is involved in running an origin trials experiment for a new browser feature. Most importantly, origin trials are integrated into the launch process for new web platform features. You should be following that overall process (maybe you ended up here from that page).
If you answer “yes” to any of the following questions, you should consider running an origin trial (see caveat in ).
- Is there disagreement about how well this API satisfies its intended use case?
- Are you unsure about what API shape will be the most ergonomic in real world scenarios?
- Is it hard to quantify performance gains without testing on real world sites?
- Is there a reason that this API needs to be deployed to real users, rather than behind a flag, for data to be meaningful?
 Origin trials should be run for a specific reason. These questions are guidance to identifying that reason. However, there is still debate about the right reasons, so the guidance may change. You can join the conversation in this doc.
If you're planning to run an Origin Trial please first schedule a meeting with the Origin Trials core team to quickly talk over your feature and the reason for running the trial. To set up this meeting you can email firstname.lastname@example.org or email@example.com. Google employees can alternatively schedule a meeting directly with firstname.lastname@example.org.
- an HTTP Origin-Trial header in the server response,
- an HTML <META> tag in the document's head, or
- (for Dedicated Workers only) the HTTP response or document head of the parent document.
The logic for enabling includes a check of your runtime feature flag (even if the origin trials framework isn't being used). This means you can easily test your feature locally, even without any trial tokens.
Origin Trials are being enabled in documents (for both inline and external scripts), and in service, shared, and dedicated workers. (Note that for service workers and shared workers, HTTP headers are the only way to enable trials. Dedicated workers will also inherit any trials enabled by their parent document).
If an experiment gets out of hand (way too popular to be an experiment anymore, for instance), we’ll be able to turn it off remotely, for all origins. Similarly, if there turns out to be major problems with the implementation of the framework itself, we’ll be able to turn it off completely, and disable all trials. (Hopefully we don’t have to do that, but we're still in the early stages of origin trials, and we’re being careful.)
- Be approved by the internal Chrome launch review process
- Users may be exposed to your feature without opting in, so the appropriate measures must be taken for privacy, security, etc.
- Have a way to remotely disable the feature
- Origin trials provides infrastructure to disable a feature (or a specific origin), but this only applies to the exposure as an origin trial. That means, any interface(s) controlled by the trial will be disabled, but it will still be possible to enable the feature via its runtime flag. As well, all of the token validation/revocation happens in the renderer.
- If the previous point is not sufficient for disabling the feature, you should implement a kill switch that allows your feature to be disabled remotely via Finch
- This can use the existing functionality in PermissionContextBase or base::FeatureList, or be a feature-specific implementation.
- Have UMA metrics to track feature usage
- Typically you will record usage with UseCounter
- The feature must have a corresponding entry in the enum UseCounter::Feature.
- If not exposed via IDL, the appropriate UseCounter::count*() method can be used directly from your feature implementation.
- Your feature may use a different UMA metric to track usage. For example, if it's not feasible to integrate with UseCounter, usage is best tracked outside a renderer, etc.
- Have an established community for discussion of the feature
- At a minimum, this should be a WICG group, Github repo, etc. Anywhere developers can find discussion or log issues about your feature
- The origin trials system will facilitate collecting feedback from web developers. However, the goal is to have web developers participate in the existing community around the feature
- Prepared a blog post/article/landing page introducing the feature
- There needs to be single link that will provide details about the feature
- Should make it clear how developers provide feedback/log issues for your feature
- This could be the README.md in your Github repo, or any other page of your choice
- Should include details about availability via origin trials
Please see our overview of the timeline for running a trial and collecting feedback. Contact email@example.com with any questions.Blink launch process. Please contact firstname.lastname@example.org with any questions about these steps, .f you don't have access to any of the links below the mailing list can help find someone to guide you.
Running an origin trial requires the following:
- Make sure your feature is ready to run an origin trial experiment (see above)
- Email email@example.com letting them know you plan to run an origin trial
- Review go/newChromeFeature and determine what launch approvals you require
- Integrate with the origin trials framework (see below)
- Send an Intent to Experiment
- Add your feature to go/origin-trials-feature-pipeline. This will ensure it is tracked correctly,
- Land the feature in Chrome prior to beta
- Publish a blog post on developers.google.com/web/updates about the feature when it lands beta (contact firstname.lastname@example.org for assistance if needed)
- The origin trials team will add your feature to the sign up form, and to the list of available trials.
- See below for more details
- You can review the sign ups for your feature (and renewals) by following the links in the Origin Trials feature pipeline spreadsheet.
In some cases, this may lead to a chicken-and-egg problem. For example, you may not want to publish a blog post until the feature is added the form. If the blog post has detailed information on joining the origin trial, it doesn't make sense to publish and have web developers unable to see your feature on the sign up form. Conversely, if the feature is added to the form first, web developers can (and have in the past) seen the change and signed up before the docs are ready.
- Publish the blog post for the feature when the beta release is available
- Include instructions about the origin trial, and a link to the signup form (bit.ly/OriginTrialSignup)
- Ensure the correct link to the blog post is recorded in go/origin-trials-feature-pipeline.
- Notify the origin trials team that the trial is ready for signups
- Origin trials team will add the feature to the signup form, and the list of available trials
For our 2017 plans, see bit.ly/origin-trials-in-2017.
To follow the most up-to-date progress and plans, filter in crbug.com for “component:Internals>OriginTrials”.