optable-targeting: Enhance Optable Targeting: Non-blocking network calls and granular traffic controls by softcoder594 · Pull Request #2 · Optable/prebid-server-java

softcoder594 · 2026-05-05T15:56:04Z

Type of changes

module update

What's the context?

This update reduces auction latency by initiating the Optable API call at the earliest hook stage (raw-auction-request) and deferring the wait to the per-bidder stage (bidder-request), where the enrichment data is actually injected. It also adds granular controls over which traffic and which bidders receive enrichment.

New Features

Non-Blocking Early Network Call: The API call starts in raw-auction-request and runs in parallel with other auction processing. The result is consumed per-bidder in bidder-request, avoiding pipeline blocking.
Per-Bidder Enrichment Percentage: Configurable sampling rate per bidder (0-100%) to control what fraction of bid requests receive enrichment.
Web vs. App Traffic Toggle: enrich-web / enrich-app flags to select which traffic sources are enriched.

Backwards Compatibility

The processed-auction-request hook is retained as a legacy fallback. If operators have not migrated to the new execution plan, the module behaves as before — enrichment happens synchronously in the processed hook.

New Configuration (recommended)

hooks:
  modules:
    optable-targeting:
      enrichment-percentage: 100
      bidder-enrichment-percentages:
        appnexus: 75
        rubicon: 75
        pubmatic: 100
        criteo: 0
      enrich-web: true
      enrich-app: true

  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"
          bidder-request:
            groups:
              - timeout: 50
                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"

Legacy Configuration (to be migrated)

The following execution plan fragment should be removed once migrated to the new configuration above:

          processed-auction-request:
            groups:
              - timeout: 600
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-processed-auction-request-hook"

The processed-auction-request hook detects whether the new hooks (raw-auction-request and bidder-request) are present in the execution plan. If both are active, it passes through immediately without blocking the pipeline. If the new hooks are absent, it falls back to the legacy synchronous behavior. This means the legacy fragment can be kept during migration without negating the latency benefit of the new configuration.

Test plan

Unit Tests
Manual Integration Tests

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

…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.

ericst-amand-optable · 2026-06-02T19:51:15Z

I suggest you avoid keeping "legacy" files. Those 2 files in this PR seem to not be referenced anywhere. It feels like you are just duplicating effort relative to git history. This causes bloat and will drift. Also, what does legacy mean when you'll have a third version ?

The README already describes the relevant content that was there before (the migration section). I think this is sufficient and those legacy files could be removed to keep it more tidy.

ericst-amand-optable · 2026-06-03T15:51:09Z

+            return bidRequest;
+        }
+
+        final com.iab.openrtb.request.User bidRequestUser = Optional.ofNullable(bidRequest.getUser())


Prefer importing com.iab.openrtb.request.User

This comment applies everywhere in this file, other modified files and for anything else that can be imported.

done, there was another FQN that was colliding final org.prebid.server.hooks.modules.optable.targeting.model.openrtb.User optableUser - replaced with var instead of type

ericst-amand-optable · 2026-06-03T19:15:52Z

+    public boolean hasRawAuctionRequestHook(Account account) {
+        final String accountId = account != null ? account.getId() : null;
+
+        return StringUtils.isNotEmpty(accountId)
+                ? rawAuctionRequestHookCache.computeIfAbsent(accountId, id -> {
+                    final ExecutionPlan accountSpecificHooksExecutionPlan = resolveExecutionPlan(account);
+                    return hasHook(
+                            accountSpecificHooksExecutionPlan, STAGE_RAW_AUCTION_REQUEST, HOOK_CODE_OPTABLE_RAW_AUCTION)
+                            || hasGlobalRawAuctionRequestHook;
+                })
+                : false;
+    }
+
+    public boolean hasBidderRequestHook(Account account) {
+        final String accountId = account != null ? account.getId() : null;
+
+        return StringUtils.isNotEmpty(accountId)
+                ? bidderRequestHookCache.computeIfAbsent(accountId, id -> {
+                    final ExecutionPlan accountSpecificHoksExecutionPlan = resolveExecutionPlan(account);
+                    return hasHook(
+                            accountSpecificHoksExecutionPlan, STAGE_BIDDER_REQUEST, HOOK_CODE_OPTABLE_BIDDER_REQUEST)
+                            || hasGlobalBidderRequestHook;
+                })
+                : false;
+    }
+
+    public long getOptableTargetingBidderRequestTimeout(Account account) {
+        final String accountId = account != null ? account.getId() : null;
+
+        return StringUtils.isNotEmpty(accountId)
+                ? bidderRequestHookTimeoutCache.computeIfAbsent(accountId, id -> {
+                    final ExecutionPlan accountSpecificHoksExecutionPlan = resolveExecutionPlan(account);
+                    final long hookTimeOut = getHookTimeout(
+                            accountSpecificHoksExecutionPlan,
+                            STAGE_BIDDER_REQUEST,
+                            HOOK_CODE_OPTABLE_BIDDER_REQUEST);
+                    return hookTimeOut != 0 ? hookTimeOut : globalBidderRequestHookTimeout;
+                })
+                : globalBidderRequestHookTimeout;
+    }


There is quite some code duplication in these 3 methods. Consider a refactor. Here is a Claude code suggestion where the logic of getting the accountId, then resolving the execution plan, then use the plan to do whatever evaluation, is written only once. The three initial methods then become one-liners.

private static <T> T computeFromAccount(Account account, ConcurrentHashMap<String, T> cache, T defaultValue, Function<ExecutionPlan, T> compute) { final String accountId = account != null ? account.getId() : null; return StringUtils.isNotEmpty(accountId) ? cache.computeIfAbsent(accountId, id -> compute.apply(resolveExecutionPlan(account))) : defaultValue; } public boolean hasRawAuctionRequestHook(Account account) { return computeFromAccount(account, rawAuctionRequestHookCache, false, plan -> hasHook(plan, STAGE_RAW_AUCTION_REQUEST, HOOK_CODE_OPTABLE_RAW_AUCTION) || hasGlobalRawAuctionRequestHook); } public boolean hasBidderRequestHook(Account account) { return computeFromAccount(account, bidderRequestHookCache, false, plan -> hasHook(plan, STAGE_BIDDER_REQUEST, HOOK_CODE_OPTABLE_BIDDER_REQUEST) || hasGlobalBidderRequestHook); } public long getOptableTargetingBidderRequestTimeout(Account account) { return computeFromAccount(account, bidderRequestHookTimeoutCache, globalBidderRequestHookTimeout, plan -> { final long timeout = getHookTimeout(plan, STAGE_BIDDER_REQUEST, HOOK_CODE_OPTABLE_BIDDER_REQUEST); return timeout != 0 ? timeout : globalBidderRequestHookTimeout; }); }

This change requires also resolveExecutionPlan to be static, which it can be.

@softcoder594 please take a look, as it is beyond cosmetical refactor for me, or we can just accept the suggestion of claude code, just verify we don't break anything

ericst-amand-optable · 2026-06-03T19:43:40Z

+
+import java.util.Objects;
+
+public class NetworkCall {


This name is vague, generic. Consider finding a more suitable name that properly describes the purpose of this class. Something like OptableTargetingHelper ? Or something related to applying privacy and other properties to the targeting request.

renamed to TargetingRequestExecutor

ericst-amand-optable · 2026-06-03T19:54:25Z

I suggest those validation functions are placed in the same package as OptableTargetingProperties. It will encourage reusability and reduce imports.

@softcoder594

ericst-amand-optable · 2026-06-03T20:03:43Z

+    }
+
+    @Test
+    public void shouldLimitGppSidToTwoValues() {


why this limit of 2 ?

well because Targeting API processes only 2 gpp_sids... according to optable-sandbox code. maybe we were wrong

Ok, I confirm, just found that in the sandbox code, didn't know about this limit 👍

ericst-amand-optable · 2026-06-03T20:05:16Z

+
+        // then
+        assertThat(query).contains("&gpp=DBABzw~1YNY~BVQqAAAAAgA");
+        assertThat(query).containsPattern("&gpp_sid=\\d+,\\d+");


You should assert that the 2 values are indeed 7 and 22. I think order does not matter here ? But the actual values do.

ericst-amand-optable · 2026-06-04T01:42:22Z

+        return update(BidRequestCleaner.instance(), moduleContext);
+    }
+
+    public static <AuctionRequestPayload> Future<InvocationResult<AuctionRequestPayload>> update(


I think you can remove the first <AuctionRequestPayload> type parameter

ericst-amand-optable · 2026-06-04T01:54:17Z


 import java.util.Objects;

 public class OptableTargetingProcessedAuctionRequestHook implements ProcessedAuctionRequestHook {


Please add a comment here if this is the now deprecated hook

ericst-amand-optable

Looks good overall. Submitted some small comments/refactor. I did not try to run the server, nor the tests, so this is pure code review for what it is.

softcoder added 8 commits May 4, 2026 23:29

optable-targeting: implement Non-Blocking Early Network Call

34d95a6

optable-targeting: implement per-bidder enrichment percentage

97fa4a9

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

57582cb

optable-targeting: add Web vs. Mobile Traffic Toggle

cd70c5d

optable-targeting: add hook execution plan helper inside hook

4776277

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

d633254

…aching

optable-targeting: code cleanup

b6c11f7

optable-targeting: update timeouts

ed24621

softcoder594 changed the title ~~optable-targeting: implement Non-Blocking Early Network Call~~ optable-targeting: Enhance Optable Targeting: Non-blocking network calls and granular traffic controls May 25, 2026

justadreamer and others added 13 commits May 25, 2026 20:01

extract timeout for the future from bidder-request

33943ca

only block processed-auction hook in legacy mode

6676f28

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

update sample request body

bd69c4b

update doc

43c10ad

BidRequestCleaner in the raw-auction-request

71bdbb0

increase bidder-request timeout in the sample config

4eea424

gpp_sid serialization bug fix

3c63393

update readme re: timeout

5424150

sampler bug fixed, it was always enrichin for 0

87ae03e

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

3151f5b

set sample email hash that leads to enrichment

49f0c67

improve analytics tags

1e524b9

improve doc

96272f2

justadreamer mentioned this pull request Jun 2, 2026

Optable targeting doc Optable/prebid.github.io#5

Open

2 tasks

ericst-amand-optable reviewed Jun 2, 2026

View reviewed changes

ericst-amand-optable reviewed Jun 3, 2026

View reviewed changes

justadreamer added 4 commits June 3, 2026 22:17

remove legacy config files

d47b1b0

update gpp_sid test

f5ad5ee

shorten fully qualified type name

fd78685

rename NetworkCall -> TargetingRequestExecutor

dffdb71

ericst-amand-optable reviewed Jun 4, 2026

View reviewed changes

ericst-amand-optable approved these changes Jun 4, 2026

View reviewed changes


		import java.util.Objects;

		public class OptableTargetingProcessedAuctionRequestHook implements ProcessedAuctionRequestHook {

Conversation

softcoder594 commented May 5, 2026 • edited by justadreamer Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of changes

What's the context?

New Features

Backwards Compatibility

New Configuration (recommended)

Legacy Configuration (to be migrated)

Test plan

Quality check

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!

Choose a reason for hiding this comment

Uh oh!

ericst-amand-optable left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

softcoder594 commented May 5, 2026 •

edited by justadreamer

Loading