Sign up for the Ad Selection API

The Ad Selection API provides user-relevant ads on your site without using third-party cookies. See Ad Selection Overview in the privacy-preserving-ads repo.

The Ad Selection API can be used by:

• Sellers running a supply-side platform (SSP), who can use the API to provide higher-quality ads for their publishers.
• Buyers running a demand-side platform (DSP), who can use the API to improve the effectiveness of advertising campaigns.

To get started using the Ad Selection API and test out the end-to-end flow, sign up for the limited preview of the Ad Selection API.

As a seller operating a supply-side platform or a buyer operating a demand-side platform, use this guide to:

• Sign up for the Ad Selection API limited preview by registering for the origin trial.
• Complete the API attestation by publishing your attestations JSON file.
• Set up an evaluation environment with a supported cloud provider.
• View the Ad Selection API documentation.
• Prepare your User-Defined Functions (UDFs).
• Deploy your services to Azure.
• Test the Ad Selection API on your site.

Attestation enrollment and alpha sign-up

When and where is the preview available?

Microsoft Edge versions starting with 130.0.2808.0 have support for the Ad Selection API in a limited, developer opt-in preview outside of the European Economic Area (EEA) and the United Kingdom (UK).

Flags for testing

To change the Ad Selection API platform features on your developer machine, use the Ad Selection API testing flags at edge://flags#edge-ad-selection-api:

The Ad Selection API flag enables the Ad Selection API and associated features such as:

• Attribution Reporting.
• Fenced Frames.
• Shared Storage.
• Private Aggregation.

Sign-up and attestation requirements and process

Developers interested in alpha testing can join the origin trial for the Ad Selection API. This origin trial enables end-to-end testing of Ad Selection API features, covering both the API usage and the deployment of secure container images.

For each top-level domain that you intend to use with the Ad Selection API, fill in the Origin Trial Registration form for that domain, and then submit the form.

To sign up for the Ad Selection API origin trial for a domain:

1. Open Microsoft Edge Origin Trials in a new window or tab:

   

2. In the Ad Selection API section, click the Register button. The Origin Trial Registration form opens:

   

3. Fill in the form.

   • In the Domain text box, enter a single top-level domain. For example, a top-level domain is contoso.example, and optionally includes subdomains such as subdomain.contoso.example.

   • In the Subdomain Support section, select the Yes or No option button.

   • In the Email Address text box, provide a valid developer contact for the domain.

   • In the Origin Trial Name text box, enter AdSelectionAPI (with no spaces). This is the ID of this origin trial.

4. Click the Submit button.

   An origin trial token is generated for the top-level domain and is sent to you.

5. Create a file that's named ad-selection-attestations.json, and host the file at the top-level domain, in the /.well-known/ directory. For example:

   https://contoso.example/.well-known/ad-selection-attestations.json

   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.

Example JSON file

The attestations JSON file must be named ad-selection-attestations.json, and must conform to the following standards below. The following is an example of an ad-selection-attestations.json file:

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}

Important fields and values

• The ad-selection-attestations.json file must include the origin trial token that was generated and sent to you for this top-level domain. "ownership_token": is the origin trial token that was generated when registering this domain for the Ad Selection API origin trial.

• In the "platform_attestations": section, "platform": must be "edge" or "android".

• The file must include a list of APIs (features that are associated with the Ad Services API). In the "platform_attestations": section, valid members of "attestations": are the following:

  • "ad_selection_api": - The main API, for private auction logic.
  • "attribution_reporting_api": - Attribution reporting.
  • "shared_storage_api": - Shared storage.
  • "private_aggregation_api": - Private aggregation.
  • Requirements:
    • Each "..._api": entry must have a single field, "ServiceNotUsedForIdentifyingUserAcrossSites":, with either a true or false value. true means that this service is not used for identifying the user across sites. false means that this service is used for identifying the user across sites.

Deploy the Ad Selection API services

The Ad Selection API uses a trusted execution environment (TEE) to provide a level of assurance for data integrity, data confidentiality, and code integrity; see Confidential Computing: Hardware-Based Trusted Execution for Applications and Data. Services provided by the Ad Selection API must run in a TEE to secure the data used by these services.

Ad Selection Services running in a TEE should be deployed on a cloud platform that supports the necessary security features. Initially, services can be deployed in Azure by using confidential ACI containers; see Confidential containers on Azure Container Instances.

The Ad Selection API provides different services that need to be deployed by sellers or buyers.

Images for deploying services

Add your User-Defined Functions (UDFs) within the provided images of services. The User-Defined Functions can run custom business logic. The User-Defined Functions run in private containers within the deployed services.

Each image defines one service. Some images don't contain UDFs, and consist entirely of predefined code. Some images contain UDFs, as functions with an empty body or starter code, that are the relevant User-Defined Functions for that service. Fill in the bodies of the User-Defined Functions in these images with your own custom code.

Microsoft provides an image for each service, which can be deployed on a cloud provider. These are the public images that must be used for deployment. Only official images from Microsoft are able to run private auctions.

Images for deployment:

• Sellers
  • Ad Selection Seller Front End Service
  • Ad Selection Auction Service
• Buyers
  • Ad Selection Buyer Front End Service
  • Ad Selection Bidding Service
  • Ad Selection K-Anonymity Service
• Sellers and buyers
  • Ad Selection Key Value Service

Services for sellers

Service	Description
SellerFrontEnd	Provides a /SelectAd HTTPS endpoint, which receives requests from the seller's untrusted ad service to initiate the Protected Audience auction flow.
Auction	Provides a /ScoreAds endpoint, which receives requests from the SellerFrontEnd service, containing bids that are participating in the auction. Responds with a score value that the SellerFrontEnd service uses to choose the winner.
Key/Value	Receives requests from the SellerFrontEnd service, which contain lookup keys from buyers' bids (such as ad_render_urls). Returns real-time scoring signals that are required for the auction. Runs in Bring Your Own Service (BYOS) mode, so the seller does not need to deploy this service in a trusted execution environment (TEE), and can instead use the image that's provided by Microsoft.

Services for buyers

Service	Description
BuyerFrontEnd	Provides a /GetBids endpoint, which receives requests from the SellerFrontEnd service to initiate the bidding flow.
Bidding	Provides a /GenerateBids endpoint, which receives requests from the BuyerFrontEnd service to handle the bidding and generate a bid. Generates a bid, chooses the winner, and selects the banner to be rendered.
Key/Value	Receives requests from the BuyerFrontEnd service and returns real-time buyer data required for bidding, corresponding to lookup keys from Interest Groups. Such a request happens once per workflow. Runs in Bring Your Own Service (BYOS) mode.
Bidding Selection & Key/Value	Receives requests from the Bidding service to select and return additional ad banners (candidates) that can participate in bidding. The Bidding Selection & Key/Value service can also return additional signals that are needed for bidding. The Bidding service may send multiple requests to the Bidding Selection & Key/Value service, or may choose not to send any requests, because the Bidding Selection & Key/Value service is optional. The Bidding Selection & Key/Value service must be deployed in a trusted execution environment (TEE).
K-Anonymity	Collects k-anonymity counters and checks that the winning ad creative passes the k-anonymity check.

User-Defined Functions

Sellers and buyers need to provide their own custom code as User-Defined Functions (UDFs) that run in private containers within the deployed services. These User-Defined Functions can execute custom business logic.

Each buyer or seller can deploy multiple instances of a given service, such as:

• SellerFrontEnd and Auction.
• BuyerFrontend, Bidding, and K-Anonymity.

Some of these services take an input which is a JavaScript worklet that defines User-Defined Functions.

User-Defined Functions for sellers

UDF	Service in which the UDF runs	Description
scoreAd()	Auction	Generates a score for each buyer's bid, or rejects the bid. This score is then used by the SellerFrontEnd service, to choose a winner from among all buyers.
reportResult()	SellerFrontEnd	For event-level reporting. Runs in the SellerFrontEnd service after the final winner has been chosen. Notifies the seller about the winning bidder, and provides the bid value.

User-Defined Functions for buyers

UDF	Service in which the UDF runs	Description
generateBids()	Bidding	Generates a bid, and chooses the banner that will be shown.
reportWin()	SellerFrontEnd	For event-level reporting. Runs in the SellerFrontEnd service, if the buyer's bid wins the auction. Notifies the buyer that they have won the auction, and generates notification URLs that will be triggered later, such as during banner rendering or other client events.
getValues()	Bidding Selection & Key/Value	Runs in the Bidding Selection & Key/Value service, if the buyer uses that service. Allows for custom code execution for data lookup and selection.

Deployment guide

To deploy the Ad Selection API service to Azure:

1. Create an Azure account and create a subscription at Microsoft Azure.

2. Choose the Confidential ACO containers option.

3. Go to Terraform deployment scripts in a new window or tab, and then download the Terraform deployment scripts and view the deployment documentation. Note: Make sure the hash of the image you downloaded matches the hash in the script you download.

4. The Terraform scripts already include links to public images that are provided by Microsoft. Choose the required services and deploy them by following the steps in the included readme.md.

   1. Set any specific flags for your environment, including auction worklet locations.

   2. Configure all prerequisites and prepare all tools for deployment.

   3. Create Azure Resources and run the Terraform script that finishes deployment.

5. Develop worklets including user-defined-function (UDF) and start Ad Selection API services.

Use the Ad Selection API on your website

To start using the Ad Selection API, sellers and buyers need to modify their websites' JavaScript code that's run when the browser is Microsoft Edge.

• Sellers: To run private auctions, fetch interest groups, and do reporting, update your code on publishers' websites.

• Buyers: To create interest groups and store them in the browser, update the code on your advertising partners' websites. You can use the delegation mechanism to restrict and allow Interest Group creation on third-party domains.

To learn more about which API methods are available and to view example code, see Ad Selection API details.

Provide feedback about the origin trial

To provide feedback about the Ad Selection API origin trial:

1. Go to the Microsoft Edge Origin Trials portal at Github.io.

2. Go to the row for the Ad Selection API origin trial.

3. Click the issues button in the row. The privacy-preserving-ads repo opens.

4. Submit a new issue, or click the Issues tab to view the issues.

See also

Design and technical documents

• Ad Selection Overview
• Ad Selection API Proposal
• Ad Selection API details

Images for deployment:

• Sellers
  • Ad Selection Seller Front End Service
  • Ad Selection Auction Service
• Buyers
  • Ad Selection Buyer Front End Service
  • Ad Selection Bidding Service
  • Ad Selection K-Anonymity Service
• Sellers and buyers
  • Ad Selection Key Value Service

Deployment scripts:

• Terraform deployment scripts

Origin trials:

• Microsoft Edge Origin Trials

Trusted execution environment (TEE):

• Confidential Computing: Hardware-Based Trusted Execution for Applications and Data

Azure:

• Microsoft Azure
• Confidential containers on Azure Container Instances