Add to explainer: creative scanning via BYOS/V1 trusted scoring signals. #1406
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
As noted in WICG#792, one of the responsibilities of sellers is to make sure that the ad shown meets the publisher's restrictions. Today, when a seller considers an ad for which a buyer is bidding, they verify, for example, that the ad is not about any of the subjects the publisher does not want shown on their site. Determining the subject of an ad - a process called creative scanning - can be slow, as it utilizes some combination of AI and human evaluation. Sellers have historically relied on populating a creative scanning pipeline through a combination of pre-registration and by discovering ads through the bid stream. Sellers generally require creative scanning to complete before allowing an ad to win an auction. This process proves to be challenging in Protected Audience API because the auction runs in isolation, and so it can't send ads out to have them evaluated, since doing so would potentially leak information about the user's identity by associating their activity on the publisher site with past activity on advertiser sites. This change enables sellers to discover ads for creative scanning by leveraging the stream of ads sent to their bring-your-own-server (BYOS) real-time scoring signals key/value service. It does so by making it possible for sellers to request that the auction include some additional metadata alongside each ad's renderURL on the request to the real-time scoring signals key/value service. This includes some existing metadata — the buyer's origin, ad size, and buyerAndSellerReportingId — as well as a new field titled creativeScanningMetadata. This solution addresses the needs of creative scanning until a future solution is implemented that's compatible with the privacy-advancing requirement of Trusted Execution Environment (TEE)-hosting for real-time scoring signals key/value service. This solution does not regress the current privacy properties of Protected Audience.
JensenPaul
reviewed
Mar 12, 2025
| @@ -297,9 +302,11 @@ The `ads` list contains the various ads that the interest group might show. Eac | |||
|
|
|||
| * `metadata`: Arbitrary metadata that can be used at bidding time. | |||
|
|
|||
| * `creativeScanningMetadata`: A USVString, no character limit. If `sendCreativeScanningMetadata` is set to true in the auction config, then this string -- along with other metadata as described in [2.1 Initiating an On-Device Auction](#21-initiating-an-on-device-auction) -- is sent as part of the scoring signals fetch request. This provides a way for buyers to convey additional information that sellers need in order to scan an advertisement, such as the associated advertiser domain, which isn't captured in the `renderURL` and other fields sent on the scoring signals fetch request. | |||
There was a problem hiding this comment.
would you mind line wrapping this (and any other lines this PR adds or modifies)?
can we linkify USVString like we do above on line 287?
true->true
Can we elaborate slightly on "other metadata"? I don't know what that is.
"and other fields sent on the scoring signals request" is a little confusing (I thought it was attached to the first half of the sentence). Maybe it might be clearer to write "...which isn't captured in other fields sent on the scoring signals fetch request (e.g. renderURL)."
| @@ -464,6 +472,8 @@ This will cause the browser to execute the appropriate bidding and auction logic | |||
|
|
|||
| `maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes), but affect the seller's trusted scoring signals fetch as opposed to the trusted bidding signals fetch. | |||
|
|
|||
| When set to true, `sendCreativeScanningMetadata` instructs the browser to send a collection of metadata associated with each ad and component ad as part of the scoring signals fetch request, as described in [3.1.1.2 Trusted Scoring Signals](#3112-trusted-scoring-signals). | |||
There was a problem hiding this comment.
Suggested change
| When set to true, `sendCreativeScanningMetadata` instructs the browser to send a collection of metadata associated with each ad and component ad as part of the scoring signals fetch request, as described in [3.1.1.2 Trusted Scoring Signals](#3112-trusted-scoring-signals). | |
| When set to `true`, `sendCreativeScanningMetadata` instructs the browser to send the collection of metadata | |
| stored with each ad and component ad in the `creativeScanningMetadata` field as part of the scoring signals fetch | |
| request, as described in [3.1.1.2 Trusted Scoring Signals](#3112-trusted-scoring-signals). |
| @@ -584,7 +594,7 @@ The function gets called once for each candidate ad in the auction. The argumen | |||
| * bid: A numerical bid value. | |||
| * auctionConfig: The auction configuration object passed to `navigator.runAdAuction()`. | |||
| * trustedScoringSignals: A value retrieved from a real-time trusted server chosen by the seller and reflecting the seller's opinion of this particular creative, as further described in [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) below. This is used when the server is same-origin to the seller; crossOriginTrustedSignals is used otherwise. | |||
| * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify: | |||
| * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify. Note that each element in `adComponentsCreativeScanningMetadata` might be either the string value of that component ad's `creativeScanningMetadata`, or null if that component ad didn't provide one. | |||
There was a problem hiding this comment.
Suggested change
| * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify. Note that each element in `adComponentsCreativeScanningMetadata` might be either the string value of that component ad's `creativeScanningMetadata`, or null if that component ad didn't provide one. | |
| * browserSignals: An object constructed by the browser, containing information that the browser | |
| knows and which the seller's auction script might want to verify. | |
| `adComponentsCreativeScanningMetadata` is a list where each element corresponds to the | |
| respective element in the `adComponents` list. Each element might be either the string value | |
| of that component ad's `creativeScanningMetadata`, or `null` if that component ad didn't provide one. |
| Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way as [`trustedBiddingSignalsURL`](#311-trusted-signals-server-with-byos-model). If `trustedScoringSignalsCoordinator` is not present in the auction config, it will send the scoring signals fetch request to a BYOS server. The request base URL is set from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. However, the URL has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderURLs bids offered in the auction. Note that the query params use "Urls" instead of "URLs". It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. | ||
| ###### 3.1.1.2 Trusted Scoring Signals | ||
|
|
||
| Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way as [`trustedBiddingSignalsURL`](#311-trusted-signals-server-with-byos-model). If `trustedScoringSignalsCoordinator` is not present in the auction config, it will send the scoring signals fetch request to a BYOS server. The request base URL is set from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. For bids offered in the auction, the `renderURL` and metadata from both the main ad and component ads of those bids will be appended to the URL using several query parameters. |
There was a problem hiding this comment.
Perhaps not for this PR, but it's kinda non sequitur how it starts talking about experimentGroupId in the middle of the intro paragraph. I wonder if we should pull that into a bullet point so that it's easier for folks find definitions of each parameter (without having to look half way through the paragraph). I also feel like we should start with an example request URL and then go into detailed explanations of each parameter.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As noted in #792, one of the
responsibilities of sellers is to make sure that the ad shown meets the
publisher's restrictions. Today, when a seller considers an ad for which
a buyer is bidding, they verify, for example, that the ad is not about
any of the subjects the publisher does not want shown on their site.
Determining the subject of an ad - a process called creative scanning -
can be slow, as it utilizes some combination of AI and human evaluation.
Sellers have historically relied on populating a creative scanning
pipeline through a combination of pre-registration and by discovering
ads through the bid stream. Sellers generally require creative scanning
to complete before allowing an ad to win an auction. This process proves
to be challenging in Protected Audience API because the auction runs in
isolation, and so it can't send ads out to have them evaluated, since
doing so would potentially leak information about the user's identity by
associating their activity on the publisher site with past activity on
advertiser sites. This change enables sellers to discover ads for
creative scanning by leveraging the stream of ads sent to their
bring-your-own-server (BYOS) real-time scoring signals key/value
service. It does so by making it possible for sellers to request that
the auction include some additional metadata alongside each ad's
renderURL on the request to the real-time scoring signals key/value
service. This includes some existing metadata — the buyer's origin, ad
size, and buyerAndSellerReportingId — as well as a new field titled
creativeScanningMetadata. This solution addresses the needs of creative
scanning until a future solution is implemented that's compatible with
the privacy-advancing requirement of Trusted Execution Environment
(TEE)-hosting for real-time scoring signals key/value service. This
solution does not regress the current privacy properties of Protected
Audience.