optable-targeting new features: non-blocking early network call + hid + id5

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

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 is retained and detects whether both
new hooks are present in the execution plan: if so it passes through immediately, otherwise it
falls back to the previous synchronous behavior. The legacy fragment can therefore be left in
place during migration without negating the latency benefit.

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"
          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 timeout only covers dispatch.

To migrate, drop the legacy fragment:

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

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