ID5ID userId module

[pkowalski-id5]

🔧 Type of changes

• new module

✨ What's the context?

ID5 wants to have its own module that can enrich bid requests with ID5 universal identifiers. This module fetches identity signals from ID5's API and automatically injects them into OpenRTB bid requests as Extended
Identifiers (EIDs).

🧠 Rationale behind the change

Why a dedicated module?

• ID5 identifiers enhance user matching capabilities across the programmatic ecosystem
• Having a dedicated module allows PBS operators to enable ID5 enrichment without requiring publisher-side changes
• The module respects all major privacy signals (GDPR, CCPA, COPPA, GPP)

Key design decisions:

• Two-hook architecture: Separate fetch and inject hooks to optimize performance
  • Fetch hook (ProcessedAuctionRequestHook): Initiates async ID5 API call early in the request lifecycle
  • Inject hook (BidderRequestHook): Injects EIDs into each bidder request only when not already present
• Non-blocking async implementation: ID5 fetch doesn't block the auction processing
• Preservation of existing IDs: Module checks if ID5 EID already exists before fetching/injecting
• Flexible filtering: Account, country, bidder filters and sampling for gradual rollout
• Configurable partner ID provider: Interface allows custom logic for determining partner ID per request

Trade-offs:

• Requires both hooks to be configured in execution plan (fetch + inject) for the module to function
• Additional HTTP call to ID5 API adds latency (mitigated by async execution and timeout awareness)

🔎 New Bid Adapter Checklist

Not applicable - this is a module, not a bid adapter

🧪 Test plan

Unit Tests:

• Comprehensive unit test coverage for both hooks
• Filter logic tested (account, country, bidder, sampling)
• Privacy signal handling tested (GDPR, CCPA, COPPA, GPP)
• Edge cases covered (timeouts, existing IDs, empty responses)

Integration Tests:

• Full PBS instance integration tests with the module enabled
• Tests verify complete fetch + inject flow
• WireMock-based local testing setup included in sample/ directory

Manual Testing:

• Local end-to-end testing with WireMock mocks
• Sample configurations provided for testing different scenarios
• Debug logging available for troubleshooting

The module has been tested with various configurations and filter combinations to ensure safe production deployment.

🏎 Quality check

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

🤔 Questions for reviewers

1. Hook invocation status/action handling:
We would particularly appreciate review of our hook invocation status and action returns. Please verify that we're correctly returning:

• Appropriate InvocationStatus values in different scenarios (success, failure, skipped)
• Correct InvocationAction to control execution flow
• Proper handling of edge cases (timeouts, errors, existing IDs)

2. Execution plan configuration simplification:
Both hooks (fetch + inject) are required for the module to function - the module is non-functional if either hook is missing from the execution plan. Currently, operators must configure both hooks separately in the
execution plan:

stages:
  processed-auction-request:
    groups:
      - hook-sequence:
          - module-code: "id5-user-id"
            hook-impl-code: "id5-user-id-fetch-hook"
  bidder-request:
    groups:
      - hook-sequence:
          - module-code: "id5-user-id"
            hook-impl-code: "id5-user-id-inject-hook"

Question: Is there a way to simplify this configuration? For example:

• A single module registration that automatically registers both required hooks?
• A validation mechanism that warns when one hook is configured without the other?
• Any other pattern for "atomic" multi-hook modules?