MicrosoftDocs · captainbrosset · Oct 31, 2024 · Oct 14, 2024 · Oct 14, 2024 · Oct 14, 2024
diff --git a/microsoft-edge/origin-trials/index-images/reg-form.png b/microsoft-edge/origin-trials/index-images/reg-form.png
diff --git a/microsoft-edge/origin-trials/index-images/renew-token.png b/microsoft-edge/origin-trials/index-images/renew-token.png
diff --git a/microsoft-edge/origin-trials/index-images/token-displayed.png b/microsoft-edge/origin-trials/index-images/token-displayed.png
diff --git a/microsoft-edge/origin-trials/index.md b/microsoft-edge/origin-trials/index.md
@@ -1,26 +1,214 @@
 ---
-title: Use Origin Trials in Microsoft Edge
+title: Use origin trials in Microsoft Edge
 description: Safely experiment for a fixed period of time and provide feedback on new platform features.
 author: MSEdgeTeam
 ms.author: msedgedevrel
 ms.topic: conceptual
 ms.service: microsoft-edge
-ms.date: 10/25/2023
+ms.date: 10/15/2024
 ---
-# Use Origin Trials in Microsoft Edge
+# Use origin trials in Microsoft Edge
 
-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.
+<!-- ====================================================================== 
+## Introduction -->
 
-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.
+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 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.
+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.
 
-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.
+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.
 
-For more information, see the **Getting Started** and **Developer Guidelines** sections in [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/).
+
+<!-- ------------------------------ -->
+#### How the origin trial token works
+
+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:
+
+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.
+
+1. Copy the token to your webpage within a `<head>/<meta>` element, or in an `Origin-Trial` HTTP server response header.
+
+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.
+
+
+<!-- ====================================================================== -->
+## Registering for an origin trial
+<!-- fwlink that points to this anchor/ article section heading: pending -->
+<!-- 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 -->
+
+To register for an origin trial:
+
+1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
+
+   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).
+
+1. Select an active trial.
+
+1. Click the **I Accept the Terms of Use** button.
+
+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.
+
+   The **New Origin Trial Registration** form opens:
+
+   ![New Origin Trial Registration form](./index-images/reg-form.png)
+
+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`).
+
+   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 as `https://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 as `https://example.com`) or subdomain will be registered, ignoring any trailing path or query parameters.
+
+1. 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 as `https://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 as `https://beta.example.com`), turn on the **Enable token for subdomains?** toggle.
+
+1. Click the **Submit** button.
+
+   An origin trial token is generated, and is displayed in the **Registrations** section near the **New Origin Trial Registration** form:
+
+   ![The generated token displayed in the Registration section](./index-images/token-displayed.png)
+
+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.
+
+
+<!-- ====================================================================== -->
+## Using the origin trial token at your website
+<!-- fwlink that points to this anchor/ article section heading: pending -->
+<!-- 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 -->
+
+Use the token at your website in either of the following ways:
+
+
+<!-- ------------------------------ -->
+#### Option 1: A \<meta\> tag within the \<head\> element of a webpage
+
+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.
+
+
+<!-- ------------------------------ -->
+#### Option 2: An HTTP header in your HTTP server response
+
+In your HTTP server response, add the following HTTP header:
+
+`Origin-Trial: EXAMPLE_TOKEN`
+
+Replace `EXAMPLE_TOKEN` by your token.
+
+
+<!-- ------------------------------ -->
+#### Opting out of an origin trial experiment
+
+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.
+
+
+<!-- ====================================================================== -->
+## Performing feature detection and providing graceful fallback
+
+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](https://developer.mozilla.org/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) at MDN.
+
+
+<!-- ====================================================================== -->
+## Testing an origin trial at `localhost`
+
+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`.
+
+
+<!-- ====================================================================== -->
+## Renewing an origin trial token
+
+Origin trial tokens expire in 6 weeks, by default<!-- todo: strike ", 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:
+
+1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
+
+   For the Ad Selection API origin trial, instead see [Sign up for the Ad Selection API](../web-platform/ad-selection-api.md).
+
+1. In the **My Registered Trials** section, select an origin trial.
+
+1. In the **Registrations** section, in a token row that contains an **Expired** badge, click the **Renew** button:
+
+   ![UI to renewing a token](./index-images/renew-token.png)
+
+   A fresh token is generated and displayed.
+
+1. In the row that contains the new token, click the **Copy** button, and then paste the fresh token into your code.
+
+
+<!-- ====================================================================== -->
+## Duration of an origin trial
+
+An origin trial may last until the planned expiration date, or may end early.
+
+
+<!-- ------------------------------ -->
+#### Scheduled expiration date
+
+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.
+
+
+<!-- ------------------------------ -->
+#### Early end
+
+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.
+
+
+<!-- ====================================================================== -->
+## Providing feedback about an origin trial
+
+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:
+
+1. Go to [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials).
+
+1. Select an active trial.
+
+1. Click the **Feedback** button.  The **Issues** tab of the product's GitHub repo opens.
+
+1. View the issues.
+
+1. 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](../web-platform/ad-selection-api.md#provide-feedback-about-the-origin-trial) in _Sign up for the Ad Selection API_.
 
 
 <!-- ====================================================================== -->
 ## See also
+<!-- all links in the article -->
+
+* [Microsoft Edge Origin Trials](https://developer.microsoft.com/microsoft-edge/origin-trials) - Developer.microsoft.com.
+* [Experimental features and origin trials](../progressive-web-apps-chromium/how-to/origin-trials.md) - origin trials for Progressive Web Apps (PWAs).
+
+Ad Selection API:
+* [Sign up for the Ad Selection API](../web-platform/ad-selection-api.md)
+   * [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/) - portal at Github.io, for the Ad Selection API origin trial only.
 
-* [Experimental features and origin trials](../progressive-web-apps-chromium/how-to/origin-trials.md) in the Progressive Web Apps (PWA) docs
+External:
+* [Implementing feature detection](https://developer.mozilla.org/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) - MDN.
+* [Get started with origin trials](https://developer.chrome.com/docs/web-platform/origin-trials) - Chrome docs.<!-- not in article body -->
diff --git a/microsoft-edge/web-platform/ad-selection-api.md b/microsoft-edge/web-platform/ad-selection-api.md
@@ -90,6 +90,11 @@ To sign up for the **Ad Selection API** origin trial for a domain:
    The `ad-selection-attestations.json` file must be published within **30 days** of receiving the OT token.  Hosting this JSON file is required, in order to complete your attestation and allow your code to access the Ad Selection API, to test the Ad Selection API with supported Microsoft Edge clients.
 
 
+<!-- ------------------------------ 
+#### Renewing the origin trial token
+todo -->
+
+
 <!-- ------------------------------ -->
 #### Example JSON file
 
@@ -269,6 +274,20 @@ To start using the Ad Selection API, sellers and buyers need to modify their web
 To learn more about which API methods are available and to view example code, see [Ad Selection API details](https://github.com/WICG/privacy-preserving-ads/blob/main/API%20Details.md).
 
 
+<!-- ====================================================================== -->
+## Provide feedback about the origin trial
+
+To provide feedback about the Ad Selection API origin trial:
+
+1. Go to the [Microsoft Edge Origin Trials](https://microsoftedge.github.io/MSEdgeExplainers/origin-trials/) portal at Github.io.
+
+1. Go to the row for the **Ad Selection API** origin trial.
+
+1. Click the **issues** button in the row.  The `privacy-preserving-ads` repo opens.
+
+1. Submit a new issue, or click the **Issues** tab to view the issues.
+
+
 <!-- ====================================================================== -->
 ## See also
 <!-- all links in article -->