PBS rules update (prebid#4359)

bretg · web-flow · commit 1f06ec62a238 · 2023-03-02T10:41:13.000-05:00
* PBS rules update

* review feedback

* Update module-rules.md
diff --git a/dev-docs/module-rules.md b/dev-docs/module-rules.md
@@ -20,7 +20,7 @@ several kinds of modules built by the community to enhance header bidding:
 | Bid Adapter | Obtains Open Market or Private Market bids for the current ad request. | Prebid.js, Prebid Server |
 | Analytics Adapter | Listens to auction events and reports to an analytics system. | Prebid.js, Prebid Server |
 | User ID Sub-Module | Obtains an ID for this user and makes that ID available to other types of modules. | Prebid.js |
-| Real Time Data Sub-Module | Obtains data for the current user's context that may be of interest to advertisers. | Prebid.js |
+| Real Time Data Sub-Module | Obtains data for the current user's context that may be of interest to advertisers. | Prebid.js, Prebid Server |
 | Other | Modules that don't fall into one of the other categories. | Prebid.js |
 
 ## Prebid.org Core Values
@@ -40,65 +40,78 @@ Bid adapters, user ID adapters, analytics adapters, and other modules will be re
 
 This set of module rules applies to both Prebid.js and Prebid Server.  However, these rules don’t necessarily apply to tools or the Prebid Mobile SDK. Rules and guidelines for those products will be determined by their respective committees as required.
 
-The use of the terms "must" and "should" in this document is deliberate.  However, some of the rules are "aspirational," in that we know there are existing exceptions to the rule that will need to get sorted out over time. These are marked with an asterisk (*). The goal is:
-
-- Every new module adheres to all required rules.
-- Even grandfathered modules must adhere to all required rules by Prebid.js 5.0.
+The use of the terms "must" and "should" in this document is deliberate.  However, some of the rules are "aspirational," in that we know there are existing exceptions to the rule that will need to get sorted out over time. These are marked with an asterisk (*).
 
 ### Global Module Rules
 
-1. Modules must(*) not load outside code files unless those libraries are approved and open source.
+#### Strictly Enforced Rules
+
+1. Each adapter and module must include maintainer information with a group email address for Prebid.org to contact for support or maintenance. The group email address must remain current and respond to enquiries in a timely manner.
+1. Modules must not load outside code files unless those libraries are approved and open source.
     1. External modules may be used at build-time at the discretion of the relevant Prebid committee. Build-time modules must be locked to a particular version so that any upgrades must be done via Prebid pull request.
     1. Exceptions may be made in the following cases:
         - When the publisher has control over whether the file is loaded and which version, the base module should be able to work without the auxiliary file.
         - If run-time code is not needed for the auction, it should support a deferred load. E.g. User ID modules.
-        - The file loaded must be locked to a particular version so that any upgrades must be done via Prebid pull request.
-        - A prominent disclosure must be made about the loading of the file and why they need the file, and a size warning provided if it’s greater than 10KB.
-    1. If a functionality is supported by Prebid core or an existing module, Prebid modules must prefer the Prebid version of that functionality rather than an externally coded version.
-    1. The build-time or run-time loading of required or optional external files must be disclosed. (See the disclosure section below.)
-    1. Modules must not import other Prebid modules at build time.
-1. Modules must not(*)  add any pixel, iframe, cookie or local storage directly onto the page. Rather, they must use wrapper-provided mechanisms for usersyncs, cookies, and local storage.
+        - The file loaded is locked to a particular version so that any upgrades must be done via Prebid pull request.
+        - A prominent disclosure is made about the loading of the file and why they need the file, and a size warning provided if it’s greater than 10KB.
+    1. If a functionality is supported by Prebid core or an existing module, modules must prefer the Prebid version of that functionality rather than an externally coded version.
+    1. The build-time or run-time loading of required or optional external files must be disclosed. (See the [disclosure](#disclosure) section below.)
 1. Modules must use the communication functions provided by the Prebid core (both Prebid.js and Prebid Server) for external communication.
-1. Prebid.js modules must not use the $$PREBID_GLOBAL$$ variable nor otherwise obtain a pointer to the global PBJS object. This preserves data integrity.
+1. Modules must not add any pixel, iframe, cookie or local storage directly onto the page. Rather, they must use wrapper-provided mechanisms for usersyncs, cookies, and local storage.
 1. All modules must support the creation of multiple concurrent instances. This means, for example, they cannot rely on mutable global variables.
-    - Writing to the global window object must be non-intrusive, disclosed, and done in a way that supports multiple instances.
-1. All modules and any external code references must disclose their support of privacy regulations such as GDPR, CCPA, COPPA, etc. (See the disclosure section below.)
+    - PBJS: Writing to the global window object must be non-intrusive, disclosed, and done in a way that supports multiple instances.
+1. Modules must not include polyfills and must not override standard or Prebid JavaScript functions
+1. Endpoint domain names cannot be fully variable. At some point, they won't be able contain any variables at all. e.g. $PARAM1.example.com.
+1. To be listed on the Prebid.org website, a module must be in a Prebid open source repository.
+1. Prebid.js requests and responses must be secure HTTPS.
+1. Prebid.js modules must not use the PREBID_GLOBAL variable nor otherwise obtain a pointer to the global PBJS object. This preserves data integrity.
+
+#### Rules that May Someday Be Enforced
+
 1. Responses to auction or data requests should be compressed as long as the client supports that functionality (e.g. gzip, compress, deflate).
-1. Prebid.js requests and responses must be secure HTTPS. Prebid Server requests should be HTTPS.
 1. Endpoints should use HTTP/2 with keepalives so that connections don’t need to be re-created.
-1. In order to be listed on the Prebid.org website, a module must be in a Prebid open source repository.
-1. Each module must include maintainer information with a group email address for Prebid.org to contact for support or maintenance.
-1. Modules must not include polyfills or override standard or Prebid JavaScript functions.
 1. External modules must not use getEidPermissions function of userId module (e.g. prebidServerBidAdapter is an internal prebid module). 
+1. All modules and any external code references must disclose their support of privacy regulations such as GDPR, CCPA, COPPA, etc. (See the [disclosure](#disclosure) section below.)
 
 ### Bidder Adapter Rules
 
-1. All global rules apply.
+All global rules apply.
+
+#### Stricly Enforced Rules
+
 1. Bid adapters must be able to bid. If they cannot return an auction bid, they should consider integration as a Real-Time Data or other module type.
-1. Creative rendering scripts must(*) load from the creative frame and not directly in the page. In other words, creative rendering JavaScript cannot be used to bypass the “no external code” rule.
-1. Bidder modules must not(*) make requests to endpoints for functionality other than auctions without:
+1. Bidder modules must not make requests to endpoints for functionality other than auctions. There's no exceptions to this rule for Prebid Server, though Prebid.js may allow exceptions with:
     1. Disclosure
     1. Ability for the publisher to control the additional functionality.
     1. Ensuring auctions are still operable if the publisher turns off the additional functionality; i.e., bid adapters may log certain analytics events, but if a publisher turns it off, the auction should still happen.
     1. Building a Real-Time Data sub-module that obtains data in a way that can be utilized by other bidders as well if a bidder would like to incorporate an external data fetch that would influence the auction.
 1. Bidder modules must not obtain bid information from or about any other party in the auction. E.g., they cannot listen to ad server events and forward information naming other bidders back to their endpoint - that is the job of an analytics module.
-1. Bidder modules must not(*) cache bids from previous auctions. That functionality is reserved for Prebid core.
-1. Bidders must accept parameters in the conventional location in preference to bidder-specific parameters. The list of these parameters is in the [bidder adapter documentation](/dev-docs/bidder-adaptor.html#std-param-location).
+1. Bidder modules must not cache bids from previous auctions. That functionality is reserved for Prebid core.
+1. Bidders must accept parameters in the conventional location in preference to bidder-specific parameters. The list of these parameters is in the bidder adapter documentation for [PBJS](/dev-docs/bidder-adaptor.html#std-param-location) and [PBS](/developers/add-new-bidder-go.html#bidder-parameters).
 1. Bidders must not override the standard ad server targeting values: hb_adid, hb_bidder, hb_pb, hb_deal, or hb_size, hb_source, hb_format.
+1. If a bidder has adapters for both Prebid.js and Prebid Server, all parameters (including biddercodes and aliases) must be consistent between client- and server-side adapters. This allows publishers to utilize the PBJS [s2sTesting module](/dev-docs/modules/s2sTesting.html).
+1. Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid.
+
+#### Rules that May Someday Be Enforced
+
+1. Creative rendering scripts must load from the creative frame and not directly in the page. In other words, creative rendering JavaScript cannot be used to bypass the “no external code” rule.
 1. If bid adapters are reporting multiple media types in the hb_format as ‘banner’, they must(*) indicate the actual mediatype in the metadata object. One use case for this is that it allows publishers to manage which creatives support safeframes.
 1. Bidder modules should supply buyer metadata - including advertiser, advertiser domain, network, actual mediatype, and others defined in the Prebid documentation.
 1. Creatives returned must be fully HTTPS.
+1. Bid adapters should understand how their endpoints handle currency and floors, and make the necessary changes in the endpoint request.
 
 ### Analytics Adapter Rules
 
-1. All global rules apply.
+All global rules apply.
+
 1. Analytics adapters must not bid or supply any parameters to the auction.
 1. Analytics adapters must be neutral to the bid adapters -- not favoring any particular bidder in any way.
 1. Analytics adapters should minimize the number of times they call their endpoints by batching auction and event data.
 
 ### User ID Sub-Module Rules
 
-1. All global rules apply.
+All global rules apply.
+
 1. ID sub-modules must not gather any information from the page except for publisher-approved ID data for this user.
 1. ID sub-modules must not report analytics information back to their endpoints, including use of other user IDs, auction information, bidders, bids won, etc. This is the job of an analytics module.
 1. ID sub-modules must be neutral to the bid adapters -- each bidder must have the same opportunity to utilize each user ID.
@@ -134,7 +147,8 @@ To manage this, we plan to:
 1. Make sure that disclosures are applied to all existing and new adapter aliases.
 
 
-# Further Reading
+# Related Reading
 
 - Adding a bid adapter: [Prebid.js](/dev-docs/bidder-adaptor.html), [Prebid Server](/prebid-server/developers/add-new-bidder-go.html)
 - Adding an analytics adapter: [Prebid.js](/dev-docs/integrate-with-the-prebid-analytics-api.html), [Prebid Server](/prebid-server/developers/pbs-build-an-analytics-adapter.html)
+- Adding a module: [Prebid.js](/dev-docs/add-rtd-submodule.html), [Prebid Server](/prebid-server/developers/add-a-module.html)
diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md
@@ -39,13 +39,16 @@ Throughout the rest of this document, substitute `{bidder}` with the name you've
 
 We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://prebid.org/code-of-conduct/) and [module rules](/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions.
 
-**Please take the time to read our rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter:
+**Please take the time to read the rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter:
+  - Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance.
+  - Your bidder's endpoint domain name cannot be variable. If you want to have different endpoints in different geographical locations, Prebid Server host companies can do that for you. Publisher information can be in the query string, but not the domain.
+  - If you have a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between your client- and server-side adapters. This allows publishers to utilize the PBJS [s2sTesting module](/dev-docs/modules/s2sTesting.html).
   - Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another.
   - Adapters must use the functions provided by the core framework for all external communication. Initiation of any form of network connection outside of what is provided by the core framework is strictly prohibited. No exceptions will be made for this rule.
   - Adapters must support the creation of multiple concurrent instances. This means adapters may not mutate global or package scoped variables.
   - Bidding server endpoints should prefer secure HTTPS to protect user privacy and should allow keep alive connections (preferably with HTTP/2 support) to increase host performance.
-  - Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance.
   - Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server.
+  - Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid.
 
 {: .alert.alert-warning :}
 Failure to follow the rules will lead to delays in approving your adapter. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new).
diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md
@@ -39,13 +39,16 @@ Throughout the rest of this document, substitute `{bidder}` with the name you've
 
 We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://prebid.org/code-of-conduct/) and [module rules](/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions.
 
-**Please take the time to read our rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter:
-- Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another.
-- Adapters must use the functions provided by the core framework for all external communication. Initiation of any form of network connection outside of what is provided by the core framework is strictly prohibited. No exceptions will be made for this rule.
-- Adapters must support the creation of multiple concurrent instances. This means adapters may not mutate global or package scoped variables.
-- Bidding server endpoints should prefer secure HTTPS to protect user privacy and should allow keep alive connections (preferably with HTTP/2 support) to increase host performance.
-- Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance.
-- Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server.
+**Please take the time to read the rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter:
+  - Adapters must include maintainer information with a group email address for Prebid.org to contact for ongoing support and maintenance.
+  - Your bidder's endpoint domain name cannot be variable. If you want to have different endpoints in different geographical locations, Prebid Server host companies can do that for you. Publisher information can be in the query string, but not the domain.
+  - If you have a client-side adapter, all parameters (including biddercodes and aliases) must be consistent between your client- and server-side adapters. This allows publishers to utilize the PBJS [s2sTesting module](/dev-docs/modules/s2sTesting.html).
+  - Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another.
+  - Adapters must use the functions provided by the core framework for all external communication. Initiation of any form of network connection outside of what is provided by the core framework is strictly prohibited. No exceptions will be made for this rule.
+  - Adapters must support the creation of multiple concurrent instances. This means adapters may not mutate global or package scoped variables.
+  - Bidding server endpoints should prefer secure HTTPS to protect user privacy and should allow keep alive connections (preferably with HTTP/2 support) to increase host performance.
+  - Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server.
+  - Bid adapters must not create their own transaction IDs or overwrite the tids supplied by Prebid.
 
 {: .alert.alert-warning :}
 Failure to follow the rules will lead to delays in approving your adapter for inclusion in Prebid Server. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server-java/issues/new).
