In Microsoft Edge, we are supporting a limited version of ads reporting. For this limited version of reporting, reports will be per-event. Future work includes replacing these event-level reports with aggregated reporting.
Edge is only supporting ad auctions that are hosted by the seller’s front end (SFE), within a Trusted Execution Environment (TEE). When auctions are completed, two types of reports are generated via user-defined functions (UDFs):
- Seller Reports on Auction Results – generated by the function reportResults()
- Buyer Report on Auction Winner – generated by the function reportWin()
The output of the UDFs is a report in the format of a reporting URL. For example:
'https://buyer-reporting-server.example/reporting?bid=${bidInfo}
Additionally, reporting is available for interactions within embedded frames. These reports are generated by the reportEvent() API.
The seller’s ad service receives the following data from the browser:
- A request blob, which contains the following information:
- Properties: The version and compression type used for the message.
- Publisher: String listing the publisher site
- Generation ID: Random identifier produced by the browser that the server may use for rate limiting
- Interest groups: Encoded and compressed list of interest groups.
In particular, the interest group data is of interest as an input to our report generating UDFs. Details of the data types passed during an auction can be found in this proto file.
The auction is hosted across several TEEs, where the bids are generated, the ad is scored, and a winning bid is selected. Upon completion of the auction, the following data is made available to the reporting UDFs:
| Argument | JSON Object subfield | Description |
|---|---|---|
| auctionConfig | auctionSignals | Contextual signals passed from seller's ad service to the SellerFrontEnd service in SelectAdRequest.AuctionConfig |
| signalsForWinner | Contextual signals passed from seller's ad service to the SellerFrontEnd service in SelectAdRequest.AuctionConfig | |
| sellerReportingMetadata | interestGroupOwner | DSP/ buyer domain |
| renderURL | Ad render URL of winning bid. Nullopt if insufficient k-anonymity. | |
| bid | Value of the bid that scored the highest. | |
| desirability | Score of winning bid. Note: Winning bid refers to the bid with the highest score. | |
| highestScoringOtherBid | This is the value of a bid with the second highest score in the auction. This value represents eCPM (effective cost per thousand impressions), valued in US dollars. | |
| topWindowHostName | This is the host name of the publisher. | |
| buyerAndSellerReportingId | If set, the value is used instead of the interest group name or buyerReportingId for reporting in reportWin and reportResult. Note that this field needs to be jointly k-anonymous with the interest group owner, bidding script URL, and render URL to be provided to these reporting functions. |
| Argument | JSON Object subfield | Description |
|---|---|---|
| auctionSignals | Contextual signals passed from the seller's ad service to the SellerFrontEnd service in SelectAdRequest.AuctionConfig. | |
| signalsForWinner | Signals returned by seller's ReportResult() function execution. | |
| perBuyerSignals | Contextual signals passed from the seller's ad service to the SellerFrontEnd service in SelectAdRequest.AuctionConfig. This is the buyer signals for the winning buyer. | |
| buyerReportingMetadata | seller | Seller's origin. This will be passed to the Auction service from the SellerFrontEnd service. |
| adCost | An optional field returned by generateBid(), rounded to fit into a floating point number with an 8 bit mantissa and 8 bit exponent for reporting. | |
| interestGroupName | The name of the interest group corresponding to the highest scoring bid. | |
| madeHighestScoringOtherBid | This is set to true if the winning buyer was the only buyer that made bids with the second highest score. | |
| recency | Duration of time (in minutes) from when this device joined this interest group until now. This is passed by the client. | |
| modelingSignals | Sent as an output from the generateBid() function. This is expected to be a single integer value. | |
| joinCount | The number of times the given device has joined the same interest group in the last 30 days, while the interest group has been continuously stored. | |
| buyerReportingId | If set, the value is used instead of the interest group name for reporting in reportWin. Note that this field needs to be jointly k-anonymous with the interest group owner, bidding script URL, and render URL to be provided to these reporting functions (in the same way that the interest group name would have needed to be). | |
| buyerAndSellerReportingId | If set, the value is used instead of the interest group name or buyerReportingId for reporting in reportWin and reportResult. Note that this field needs to be jointly k-anonymous with the interest group owner, bidding script URL, and render URL to be provided to these reporting functions (in the same way that the interest group name would have needed to be). |
The report URL can contain any of the information above as a param, so long as the URL meets the following requirements:
- It is a valid HTTPS URL.
- It is no longer than the browser’s URL length limits.
- It has been attested to the Ad Selection API.
Each UDF can only send a single report URL. If multiple attempts are made, an exception will be thrown.
An optional mode is available that converts all bid-related information to the seller's preferred currency (in component auctions, for that component's seller). This is configured via the sellerCurrency setting in each auction configuration. More details on the sellerCurrency option are available here.
The reporting URL is transmitted to the browser within the Response Blob. First, the browser will verify the response is valid. If so, the reports will be enqueued by the browser, and they will begin sending once the winning ad has completed rendering. If additional reports are received after ad rendering has been completed, they are added to the queue and eligible to be sent immediately.
Interest based ads are rendered in fenced frames, which are special embedded frames that do not have any communication channels with the publisher page. For event-level reporting, we need a channel for events within the fenced frame to be correlated to the information provided by the reporting worklets and sent out on the network. This will be handled by the reportEvent function. In the long-term, these events could only be exfiltrated using an aggregate report.
While this reporting was designed with the privacy restrictions of fenced frames in mind, the features outlined in this document are also applicable for iframes.
The mapping of events and destination URLs is provided as part of the Response blob from the seller’s service to the browser. Beacons indicate what event will cause a report to be sent to what URL. Event data is associated with these events in three ways:
- The fenced frame calls reportEvent with a preregistered destination URL
- Event Type: such as “click” or “mouse-over”
- Event Data: a string of data provided by the buyer or seller
- Destination: to the buyer, seller, component-seller or direct-seller. One report will be processed for each destination specified.
- Cross Origin Exposed: true or false
For example:
window.fence.reportEvent({
'eventType': 'click',
'eventData': JSON.stringify({'clickX': '123', 'clickY': '456'}),
'destination':['buyer', 'seller'] });
- The fenced frame calls reportEvent with a custom destination URL with substitution of preregistered macros. These macros are values specified by the buyer’s worklet. Here is an example that will substitute ${PUBLISHER_ID} and ${SOURCE_URL_ENC} macros:
window.fence.reportEvent({ 'destinationURL': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'});
- There are also two “automatic beacon” event types, which occur when navigation begins or when navigation commits within the fenced frame. For these event types to occur, the fenced frame must first call window.fence.setReportEventDataForAutomaticBeacons to provide event data.
When an event occurs in an ad, the buyer’s fenced frame calls reportEvent. The browser takes the signals provided by the fenced frame and correlates them with the ID passed to it by the reporting worklet. The browser sends an HTTP POST request to the ad-tech server, like the existing navigator.sendBeacon.
The POST request body sent to the ad-tech server will contain the data specified in Event Data. These reports have the following restrictions:
- Destination has been attested to the Ad Selection API.
- Cannot exceed the maximum permissible length, which is 64KB.
- Beacon data can only be set from documents that are same-origin to the mapped URL from the fenced frame config, unless both the fenced frame root and the cross-origin document opt-in.
- The fenced frame root opts in by being served with a new Allow-Cross-Origin-Event-Reporting response header set to true.
- The cross-origin document opts in by calling reportEvent with crossOriginExposed=true.
When a rendered ad is composed of multiple pieces, it is useful to detect user clicks that happened on ad components. For fenced frames rendering the ad components under the top-level ad fenced frame, the automatic beacon event type and corresponding reporting destination registered for the top-level fenced frame are reused when beacons are sent from the ad component fenced frames. Component fenced frames are restricted to sending only automatic beacon reports. More details are available here.