Understanding the Prebid ID Import Library: Practical Integration for Publishers
Managing user identities is central to modern header bidding strategies, but handling multiple ID modules in Prebid.js can quickly become unwieldy. Publishers often face the challenge of collecting, standardizing, and leveraging these identities for improved targeting and measurement.
The Prebid ID Import Library solves a hidden pain point: securely gathering various user IDs present on a page and exporting them server-side for modeling or user graphing. This guide breaks down how it works, why it matters, and what publishers should consider when integrating it.
What Does the Prebid ID Import Library Do?
The ID Import Library is an advanced Prebid.js module designed for publishers who use several User ID submodules. Its main function is to collect all relevant user identifiers, anchor them to a persistent (hashed) value, and send this composite identity map to a server-side endpoint you control.
A Real-World Example
Suppose your Prebid.js setup includes ID5, SharedID, and other user ID modules. Each generates its own ID for each visitor, and you want to store this data to build more effective audiences and improve bid modeling later. The ID Import Library gathers these values, creates an anonymous anchor with an MD5 hash, maps everything together, and transmits it as a JSON object to your endpoint in real-time.
How the ID Import Library Collects Persistent Identifiers
Identifying a stable user value is key, but browsers and regulations limit your options. The module follows a tiered approach to extract a persistent identifier without disrupting user experience or violating privacy expectations.
Stepwise Extraction Logic
1. It first checks if you defined a DOM element (such as a login field) that reliably contains a persistent ID (like an email).
2. If no value is present upfront, it attaches a listener to the element to detect input as soon as the user types one in.
3. If still not found, it scans all input[type=’text’] and input[type=’email’] fields on the page.
4. As a last resort and only if enabled, it searches the full HTML body for patterns like emails—a feature to use carefully, as it risks false positives from static content.
Concrete Implementation Example
Consider a publisher with a login form using the input ID ‘username’. By syncing the ID Import Library to this element, you knit user ID data to a hashed version of the user’s login value, tracking returning users securely across sessions and devices.
Configuring the ID Import Library in Prebid.js
Publishers must configure this module with precision for smooth operation. The flexibility comes from a targeted setup where you specify which page element to monitor, where to POST the mapped identities, and how aggressive the scan should be.
Essential Configuration Fields
– **url** (required): Endpoint for POSTed user ID maps (e.g., your server or DMP)
– **target** (required): The HTML element id to extract the persistent identifier from
– **debounce** (optional): Delays the scan to capture late-rendered or asynchronously loaded input values
– **fullscan** (optional): Toggles whether the module combs the entire DOM for matches—disable to prevent false matches from static content
Sample Code Snippet
pbjs.setConfig({
idImportLibrary:{
url: ‘https://your-endpoint.com/user-ids’,
target: ‘username’,
debounce: 250
}
});
This configuration ensures that once a user logs in (or provides an email), all user IDs are associated, hashed for privacy, and sent off for downstream modeling or analytics.
Potential Pitfalls and Best Practices for Publisher Teams
While the ID Import Library is robust, operational teams should be aware of several traps and opportunities for optimization.
Common Mistakes
– Not specifying the correct input element in ‘target’, leading to missed IDs
– Leaving ‘fullscan’ enabled on pages where static emails (like support contacts) are present
– Delaying POST calls due to improperly set debounce values, resulting in incomplete user maps
Tips for Reliable Integration
– Always audit which input field is most likely to contain a persistent user ID and update the ‘target’ accordingly
– Use the ‘debounce’ setting if your UI is heavily dynamic or AJAX-driven
– Disable ‘fullscan’ unless absolutely certain there are no static emails that could pollute your identity graph
What this means for publishers
The ID Import Library gives publishers more autonomy and flexibility in managing user IDs outside siloed vendor solutions. It bridges the gap between multiple on-page identifiers and your own back-end systems, unlocking the ability to build richer user graphs, improve measurement accuracy, and strengthen your first-party data strategy—all while maintaining privacy controls through hashing and targeted data extraction.
Practical takeaway
Publishers looking to consolidate and activate their identity data should treat the ID Import Library as a core tool in their Prebid.js stack. Start by mapping your forms and login elements, and invest the time to test both the ‘target’ and ‘debounce’ settings to ensure accurate capture.
Run controlled rollouts, especially if you’re enabling ‘fullscan’, and always review incoming server data for false positives or missing fields. Ultimately, this integration gives you more control over identity collection, making you less reliant on opaque third-party graphs and putting your team in a stronger position to adapt to a changing privacy landscape.
