diff --git a/assets/images/prebid-server/module-example.png b/assets/images/prebid-server/module-example.png index ea864b1c15..3c3d22e468 100644 Binary files a/assets/images/prebid-server/module-example.png and b/assets/images/prebid-server/module-example.png differ diff --git a/prebid-server/developers/add-a-module-java.md b/prebid-server/developers/add-a-module-java.md index 90aaa31aa7..72b43f3b14 100644 --- a/prebid-server/developers/add-a-module-java.md +++ b/prebid-server/developers/add-a-module-java.md @@ -123,6 +123,7 @@ These are the available hooks that can be implemented in a module: - org.prebid.server.hooks.v1.bidder.RawBidderResponseHook - org.prebid.server.hooks.v1.bidder.AllProcessedBidResponsesHook - org.prebid.server.hooks.v1.auction.AuctionResponseHook +- org.prebid.server.hooks.v1.exitpoint.ExitpointHook In a module it is not necessary to implement all mentioned interfaces but only one (or several) required by your functionality. @@ -131,6 +132,17 @@ Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic int - `code()` - returns module code. - `call(...)` - returns result of hook invocation. +### Difference between AuctionResponseHook and ExitpointHook +In a nutshell, both hooks allow the modification of the OpenRTB Bid Response but in different ways. +The `AuctionResponseHook` provides a last chance to work with the Java objects that modify the auction response. +The `ExitpointHook` allows you to build a completely different response based on the received auction context. i.e. something that's not OpenRTB JSON - something like VAST. These hooks could modify the auction/amp/video response that PBS has built, or it could build another one and modify response headers accordingly. + +Important Notes: + +- The ExitpointHook is a powerful tool that allows rewriting the auction results, so make sure important data won't be lost for the client. +- Since the response body is not modified after calling the ExitpointHook, debug and traces won't be added by PBS-core. The exitpoint hook is responsible for adding its own tracing to the generated output. +- Analytics adapters doesn't have access to the response built by the ExitpointHook, but they receive the up-to-date auction context with the ExitpointHook execution status and analytics tags. + ### Examples 1. To **update** the request in the `RawAuctionRequestHook` you would return: diff --git a/prebid-server/developers/add-a-module.md b/prebid-server/developers/add-a-module.md index 74059d93a3..0edbbd3cb7 100644 --- a/prebid-server/developers/add-a-module.md +++ b/prebid-server/developers/add-a-module.md @@ -70,7 +70,8 @@ Here's a description of the Stages of a PBS request that modules can tap into fo | Bidder Request | The request has been customized for a particular bidder in the auction. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Bidder-specific bcat/badv, Bidder-specific deals | | Raw Bidder Response | Hook functions can get access to the unprocessed bidder response. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Response validations | | All Processed Bid Responses | All bids are back and PBS-core bid validations are done. | auction, amp, video | Creative validation, advanced bid validations. | -| Auction Response | Last step before the response goes back to the client | auction, amp, video | Inject ad server targeting, alternate auction winner logic | +| Auction Response | Last chance to modify the bid auction response | auction, amp, video | Inject ad server targeting, alternate auction winner logic | +| Exitpoint | (PBS-Java 3.16+) Last step before the response goes back to the client. Specify the response headers and body | auction, amp, video | Create a VAST response instead of OpenRTB. | ### 3. Figure Out Which Stages You're Going to Hook Into