Optable module operates using a DCN backend API. Please contact your account manager to get started.

Optable Targeting Module

• Overview
• Setup
  • Execution Plan
  • Global Config
  • Account-Level Config
  • Timeout considerations
  • Caching
• Module Configuration Parameters for PBS-Java
• ID Mapping
  • Optable input erasure
  • Publisher Provided IDs (PPID) Mapping
• Analytics Tags
• Running the demo (PBS-Java)
• Maintainer contacts

Overview

The optable-targeting module enriches an incoming OpenRTB request by adding to the user.eids and user.data objects. Under the hood the module extracts PPIDs (publisher provided IDs) from the incoming request’s user.ext.eids, and also if present sha256-hashed email, sha256-hashed phone, zip or Optable Visitor ID provided correspondingly in the user.ext.optable.email, .phone, .zip, .vid fields (a full list of IDs is given in a table below). These IDs are sent as input to the Targeting API. The received response data is used to enrich the OpenRTB request and response. Targeting API endpoint is configurable per publisher.

Setup

Execution Plan

This module runs at two stages:

• Processed Auction Request: to enrich user.eids and user.data.
• Auction Response: to inject ad server targeting.

We recommend defining the execution plan in the account config so the module is only invoked for specific accounts. See below for an example.

Global Config

In the host-level config you need to specify the regional endpoint that would be closest to the host:

hooks:
  optable-targeting:
    enabled: true
  modules:
    optable-targeting:
      api-endpoint: https://na.edge.optable.co/v2/targeting?t={TENANT}&o={ORIGIN}

To obtain the endpoints for your regions - please contact prebid@optable.co.

Note the endpoint contains 2 macros: {TENANT} and {ORIGIN} - the values for which are provided in the account-level config as tenant and origin parameters correspondingly.

Account-Level Config

To start using current module in PBS-Java you have to enable module and add optable-targeting-processed-auction-request-hook and optable-targeting-auction-response-hook into hooks execution plan inside your config file: Here’s a general template for the account config used in PBS-Java:

hooks:
  optable-targeting:
    api-key: key
    tenant: optable
    origin: web-sdk-demo
    ppid-mapping: { "pubcid.org": "c" }
    adserver-targeting: true
    cache:
      enabled: false
      ttlseconds: 86400
  host-execution-plan: >
    {
      "endpoints": {
        "/openrtb2/auction": {
          "stages": {
            "processed-auction-request": {
              "groups": [
                {
                  "timeout": 100,
                  "hook-sequence": [
                    {
                      "module-code": "optable-targeting",
                      "hook-impl-code": "optable-targeting-processed-auction-request-hook"
                    }
                  ]
                }
              ]
            },
            "auction-response": {
              "groups": [
                {
                  "timeout": 10,
                  "hook-sequence": [
                    {
                      "module-code": "optable-targeting",
                      "hook-impl-code": "optable-targeting-auction-response-hook"
                    }
                  ]
                }
              ]
            }
          }
        }
      }
    }

Timeout considerations

The timeout value specified in the execution plan for the processed-auction-request hook is very important to be picked such that the hook has enough time to make a roundtrip to Optable Targeting Edge API over HTTP.

Note: Do not confuse hook timeout value with the module timeout parameter which is optional. The hook timeout value would depend on the cloud/region where the PBS instance is hosted and the latency to reach the Optable’s servers. This will need to be verified experimentally upon deployment.

The timeout value for the auction-response can be set to 10 ms - usually it will be sub-millisecond time as there are no HTTP calls made in this hook - Optable-specific keywords are cached on the processed-auction-request stage and retrieved from the module invocation context later.

Caching

The module uses Prebid Cache Storage feature that relies on the existing Prebid Cache Server. By default it is disabled, but if enabled it caches Targeting API responses for ttlseconds (24 hours by default) which reduces the module processing time to milliseconds, rather than hundreds of milliseconds, for the cached Targeting API responses.

Module Configuration Parameters for PBS-Java

The parameter names are specified with full path using dot-notation. F.e. section-name .sub-section .param-name would result in this nesting in the JSON configuration:

{
  "section-name": {
    "sub-section": {
      "param-name": "param-value"
    }
  }
}

ID Mapping

Internally the module sends requests to Optable Targeting API. The output of Targeting API is used to enrich the request and response. The below table describes the parameters that the module automatically fetches from OpenRTB request and then sends to the Targeting API. The module will use a prefix as specified in the table to prepend the corresponding ID value when sending it to the Targeting API in the form id=prefix:value.

See Optable documentation on identifier types. Targeting API accepts multiple id parameters - and their order may affect the results, thus id-prefix-order specifies the order of the ids.

Optable input erasure

Note: user.ext.optable.email, .phone, .zip, .vid fields will be removed by the module from the original OpenRTB request before being sent to bidders.

Publisher Provided IDs (PPID) Mapping

Custom user IDs are sent in the OpenRTB request in the user.ext.eids[]. The ppid-mapping allows to specify the mapping of a source to one of the custom identifier type prefixes c-c19 - see documentation, f.e.:

ppid-mapping: {"example.com": "c2", "test.com": "c3"}

It is also possible to override any of the automatically retrieved user.ext.eids[] mentioned in the table above (s.a. id5, utiq) so they are mapped to a different prefix. f.e. id5-sync.com can be mapped to a prefix other than id5:, like:

ppid-mapping: {"id5-sync.com": "c1"}

This will lead to id5 ID supplied as id=c1:... to the Targeting API.

Analytics Tags

The following 2 analytics tags are written by the module:

• optable-enrich-request
• optable-enrich-response

The status is either success or failure. Where it is failure a results[0].value.reason is provided.
For the optable-enrich-request activity the execution-time value is logged. Example:

{
  "analytics": {
    "tags": [
      {
        "stage": "auction-response",
        "module": "optable-targeting",
        "analyticstags": {
          "activities": [
            {
              "name": "optable-enrich-request",
              "status": "success",
              "results": [
                {
                  "values": {
                    "execution-time": 33
                  }
                }
              ]
            },
            {
              "name": "optable-enrich-response",
              "status": "success",
              "results": [
                {
                  "values": {
                    "reason": "none"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

If adserver-targeting was set to false in the config optable-enrich-response analytics tag is not written.

Running the demo (PBS-Java)

1. Build the server bundle JAR as described in Build Project, e.g.

mvn clean package --file extra/pom.xml

2. Start server bundle JAR as described in Running project, e.g.

java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-with-optable.yaml

3. Run sample request against the server as described in the sample directory, e.g.

curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-targeting/sample-requests/data.json

4. Observe the user.eids and user.data objects enriched.

Maintainer contacts

Any suggestions or questions can be directed to prebid@optable.co.

Alternatively please open a new issue or pull request in this repository.