Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Alternate B&A header mechanism to facilitate delaying response to body #1233

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion FLEDGE_browser_bidding_and_auction_API.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,39 @@ and both versions should be accepted.

It should be noted that the `fetch()` request using `adAuctionHeaders` can also be used to send `auctionBlob` (e.g. in the request body) and receive the response blob (e.g. in the response body).

#### Alternate header to facilitate delaying response blobs to response body

The aforementioned Step 3 includes the hash of the response blob in an
`Ad-Auction-Result` HTTP response header, which requires that the response blob
be available *before* the HTTP response headers are sent back to the device.
The server operator may want to instead delay inclusion of the response blob
until the HTTP response body is sent back to the device. If the response is
[streamed](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) back
to the device, the response blob could even come *after* other data that is
available earlier. One example of when this might be useful is if this other
data [fullfills Promises for on-device auction signals](FLEDGE.md#211-providing-signals-asynchronously)
to unblock on-device auctions so they proceed concurrently to auctions running
on B&A servers. This delaying inclusion of the response blob can be accomplished
by omitting the `Ad-Auction-Result` HTTP header and instead:

1. Generate a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.html) nonce on
their server.
1. Instead of returning the `Ad-Auction-Result` header, return an
`Ad-Auction-Result-Nonce` header passing the nonce, e.g.
`Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like
`Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated
list instead of a single value if desired.
1. Pass the nonce in a TBD field of the
[SelectAdRequest](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L282)
to the [SellerFrontEnd service](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L267).

Behind the scenes, the Bidding and Auction servers will include the nonce inside
the response blob so it's passed back to the browser which verifies that it
matches the nonce from the `Ad-Auction-Result-Nonce` header.

More information about this flow can be found
[here](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/protected_audience_auctions_mixed_mode.md#server-side-auctions).

### Step 4: Complete auction in browser

Now the auction can be completed by passing the response blob to `runAdAuction()` as part of a specially configured auction configuration:
Expand Down Expand Up @@ -466,7 +499,11 @@ Prior to compression and encryption, the AuctionResult is encoded as CBOR with t
"description": "Boolean to indicate that there is no remarketing winner from the auction. AuctionResult may be ignored by the client (after decryption) if this is set to true."
},
"winReportingUrls": { "$ref": "#/$defs/winReportingUrlsDef" },
"error": { "$ref": "#/$defs/errorDef" }
"error": { "$ref": "#/$defs/errorDef" },
"nonce": {
"type": "string",
"description": "UUIDv4 nonce that was passed to SelectAdRequest, in standard UUIDv4 string representation: 32 lower-case hexadecimal characters with blocks of 8, 4, 4, 4, and 12 separated by dashes as per RFC4122. Browser enforces that this matches exactly the string passed via the Ad-Auction-Result-Nonce header."
}
}
}
```