Prebid Server Rules Enforcement

[bretg]

We had a discussion during backlog grooming about rules. There are several rules that we've been relaxed about enforcing in Prebid Server that Prebid.org publisher members are increasingly wanting to enforce.

The Prebid.js team has gone through a couple of rounds of tightening rules on client-side adapters, and many adapters have been removed. It's time for the Prebid Server community to consider which rules will be strictly enforced and a timeline for enforcement.

Here's an initial proposal based on the module rules reference.

Strictly enforceable rules

These rules will be enforced at a date TBD within 2nd or 3rd quarter in 2023. If an adapter doesn't adhere to all rules, they will be removed from the repo. We may consider extensions if a disclosure is added to the adapter documentation.

1. The contact info for bid adapters must be a current and working group address - not an individual.
2. Endpoint domain names cannot be fully variable. See Bidders that need to change whole-hostname parameter #2127
3. If the adapter has a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between client- and server-side adapters. This allows publishers to utilize the PBJS s2sTesting module.
4. Bid adapters cannot include unapproved libraries.
5. Bidder modules must not make requests to endpoints for functionality other than auctions.
6. Bidder modules must not cache bids from previous auctions.
7. Bid adapters cannot contact their endpoints directly, but only through the PBS-core interface.
8. Modules must utilize PBS-supplied communication functions so that the host company has insight into metrics and can configure circuit breaker logic that limits the damage misbehaving endpoints.
9. Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid.

Rules that will be enforced later

These rules will be enforced at a later date TBD. If an adapter doesn't adhere to all rules, they will be removed from the repo. We may consider extensions if a disclosure is added to the adapter documentation.

1. Endpoint domain names cannot contain any variables.
2. Once the iframe-multisync feature is available, bid adapters will have a time horizon to ensure that their Iframe usersyncs multi-sync according to the limits imposed.
3. Bidder modules should supply buyer metadata - including advertiser domain, actual mediatype, as defined in the Prebid documentation.

Recommended, but not strictly enforced

1. Bid adapters should support gzip compression on requests from PBS to their auction endpoints.
2. Bid adapters should understand how their endpoints handle currency and floors and transform the PBS request appropriately.

Process for removing a bid adapter or module

If a bid adapter or module is found to be in violation of one of these rules, the code will not be accepted. If the code has already been accepted and a violation is found, Prebid will work with the maintainers of the adapter/module and give them a reasonable amount of time to address the violation. In some cases, we may allow a documentation disclosure so publishers and host companies are aware of the situation.

Prebid and the adapter/module vendor will agree on a timeline that should be 3 months or less, depending on the nature of the violation and amount of work needed to address it. e.g. adding an alias should not take that long.

If the vendor does not respond to repeated requests or otherwise does not conform to these rules, we may place a disclosure on their Prebid documentation and schedule them for removal in a future release of Prebid Server.

[SyntaxNode]

Feedback from a discussion with the Prebid Server Committee:

Strictly enforceable rules:
3. Endpoint domain names cannot be fully variable. See #2127

We should discourage subdomains. We should provide guidance that region specific endpoints are intended to be configured by the host and not by publishers using bidder params. Should we require or suggest region specific endpoints to be listed in docs? This is a best practice we have today that might not be written down.

Strictly enforceable rules:
4. If the adapter has a client-side adapter, all parameters must be consistent between client- and server-side adapters. This allows publishers to utilize the PBJS s2sTesting module.

Should the rule include matching the bidder code / bidder name across Prebid.js and Prebid Server? As a random example, Colossus is “colossus” in Prebid Server and “colossusssp” in Prebid.js. Sometimes a bidder wishes to use a simpler name in their Prebid Server adapter. Perhaps we can mandate that Prebid Server must at least have an alias for the Prebid.js bidder code?

Also, if an alias is defined in Prebid.js it must be defined the same way in Prebid Server. As a random example, 152 Media is defined as an alias of AppNexus in Prebid.js and an alias of Adtelligent in Prebid Server. I'll look into how many aliases currently mistmach.

Strictly enforceable rules:
7. Bidder modules must not make requests to endpoints for functionality other than auctions.

In PBS-Java, modules are not allowed to listen for connections but can initiate outgoing connections. Can they initiate outgoing connections on their own or must they use a PBS-Core provided feature to allow control over latency, retry, circuit breaking, etc.? The Modularity PRD might specify these rules, but we didn’t remember in the discussion.

Also, this is separate from loss notifications. Notification should be a PBS-Core feature and not initiated by a module.

Actual Media Type

This is listed as both a requirement and a suggestion. Which is it? It is listed as required in “Rules That Will Be Enforced Later” Rule 2 and “Recommended” Rule 3. No preference from the group as to which it should be.

TID + Specific Field Rules

Should we create a new required rule that adapters must not create their own TID? This would defeat the purpose and harm DSPs, as they would not be able to understand the supply source. Is it important enough to be a rule? .. and should we include other fields adapters should respect, such as this bidfloors issue?

[bretg]

updated the description with the feedback above, and added a draft process for removal.

[dgirardi]

If the adapter has a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between client- and server-side adapters. This allows publishers to utilize the PBJS s2sTesting module.

I think this could be enforced as code: if we require adapters across all 3 of PBS and JS to first "declare" themselves in a shared registry, we should be able to use that as the single source of truth. For example, the declaration could look like:

// gh/prebid/AdapterRegistry/bidderA.json - file name defines bidder code
{
    gvlid: 123,
    aliases: [
        {
            code: "aliasB",
            gvlid: 321
        }
    ],
    params: {
        "siteId": {
               type: "String" 
         }
    }
}

From the POV of JS that would mean pulling the declaration in (at build time) instead of it being part of the adapter's spec. In fact I'd expect something like this to already exist between PBS-Go and Java (or do you need to define everything twice?) if that's the case we may already be able to reuse it for JS.

A registry of this sort could also work better for keeping things like contact info and documentation - especially the kind that's now in JS .md files.

[SyntaxNode]

I'd expect something like this to already exist between PBS-Go and Java (or do you need to define everything twice?

You need to define everything twice.

[SyntaxNode]

This would be good for some common data as you've suggested, including bidder code, params, contact info, supported inventory and media types. The hurdle we'll need to overcome is how this information is represented. PBS-Go and PBS-Java have different configuration, and then I'm sure there's bound to be further differences when we add in PBJS. Certainly worth a shot.

I do like the idea of the the file name defining the bidder code. We use a similar approach in parts of PBS-Go.

[dgirardi]

I'd expect JS to be the easiest to adapt by far since we don't have to fight with the type system, so you're welcome to choose the representation that works best between Go and Java. My hunch is that'll likely be the minimum common denominator between the serialization libraries they are using (since that's probably where you are expressing constraints on params or other inputs) - if this is part of a major PBS release, you could even take the opportunity to reframe those in something that works in both like protobuf.

[SyntaxNode]

The rules from this thread and ratified in the Prebid Server Committee are now incorporated in the module rules reference.