New Module: ID5 User ID by pkowalski-id5 · Pull Request #4318 · prebid/prebid-server-java

pkowalski-id5 · 2025-12-11T11:12:21Z

🔧 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?

ID5 basic module See merge request id5-sync/prebid-server-java!1

CTMBNara · 2026-02-13T13:01:57Z

...ain/java/org/prebid/server/hooks/modules/id5/userid/config/Id5UserIdModuleConfiguration.java

+@Configuration
+@EnableConfigurationProperties(Id5IdModuleProperties.class)
+@ConditionalOnProperty(prefix = "hooks." + Id5IdModule.CODE, name = "enabled", havingValue = "true")
+@Slf4j


Remove any usage of Slf4j. Use LoggerFactory.getLogger instead

CTMBNara · 2026-02-13T13:06:16Z

...ain/java/org/prebid/server/hooks/modules/id5/userid/config/Id5UserIdModuleConfiguration.java

+    }
+
+    @Bean
+    @ConditionalOnMissingBean(Id5PartnerIdProvider.class)


No need for @ConditionalOnMissingBean(Id5PartnerIdProvider.class)

CTMBNara · 2026-02-13T13:12:30Z

...ain/java/org/prebid/server/hooks/modules/id5/userid/config/Id5UserIdModuleConfiguration.java

+                                      Id5PartnerIdProvider id5PartnerIdProvider) {
+        final HttpFetchClient client = new HttpFetchClient(


Add empty line after multi-line declaration

CTMBNara · 2026-02-13T13:13:26Z

...ain/java/org/prebid/server/hooks/modules/id5/userid/config/Id5UserIdModuleConfiguration.java

+                properties.getFetchEndpoint(),
+                httpClient,
+                jacksonMapper,
+                Clock.systemUTC(),


Use Clock bean instead

CTMBNara · 2026-02-13T13:16:44Z

...rc/main/java/org/prebid/server/hooks/modules/id5/userid/v1/config/Id5IdModuleProperties.java

+/**
+ * Configuration model for the ID5 ID module.
+ */


Please, remove all unnecessary comments

CTMBNara · 2026-02-13T13:54:55Z

...5-user-id/src/main/java/org/prebid/server/hooks/modules/id5/userid/v1/fetch/FetchClient.java

+    Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload,
+                            AuctionInvocationContext invocationContext);


One-line it

CTMBNara · 2026-02-13T13:56:55Z

...er-id/src/main/java/org/prebid/server/hooks/modules/id5/userid/v1/fetch/HttpFetchClient.java

+    public Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload,
+                                   AuctionInvocationContext invocationContext) {
+        final FetchRequest fetchRequest = createFetchRequest(partnerId, payload, invocationContext);
+        try {


No need for this try catch. There is no real IO while encoding request to string

CTMBNara · 2026-02-13T13:57:36Z

...er-id/src/main/java/org/prebid/server/hooks/modules/id5/userid/v1/fetch/HttpFetchClient.java

+    public Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload,
+                                   AuctionInvocationContext invocationContext) {


public Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload, AuctionInvocationContext invocationContext) {

CTMBNara · 2026-02-13T13:59:11Z

...er-id/src/main/java/org/prebid/server/hooks/modules/id5/userid/v1/fetch/HttpFetchClient.java

+        this.fetchUrl = endpoint;
+        this.httpClient = httpClient;
+        this.mapper = mapper;
+        this.clock = clock;
+        this.versionInfo = versionInfo;
+        this.id5IdModuleProperties = id5IdModuleProperties;


Add Objects.requireNonNull where possible for all fields in all services

CTMBNara · 2026-02-13T14:01:32Z

...er-id/src/main/java/org/prebid/server/hooks/modules/id5/userid/v1/fetch/HttpFetchClient.java

https://docs.prebid.org/prebid-server/developers/add-a-module-java.html#interaction-with-activity-infrastructure

pkowalski-id5 · 2026-02-16T13:28:36Z

@CTMBNara Thank you for the review. I've updated the code. Could you please take another look?

pkowalski-id5 added 4 commits December 11, 2025 11:35

ID5 user id module

cbceb8e

Merge branch 'id5-module' into 'pr/id5id-module'

cb78995

ID5 basic module See merge request id5-sync/prebid-server-java!1

Merge branch 'master' into pr/id5id-module

7c2b6d2

master merge

c178ec4

osulzhenko added the do not port label Dec 12, 2025

osulzhenko requested review from And1sS and CTMBNara December 12, 2025 08:33

fix functional tests

1082bae

marki1an requested review from And1sS and osulzhenko and removed request for And1sS December 31, 2025 11:15

osulzhenko changed the title ~~ID5ID userId module~~ New Module: ID5 User ID Jan 2, 2026

osulzhenko added blocked and removed blocked labels Jan 16, 2026

CTMBNara requested changes Feb 13, 2026

View reviewed changes

pkowalski-id5 added 3 commits February 13, 2026 15:24

Merge branch 'master' into pr/id5id-module

aa93287

review remarks, master merge fix

b8e5dfb

Masking user fpd if required before sending to ID5 fetch server

cc3a285

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Module: ID5 User ID#4318

New Module: ID5 User ID#4318
pkowalski-id5 wants to merge 8 commits intoprebid:masterfrom
id5io:pr/id5id-module

pkowalski-id5 commented Dec 11, 2025

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

CTMBNara Feb 13, 2026

Uh oh!

pkowalski-id5 commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		Id5PartnerIdProvider id5PartnerIdProvider) {
		final HttpFetchClient client = new HttpFetchClient(

		Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload,
		AuctionInvocationContext invocationContext);

		public Future<Id5UserId> fetch(long partnerId, AuctionRequestPayload payload,
		AuctionInvocationContext invocationContext) {

Conversation

pkowalski-id5 commented Dec 11, 2025

🔧 Type of changes

✨ What's the context?

🧠 Rationale behind the change

🔎 New Bid Adapter Checklist

🧪 Test plan

🏎 Quality check

🤔 Questions for reviewers

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!

pkowalski-id5 commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants