the Chromium logo

The Chromium Projects

Running an Origin Trial

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

Should you run an origin trial?

Origin trials are intended to be used to ensure we design the best possible features by getting feedback from developers before the standard is finalized. They may also be used to prove developer interest in a feature proposal that is otherwise undesired due to an expected lack of interest. Typically, you should have a specific hypothesis that you wish to test by collecting data.

If you answer “yes” to any of the following questions, you should consider running an origin trial (see caveat in [1]).

[1] 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 contact the origin trials team (OT team) to quickly talk over your feature and the reason for running the trial. You can email experimentation-dev@chromium.org or chasej@chromium.org. Google employees can alternatively contact origin-trials-core@google.com.

How do origin trials work in Chrome?

The framework will enable features at runtime, on a per-execution-context basis (practically, this will be per-document or per-worker). Features are disabled by default, and only be enabled if a properly signed token, scoped to the origin that it is being presented on, and scoped to the specific feature name, is present in either:

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

Is your feature ready to be an origin trial?

Before running an origin trial experiment, your feature needs to be ready for both web developers and users. Your feature must satisfy the following:

What is the actual process to run an origin trial?

First review the Blink launch process. Please contact experimentation-dev@chromium.org with any questions about these steps. If 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:

Note that these steps are not meant to be sequential. For example, you can certainly start integrating your feature with origin trials prior to getting various launch approvals.

Adding your feature to the public developer console

The configuration of a trial in the developer console requires basic information, including some public landing page/documentation link (see above). In some cases, this may seem like a chicken-and-egg problem. For example, you may not want to publish a blog post until the feature is ready for developers. 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 register. Fortunately, a trial can be configured in the developer console in advance, separately from making it available to the public.

Recommended process:

How long do Origin Trials typically last?

Origin trials can run for up to 6 milestones (~24 weeks), and can be extended under certain conditions. See here for more details.

What is the process to extend an origin trial?

Origin trials are not intended as a mechanism for shipping a feature early without following the full launch process. This is one of the reasons that each trial has a predefined end date (rather than running indefinitely until the feature ships). That said, there are situations where it is beneficial to allow experimentation to continue beyond the planned end date of the trial.

There two general cases where experimentation may continue beyond the planned end date:

  1. Unexpected delays in releasing
    • With the 6 week Chrome release cycle, code may not land in the intended release, meaning it is not shipped until the subsequent release. Alternatively, the code may land in the release, but the Chrome stable rollout is delayed, meaning it not available/installed until much later than expected. When a trial typically runs for 18 weeks (3 Chrome releases), such delays can significantly impact the availability of the experimental feature and the ability to collect sufficient data. For features that transition from origin trial to shipping in consecutive releases, the unavailability of the feature might extend well beyond the intended 1 week gap.
  2. Feature changes or new areas experimentation
    • As the origin trial progress, you may determine that a feature is not ready to be shipped, but do want to continuing experimenting. For example, feedback indicates that changes are needed to the feature (especially in API surface), but the changes would benefit from further feedback. In other cases, the hypothesis for the experiment may be proved or disproved, but you uncover new hypotheses for experimentation.

Consult with the OT team to figure out if you're in a situation where it makes sense to continue experimenting. For unexpected delays (1), this generally means requesting an extension to the trial end date. For feature changes and such (2), this generally means starting a new origin trial, to follow the previous trial.

In order to be eligible for an extension, you must demonstrate substantial progress towards meeting the bar for shipping the feature. See here for more details.

How to setup an extension or continued experiment?

The process is as follows:

How to integrate your feature with the framework?

The integration instructions now live in the Chromium source repo: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/origin_trials_integration.md

Roadmap

All of this may change, as we respond to your feedback about the framework itself. Please let us know how it works, and what's missing! To follow the most up-to-date progress and plans, filter in crbug.com for “component:Internals>OriginTrials”.