Use origin trials in Microsoft Edge
Use origin trials to try out experimental APIs on your own live site for a limited period of time. When using origin trials, users of Microsoft Edge that visit your site can run code that uses experimental APIs.
To see a list of the available origin trials and register your origin to try out any of the origin trials, see Microsoft Edge Origin Trials. To assess the suitability of using the experimental APIs on your website, check the minimum version requirements for Microsoft Edge, and check the trial expiration date.
You can provide feedback to browser feature engineers and the web standards community about the design of the feature's API, your use-cases, or your experience with using the feature's API, by using the Issues tab in the browser feature's repo.
The origin-trials mechanism allows a user of your webpage to use the origin trial's experimental feature API in their Microsoft Edge browser, despite the feature's off-by-default state. The user's Microsoft Edge browser detects the origin trial's token, and then automatically turns on the browser's feature flag that corresponds to the origin trial for which the token is valid. The user doesn't need to set any edge://flags
in Microsoft Edge.
To support using an origin trial's experimental APIs in your website:
Register the origin domain that you want to use the experimental feature on (for example,
https://example.com
), and then an origin trial token is generated for you.Copy the token to your webpage within a
<head>/<meta>
element, or in anOrigin-Trial
HTTP server response header.When a Microsoft Edge user visits your webpage and the browser finds an origin-trial token, the browser turns on the associated origin-trial feature.
To register for an origin trial:
Go to Microsoft Edge Origin Trials.
To sign up for the Ad Selection API origin trial, instead see Sign up for the Ad Selection API.
Select an active trial.
Click the I Accept the Terms of Use button.
If you are prompted to, sign in. For example, sign in to GitHub, and then authorize the Microsoft Edge Origin Trials page to use the account sign-in.
The New Origin Trial Registration form opens:
In the Domain text box, enter a domain URL (such as
https://example.com
) or a subdomain URL (such ashttps://beta.example.com
).You can configure the origin trial token to support any of the following:
- A single domain, such as
https://example.com
, without supporting its subdomains. - A single subdomain, such as
https://beta.example.com
. - A domain, such as
https://example.com
, and its subdomains, such ashttps://beta.example.com
.
Trailing paths and query parameters aren't supported. If a URI is entered that has a trailing path or a query parameter, such as
https://example.com/path/new-feature
, the root domain (such ashttps://example.com
) or subdomain will be registered, ignoring any trailing path or query parameters.- A single domain, such as
Set the Enable token for subdomains? toggle.
To enable using the origin trial at a domain (such as
https://example.com
) without supporting its subdomains (such ashttps://beta.example.com
), make sure the Enable token for subdomains? toggle is turned off.To enable using the origin trial only at a specific subdomain (such as
https://beta.example.com
), make sure the Enable token for subdomains? toggle is turned off.To enable using the origin trial at a domain (such as
https://example.com
) and its subdomains (such ashttps://beta.example.com
), turn on the Enable token for subdomains? toggle.
Click the Submit button.
An origin trial token is generated, and is displayed in the Registrations section near the New Origin Trial Registration form:
Click the Copy button, and then paste the origin trial token into a safe place, noting which domain it's for. You can also view this information in this webpage later.
Use the token at your website in either of the following ways:
Within the <head>
element of a webpage, include the following <meta>
tag:
<meta http-equiv="origin-trial" content="EXAMPLE_TOKEN">
Replace EXAMPLE_TOKEN
by your token.
In your HTTP server response, add the following HTTP header:
Origin-Trial: EXAMPLE_TOKEN
Replace EXAMPLE_TOKEN
by your token.
To opt out of an experiment (origin trial) that you're enrolled in, remove the origin trial token from the <meta>
tag or from the server response headers.
Treat origin trials as experimental. As a best practice, in your website code, perform feature detection and provide graceful fallback for these cases:
- If the experimental feature API isn't available in the user's browser.
- If the origin-trial token expires.
- If the Microsoft Edge feature team ends the origin trial.
See Implementing feature detection at MDN.
To test an origin-trial feature at localhost
, go to edge://flags
and turn on the appropriate feature flag.
The mechanism that detects and uses Microsoft Edge origin-trial tokens is only supported for SSL-enabled domains, not for localhost
.
Origin trial tokens expire in 6 weeks, by default. When the origin trial token expires, you must renew the token, which means generating a fresh, new token for this origin trial. You can renew the token before it expires.
To renew an origin trial token:
Go to Microsoft Edge Origin Trials.
For the Ad Selection API origin trial, instead see Sign up for the Ad Selection API.
In the My Registered Trials section, select an origin trial.
In the Registrations section, in a token row that contains an Expired badge, click the Renew button:
A fresh token is generated and displayed.
In the row that contains the new token, click the Copy button, and then paste the fresh token into your code.
An origin trial may last until the planned expiration date, or may end early.
After you register for a trial, your token remains valid until the trial expiration date shown on the origin trial's informational card. After the origin trial's expiration date, the token will no longer function, and the feature that's associated with the origin trial will be considered ready to ship, or the feature will be withheld for further development.
A Microsoft Edge feature team may decide to end an experiment early, before the trial expiration date; for example:
- If a security incident is caused by the feature.
- If the feature team has collected enough feedback and has concluded that the currently proposed API doesn't meet the needs of web developers, and a major redesign needs to happen.
If an experiment ends early, the feature team that owns the origin trial sends emails to all developers who are enrolled in the experiment.
Please provide feedback about the experimental feature. The Issues tab of the feature's GitHub repo allows public discourse about the usability and stability of the feature.
To provide feedback about an origin trial:
Go to Microsoft Edge Origin Trials.
Select an active trial.
Click the Feedback button. The Issues tab of the product's GitHub repo opens.
View the issues.
If a new issue is needed, click the New issue button.
For the Ad Selection API origin trial, instead see Provide feedback about the origin trial in Sign up for the Ad Selection API.
- Microsoft Edge Origin Trials - Developer.microsoft.com.
Ad Selection API:
- Sign up for the Ad Selection API
- Microsoft Edge Origin Trials - portal at Github.io, for the Ad Selection API origin trial only.
External:
- Implementing feature detection - MDN.
- Get started with origin trials - Chrome docs.