Skip to content

Commit 6198ec9

Browse files
captainbrossetcaptainbrosset
authored
Merge pull request #3288 from MicrosoftDocs/user/leahtu/origin-trials-update
Update "Use Origin Trials in Microsoft Edge" per new OT portal
2 parents bcc96ab + cb44872 commit 6198ec9

File tree

14 files changed

+307
-59
lines changed

14 files changed

+307
-59
lines changed

‎microsoft-edge/develop-web-microsoft-edge.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ See [Introduction to Microsoft Edge WebView2](webview2/index.md).
9191
The following are tools to automate testing in Microsoft Edge:
9292

9393
* **DevTools Protocol** is used to instrument, inspect, debug, and profile browsers.
94-
* Use **Origin Trials** to try experimental APIs.
94+
* Use **origin trials** to try experimental APIs.
9595
* **Playwright** provides cross-browser automation through a single API.
9696
* **Puppeteer**'s API controls Microsoft Edge via DevTools Protocol.
9797
* **WebDriver** simulates user interaction with Microsoft Edge.

‎microsoft-edge/developer/index.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -260,16 +260,16 @@ landingContent:
260260
- text: DevTools Protocol
261261
url: ../devtools-protocol-chromium/index.md # https://learn.microsoft.com/microsoft-edge/devtools-protocol-chromium/
262262

263-
- text: Origin Trials
263+
- text: Use origin trials in Microsoft Edge
264264
url: ../origin-trials/index.md
265265

266-
- text: Playwright
266+
- text: Use Playwright to automate and test in Microsoft Edge
267267
url: ../playwright/index.md
268268

269-
- text: Puppeteer
269+
- text: Puppeteer overview
270270
url: ../puppeteer/index.md
271271

272-
- text: WebDriver
272+
- text: Use WebDriver to automate Microsoft Edge
273273
url: ../webdriver-chromium/index.md
274274

275275
- text: webhint extension for Visual Studio Code

‎microsoft-edge/index.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -309,19 +309,19 @@ conceptualContent:
309309
url: ./test-and-automation/devtools-protocol.md
310310
itemType: how-to-guide
311311

312-
- text: Origin Trials
312+
- text: Use origin trials in Microsoft Edge
313313
url: ./origin-trials/index.md
314314
itemType: overview
315315

316-
- text: Playwright
316+
- text: Use Playwright to automate and test in Microsoft Edge
317317
url: ./playwright/index.md
318318
itemType: overview
319319

320-
- text: Puppeteer
320+
- text: Puppeteer overview
321321
url: ./puppeteer/index.md
322322
itemType: how-to-guide
323323

324-
- text: WebDriver
324+
- text: Use WebDriver to automate Microsoft Edge
325325
url: ./webdriver-chromium/index.md
326326
itemType: how-to-guide
327327

‎microsoft-edge/origin-trials/index-images/reg-form.png

32.9 KB
Loading

‎microsoft-edge/origin-trials/index-images/renew-token.png

56.9 KB
Loading

‎microsoft-edge/origin-trials/index-images/token-displayed.png

48.6 KB
Loading

‎microsoft-edge/origin-trials/index.md

Lines changed: 194 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,211 @@
11
---
2-
title: Use Origin Trials in Microsoft Edge
2+
title: Use origin trials in Microsoft Edge
33
description: Safely experiment for a fixed period of time and provide feedback on new platform features.
44
author: MSEdgeTeam
55
ms.author: msedgedevrel
66
ms.topic: conceptual
77
ms.service: microsoft-edge
8-
ms.date: 10/25/2023
8+
ms.date: 10/18/2024
99
---
10-
# Use Origin Trials in Microsoft Edge
10+
# Use origin trials in Microsoft Edge
1111

12-
You can 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 might run code that uses experimental APIs.
12+
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.
1313

14-
To support the experimental APIs, users don't need to go to `edge://flags` on their own device to access the experimental APIs that your site uses. Instead, you register the origin that you want to use the experimental feature on (for example, `https://www.contoso.com:443`), and you'll then be sent a token that you add to the code of your website.
14+
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](https://developer.microsoft.com/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.
1515

16-
To see a list of the available origin trials and register your origin to give them a try, see [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/). To assess the suitability of using the experimental APIs on your website, check the minimum version requirements for Microsoft Edge, and the trial end date.
16+
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.
1717

18-
You can also provide feedback to browser engineers and the web standards community about the design of the API, your use cases, or your experience using the APIs.
1918

20-
For more information, see the **Getting Started** and **Developer Guidelines** sections in [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/).
19+
<!-- ------------------------------ -->
20+
#### How the origin trial token works
21+
22+
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.
23+
24+
To support using an origin trial's experimental APIs in your website:
25+
26+
1. 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.
27+
28+
1. Copy the token to your webpage within a `<head>/<meta>` element, or in an `Origin-Trial` HTTP server response header.
29+
30+
1. 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.
31+
32+
33+
<!-- ====================================================================== -->
34+
## Registering for an origin trial
35+
<!-- fwlink that points to this anchor/ article section heading: pending -->
36+
<!-- if no fwlink is defined & used at portal: don't change wording of heading, b/c the "Register for an experiment" card at https://developer.microsoft.com/microsoft-edge/origin-trials links to this heading/anchor -->
37+
38+
To register for an origin trial:
39+
40+
1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
41+
42+
To sign up for the Ad Selection API origin trial, instead see [Sign up for the Ad Selection API](../web-platform/ad-selection-api.md).
43+
44+
1. Select an active trial.
45+
46+
1. Click the **I Accept the Terms of Use** button.
47+
48+
1. 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.
49+
50+
The **New Origin Trial Registration** form opens:
51+
52+
![New Origin Trial Registration form](./index-images/reg-form.png)
53+
54+
1. In the **Domain** text box, enter a domain URL (such as `https://example.com`) or a subdomain URL (such as `https://beta.example.com`).
55+
56+
You can configure the origin trial token to support any of the following:
57+
* A single domain, such as `https://example.com`, without supporting its subdomains.
58+
* A single subdomain, such as `https://beta.example.com`.
59+
* A domain, such as `https://example.com`, and its subdomains, such as `https://beta.example.com`.
60+
61+
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 as `https://example.com`) or subdomain will be registered, ignoring any trailing path or query parameters.
62+
63+
1. Set the **Enable token for subdomains?** toggle.
64+
65+
* To enable using the origin trial at a domain (such as `https://example.com`) without supporting its subdomains (such as `https://beta.example.com`), make sure the **Enable token for subdomains?** toggle is turned off.
66+
67+
* 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.
68+
69+
* To enable using the origin trial at a domain (such as `https://example.com`) and its subdomains (such as `https://beta.example.com`), turn on the **Enable token for subdomains?** toggle.
70+
71+
1. Click the **Submit** button.
72+
73+
An origin trial token is generated, and is displayed in the **Registrations** section near the **New Origin Trial Registration** form:
74+
75+
![The generated token displayed in the Registration section](./index-images/token-displayed.png)
76+
77+
1. 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.
78+
79+
80+
<!-- ====================================================================== -->
81+
## Using the origin trial token at your website
82+
<!-- fwlink that points to this anchor/ article section heading: pending -->
83+
<!-- if no fwlink is defined & used at portal: don't change wording of heading, b/c the "Enable the Origin Trial in your site's code" card at https://developer.microsoft.com/microsoft-edge/origin-trials links to this heading/anchor -->
84+
85+
Use the token at your website in either of the following ways:
86+
87+
88+
<!-- ------------------------------ -->
89+
#### Option 1: A \<meta\> tag within the \<head\> element of a webpage
90+
91+
Within the `<head>` element of a webpage, include the following `<meta>` tag:
92+
93+
`<meta http-equiv="origin-trial" content="EXAMPLE_TOKEN">`
94+
95+
Replace `EXAMPLE_TOKEN` by your token.
96+
97+
98+
<!-- ------------------------------ -->
99+
#### Option 2: An HTTP header in your HTTP server response
100+
101+
In your HTTP server response, add the following HTTP header:
102+
103+
`Origin-Trial: EXAMPLE_TOKEN`
104+
105+
Replace `EXAMPLE_TOKEN` by your token.
106+
107+
108+
<!-- ------------------------------ -->
109+
#### Opting out of an origin trial experiment
110+
111+
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.
112+
113+
114+
<!-- ====================================================================== -->
115+
## Performing feature detection and providing graceful fallback
116+
117+
Treat origin trials as experimental. As a best practice, in your website code, perform feature detection and provide graceful fallback for these cases:
118+
* If the experimental feature API isn't available in the user's browser.
119+
* If the origin-trial token expires.
120+
* If the Microsoft Edge feature team ends the origin trial.
121+
122+
See [Implementing feature detection](https://developer.mozilla.org/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) at MDN.
123+
124+
125+
<!-- ====================================================================== -->
126+
## Testing an origin trial at `localhost`
127+
128+
To test an origin-trial feature at `localhost`, go to `edge://flags` and turn on the appropriate feature flag.
129+
130+
The mechanism that detects and uses Microsoft Edge origin-trial tokens is only supported for SSL-enabled domains, not for `localhost`.
131+
132+
133+
<!-- ====================================================================== -->
134+
## Renewing an origin trial token
135+
136+
Origin trial tokens expire in 6 weeks, by default<!-- todo: strike or clarify -->. 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.
137+
138+
To renew an origin trial token:
139+
140+
1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
141+
142+
For the Ad Selection API origin trial, instead see [Sign up for the Ad Selection API](../web-platform/ad-selection-api.md).
143+
144+
1. In the **My Registered Trials** section, select an origin trial.
145+
146+
1. In the **Registrations** section, in a token row that contains an **Expired** badge, click the **Renew** button:
147+
148+
![UI to renewing a token](./index-images/renew-token.png)
149+
150+
A fresh token is generated and displayed.
151+
152+
1. In the row that contains the new token, click the **Copy** button, and then paste the fresh token into your code.
153+
154+
155+
<!-- ====================================================================== -->
156+
## Duration of an origin trial
157+
158+
An origin trial may last until the planned expiration date, or may end early.
159+
160+
161+
<!-- ------------------------------ -->
162+
#### Scheduled expiration date
163+
164+
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.
165+
166+
167+
<!-- ------------------------------ -->
168+
#### Early end
169+
170+
A Microsoft Edge feature team may decide to end an experiment early, before the trial expiration date; for example:
171+
* If a security incident is caused by the feature.
172+
* 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.
173+
174+
If an experiment ends early, the feature team that owns the origin trial sends emails to all developers who are enrolled in the experiment.
175+
176+
177+
<!-- ====================================================================== -->
178+
## Providing feedback about an origin trial
179+
180+
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.
181+
182+
To provide feedback about an origin trial:
183+
184+
1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
185+
186+
1. Select an active trial.
187+
188+
1. Click the **Feedback** button. The **Issues** tab of the product's GitHub repo opens.
189+
190+
1. View the issues.
191+
192+
1. If a new issue is needed, click the **New issue** button.
193+
194+
195+
For the Ad Selection API origin trial, instead see [Provide feedback about the origin trial](../web-platform/ad-selection-api.md#provide-feedback-about-the-origin-trial) in _Sign up for the Ad Selection API_.
21196

22197

23198
<!-- ====================================================================== -->
24199
## See also
200+
<!-- all links in the article -->
201+
202+
* [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials) - Developer.microsoft.com.
203+
* [Experimental features and origin trials for PWAs](../progressive-web-apps-chromium/how-to/origin-trials.md) - origin trials for Progressive Web Apps (PWAs).
204+
205+
Ad Selection API:
206+
* [Sign up for the Ad Selection API](../web-platform/ad-selection-api.md)
207+
* [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/) - portal at Github.io, for the Ad Selection API origin trial only.
25208

26-
* [Experimental features and origin trials](../progressive-web-apps-chromium/how-to/origin-trials.md) in the Progressive Web Apps (PWA) docs
209+
External:
210+
* [Implementing feature detection](https://developer.mozilla.org/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) - MDN.
211+
* [Get started with origin trials](https://developer.chrome.com/docs/web-platform/origin-trials) - Chrome docs.<!-- not in article body -->

‎microsoft-edge/progressive-web-apps-chromium/demo-pwas.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ This simple PWA demo lets you search for made up movies and store them locally.
9494

9595
![The My Movies app](./demo-pwas-images/my-movies.png)
9696

97-
[App](https://quirky-rosalind-ac1e65.netlify.app/), [source code](https://github.com/captainbrosset/movies-db-pwa).<!-- todo: link to readme -->
97+
[App](https://quirky-rosalind-ac1e65.netlify.app/), [source code](https://github.com/captainbrosset/movies-db-pwa).<!-- todo: link to readme when exists -->
9898

9999
My Movies uses the following features:
100100

‎microsoft-edge/progressive-web-apps-chromium/how-to/handle-urls.md

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,22 @@ No code is required for automatic link handling to work, but end users can opt-o
4242

4343

4444
<!-- ====================================================================== -->
45-
## Handle links from other origins with scope extensions
45+
## Handle links from other origins by using scope extensions
4646

47-
The manifest of a PWA defines which part of the hosting domain the PWA is scoped to. For example, the `www.contoso.com` domain name may have a PWA defined under `www.contoso.com/app` with its scope set to `/app`. In this case, all the web pages available within the `www.contoso.com/app` path are part of the PWA scope. However the web pages within the `www.contoso.com/foo` path are not part of the PWA scope. Furthermore, web pages available at `bar.contoso.com/app` or `www.contoso.co.uk` are also not part of the PWA scope.
47+
Scope extensions make it possible for a PWA to capture navigation to paths, subdomains, or even sites other than its own scope. This can be useful for PWAs that span multiple domains for localization purposes. For example, a PWA may span `contoso.com`, `contoso.co.uk`, and `contoso.fr`.
4848

49-
Scope extensions make it possible for a PWA to capture navigation to paths, subdomains, or even sites other than its own scope. This can be useful for PWAs that span multiple domains for localization purposes. For example, a PWA may span `contoso.com`, `contoso.co.uk`, and `contoso.fr`.
49+
The manifest of a PWA defines which part of the hosting domain the PWA is scoped to. For example, the `www.contoso.com` domain name may have a PWA defined under `www.contoso.com/app` with its scope set to `/app`. In this case, all the web pages available within the `www.contoso.com/app` path are part of the PWA scope. However, the web pages within the `www.contoso.com/foo` path are not part of the PWA scope. Furthermore, web pages that are available at `bar.contoso.com/app` or `www.contoso.co.uk` are also not part of the PWA scope.
5050

51-
**Note**: The scope extensions feature is currently in origin trial. See [Experimental features and origin trials](./origin-trials.md). To find out more about the state of development of this feature in Chromium, check out the [Web app scope extensions feature](https://chromestatus.com/feature/5746537956114432) at Chrome Platform Status.
5251

53-
Once the feature can be used in Microsoft Edge, we will document it here. In the meantime, to learn more about how scope extensions will work, see [the explainer document on the WICG repository](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md).
52+
<!-- ------------------------------ -->
53+
#### Origin trial
54+
55+
As of October 17, 2024, the scope extensions feature is an origin trial. For status, see [Web app scope extensions feature](https://chromestatus.com/feature/5746537956114432) at Chrome Platform Status.
56+
57+
When the feature can be used in Microsoft Edge and is no longer in origin trial, the feature will be documented in the present article. See [Scope Extensions for Web Apps](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md), an Explainer in the **manifest-incubations** repo.
58+
59+
See also:
60+
* [Experimental features and origin trials for PWAs](./origin-trials.md)
5461

5562

5663
<!-- ====================================================================== -->

0 commit comments

Comments
 (0)