optable-targeting new features: non-blocking early network call + hid + id5 by justadreamer · Pull Request #4601 · prebid/prebid-server-java

justadreamer · 2026-08-14T10:41:28Z

Type of changes

module update

What's the context?

Two related improvements to the optable-targeting module: the Optable API call no longer blocks the auction pipeline, and the Targeting API request now carries the parameters needed for mobile in-app resolution (hid, bundle/ver, ID5).

Latency: non-blocking early network call

The API call starts at raw-auction-request and runs in parallel with the rest of the auction. The result is consumed per bidder at bidder-request, where enrichment is actually injected, so the pipeline never waits on the network.

Stored requests and stored imps are merged after raw-auction-request, so for requests whose bidders or site/app live there (f.e. Prebid Mobile SDK traffic) the call is started by the async processed-auction-request hook (optable-targeting-async-processed-auction-request-hook) on the merged request instead. The same hook starts the call for AMP, which has no raw-auction-request stage. Bidders are read from both imp.ext.prebid.bidder and the old-style imp.ext.<bidder>.

Traffic controls

enrichment-percentage / bidder-enrichment-percentages: sampling rate (0-100) applied per bidder. A bidder with no entry falls back to the account default; 0 disables it entirely.
enrich-web / enrich-app: select which traffic sources are enriched.

Sampling applies to the split plan only. The legacy optable-targeting-processed-auction-request-hook enriches the whole bid request before bidders split out, so it cannot sample per bidder.

Targeting API request parameters

hid-prefixes (new config entry): comma-separated id prefixes to emit as hid=, in the given order (e.g. "e,p,i6,a,g,c"). Independent of id-prefix-order, and selective rather than merely ordering: only the listed prefixes are sent as hid.
bundle / ver: emitted from bidRequest.app when present.
id5_signature in: read from user.ext.optable, forwarded as a Targeting API query attribute alongside email/phone/zip/vid.
id5_signature out: returned in ext.prebid.passthrough.optable.id5_signature. PBS cannot persist the signature between requests, so it round-trips through the client, which caches it and replays it on the next auction.

Backwards compatibility

No breaking changes. The existing optable-targeting-processed-auction-request-hook keeps its previous synchronous behavior and is now deprecated. The split plan uses the new optable-targeting-async-processed-auction-request-hook at processed-auction-request, which never blocks and only starts the call for stored-request and AMP traffic.

Configuration (recommended)

hooks:
  modules:
    optable-targeting:
      enrichment-percentage: 100
      bidder-enrichment-percentages:
        appnexus: 75
        pubmatic: 0
      enrich-web: true
      enrich-app: true
      id-prefix-order: "e,v,c"
      hid-prefixes: "a,c,i6"

  execution-plan:
    endpoints:
      "/openrtb2/auction":
        stages:
          raw-auction-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-raw-auction-request-hook"
          processed-auction-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-async-processed-auction-request-hook"
          bidder-request:
            groups:
              - timeout: 500
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-bidder-request-hook"
          auction-response:
            groups:
              - timeout: 10
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-auction-response-hook"

The bidder-request group timeout bounds the wait on the API call, so it must accommodate round-trip latency to the Optable edge. The raw-auction-request and processed-auction-request timeouts only cover dispatch.

To migrate from the legacy plan, replace optable-targeting-processed-auction-request-hook with optable-targeting-async-processed-auction-request-hook and add the raw-auction-request and bidder-request hooks.

Test plan

Unit tests
Semi-automated integration tests against the live Optable edge, covering enrichment with eids, per-bidder sampling (including a bidder pinned at 0%), ad server targeting keywords, ID5 signature passthrough, and the legacy execution plan

Quality check

Are your changes following our code style guidelines?
Are there any breaking changes in your code? No
Does your test coverage exceed 90%?
Are there any erroneous console logs, debuggers or leftover code in your changes? No

cc: @jrosendahl-opt @softcoder594

…aching

return early from the hook if (hasRawAuctionRequestHook && hasBidderRequestHook) - the new mode

random is 0-99, percentage is 0-100. enrich when random < (strictly less than) percentage. so if we specify percentage 0 we never enrich, if we specify percentage 100 we always enrich.

…ntage property is specified and it's value is 100%

The account config node is deserialized with the prebid mapper, which uses SNAKE_CASE, so the unannotated fields bound to enrich_web and enrich_app while the documented account keys are enrich-web and enrich-app. Per-account overrides of both were silently dropped and the global value kept.

…change Core changed ExecutionPlan.endpoints key type from Endpoint to HookHttpEndpoint. Map.get accepts Object, so the stale lookup kept compiling but always returned null against the EnumMap: the module read a bidder-request hook timeout of 0, so the targeting API call inherited only the raw-auction-request stage budget (50ms) instead of the configured 500ms and timed out on every auction.

Bidders from stored imps are never enriched when other imps name bidders inline. If one imp lists its bidders and another only references a stored imp, the raw hook doesn't defer. This affects mixed Prebid Mobile and web setups.

…execution-plan lookup

… every bidder.

… into hooks

…nd async hooks

…ivity

…resolving ips

…s available

…taining Optable hook

…larify execution-time

… stage and make cleaner non-mutating

Lightwood13 · 2026-10-29T19:40:49Z

 import java.util.List;

-public class BidRequestCleaner implements PayloadUpdate<AuctionRequestPayload> {
+public class AuctionRequestCleaner implements PayloadUpdate<AuctionRequestPayload> {


Please make the default constructor private.

Lightwood13 · 2026-10-29T20:02:02Z

    }

-    private static BidRequest clearExtUserOptable(BidRequest bidRequest) {
+    protected static BidRequest clearExtUserOptable(BidRequest bidRequest) {


This method should be private. There are no classes inheriting from this class.

Lightwood13 · 2026-10-29T20:08:21Z

        final ObjectNode cleanedOptable = cleanOptable((ObjectNode) optable);
+        final ExtUser extUserCopy = extUser.toBuilder().build();
+        extUserCopy.addProperties(extUser.getProperties());
        if (cleanedOptable.isEmpty()) {


This if/else statement can be replaced with a ternary expression:

extUserCopy.addProperty(OPTABLE_FIELD, cleanedOptable.isEmpty() ? null : cleanedOptable);

Lightwood13 · 2026-10-29T20:18:20Z

+    }
+
+    private static Set<String> extractUniqueBidders(BidRequest bidRequest) {
+        return Optional.ofNullable(bidRequest.getImp())


Optional.ofNullable().stream() can be simplified to Stream.ofNullable().

Lightwood13 · 2026-10-29T20:36:42Z

+@AllArgsConstructor(staticName = "of")
+public class BidderEnrichmentSampler {
+
+    private static final String PREBID_BIDDER_PATH = "/prebid/bidder";


Replace PREBID_BIDDER_PATH with

private static final JsonPointer PREBID_BIDDER_JSON_POINTER = JsonPointer.valueOf("/prebid/bidder");

to avoid recompiling the JsonPointer at every usage.

Lightwood13 · 2026-11-02T19:29:27Z

+        setEnrichRequestStatus(EnrichmentStatus.failure());
+    }
+
+    public boolean hasOptableTargetingProperties() {


Unused method, please remove.

Lightwood13 · 2026-11-02T19:36:06Z

+    }
+
+    @Bean
+    OptableTargetingFlowResolver earlyOptableCallResolver(


Align bean name with the class name.

Lightwood13 · 2026-11-03T14:35:05Z

+        }
+        moduleContext.setBiddersToEnrich(biddersToEnrich);
+        final Account account = invocationContext.auctionContext().getAccount();
+        final long crossHookFutureTimeout =


This is a cross hook timeout, so it shouldn't be taken from a single hook's timeout. Please use the whole request's timeout invocationContext.auctionContext().getTimeoutContext().getTimeout(). The idea is to keep hook timeouts as small as possible to not stall the processing pipeline.

It's done this way by design.
We understand the intention to keep hook execution times as short as possible to avoid blocking the auction processing pipeline. However, the current proposal doesn't address our requirements.

We need to make a remote API call during hook steps execution and receive its response before proceeding with bidder invocation, as the returned targeting data is required to enrich the auction request. If the hook times out before the API call completes, we lose that data and cannot properly enrich the request.

At the same time, we use this value to control the API call timeout. It should be shorter than the whole auction execution timeout, allowing us to fail fast if the remote service is slow or unresponsive, rather than waiting for the entire auction execution window.

In other words, Hook execution time:

lmits how long we wait for the remote service.

limits the total time the hook is allowed to consume.

This gives us predictable latency, prevents unnecessary slow API calls, and ensures that the hook has enough time to get a response from API call.

The shorter HTTP client timeout also allows us to keep Connection Pool more robust.

Lightwood13 · 2026-11-03T14:36:32Z

+                : defaultValue;
+    }
+
+    public boolean hasBidderRequestHook(Account account) {


This class exposes two public functions: hasBidderRequestHook and getOptableTargetingBidderRequestTimeout. After fixing other comments, these functions shouldn't be necessary and this class can be removed.

hasBidderRequestHook was removed. getOptableTargetingBidderRequestTimeout is left due to comment above.

Lightwood13 · 2026-11-03T14:39:42Z

+
+        final BidRequest bidRequest = applyActivityRestrictions(payload.bidRequest(), invocationContext);
+
+        final Timeout timeout = apiTimeout == null


Please remove this conditional from here. You can just change the apiTimeout parameter from type Long to type Timeout and perform these calculations in calling functions, instead of passing null in one of the cases and calculating timeout here.

Lightwood13 · 2026-11-03T15:14:29Z

+    enabled: true
  triplelift:
    enabled: true
+  adf:


Please remove unnecessary bidders from sample config to keep it clean.

I kept several bidders because they are referenced in the sample request and configuration.

Lightwood13 · 2026-11-03T15:18:49Z

Please update the PR description to match the latest changes.

The "Backwards compatibility" section is currently incorrect.
Recommended configuration incorrectly uses the legacy processed auction request hook instead of the new async hook.
To migrate from the legacy plan, keep the processed-auction-request hook and add the raw-auction-request and bidder-request hooks. is incorrect.

softcoder and others added 30 commits August 13, 2026 22:38

optable-targeting: implement Non-Blocking Early Network Call

11b1195

optable-targeting: implement per-bidder enrichment percentage

5e2d1b8

optable-targeting: Add unit tests, rename dicer to sampler

5e26ce7

optable-targeting: add Web vs. Mobile Traffic Toggle

617bdf2

optable-targeting: add hook execution plan helper inside hook

3d3ea39

optable-targeting: optimize hook execution plan helper. Add results c…

8403993

…aching

optable-targeting: code cleanup

dc8cfd0

optable-targeting: update timeouts

b38c68b

extract timeout for the future from bidder-request

6ca0d9c

only block processed-auction hook in legacy mode

abe07dd

return early from the hook if (hasRawAuctionRequestHook && hasBidderRequestHook) - the new mode

update sample request body

c8842c1

update doc

6aa7fb9

BidRequestCleaner in the raw-auction-request

87d6d4d

increase bidder-request timeout in the sample config

b719a3a

gpp_sid serialization bug fix

7ca5987

update readme re: timeout

6580a76

sampler bug fixed, it was always enrichin for 0

a5a960a

random is 0-99, percentage is 0-100. enrich when random < (strictly less than) percentage. so if we specify percentage 0 we never enrich, if we specify percentage 100 we always enrich.

optable-targeting: add analytic tags

39da4dd

set sample email hash that leads to enrichment

b247432

improve analytics tags

becbd2e

improve doc

000d389

remove legacy config files

a808b49

update gpp_sid test

e647f23

shorten fully qualified type name

b7bcda8

rename NetworkCall -> TargetingRequestExecutor

7df477e

optable-targeting: code cleanup

a32c06c

optable-targeting: fix endpoint template

2d956b1

optable-targeting: fix per bidder enrichment if only enrichment-perca…

3956b65

…ntage property is specified and it's value is 100%

softcoder added 4 commits October 2, 2026 00:20

optable-targeting: Add hooks.default-account-execution-plan to the …

5859be4

…execution-plan lookup

optable-targeting: Fix twice enrichment sampling run for stored requests

d5f76d9

optable-targeting: Clean user.ext.optable tag when sampling rejects…

58785a2

… every bidder.

Net-burst requested a review from Lightwood13 October 9, 2026 13:53

Lightwood13 requested changes Oct 12, 2026

View reviewed changes

softcoder added 11 commits October 15, 2026 18:45

optable-targeting: Set right class name to logger

20bddf8

optable-targeting: Remove redundant code

e88a3a8

optable-targeting: Code cleanup

36a69b4

optable-targeting: Move auction request validation from flow resolver…

8966445

… into hooks

optable-targeting: Mask user data and ips based on activity restrictions

be61824

optable-targeting: Split processed auction request hook into legacy a…

2642447

…nd async hooks

optable-targeting: Mask X-Forwarded-For ips based on transmit geo act…

fb829b4

…ivity

optable-targeting: Skip empty or null-masked X-Forwarded-For ip when …

7c9938a

…resolving ips

optable-targeting: Resolve GDPR attributes from TCF context when it i…

094dbd8

…s available

optable-targeting: Resolve bidder request hook timeout from group con…

5eb4f6f

…taining Optable hook

optable-targeting: Document bidder enrich request analytics tag and c…

0c26583

…larify execution-time

justadreamer requested a review from Lightwood13 October 19, 2026 20:01

Lightwood13 reviewed Oct 27, 2026

View reviewed changes

Comment thread .../main/java/org/prebid/server/hooks/modules/optable/targeting/v1/core/BaseRequestCleaner.java Resolved

softcoder added 4 commits October 28, 2026 18:46

optable-targeting: Cleanup BidderEnrichmentSampler

b8bed9e

optable-targeting: Clean ext.user.optable tag only at auction request…

abc8d91

… stage and make cleaner non-mutating

optable-targeting: Code cleanup

1be1b32

Merge branch 'master' into optable-targeting-features

c0e94a7

justadreamer requested a review from Lightwood13 October 29, 2026 15:07

Lightwood13 requested changes Nov 3, 2026

View reviewed changes

Lightwood13 reviewed Nov 3, 2026

View reviewed changes

softcoder added 2 commits November 5, 2026 22:49

optable-targeting: Code cleanup

4b01445

optable-targeting: Code cleanup

f64dddf


		final BidRequest bidRequest = applyActivityRestrictions(payload.bidRequest(), invocationContext);

		final Timeout timeout = apiTimeout == null

Conversation

justadreamer commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of changes

What's the context?

Latency: non-blocking early network call

Traffic controls

Targeting API request parameters

Backwards compatibility

Configuration (recommended)

Test plan

Quality check

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softcoder594 Nov 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lightwood13 commented Nov 3, 2026

justadreamer commented Aug 14, 2026 •

edited

Loading

softcoder594 Nov 11, 2026 •

edited

Loading