Skip to content

Latest commit

 

History

History
280 lines (232 loc) · 7.19 KB

stored-requests.md

File metadata and controls

280 lines (232 loc) · 7.19 KB
Raw

Stored Requests

This document gives a technical overview of the Stored Requests feature.

Docs outlining the motivation and uses will be added sometime in the future.

Quickstart

Configure your server to read stored requests from the filesystem:

settings:
  filesystem:
    settings-filename: sample-app-settings.yaml
    stored-requests-dir: stored_requests
    stored-imps-dir: stored_imps

Choose an ID to reference your stored request data. Throughout this doc, replace {id} with the ID you've chosen.

Add the file stored_imps/{id}.json and populate it with some Imp data.

{
  "id": "test-imp-id",
  "banner": {
    "format": [
      {
        "w": 300,
        "h": 250
      },
      {
        "w": 300,
        "h": 600
      }
    ]
  },
  "ext": {
    "prebid": {
      "bidder": {
        "appnexus": {
          "placement_id": 10433394
        }
      }
    }
  }
}

Start your server and then POST to /openrtb2/auction with your chosen ID.

{
  "id": "test-request-id",
  "imp": [
    {
      "ext": {
        "prebid": {
          "storedrequest": {
            "id": "{id}"
          }
        }
      }
    }
  ]
}

The auction will occur as if the HTTP request had included the content from stored_requests/{id}.json instead.

Partially Stored Requests

You can also store part of the Imp on the server. For example:

{
  "banner": {
    "format": [
      {
        "w": 300,
        "h": 250
      },
      {
        "w": 300,
        "h": 600
      }
    ]
  },
  "ext": {
    "prebid": {
      "bidder": {
        "appnexus": {
          "placement_id": 10433394
        }
      }
    }
  }
}

This is not fully legal OpenRTB imp data, since it lacks an id.

However, incoming HTTP requests can fill in the missing data to complete the OpenRTB request:

{
  "id": "test-request-id",
  "imp": [
    {
      "id": "test-imp-id",
      "ext": {
        "prebid": {
          "storedrequest": {
            "id": "{id}"
          }
        }
      }
    }
  ]
}

If the Stored Request and the HTTP request have conflicting properties, they will be resolved with a JSON Merge Patch. HTTP request properties will overwrite the Stored Request ones.

Stored BidRequests

So far, our examples have only used Stored Imp data. However, Stored Requests are also allowed on the BidRequest. These work exactly the same way, but support storing properties like timeouts and price granularity.

For example, assume the following stored-requests/{id}.json:

{
    "tmax": 1000,
    "ext": {
      "prebid": {
        "targeting": {
          "pricegranularity": "low"
        }
      }
    }
  }

Then HTTP request like:

{
  "id": "test-request-id",
  "imp": [
    "Any valid Imp data in here"
  ],
  "ext": {
    "prebid": {
      "storedrequest": {
        "id": "{id}"
      }
    }
  }
}

will produce the same auction as if the HTTP request had been:

{
  "id": "test-request-id",
  "tmax": 1000,
  "imp": [
    "Any valid Imp data in here"
  ],
  "ext": {
    "prebid": {
      "targeting": {
        "pricegranularity": "low"
      }
    }
  }
}

Prebid Server does allow Stored BidRequests and Stored Imps in the same HTTP Request. The Stored BidRequest will be applied first, and then the Stored Imps after.

Beware: Stored Request data will not be applied recursively. If a Stored BidRequest includes Imps with their own Stored Request IDs, then the data for those Stored Imps will not be resolved.

Alternate backends

Stored Requests do not need to be saved to files. Other backends are supported with different configuration options.

Database backend

For PostgreSQL:

settings:
  database:
    type: postgres

For MySQL:

settings:
  database:
    type: mysql

The select query columns of stored-requests-query and amp-stored-requests-query properties should correspond to the specific format:

  • first column: account ID which is searched by.
  • second column: ID of stored data item which is searched by.
  • third column: value of stored data item.
  • forth column: type of stored data item. Can be request for stored requests or imp for stored impressions.

HTTP backend

settings:
  http:
    endpoint: http://stored-requests.prebid.com
    amp_endpoint: http://stored-requests.prebid.com?amp=true

Note: HTTP backend implementation always gives an empty result (with "Not supported" error inside) for obtaining the Account or AdUnitConfig by ID for the legacy auction endpoint.

Full list of application configuration options can be found here.

If you need support for a backend that you don't see, please contribute it.

Caches and updates

Stored Request data can also be cached or updated while PBS is running. Conceptually, Stored Request data is managed by the following components in the code:

ApplicationSettings: Implementations of this interface pull data directly from a backend. SettingsCache: Duplicates data which the ApplicationSettings could find so that it can be accessed more quickly. CacheNotificationListener: Provides interface apply changes to Stored Request data.

ApplicationSettings and methods of updating Stored Request data at runtime can also be chosen in the the app config. At least one ApplicationSettings is required to make use of Stored Requests.

If more than one ApplicationSettings is defined, they will be ordered and used as fallback data sources. This isn't a great idea for Prod in the long-term, but may be useful temporarily if you're trying to transition from one backend to another.

CacheNotificationListener is used to Save or Invalidate values from the cache.

Here is an example configuration file which looks for Stored Requests first from Postgres, and then from an HTTP endpoint. It will use an in-memory LRU cache to store data locally, and poll another HTTP endpoint to listen for updates.

settings:
  database:
    type: postgres
    host: localhost
    port: 5432
    dbname: database-name
    user: username
    password: password
    stored-requests-query: SELECT accountId, reqid, requestData, 'request' as dataType FROM stored_requests WHERE reqid IN (%REQUEST_ID_LIST%) UNION ALL SELECT accountId, impid, impData, 'imp' as dataType FROM stored_imps WHERE impid IN (%IMP_ID_LIST%)
    amp-stored-requests-query: SELECT accountId, reqid, requestData, 'request' as dataType FROM stored_requests WHERE reqid IN (%REQUEST_ID_LIST%)
  http:
    endpoint: http://stored-requests.prebid.com
    amp-endpoint: http://stored-requests.prebid.com?amp=true
  in-memory-cache:
    cache-size: 10000
    ttl-seconds: 360
    http-update:
      endpoint: http://stored-requests.prebid.com
      amp-endpoint: http://stored-requests.prebid.com?amp=true
      refresh-rate: 60000
      timeout: 2000

Refresh rate can be negative or zero - in such case the data will be fetched once and never updated.