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:

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 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
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 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:

"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:

hooks:
  greenbids-real-time-data:
    enabled: true

Analytics Tags

The RTD module also communicates the filtering results with the GreenbidsAnalyticsReporter via AnalyticsTags. 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:

{
  "activities": [
    {
      "name": "greenbids-filter",
      "status": "success",
      "results": [
        {
          "status": "success",
          "values": {
            "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"
            }
          },
          "appliedTo": {
            "bidders": "bidderA",
            "impIds": "impId1"
          }
        }
      ]
    }
  ]
}

Maintainer contacts

For any questions and suggestions please reach out to our team for more information greenbids.ai.

Or just open new issue or pull request in this repository.

Further Reading