Setup
Troubleshooting
Overview
Prebid is an open-source header bidding solution that enables publishers to offer their ad inventory to multiple demand sources simultaneously before making calls to their ad servers. Permutive provides two specialized Prebid modules that work independently or together:- Real-Time Data (RTD) Module - Activates cohort signals in bid requests for audience targeting
- Identity Manager Module - Passes identity signals from third-party identity providers to bidders
- Source: Permutive collects bid data and auction information from Prebid.js auctions, including bid prices, response times, and winning bids.
- Destination (Cohort Activation): Permutive activates your cohorts in Prebid.js auctions for real-time targeting via the RTD module.
- Destination (Identity Signal Activation): Permutive passes identity signals (RampID, ID5, UID2) to bidders via the Identity Manager module.
How It Works
RTD Module (Cohort Activation): The Permutive RTD module acts as a bridge between the Permutive Web SDK and Prebid.js:- When users fall into activated cohorts, these are detected by Permutive’s Prebid RTD module
- Cohort data is attached to the
ortb2.user.dataobject in bid requests for configured SSPs - SSPs receive cohort targeting data and can use it for real-time decisioning
- Identity providers (RampID, ID5, UID2) generate identity envelopes through Permutive’s Identity Manager
- The Permutive Identity Manager module retrieves these identities from the Permutive SDK
- Identity signals are passed to bidders via the
user.eidsobject in bid requests - Bidders can decrypt and use these identity signals for targeting and measurement
Cohort Types
- Standard Cohorts (IDs > 1,000,000): Automatically available to all configured AC bidders without specific activation. These are general audience segments.
- Custom Cohorts: Must be explicitly activated for each SSP in the Permutive Dashboard. These are your custom-built audience segments.
- Advertiser Cohorts: Must be configured by your Customer Success Manager for customers using Permutive’s Data Clean Room.
- Send Permutive cohorts to your Prebid.js auctions for real-time targeting and decisioning across multiple SSPs.
- Pass identity signals (RampID, ID5, UID2) from third-party identity providers to bidders for enhanced addressability and targeting.
- Track bid data and auction performance in Permutive for insights and optimization.
- Build cohorts based on bidder behavior, auction outcomes, and advertiser information.
- Optimize header bidding performance with data-driven audience insights and identity resolution.
Environment Compatibility
Prerequisites
For both modules:- Prebid.js Version: You must have Prebid.js v9.5.0 or later installed on your website.
- Web SDK: The Permutive Web SDK must be deployed on your site.
- GDPR/Consent Management: If operating in regions with GDPR requirements, you must configure the Prebid consent management module with proper storage exceptions for Permutive.
- Permutive RTD Module: The
permutiveRtdProvidermodule must be included in your Prebid.js build. This module is essential for reading cohort data from local storage and passing it to SSPs.
- Permutive Identity Manager Module: The
permutiveIdentityManagerIdSystemmodule must be included in your Prebid.js build. - Identity Provider Setup: You must have at least one identity provider (RampID, ID5, or UID2) configured in the Permutive Dashboard. See the Identity Integration Catalog for details on setting up identity providers.
Setup
Choose which module(s) you want to configure based on your needs. You can use either module independently or both together.- Cohort Activation (RTD Module)
- Identity Signal Activation (Identity Manager Module)
1
Install Prebid.js RTD Module
The Permutive Real-Time Data (RTD) module must be included in your Prebid.js build. This module reads cohort data from local storage and passes it to configured SSPs. Ensure your Prebid.js build includes the
permutiveRtdProvider module, together with Prebid’s global rtdModule, which it depends on:2
Configure Prebid.js RTD Module
Configure your Prebid.js setup to include the Permutive RTD module. Add the following configuration to your Prebid.js setup:Configuration Notes:
waitForIt: true: Ensures the auction waits for the RTD module to complete before sending bid requests. This is critical for cohorts to be included in all bid requests.auctionDelay: Maximum time (in milliseconds) to wait for RTD data. Recommended value is 200-300ms to balance cohort availability with auction speed.
3
Configure GDPR Consent Management (If Applicable)
If you operate in regions with GDPR requirements, you must configure Prebid’s consent management to allow Permutive access to local storage. Without this, the RTD module cannot read cohort data.As Permutive acts as a processor on behalf of publishers, consent is given to the Permutive SDK by the publisher, not by the GDPR Consent Management Module.Important: While Permutive is listed as a TCF vendor (ID: 361), Permutive does not obtain consent directly from the TCF. If you are using the TCF Control Module and need to prevent Permutive from being blocked, you must add Permutive as a vendor exception. Here’s an example configuration:Consult the Prebid consent management documentation and Permutive RTD Provider documentation for detailed guidance.
4
Verify Setup
In the Permutive Dashboard, navigate to your events page. You should start seeing Prebid event data appear. For cohorts with Prebid activation configured, you should see these cohorts available for targeting in your Prebid auctions.To verify cohorts are being passed to SSPs:
- Add
?pbjs_debug=trueto your URL - Open your browser’s Developer Console
- Filter logs for “permutiveRTD” to see RTD module activity
- Look for “Bid requests” logs in Prebid to see cohort data attached to bid requests in the
ortb2.user.datafield
Curation
For the curation-specific Prebid setup, see Configuring Prebid for Curation.Data Types
With your Prebid integration setup, you’ll see the following additional event types collected in Permutive:PrebidBid
PrebidBid
Tracks winning bids from Prebid auctions. The Permutive SDK sends a
PrebidBid event when a bid wins an auction, with winning_bid set to true. There is no separate winning-bid event.PrebidAuctions
PrebidAuctions
Tracks aggregated auction data containing bids and no-bid responses. A single event can contain several auctions, nested under The event also carries
aggregations.auctions. This event provides comprehensive auction-level insights.Array of bids received in the auction. Each bid has the same fields as
PrebidBid, plus creative_id, brand_id, brand_name, is_rendered and rendered_timestamp.Array of no-bid responses from bidders who chose not to bid. Each entry has
ad_unit_code, bidder, bidder_timeout and request_timestamp.geo_info and isp_info properties.Troubleshooting
Prebid events not appearing in Permutive Dashboard
Prebid events not appearing in Permutive Dashboard
Check that your Prebid.js version is 9.5.0 or later. Verify that the Permutive RTD module (
permutiveRtdProvider) is included in your Prebid.js build and properly configured. Ensure the Prebid integration is enabled in your Permutive Dashboard. Use the debugging query parameters ?__permutive.loggingEnabled=true&pbjs_debug=true in your browser to view detailed logs in the developer console.Cohorts not being passed to SSPs
Cohorts not being passed to SSPs
Check local storage first: Open your browser’s Developer Tools, navigate to Application > Local Storage, and verify that cohort data is being written to keys starting with
_P (e.g., _prubicons, _papns, _pindexs). If these keys are empty, cohorts are not being activated in the Permutive Dashboard. Standard cohorts (IDs over 1,000,000) are automatically available to all AC bidders without specific activation, but custom cohorts must be explicitly activated for each SSP.GDPR / Consent Management blocking cohorts
GDPR / Consent Management blocking cohorts
If you’re seeing warnings about “TCF2 framework” or “activity control”
denying access in your browser console, your Prebid consent management
configuration is preventing the RTD module from reading Permutive cohorts.Background: While Permutive is listed as a TCF vendor (ID: 361), Permutive does not obtain consent directly from the TCF framework. Consent is given to the Permutive SDK by the publisher, not by the GDPR Consent Management Module.Solution: If using the TCF Control Module, add Permutive as a vendor exception in your consent management configuration. Add the following to your Refer to the Prebid Permutive RTD Provider documentation for detailed guidance.
pbjs.setConfig().consentManagement.gdpr.rules:RTD module not delaying auction correctly
RTD module not delaying auction correctly
If cohorts are missing from some bid requests, ensure your Real-Time Data configuration includes
waitForIt: true in the Permutive RTD provider setup. This setting delays the auction until the Permutive RTD module has completed processing. Also verify that auctionDelay is set to an appropriate value (typically 200ms or higher) in your pbjs.setConfig().realTimeData configuration.Prebid version 9.5.0+ upgrade issues
Prebid version 9.5.0+ upgrade issues
If you recently upgraded to Prebid.js v9.5.0 or later and are experiencing issues, this version fixed a critical bug related to how the Permutive RTD module pushes values into ORTB2 objects. If you’re on an older version and seeing intermittent targeting issues (especially when numeric targeting values are present), upgrade to v9.5.0 or later. After upgrading, verify that all required modules (RTD module, bid adapter modules, Permutive RTD provider) are still included in your build.
Multiple Prebid versions causing conflicts
Multiple Prebid versions causing conflicts
Some publishers run multiple versions of Prebid.js on their site (e.g., one for display ads and another for video). This can cause conflicts with the Permutive RTD module. Ensure you’re using a single, consistent Prebid.js setup across your site.
Identity signals not appearing in bid requests
Identity signals not appearing in bid requests
If identity signals (RampID, ID5, UID2) are not appearing in the
user.eids field of bid requests:- Verify identity provider is enabled: Navigate to Identity → Catalog in the Permutive Dashboard and confirm your identity provider is enabled and configured correctly
- Check Prebid module inclusion: Verify the
permutiveIdentityManagerIdSystemmodule is included in your Prebid build by checking your Prebid configuration - Confirm consent: Ensure your identity provider has proper consent in your CMP. Each identity provider requires specific TCF purposes to be enabled
- Check SDK timing: The Identity Manager module needs the Permutive SDK to be available. Increase the
ajaxTimeoutparameter if your SDK loads slowly - Review debug logs: Add
?pbjs_debug=trueto your URL and check for “User ID” logs in the console
Identity Manager module not loading in time
Identity Manager module not loading in time
If you see empty
user.eids in some bid requests but not others, the Identity Manager module may not be loading in time for the auction. This can happen if:- The Permutive SDK loads slowly on your page
- The
ajaxTimeoutparameter is too low - The
auctionDelayin userSync configuration is too short
ajaxTimeout (in the module params) and auctionDelay (in userSync config). Start with ajaxTimeout: 90 and auctionDelay: 100, then adjust based on your page load times.Both RTD and Identity Manager modules causing auction delays
Both RTD and Identity Manager modules causing auction delays
If you’re using both modules and experiencing slow auctions, you may need to optimize your timeout configuration:
- RTD module
auctionDelay: Controls how long to wait for cohort data (recommended: 200ms) - Identity Manager
auctionDelay: Controls how long to wait for identity signals (recommended: 100ms) - Identity Manager
ajaxTimeout: Controls how long to wait for the SDK (recommended: 50-90ms)
Debugging with query parameters
Debugging with query parameters
To troubleshoot Prebid integration issues, add these query parameters to your URL:
?__permutive.loggingEnabled=true&pbjs_debug=true. This enables detailed logging from both the Permutive SDK and Prebid.js in your browser’s developer console. Look for logs tagged with “permutiveRTD” to see exactly what the RTD module is doing, including which segments it’s reading and which bidders it’s attaching data to. For the Identity Manager module, look for “User ID” logs showing identity retrieval.Changelog
July 2025
- Enhanced support for advertiser cohort activation via Prebid
- Improved Prebid RTD module configuration options
June 2025
- Added support for PrebidAuctions event collection
- Enhanced bid data collection and auction insights
For detailed changelog information, visit our
Changelog.