From b5515c395a62931eb21f26785757685d35cc5e75 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Fri, 17 Jan 2025 19:56:11 +0100 Subject: [PATCH 01/17] optable-targeing module draft doc --- prebid-server/pbs-modules/index.md | 1 + .../pbs-modules/optable-targeting.md | 166 ++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 prebid-server/pbs-modules/optable-targeting.md diff --git a/prebid-server/pbs-modules/index.md b/prebid-server/pbs-modules/index.md index bae04a3aa3..25da1731f0 100644 --- a/prebid-server/pbs-modules/index.md +++ b/prebid-server/pbs-modules/index.md @@ -36,6 +36,7 @@ The full list of modules: | [**Greenbids Real Time Data**](/prebid-server/pbs-modules/greenbids-real-time-data.html) | Filters out bidders that are not expected to bid on this request, saving money and carbon. | general | | check | | [**Request Correction**](/prebid-server/pbs-modules/request-correction.html) | Apply optional corrections to bid requests. | general | | check | | [**Response Correction**](/prebid-server/pbs-modules/response-correction.html) | Apply optional corrections to bid responses. | general | | check | +| [**Optable Targeting**](/prebid-server/pbs-modules/optable-targeting.html) | Enrich `user.ext.eids`, `user.ext.data`. | general | | check | ## Installing a PBS General Module diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md new file mode 100644 index 0000000000..69bf62e4b0 --- /dev/null +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -0,0 +1,166 @@ +--- +layout: page_v2 +page_type: pbs-module +title: Prebid Server Optable Targeting Module +display_name : Optable Targeting Module +sidebarType : 5 +--- + +{: .alert.alert-warning :} +Optable module operates using a DCN backend API. Please contact your account manager to get started. + +# Optable Targeting Module +{:.no_toc} + +* TOC +{:toc } + +## Overview + +Optable module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.data` objects. +As input module may use PPIDs (publisher provided IDs) as part of the `user.ext.eids` and/or sha256-hashed email, sha256-hashed phone or postal_code provided at `user.ext.optable.email`, `.phone`, `.postal_code` fields. + +## Setup + +### Execution Plan + +This module runs at two stages: + +* Processed Auction Request: to enrich `user.ext.eids` and `user.ext.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 + +There is no host-company level config for this module. + +### 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: + +```yaml +hooks: + optable-targeting: + enabled: true + 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" + } + ] + } + ] + } + } + } + } + } +``` + +Sample module enablement configuration in JSON and YAML formats: + +```json +{ + "modules": + { + "optable-targeting": + { + "api-endpoint": "", + "api-key": "", + "ppid-mapping": {}, + "adserver-targeting": false, + } + } +} +``` + +```yaml + modules: + optable-targeting: + api-endpoint: + api-key: + ppid-mapping: + adserver-targeting: false +``` + +## 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: + +```json +{ + "section-name": { + "sub-section": { + "param-name": "param-value" + } + } +} +``` + +{: .table .table-bordered .table-striped } +| Param Name | Required| Type | Default value | Description | +|:-------|:------|:------|:------|:---------------------------------------| +| api-endpoint | yes | string | none | Targeting Edge API endpoint URL, required | +| api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | +| ppid-mapping | no | map | none | This specifies PPID source to custom identifier name mapping, f.e. {"example-id.com" : "c_0" } | +| adserver-targeting | no | boolean | false | If set to true - will add the adserver targeting keywords into the response | + +## Running the demo (PBS-Java) + +1. Build the server bundle JAR as described in [Build Project](https://github.com/prebid/prebid-server-java/blob/master/docs/build.md#build-project), e.g. + +```bash +mvn clean package --file extra/pom.xml +``` + +{:start="3"} +2. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. + +```bash +java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/prebid-config-optable.yaml +``` + +{:start="4"} +3. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. + +```bash +curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-targeting/sample-requests/data.json +``` + +{:start="5"} +4. Observe the `user.ext.eids` and `user.ext.data` objects enriched. + + +## Maintainer contacts + +Any suggestions or questions can be directed to [](mailto:) e-mail. + +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) From 4ea6e5014cf7e08a02477a642c607db831a456bc Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 22 Jan 2025 11:28:43 +0100 Subject: [PATCH 02/17] optable-targeting: fix paths --- prebid-server/pbs-modules/optable-targeting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 69bf62e4b0..7b697112be 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -44,7 +44,7 @@ Here's a general template for the account config used in PBS-Java: hooks: optable-targeting: enabled: true - host_execution_plan: > + host-execution-plan: > { "endpoints": { "/openrtb2/auction": { @@ -141,7 +141,7 @@ mvn clean package --file extra/pom.xml 2. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. ```bash -java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/prebid-config-optable.yaml +java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-optable.yaml ``` {:start="4"} From 3406c69d2c03cb900ff0e7e20a854f0d3eae0002 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Mon, 27 Jan 2025 17:48:46 +0100 Subject: [PATCH 03/17] optable-targeting: update maintainer contacts --- prebid-server/pbs-modules/optable-targeting.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 7b697112be..90dd5e2004 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -157,10 +157,6 @@ curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-target ## Maintainer contacts -Any suggestions or questions can be directed to [](mailto:) e-mail. +Any suggestions or questions can be directed to [prebid@optable.co](mailto:prebid@optable.co). -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) +Alternatively please open a 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. From 29e16676b4d7d173f31861a4adc3dd79d423e174 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 19 Feb 2025 19:44:32 +0100 Subject: [PATCH 04/17] optable-targeting: add timeout considerations and params info --- .../pbs-modules/optable-targeting.md | 32 +++++++++++++------ 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 90dd5e2004..7c92c54796 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -89,9 +89,12 @@ Sample module enablement configuration in JSON and YAML formats: { "optable-targeting": { - "api-endpoint": "", - "api-key": "", - "ppid-mapping": {}, + "api-endpoint": "endpoint", + "api-key": "key", + "timeout": 50, + "ppid-mapping": { + "pubcid.org": "c" + }, "adserver-targeting": false, } } @@ -101,12 +104,21 @@ Sample module enablement configuration in JSON and YAML formats: ```yaml modules: optable-targeting: - api-endpoint: - api-key: - ppid-mapping: + api-endpoint: endpoint + api-key: key + timeout: 50 + ppid-mapping: { + "pubcid.org": "c" + } adserver-targeting: false ``` +### 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. + ## 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: @@ -124,10 +136,12 @@ The parameter names are specified with full path using dot-notation. F.e. `sect {: .table .table-bordered .table-striped } | Param Name | Required| Type | Default value | Description | |:-------|:------|:------|:------|:---------------------------------------| -| api-endpoint | yes | string | none | Targeting Edge API endpoint URL, required | +| api-endpoint | yes | string | none | Optable Targeting Edge API endpoint URL, required | | api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | -| ppid-mapping | no | map | none | This specifies PPID source to custom identifier name mapping, f.e. {"example-id.com" : "c_0" } | -| adserver-targeting | no | boolean | false | If set to true - will add the adserver targeting keywords into the response | +| ppid-mapping | no | map | none | This specifies PPID source to custom identifier name mapping, f.e. `{"example-id.com" : "c_0"}` | +| adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | +| timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | +| id-prefix-order | no | list | [] | An optional list of id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. ["c","c1","id5"] will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | ## Running the demo (PBS-Java) From 06f621bf4035e2202a71cf29be449473e218275b Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Mon, 24 Feb 2025 16:54:14 +0100 Subject: [PATCH 05/17] optable: add section on analytics tags --- .../pbs-modules/optable-targeting.md | 60 ++++++++++++++++++- 1 file changed, 57 insertions(+), 3 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 7c92c54796..1f1b8c5d81 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -143,30 +143,84 @@ The parameter names are specified with full path using dot-notation. F.e. `sect | timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | | id-prefix-order | no | list | [] | An optional list of id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. ["c","c1","id5"] will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | +## 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: +```json +"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-targeing` was set to `false` in the config `optable-enrich-response` analytics tag is not written. + ## Running the demo (PBS-Java) +{:start="1"} 1. Build the server bundle JAR as described in [Build Project](https://github.com/prebid/prebid-server-java/blob/master/docs/build.md#build-project), e.g. ```bash mvn clean package --file extra/pom.xml ``` +{:start="2"} +2. In the `sample/configs/prebid-config-optable.yaml` file specify the `api-endpoint` URL of your DCN, f.e.: +```yaml +api-endpoint: https://example.com/v2/targeting +``` + {:start="3"} -2. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. +3. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. ```bash java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-optable.yaml ``` {:start="4"} -3. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. +4. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. ```bash curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-targeting/sample-requests/data.json ``` {:start="5"} -4. Observe the `user.ext.eids` and `user.ext.data` objects enriched. +5. Observe the `user.ext.eids` and `user.ext.data` objects enriched. ## Maintainer contacts From 9721b62f48d87d4771b9fb1f752b53f84f1ac006 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 26 Feb 2025 19:12:37 +0100 Subject: [PATCH 06/17] optable: extend the doc on ID mapping --- .../pbs-modules/optable-targeting.md | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 1f1b8c5d81..43c35dd092 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -138,11 +138,47 @@ The parameter names are specified with full path using dot-notation. F.e. `sect |:-------|:------|:------|:------|:---------------------------------------| | api-endpoint | yes | string | none | Optable Targeting Edge API endpoint URL, required | | api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | -| ppid-mapping | no | map | none | This specifies PPID source to custom identifier name mapping, f.e. `{"example-id.com" : "c_0"}` | +| ppid-mapping | no | map | none | This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | | adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | | timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | | id-prefix-order | no | list | [] | An optional list of id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. ["c","c1","id5"] will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | +## 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](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes) 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. + +{: .table .table-bordered .table-striped } +| Type | ortb2 path | Targeting API id param prefix | +| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------- | +| Email Address | `user.ext.optable.email` | `e:` | +| Phone Number | `user.ext.optable.phone` | `p:` | +| Postal Code | `user.ext.optable.zip` | `z:` | +| IPv4 Address | `device.ip` | ~~i4:~~ `x-forwarded-for` header | +| IPv6 Address | `device.ipv6` | ~~i6:~~ `x-forwarded-for` header | +| Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt=0` | `a:` | +| Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt=0` | `g:` | +| Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt=0` | `r:` | +| Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt=0` | `s:` | +| Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt=0` | `f:` | +| [NetID](https://docs.prebid.org/dev-docs/modules/userid-submodules/netid.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="netid.de"` | `n:` | +| ID5 | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | +| Utiq | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | +| Optable VID | `user.ext.optable.vid` | `v:` | + +**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[]`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-). The `ppid-mapping` allows to specify the mapping of a source to one of the custom identifier type prefixes `c`-`c19` - see [documentation](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes), 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` @@ -188,7 +224,7 @@ Example: } ``` -If `adserver-targeing` was set to `false` in the config `optable-enrich-response` analytics tag is not written. +If `adserver-targeting` was set to `false` in the config `optable-enrich-response` analytics tag is not written. ## Running the demo (PBS-Java) From 44ee8c3282fea359e0fa0539c6c91b626e09e0a0 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 26 Feb 2025 19:19:16 +0100 Subject: [PATCH 07/17] otpable: cosmetics --- prebid-server/pbs-modules/optable-targeting.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 43c35dd092..8cb09762f7 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -148,24 +148,27 @@ The parameter names are specified with full path using dot-notation. F.e. `sect 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](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes) 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. {: .table .table-bordered .table-striped } -| Type | ortb2 path | Targeting API id param prefix | +| Identifier Type | OpenRTB field | ID Type Prefix | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------- | | Email Address | `user.ext.optable.email` | `e:` | | Phone Number | `user.ext.optable.phone` | `p:` | | Postal Code | `user.ext.optable.zip` | `z:` | -| IPv4 Address | `device.ip` | ~~i4:~~ `x-forwarded-for` header | -| IPv6 Address | `device.ipv6` | ~~i6:~~ `x-forwarded-for` header | +| IPv4 Address | `device.ip` | ~~i4:~~ Sent as `X-Forwarded-For` header | +| IPv6 Address | `device.ipv6` | ~~i6:~~ Sent as `X-Forwarded-For` header | | Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt=0` | `a:` | | Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt=0` | `g:` | | Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt=0` | `r:` | | Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt=0` | `s:` | | Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt=0` | `f:` | | [NetID](https://docs.prebid.org/dev-docs/modules/userid-submodules/netid.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="netid.de"` | `n:` | -| ID5 | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | -| Utiq | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | +| [ID5](https://docs.prebid.org/dev-docs/modules/userid-submodules/id5.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | +| [Utiq](https://docs.prebid.org/dev-docs/modules/userid-submodules/utiq.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | | Optable VID | `user.ext.optable.vid` | `v:` | -**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. + +### 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[]`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-). The `ppid-mapping` allows to specify the mapping of a source to one of the custom identifier type prefixes `c`-`c19` - see [documentation](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes), f.e.: From 69e20fdca8edd8d5f9dba7c40e3d13c7815076db Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Fri, 28 Feb 2025 17:40:32 +0100 Subject: [PATCH 08/17] optable-targeting: enhance summary --- prebid-server/pbs-modules/optable-targeting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 8cb09762f7..7e307c7b70 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -17,8 +17,7 @@ Optable module operates using a DCN backend API. Please contact your account man ## Overview -Optable module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.data` objects. -As input module may use PPIDs (publisher provided IDs) as part of the `user.ext.eids` and/or sha256-hashed email, sha256-hashed phone or postal_code provided at `user.ext.optable.email`, `.phone`, `.postal_code` fields. +The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.data` objects. Under the hood the module extracts PPIDs (publisher provided IDs) from the incoming request's `user.ext.eids`, and also if provided sha256-hashed email, sha256-hashed phone, zip or Optable Visitor ID provided correspondingly in the `user.ext.optable.email`, `.phone`, `.zip`, `.vid` fields (see the full list of extracted IDs in the section on ID mapping 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 From 9f00ddff27c9d3d785a61346129facdbd1ef8a15 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Fri, 28 Feb 2025 23:41:09 +0100 Subject: [PATCH 09/17] optable-targeting: enhance summary and table .lmt!=1 condition --- prebid-server/pbs-modules/optable-targeting.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 7e307c7b70..03e0043db9 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -17,7 +17,7 @@ Optable module operates using a DCN backend API. Please contact your account man ## Overview -The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.data` objects. Under the hood the module extracts PPIDs (publisher provided IDs) from the incoming request's `user.ext.eids`, and also if provided sha256-hashed email, sha256-hashed phone, zip or Optable Visitor ID provided correspondingly in the `user.ext.optable.email`, `.phone`, `.zip`, `.vid` fields (see the full list of extracted IDs in the section on ID mapping 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. +The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.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 @@ -154,11 +154,11 @@ Internally the module sends requests to Optable Targeting API. The output of Tar | Postal Code | `user.ext.optable.zip` | `z:` | | IPv4 Address | `device.ip` | ~~i4:~~ Sent as `X-Forwarded-For` header | | IPv6 Address | `device.ipv6` | ~~i6:~~ Sent as `X-Forwarded-For` header | -| Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt=0` | `a:` | -| Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt=0` | `g:` | -| Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt=0` | `r:` | -| Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt=0` | `s:` | -| Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt=0` | `f:` | +| Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt!=1` | `a:` | +| Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt!=1` | `g:` | +| Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt!=1` | `r:` | +| Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt!=1` | `s:` | +| Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt!=1` | `f:` | | [NetID](https://docs.prebid.org/dev-docs/modules/userid-submodules/netid.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="netid.de"` | `n:` | | [ID5](https://docs.prebid.org/dev-docs/modules/userid-submodules/id5.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | | [Utiq](https://docs.prebid.org/dev-docs/modules/userid-submodules/utiq.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | From dda36702713555e4983ca95e42841e031e9f1df7 Mon Sep 17 00:00:00 2001 From: softcoder594 Date: Tue, 4 Mar 2025 19:43:06 +0100 Subject: [PATCH 10/17] optable-targeting: update id-prefix-order configuration parameter description --- prebid-server/pbs-modules/optable-targeting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 03e0043db9..039a882374 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -140,7 +140,7 @@ The parameter names are specified with full path using dot-notation. F.e. `sect | ppid-mapping | no | map | none | This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | | adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | | timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | -| id-prefix-order | no | list | [] | An optional list of id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. ["c","c1","id5"] will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | +| id-prefix-order | no | string | none | An optional string of comma separated id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. "c,c1,id5" will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | ## ID Mapping From be2e4e2fca3d513cde3d245be770ae593984e381 Mon Sep 17 00:00:00 2001 From: Bohdan V <25197509+BohdanVV@users.noreply.github.com> Date: Fri, 7 Mar 2025 17:25:11 +0100 Subject: [PATCH 11/17] optable-targeting: fix lint issues --- .../pbs-modules/optable-targeting.md | 184 +++++++++++------- 1 file changed, 114 insertions(+), 70 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 039a882374..69f5955819 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -13,11 +13,16 @@ Optable module operates using a DCN backend API. Please contact your account man {:.no_toc} * TOC -{:toc } +{:toc} ## Overview -The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.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. +The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.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 @@ -28,7 +33,8 @@ This module runs at two stages: * Processed Auction Request: to enrich `user.ext.eids` and `user.ext.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. +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 @@ -36,7 +42,9 @@ There is no host-company level config for this module. ### 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: +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: ```yaml @@ -94,7 +102,7 @@ Sample module enablement configuration in JSON and YAML formats: "ppid-mapping": { "pubcid.org": "c" }, - "adserver-targeting": false, + "adserver-targeting": false } } } @@ -114,13 +122,21 @@ Sample module enablement configuration in JSON and YAML formats: ### 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 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. -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. +**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. ## 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: +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: ```json { @@ -133,96 +149,119 @@ The parameter names are specified with full path using dot-notation. F.e. `sect ``` {: .table .table-bordered .table-striped } -| Param Name | Required| Type | Default value | Description | -|:-------|:------|:------|:------|:---------------------------------------| -| api-endpoint | yes | string | none | Optable Targeting Edge API endpoint URL, required | -| api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | -| ppid-mapping | no | map | none | This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | -| adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | -| timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | -| id-prefix-order | no | string | none | An optional string of comma separated id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. "c,c1,id5" will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | + +| Param Name | Required | Type | Default value | Description | +|:-------------------|:---------|:--------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| api-endpoint | yes | string | none | Optable Targeting Edge API endpoint URL, required | +| api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | +| ppid-mapping | no | map | none | This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | +| adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | +| timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | +| id-prefix-order | no | string | none | An optional string of comma separated id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. "c,c1,id5" will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | ## 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](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes) 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. +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](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes) +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. {: .table .table-bordered .table-striped } -| Identifier Type | OpenRTB field | ID Type Prefix | -| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------- | -| Email Address | `user.ext.optable.email` | `e:` | -| Phone Number | `user.ext.optable.phone` | `p:` | -| Postal Code | `user.ext.optable.zip` | `z:` | -| IPv4 Address | `device.ip` | ~~i4:~~ Sent as `X-Forwarded-For` header | -| IPv6 Address | `device.ipv6` | ~~i6:~~ Sent as `X-Forwarded-For` header | -| Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt!=1` | `a:` | -| Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt!=1` | `g:` | -| Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt!=1` | `r:` | -| Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt!=1` | `s:` | -| Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt!=1` | `f:` | -| [NetID](https://docs.prebid.org/dev-docs/modules/userid-submodules/netid.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="netid.de"` | `n:` | -| [ID5](https://docs.prebid.org/dev-docs/modules/userid-submodules/id5.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | -| [Utiq](https://docs.prebid.org/dev-docs/modules/userid-submodules/utiq.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | -| Optable VID | `user.ext.optable.vid` | `v:` | +| Identifier Type | OpenRTB field | ID Type Prefix | +|--------------------------------------------------------------------------------|-----------------------------------------------------------------------|------------------------------------------| +| Email Address | `user.ext.optable.email` | `e:` | +| Phone Number | `user.ext.optable.phone` | `p:` | +| Postal Code | `user.ext.optable.zip` | `z:` | +| IPv4 Address | `device.ip` | ~~i4:~~ Sent as `X-Forwarded-For` header | +| IPv6 Address | `device.ipv6` | ~~i6:~~ Sent as `X-Forwarded-For` header | +| Apple IDFA | `device.ifa if lcase(device.os) contains 'ios' and device.lmt!=1` | `a:` | +| Google GAID | `device.ifa if lcase(device.os) contains 'android' and device.lmt!=1` | `g:` | +| Roku RIDA | `device.ifa if lcase(device.os) contains 'roku' and device.lmt!=1` | `r:` | +| Samsung TV TIFA | `device.ifa if lcase(device.os) contains 'tizen' and device.lmt!=1` | `s:` | +| Amazon Fire AFAI | `device.ifa if lcase(device.os) contains 'fire' and device.lmt!=1` | `f:` | +| [NetID](https://docs.prebid.org/dev-docs/modules/userid-submodules/netid.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="netid.de"` | `n:` | +| [ID5](https://docs.prebid.org/dev-docs/modules/userid-submodules/id5.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="id5-sync.com"` | `id5:` | +| [Utiq](https://docs.prebid.org/dev-docs/modules/userid-submodules/utiq.html) | `user.ext.eids[].uids[0] when user.ext.eids[].source="utiq.com"` | `utiq:` | +| Optable VID | `user.ext.optable.vid` | `v:` | ### 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. +**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[]`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-). The `ppid-mapping` allows to specify the mapping of a source to one of the custom identifier type prefixes `c`-`c19` - see [documentation](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes), f.e.: -``` + +Custom user IDs are sent in the OpenRTB request in the +[`user.ext.eids[]`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-). +The `ppid-mapping` allows to specify the mapping of a source to one of the custom identifier type prefixes `c`-`c19` - +see [documentation](https://docs.optable.co/optable-documentation/dmp/reference/identifier-types#type-prefixes), f.e.: + +```yaml 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: -``` +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: + +```yaml 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` + +* `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: + ```json -"analytics": { +{ + "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" - } - } - ] - } - ] + { + "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" + } + } + ] } + ] } + } ] + } } ``` @@ -231,6 +270,7 @@ If `adserver-targeting` was set to `false` in the config `optable-enrich-respons ## Running the demo (PBS-Java) {:start="1"} + 1. Build the server bundle JAR as described in [Build Project](https://github.com/prebid/prebid-server-java/blob/master/docs/build.md#build-project), e.g. ```bash @@ -238,12 +278,15 @@ mvn clean package --file extra/pom.xml ``` {:start="2"} + 2. In the `sample/configs/prebid-config-optable.yaml` file specify the `api-endpoint` URL of your DCN, f.e.: + ```yaml api-endpoint: https://example.com/v2/targeting ``` {:start="3"} + 3. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. ```bash @@ -251,6 +294,7 @@ java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sa ``` {:start="4"} + 4. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. ```bash @@ -258,8 +302,8 @@ curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-target ``` {:start="5"} -5. Observe the `user.ext.eids` and `user.ext.data` objects enriched. +5. Observe the `user.ext.eids` and `user.ext.data` objects enriched. ## Maintainer contacts From 9f337a5870a0abc385f9605b1824d24e26c9b527 Mon Sep 17 00:00:00 2001 From: Bohdan V <25197509+BohdanVV@users.noreply.github.com> Date: Fri, 7 Mar 2025 17:30:53 +0100 Subject: [PATCH 12/17] optable-targeting: fix lint issues --- prebid-server/pbs-modules/optable-targeting.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 69f5955819..b023316a96 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -278,7 +278,6 @@ mvn clean package --file extra/pom.xml ``` {:start="2"} - 2. In the `sample/configs/prebid-config-optable.yaml` file specify the `api-endpoint` URL of your DCN, f.e.: ```yaml @@ -286,7 +285,6 @@ api-endpoint: https://example.com/v2/targeting ``` {:start="3"} - 3. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. ```bash @@ -294,7 +292,6 @@ java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sa ``` {:start="4"} - 4. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. ```bash @@ -302,7 +299,6 @@ curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-target ``` {:start="5"} - 5. Observe the `user.ext.eids` and `user.ext.data` objects enriched. ## Maintainer contacts From b46f2a8d9b8f527b4acc8174605d4842e2b7eff2 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 13 Mar 2025 13:52:49 +0100 Subject: [PATCH 13/17] optable-targeting: fix typos: user.ext.data -> user.data, user.ext.eids -> user.eids (as server converts user.ext.eids to user.eids according to OpenRTB 2.6) --- prebid-server/pbs-modules/optable-targeting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index b023316a96..c7765d5b4b 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -17,7 +17,7 @@ Optable module operates using a DCN backend API. Please contact your account man ## Overview -The optable-targeting module enriches an incoming OpenRTB request by adding to the `user.ext.eids` and `user.ext.data` +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 @@ -30,7 +30,7 @@ Targeting API endpoint is configurable per publisher. This module runs at two stages: -* Processed Auction Request: to enrich `user.ext.eids` and `user.ext.data`. +* 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 @@ -299,7 +299,7 @@ curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-target ``` {:start="5"} -5. Observe the `user.ext.eids` and `user.ext.data` objects enriched. +5. Observe the `user.eids` and `user.data` objects enriched. ## Maintainer contacts From b69d2cd5d8697a7779043c68c10b7fc3b0d00985 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 17 Apr 2025 14:55:31 +0200 Subject: [PATCH 14/17] optable-targeting: introduce host-level regional endpoint config, cache feature --- .../pbs-modules/optable-targeting.md | 96 ++++++++----------- 1 file changed, 41 insertions(+), 55 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index c7765d5b4b..220bb847cd 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -38,7 +38,19 @@ below for an example. ### Global Config -There is no host-company level config for this module. +In the host-level config you need to specify the regional endpoint that would be closest to the host: +```yaml +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](mailto: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 @@ -50,7 +62,14 @@ Here's a general template for the account config used in PBS-Java: ```yaml hooks: optable-targeting: - enabled: true + 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": { @@ -88,38 +107,6 @@ hooks: } ``` -Sample module enablement configuration in JSON and YAML formats: - -```json -{ - "modules": - { - "optable-targeting": - { - "api-endpoint": "endpoint", - "api-key": "key", - "timeout": 50, - "ppid-mapping": { - "pubcid.org": "c" - }, - "adserver-targeting": false - } - } -} -``` - -```yaml - modules: - optable-targeting: - api-endpoint: endpoint - api-key: key - timeout: 50 - ppid-mapping: { - "pubcid.org": "c" - } - adserver-targeting: false -``` - ### Timeout considerations The timeout value specified in the execution plan for the `processed-auction-request` hook is very important to be @@ -133,6 +120,10 @@ The timeout value for the `auction-response` can be set to 10 ms - usually it wi 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](https://docs.prebid.org/prebid-server/features/pbs-pbc-storage.html) 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` @@ -152,12 +143,16 @@ would result in this nesting in the JSON configuration: | Param Name | Required | Type | Default value | Description | |:-------------------|:---------|:--------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| api-endpoint | yes | string | none | Optable Targeting Edge API endpoint URL, required | -| api-key | no | string | none | If the API is protected with a key - this param needs to be specified to be sent in the auth header | -| ppid-mapping | no | map | none | This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | -| adserver-targeting | no | boolean | false | If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | -| timeout | no | integer | false | A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | -| id-prefix-order | no | string | none | An optional string of comma separated id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. "c,c1,id5" will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | +| api-endpoint | yes | string | none | Host-Level. Optable Targeting Edge API endpoint URL. Note it must: include {TENANT} and {ORIGIN} macros that are substituted from account-level config values | +| tenant | yes | string | none | Account-Level. Your Optable tenant aka account ID. | +| origin | yes | string | none | Account-Level. Optable data `origin` aka `source`. | +| api-key | no | string | none | Account-Level. If the API is protected with a key - this param needs to be specified to be sent in the auth header | +| ppid-mapping | no | map | none | Account-Level. This specifies PPID source (`user.ext.eids[].source`) to a custom identifier prefix mapping, f.e. `{"example.com" : "c"}`. See the section on ID Mapping below for more detail. | +| adserver-targeting | no | boolean | false | Account-Level. If set to true - will add the Optable-specific adserver targeting keywords into the PBS response for every `seatbid[].bid[].ext.prebid.targeting` | +| timeout | no | integer | false | Account-Level. A soft timeout (in ms) sent as a hint to the Targeting API endpoint to limit the request times to Optable's external tokenizer services | +| id-prefix-order | no | string | none | Account-Level. An optional string of comma separated id prefixes that prioritizes and specifies the order in which ids are provided to Targeting API in a query string. F.e. "c,c1,id5" will guarantee that Targeting API will see id=c:...,c1:...,id5:... if these ids are provided. id-prefixes not mentioned in this list will be added in arbitrary order after the priority prefix ids. This affects Targeting API processing logic | +| cache.enabled | no | string | false | Account-Level. Optionally use [Prebid Cache Storage](https://docs.prebid.org/prebid-server/features/pbs-pbc-storage.html) feature - this significantly reduces the processing time when the Targeting API response has been cached | +| cache.ttlseconds | no | int | 86400 | Account-Level. The TTL in seconds for the Targeting API response to live in cache - by default is equal to 24 hours | ## ID Mapping @@ -270,36 +265,27 @@ If `adserver-targeting` was set to `false` in the config `optable-enrich-respons ## Running the demo (PBS-Java) {:start="1"} - 1. Build the server bundle JAR as described in [Build Project](https://github.com/prebid/prebid-server-java/blob/master/docs/build.md#build-project), e.g. ```bash mvn clean package --file extra/pom.xml ``` - {:start="2"} -2. In the `sample/configs/prebid-config-optable.yaml` file specify the `api-endpoint` URL of your DCN, f.e.: - -```yaml -api-endpoint: https://example.com/v2/targeting -``` - -{:start="3"} -3. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. +2. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. ```bash -java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-optable.yaml +java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-with-optable.yaml ``` -{:start="4"} -4. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. +{:start="3"} +3. Run sample request against the server as described in [the sample directory](https://github.com/prebid/prebid-server-java/tree/master/sample), e.g. ```bash curl http://localhost:8080/openrtb2/auction --data @extra/modules/optable-targeting/sample-requests/data.json ``` -{:start="5"} -5. Observe the `user.eids` and `user.data` objects enriched. +{:start="4"} +4. Observe the `user.eids` and `user.data` objects enriched. ## Maintainer contacts From bd3f1571dcd5b5bf3dcec4aca0883f0bef160227 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 17 Apr 2025 14:58:28 +0200 Subject: [PATCH 15/17] optable-targeting: lint warnings --- prebid-server/pbs-modules/optable-targeting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 220bb847cd..de7b68393e 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -39,6 +39,7 @@ 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: + ```yaml hooks: optable-targeting: @@ -265,11 +266,13 @@ If `adserver-targeting` was set to `false` in the config `optable-enrich-respons ## Running the demo (PBS-Java) {:start="1"} + 1. Build the server bundle JAR as described in [Build Project](https://github.com/prebid/prebid-server-java/blob/master/docs/build.md#build-project), e.g. ```bash mvn clean package --file extra/pom.xml ``` + {:start="2"} 2. Start server bundle JAR as described in [Running project](https://github.com/prebid/prebid-server-java/blob/master/docs/run.md#running-project), e.g. From f6dbf3505c7a62c3a23168c78d6dfa97364d6f0f Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Tue, 17 Jun 2025 16:18:06 +0200 Subject: [PATCH 16/17] update ATags section --- .../pbs-modules/optable-targeting.md | 72 ++++++++++++------- 1 file changed, 45 insertions(+), 27 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index de7b68393e..5ecf551654 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -213,7 +213,7 @@ 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: +The following 2 activities are recorded by the module in the corresponding ATags on the corresponding stages: * `optable-enrich-request` * `optable-enrich-response` @@ -224,40 +224,58 @@ Example: ```json { - "analytics": { - "tags": [ - { - "stage": "auction-response", - "module": "optable-targeting", - "analyticstags": { - "activities": [ + "analytics": + { + "tags": + [ { - "name": "optable-enrich-request", - "status": "success", - "results": [ + "stage": "processed-auction-request", + "module": "optable-targeting", + "analyticstags": { - "values": { - "execution-time": 33 - } + "activities": + [ + { + "name": "optable-enrich-request", + "status": "success", + "results": + [ + { + "values": + { + "execution-time": "42" + } + } + ] + } + ] } - ] }, { - "name": "optable-enrich-response", - "status": "success", - "results": [ + "stage": "auction-response", + "module": "optable-targeting", + "analyticstags": { - "values": { - "reason": "none" - } + "activities": + [ + { + "name": "optable-enrich-response", + "status": "success", + "results": + [ + { + "values": + { + "reason": "none" + } + } + ] + } + ] } - ] } - ] - } - } - ] - } + ] + } } ``` From 59a594ba93256c6bbf134b75763ea44de8517005 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Mon, 11 Aug 2025 15:17:41 +0200 Subject: [PATCH 17/17] optable-targeting: enclose macros in the double curly brace --- prebid-server/pbs-modules/optable-targeting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/prebid-server/pbs-modules/optable-targeting.md b/prebid-server/pbs-modules/optable-targeting.md index 5ecf551654..e93e15c3a4 100644 --- a/prebid-server/pbs-modules/optable-targeting.md +++ b/prebid-server/pbs-modules/optable-targeting.md @@ -46,12 +46,12 @@ hooks: enabled: true modules: optable-targeting: - api-endpoint: https://na.edge.optable.co/v2/targeting?t={TENANT}&o={ORIGIN} + 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](mailto: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. +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 @@ -144,7 +144,7 @@ would result in this nesting in the JSON configuration: | Param Name | Required | Type | Default value | Description | |:-------------------|:---------|:--------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| api-endpoint | yes | string | none | Host-Level. Optable Targeting Edge API endpoint URL. Note it must: include {TENANT} and {ORIGIN} macros that are substituted from account-level config values | +| api-endpoint | yes | string | none | Host-Level. Optable Targeting Edge API endpoint URL. Note it must: include {{TENANT}} and {ORIGIN} macros that are substituted from account-level config values | | tenant | yes | string | none | Account-Level. Your Optable tenant aka account ID. | | origin | yes | string | none | Account-Level. Optable data `origin` aka `source`. | | api-key | no | string | none | Account-Level. If the API is protected with a key - this param needs to be specified to be sent in the auth header |