--- layout: page_v2 title: Permutive Real Time Data Provider display_name: Permutive Real Time Data Module description: Permutive Real Time Data Module page_type: module module_type: rtd module_code : permutiveRtdProvider enable_download : true vendor_specific: true sidebarType : 1 --- # Permutive RTD Provider {:.no_toc} * TOC {:toc} ## Prebid Config for Permutive RTD Module This module reads cohorts from Permutive and attaches them as targeting keys to bid requests. ### _Permutive Real-time Data Submodule_ #### Usage Compile the Permutive RTD module into your Prebid build: ```bash gulp build --modules=rtdModule,permutiveRtdProvider ``` > Note that the global RTD module, `rtdModule`, is a prerequisite of the Permutive RTD module. You then need to enable the Permutive RTD in your Prebid configuration. Below is an example of the format: ```javascript pbjs.setConfig({ ..., realTimeData: { auctionDelay: 50, // optional auction delay dataProviders: [{ name: 'permutive', waitForIt: true, // should be true if there's an `auctionDelay` params: { acBidders: ['msft'] } }] }, ... }) ``` #### Parameters The parameters below provide configurability for general behaviours of the RTD submodule, as well as enabling settings for specific use cases mentioned above (e.g. acbidders). ## Parameters {: .table .table-bordered .table-striped } | Name | Type | Description | Default | | ---------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | name | String | This should always be `permutive` | - | | waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | | params | Object | | - | | params.acBidders | String[] | An array of bidder codes to share cohorts with in certain versions of Prebid, see below | `[]` | | params.maxSegs | Integer | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500` | | params.enforceVendorConsent | Boolean | When `true`, require TCF consent for vendor 361 as well as the required purpose consent. | `false` | | params.bidders | Object | Custom cohort sources by bidder; also enables ortb2 data for bidders outside `acBidders`. | `{}` | | params.bidders.\.customCohorts | Object | Custom cohorts source configuration for a specific bidder. | - | | params.bidders.\.customCohorts.source | String | Storage type to read custom cohorts from. Currently only `'ls'` (localStorage) is supported. | - | | params.bidders.\.customCohorts.key | String | The localStorage key to read custom cohorts from. | - | ### Consent **Prebid.js 10.19.0 and later:** The Permutive RTD module uses the publisher's TCF purpose 1 signals by default, without requiring consent for Permutive's vendor ID 361 (`params.enforceVendorConsent` defaults to `false`). If publisher purpose consent is not available where GDPR applies, the module will not initialize. To also require TCF vendor consent for Permutive, include vendor ID 361 in your CMP and explicitly set `params.enforceVendorConsent: true` in the Permutive RTD provider configuration: ```javascript pbjs.setConfig({ realTimeData: { dataProviders: [{ name: 'permutive', params: { enforceVendorConsent: true } }] } }); ``` **Prebid.js 10.18.0 and earlier:** `enforceVendorConsent` is not supported. These versions identify the Permutive module with vendor ID 361, so installations using the [TCF Control Module](/dev-docs/modules/tcfControl.html) may still need the legacy `vendorExceptions` entry for `permutive` if the publisher has not collected TCF vendor consent. For example, the relevant TCF Control rules could include: ```javascript [ { purpose: 'storage', enforcePurpose: true, enforceVendor: true, vendorExceptions: ['permutive'] }, { purpose: 'basicAds', enforcePurpose: true, enforceVendor: true, vendorExceptions: [] } ] ``` {% include dev-docs/vendor-exception.md gvlId="361" %} Before making any updates to your consent configuration, please ensure that your approach aligns with internal policies and current regulations regarding consent. ## Cohort Activation with Permutive RTD Module **Note**: Publishers must be enabled on the above Permutive RTD Submodule to enable Standard Cohorts. ### _Enabling Publisher Cohorts_ #### Standard Cohorts The Permutive RTD module sets Standard Cohort IDs as bidder-specific ortb2.user.data first-party data, following the Prebid ortb2 convention. Cohorts will be sent in the `p_standard` key-value. For Prebid versions below 7.29.0, populate the acbidders config in the Permutive RTD with an array of bidder codes with whom you wish to share Standard Cohorts with. You also need to permission the bidders by communicating the bidder list to the Permutive team at . For Prebid versions 7.29.0 and above, do not populate bidder codes in acbidders for the purpose of sharing Standard Cohorts (Note: there may be other business needs that require you to populate acbidders for Prebid versions 7.29.0+, see Advertiser Cohorts below). To share Standard Cohorts with bidders in Prebid versions 7.29.0 and above, communicate the bidder list to the Permutive team at . #### _Bidder Specific Requirements for Standard Cohorts_ For PubMatic or OpenX: Please ensure you are using Prebid.js 7.13 (or later) For Xandr: Please ensure you are using Prebid.js 7.29 (or later) For Equativ: Please ensure you are using Prebid.js 7.26 (or later) #### Custom Cohorts The Permutive RTD module also supports passing any of the **Custom** Cohorts created in the dashboard to some SSP partners for targeting e.g. setting up publisher deals. For these activations, cohort IDs are set in bidder-specific locations per ad unit (custom parameters). Currently, bidders with known support for custom cohort targeting are: * Xandr * Magnite * Microsoft (msft) When enabling the respective Activation for a cohort in Permutive, this module will automatically attach that cohort ID to the bid request. There is no need to enable individual bidders in the module configuration, it will automatically reflect which SSP integrations you have enabled in your Permutive dashboard. Permutive cohorts will be sent in the permutive key-value. **Note:** Publishers migrating from the `appnexus` bidder to `msft` need to configure the `params.bidders` object so the module knows where to read custom cohorts from. The Permutive SDK writes `msft` custom cohorts to the same localStorage key used by `appnexus` (`_papns`), so publishers should add the following to their Permutive RTD config: ```javascript params: { acBidders: ['msft'], bidders: { msft: { customCohorts: { source: 'ls', key: '_papns' } } } } ``` ### _Enabling Advertiser Cohorts_ If you are connecting to an Advertiser seat within Permutive to share Advertiser Cohorts, populate the acbidders config in the Permutive RTD with an array of bidder codes with whom you wish to share Advertiser Cohorts with. ### _Managing acbidders_ If your business needs require you to populate acbidders with bidder codes based on the criteria above, there are **two** ways to manage it. #### Option 1 - Automated If you are using Prebid.js v7.13.0+, bidders may be added to or removed from the acbidders config directly within the Permutive Dashboard. **Permutive can do this on your behalf**. Simply contact your Permutive CSM with on cc, indicating which bidders you would like added. Or, a publisher may do this themselves within the Permutive Dashboard using the below instructions. ##### Create Integration In order to manage acbidders via the Permutive dashboard, it is necessary to first enable the Prebid integration via the integrations page (settings). ![Alt text](/assets/images/dev-docs/modules/permutiveRtdProvider-integration-create.png?raw=true "Permutive Prebid integration - create") **Note on Revenue Insights:** The prebid integration includes a feature for revenue insights, which is not required for the purpose of updating acbidders config. Please see [this document](https://support.permutive.com/hc/en-us/articles/360019044079-Revenue-Insights) for more information about revenue insights. ##### Update acbidders The input for the “Data Provider config” is a multi-input free text. A valid “bidder code” needs to be entered in order to enable Standard or Advertiser Cohorts to be passed to the desired partner. The [prebid Bidders page](https://docs.prebid.org/dev-docs/bidders.html) contains instructions and a link to a list of possible bidder codes. ![Alt text](/assets/images/dev-docs/modules/permutiveRtdProvider-integration-update.png?raw=true "Permutive Prebid integration - update") Bidders can be added or removed from acbidders using this feature, however, this will not impact any bidders that have been applied using the manual method below. #### Option 2 - Manual As a secondary option, bidders may be added manually. To do so, define which bidders should receive Standard or Advertiser Cohorts by including the _bidder code_ of any bidder in the `acBidders` array. **Note:** If you ever need to remove a manually-added bidder, the bidder will also need to be removed manually.