[justadreamer]

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 processed-auction-request on the merged request instead. 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 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 processed-auction-request hook stays in the plan. When the raw-auction-request and bidder-request hooks are present it no longer blocks and only starts the call for stored-request traffic; otherwise it keeps the previous synchronous behavior.

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-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, keep the 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

[Lightwood13]

Please apply masking to user and device before extracting sensitive data (like IP or user agent). This code is now being called from raw auction request hook, before masking is applied, so it has to be applied here manually. Example code: https://docs.prebid.org/prebid-server/developers/add-a-module-java.html#interaction-with-activity-infrastructure

[softcoder594]

done

[Lightwood13]

Please change IntSupplier randomSupplier field to Random random. The caller should be able to just supply the generic source of randomness (Random object) and it should be the responsibility of the current class to call .nextInt(100) on it to obtain random ints, not the responsibility of the caller. This way the logic is better encapsulated inside this class.

[softcoder594]

done