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.

Sign up for GitHub

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

Jump to bottom

fledgeForGpt module: docs update #9127

Merged
merged 1 commit into from
Oct 19, 2022
Merged

fledgeForGpt module: docs update #9127

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
124 changes: 101 additions & 23 deletions modules/fledgeForGpt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,33 @@
## Overview
# Overview
This module allows Prebid.js to support FLEDGE by integrating it with GPT's [experimental FLEDGE
support](https://github.com/google/ads-privacy/tree/master/proposals/fledge-multiple-seller-testing).

This module enables the handling of fledge auction by GPT.
Bid adapters can now return component auction configs in addition to bids.
To learn more about FLEDGE in general, go [here](https://github.com/WICG/turtledove/blob/main/FLEDGE.md).

Those component auction configs will be registered to the GPT ad slot,
and GPT will be responsible to run fledge auction and render the winning fledge ad.
This document covers the steps necessary for publishers to enable FLEDGE on their inventory. It also describes
the changes Bid Adapters need to implement in order to support FLEDGE.

Find out more [here](https://github.com/WICG/turtledove/blob/main/FLEDGE.md).

## Integration

Build the fledge module into the Prebid.js package with:
## Publisher Integration
Publishers wishing to enable FLEDGE support must do two things. First, they must compile Prebid.js with support for this module.
This is accomplished by adding the `fledgeForGpt` module to the list of modules they are already using:

```
gulp build --modules=fledgeForGpt,...
```

## Module Configuration Parameters
Second, they must enable FLEDGE in their Prebid.js configuration. To provide a high degree of flexiblity for testing, FLEDGE
settings exist at the module level, the bidder level, and the slot level.

### Module Configuration
This module exposes the following settings:

|Name |Type |Description |Notes |
| :------------ | :------------ | :------------ |:------------ |
|enabled | Boolean |Enable/disable the module |Defaults to `false` |

## Configuration
As noted above, FLEDGE support is disabled by default. To enable it, set the `enabled` value to `true` for this module
using the `setConfig` method of Prebid.js:

Fledge support need to be enabled at 3 levels:
- `fledgeForGpt` module
- bidder
- adunit
### enabling the fledgeForGpt module
```js
pbjs.que.push(function() {
pbjs.setConfig({
Expand All @@ -39,7 +38,17 @@ pbjs.que.push(function() {
});
```

### enablingthe bidder
### Bidder Configuration
This module adds the following setting for bidders:

|Name |Type |Description |Notes |
| :------------ | :------------ | :------------ |:------------ |
| fledgeEnabled | Boolean | Enable/disable a bidder to participate in FLEDGE | Defaults to `false` |

In addition to enabling FLEDGE at the module level, individual bidders must also be enabled. This allows publishers to
selectively test with one or more bidders as they desire. To enable one or more bidders, use the `setBidderConfig` method
of Prebid.js:

```js
pbjs.setBidderConfig({
bidders: ["openx"],
Expand All @@ -49,12 +58,81 @@ pbjs.setBidderConfig({
});
```

### enabling the adunit
ortb2Imp.ext.ae on the adunit must be set 1
### AdUnit Configuration
Enabling an adunit for FLEDGE eligibility is accomplished by setting an attribute of the `ortb2Imp` object for that
adunit.

|Name |Type |Description |Notes |
| :------------ | :------------ | :------------ |:------------ |
| ortb2Imp.ext.ae | Integer | Auction Environment: 1 indicates FLEDGE eligible, 0 indicates it is not | Absence indicates this is not FLEDGE eligible |

The `ae` field stands for Auction Environment and was chosen to be consistent with the field that GAM passes to bidders
in their Open Bidding and Exchange Bidding APIs. More details on that can be found
[here](https://github.com/google/ads-privacy/tree/master/proposals/fledge-rtb#bid-request-changes-indicating-interest-group-auction-support)
In practice, this looks as follows:

```js
ortb2Imp: {
ext: {
ae: 1
pbjs.addAdUnits({
code: "my-adunit-div",
// other config here
ortb2Imp: {
ext: {
ae: 1
}
}
});
```

## Bid Adapter Integration
Chrome has enabled a two-tier auction in FLEDGE. This allows multiple sellers (frequently SSPs) to act on behalf of the publisher with
a single entity serving as the final decision maker. In their [current approach](https://github.com/google/ads-privacy/tree/master/proposals/fledge-multiple-seller-testing),
GPT has opted to run the final auction layer while allowing other SSPs/sellers to participate as
[Component Auctions](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#21-initiating-an-on-device-auction) which feed their
bids to the final layer. To learn more about Component Auctions, go [here](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#24-scoring-bids-in-component-auctions).

The FLEDGE auction, including Component Auctions, are configured via an `AuctionConfig` object that defines the parameters of the auction for a given
seller. This module enables FLEDGE support by allowing bid adaptors to return `AuctionConfig` objects in addition to bids. If a bid adaptor returns an
`AuctionConfig` object, Prebid.js will register it with the appropriate GPT ad slot so the bidder can participate as a Component Auction in the overall
FLEDGE auction for that slot. More details on the GPT API can be found [here](https://developers.google.com/publisher-tag/reference#googletag.config.componentauctionconfig).

Modifying a bid adapter to support FLEDGE is a straightforward process and consists of the following steps:
1. Detecting when a bid request is FLEDGE eligible
2. Responding with AuctionConfig

FLEDGE eligibility is made available to bid adapters through the `bidderRequest.fledgeEnabled` field.
The [`bidderRequest`](https://docs.prebid.org/dev-docs/bidder-adaptor.html#bidderrequest-parameters) object is passed to
the [`buildRequests`](https://docs.prebid.org/dev-docs/bidder-adaptor.html#building-the-request) method of an adapter. Bid adapters
who wish to participate should read this flag and pass it to their server. FLEDGE eligibility depends on a number of parameters:

1. Chrome enablement
2. Publisher participatipon in the [Origin Trial](https://developer.chrome.com/docs/privacy-sandbox/unified-origin-trial/#configure)
3. Publisher Prebid.js configuration (detailed above)

When a bid request is FLEDGE enabled, a bid adapter can return a tuple consisting of bids and AuctionConfig objects rather than just a list of bids:

```js
function interpretResponse(resp, req) {
// Load the bids from the response - this is adapter specific
const bids = parseBids(resp);

// Load the auctionConfigs from the response - also adapter specific
const auctionConfigs = parseAuctionConfigs(resp);

if (auctionConfigs) {
// Return a tuple of bids and auctionConfigs. It is possible that bids could be null.
return {bids, auctionConfigs};
} else {
return bids;
}
}
```

An AuctionConfig must be associated with an adunit and auction, and this is accomplished using the value in the `bidId` field from the objects in the
`validBidRequests` array passed to the `buildRequests` function - see [here](https://docs.prebid.org/dev-docs/bidder-adaptor.html#ad-unit-params-in-the-validbidrequests-array)
for more details. This means that the AuctionConfig objects returned from `interpretResponse` must contain a `bidId` field whose value corresponds to
the request it should be associated with. This may raise the question: why isn't the AuctionConfig object returned as part of the bid? The
answer is that it's possible to participate in the FLEDGE auction without returning a contextual bid.

An example of this can be seen in the OpenX OpenRTB bid adapter [here](https://github.com/prebid/Prebid.js/blob/master/modules/openxOrtbBidAdapter.js#L327).

Other than the addition of the `bidId` field, the AuctionConfig object should adhere to the requirements set forth in FLEDGE. The details of creating an AuctionConfig object are beyond the scope of this document.