Greenbids RTD Module

prebid-server/pbs-modules/greenbids-real-time-data.md

@@ -0,0 +1,175 @@
+---
+layout: page_v2
+page_type: pbs-module
+title: Prebid Server Greenbids Real Time Data Module
+display_name : Greenbids Real Time Data Module
+sidebarType : 5
+---
+
+# Greenbids Real Time Data Module
+
+## Overview
+
+Greenbids Real Time Data module filters bidders SSPs listed in the `imp[].ext.prebid.bidder` of the bid request. 
+To perform the filtering the module uses AI to predict the bidding probability of bid per SSP for each `imp` for the given bid request.
+This bidding probability is used to choose to send the bid request or not, according to the performance constraints applied by the partner publisher.
+
+The RTD module uses 2 artefacts that are fetched from the Greenbids Google Cloud Storage bucket
+
+- ML predictor in `.onnx` format: used to predict the bidding probability
+- Probability thresholds in `.json` format: used to convert the bidding probability to a binary choice
+
+## Configuration
+
+### Execution Plan
+
+This module supports running at:
+
+- processed-auction-request: this is where PBS bid request enrichments
+are done before customizing it to a particular bidder in the auction.
+
+### Account-Level Config
+
+Here's an example of the account config used in PBS-Java:
+
+```yaml
+hooks:
+  greenbids-real-time-data:
+    enabled: true
+  host-execution-plan: >
+    {
+      "endpoints": {
+        "/openrtb2/auction": {
+          "stages": {
+            "processed-auction-request": {
+              "groups": [
+                {
+                  "timeout": 100,
+                  "hook-sequence": [
+                    {
+                      "module-code": "greenbids-real-time-data",
+                      "hook-impl-code": "greenbids-real-time-data-processed-auction-request-hook"
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+```
+
+### List of module configuration options
+
+- `google-cloud-greenbids-project`: Google Cloud project associated with Greenbids
+- `gcs-bucket-name`: Google Cloud Storage (GCS) bucket used to fetch the artefacts ([ONNX](https://onnx.ai/) model and thresholds `.json`) necessary for prediction
+- `cache-expiration-minutes`: The duration (in minutes) after which cached model and thresholds should be considered expired and refreshed
+- `geo-lite-country-path`: URL to the geo-ip database
+- `onnx-model-cache-key-prefix`: prefix necessary for getting cached ONNX model
+- `thresholds-cache-key-prefix`: prefix necessary for getting cached throttling thresholds
+
+```yaml
+greenbids-real-time-data:
+  google-cloud-greenbids-project: "greenbids-357713"
+  gcs-bucket-name: "greenbids-europe-west1-prebid-server-staging"
+  cache-expiration-minutes: 15
+  geo-lite-country-path: "https://git.io/GeoLite2-Country.mmdb"
+  onnx-model-cache-key-prefix: "onnxModelRunner_"
+  thresholds-cache-key-prefix: "throttlingThresholds_"
+```
+
+### Publisher bid request settings
+
+The activated partner publishers add their configs direclty into `bid-request.json` 
+where they indicate the activation of our module 
+in bid request extenstion `bid-request.ext.prebid.analytics.greenbids` 
+for [Analytics Reporter](https://docs.prebid.org/prebid-server/pbs-modules/greenbids-analytics-reporter.html) and 
+`bid-request.ext.prebid.analytics.greenbids-rtd` for Greenbids RTD Module.
+
+The list of the parameters necessary for RTD module activation is as follows:
+
+| Parameter       | Scope             | Description                                                                                         | Example               | Type         |
+|-----------------|-------------------|-----------------------------------------------------------------------------------------------------|-----------------------|--------------|
+| pbuid           | required          | The Greenbids Publisher ID                                                                          | greenbids-publisher-1 | string       |
+| targetTpr       | required          | Expected retained opportunities ratio [0-1]                                                         | 0.9                   | float        |
+| explorationRate | required          | Ratio of traffic without filtering used for training ML model [0-1] (a value of 0.1 will filter 90% of the traffic) | 0.1                   | float        |
+
+Here's an example of how a PBS partner publisher setup using both Greenbids RTD Module and Greenbids AnalyticsReporter should look like:
+
+```json
+"ext": {
+    "prebid": {
+      "analytics": {
+        // extension for Greenbids Analytics Reporter
+        "greenbids": {
+          "pbuid": "PBUID_FROM_GREENBIDS",
+          "greenbidsSampling": 0.01
+        },
+        // extension for Greenbids Real Time Data Module
+        "greenbids-rtd": {
+          "pbuid": "PBUID_FROM_GREENBIDS", 
+          "targetTpr": 0.95,
+          "explorationRate": 0.001
+        }
+      }
+    }
+  }
+```
+
+### Enable for Spring Boot
+
+In order to allow the module to be picked up by PBS-Java, a Spring Boot configuration property `hooks.greenbids-real-time-data.enabled` must be set to `true`.
+
+Here's an example of how your PBS configuration YAML should look like:
+
+```YAML
+hooks:
+  greenbids-real-time-data:
+    enabled: true
+```
+
+## Analytics Tags
+
+The RTD module also communicates the filtering results with the `GreenbidsAnalyticsReporter` via [AnalyticsTags](https://docs.prebid.org/prebid-server/developers/module-atags.html). 
+Here we populate analytics result of analytics tags for each `imp` the with:
+
+- `fingerprint`: greenbidsId
+- `isKeptInAuction`: map of booleans for each bidder whether we keep them in auction or not for the given imp
+- `isExploration`: flag that is necessary to isolate the training data
+
+The analytics tag is then parsed by the AnalyticsReporter from `HookExecutionContext` 
+and its content added to the analytics payload sent to Greenbids server. The exploration part of traffic is split randomly with the ratio defined for each partner publisher 
+per bid requests and is not filtered by the RTD module.
+
+Here's an example analytics tag that might be produced for use in an analytics adapter:
+
+```json
+[{
+    "pub_banniere_haute": {
+      "greenbids": {
+        "fingerprint": "ad63524e-b13f-4359-a975-dba9b5dc08f4",
+        "keptInAuction": {
+          "improvedigital": false,
+          "appnexus": true,
+          "pubmatic": false,
+          "rubicon": true,
+          "teads": false
+        },
+        "isExploration": false
+      },
+      "tid": "2c445309-06b2-47b2-a724-4aeef15faeb8"
+    }
+}]
+```
+
+## Maintainer contacts
+
+For any questions and suggestions please reach out to our team for more information [greenbids.ai](https://greenbids.ai). 
+
+Or just open new [issue](https://github.com/prebid/prebid-server-java/issues/new) or [pull request](https://github.com/prebid/prebid-server-java/pulls) in this repository.
+
+## Further Reading
+
+- [Prebid Server Module List](/prebid-server/pbs-modules/index.html)
+- [Building a Prebid Server Module](/prebid-server/developers/add-a-module.html)