Update permutive rtd dev docs

dev-docs/modules/permutiveRtdProvider.md

@@ -17,10 +17,13 @@ sidebarType : 1
 * TOC
 {:toc}
 
-## Overview
+## Prebid Config for Permutive RTD Module
+
 This module reads cohorts from Permutive and attaches them as targeting keys to bid requests.
 
-## Usage
+### _Permutive Real-time Data Submodule_
+
+#### Usage
 Compile the Permutive RTD module into your Prebid build:
 ```
 gulp build --modules=rtdModule,permutiveRtdProvider
@@ -47,30 +50,125 @@ pbjs.setConfig({
 })
 ```
 
-## Supported Bidders
-The Permutive RTD module sets Audience Connector cohorts as bidder-specific `ortb2.user.data` first-party data, following the Prebid `ortb2` convention, for any bidder included in `acBidders`. The module also supports bidder-specific data locations per ad unit (custom parameters) for the below bidders:
+#### Parameters
 
-{: .table .table-bordered .table-striped }
-| Bidder      | ID         | Custom Cohorts       | Audience Connector |
-| ----------- | ---------- | -------------------- | ------------------ |
-| Xandr       | `appnexus` | Yes                  | Yes                |
-| Magnite     | `rubicon`  | Yes                  | No                 |
-| Ozone       | `ozone`    | No                   | Yes                |
+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).
 
-Key-values details for custom parameters:
-* **Custom Cohorts:** The module configuration will automatically reflect the SSP integrations (_Activations_) you have enabled in your Permutive dashboard. Any additional bidders you want to pass data to will need to be configured. Permutive cohorts will be sent in the permutive key-value.
+## Parameters
 
-* **Audience Connector:** You'll need to define which bidders should receive Audience Connector cohorts. You need to include the `ID` of any bidder in the `acBidders` array. Audience Connector cohorts will be sent in the `p_standard` key-value.
+{: .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 bidders which should receive Audience Connector cohorts.                          | `[]`               |
+| params.maxSegs         | Integer              | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500`              |
+| params.transformations | Object[]             | An array of configurations for ORTB2 user data transformations                                |                    |
 
+##### The `transformations` parameter
 
-## Parameters
+This array contains configurations for transformations we'll apply to the Permutive object in the ORTB2 `user.data` array. The results of these transformations will be appended to the `user.data` array that's attached to ORTB2 bid requests.
+
+##### Supported transformations
 
 {: .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 bidders which should receive Audience Connector cohorts. | `[]` |
-| params.maxSegs    | Integer              | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500` |
+| Name                   | ID                   | Config structure                                        | Description                                                                          |
+| ---------------------- | -------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| IAB taxonomies         | iab                  | ```{ segtax: number, iabIds: Object<number, number>}``` | Transform segment IDs from Permutive to IAB (note: alpha version, subject to change) |
+
+#### Context
+
+Permutive is not listed as a TCF vendor as all data collection is on behalf of the publisher and based on consent the publisher has received from the user.
+Rather than through the TCF framework, this consent is provided to Permutive when the user gives the relevant permissions on the publisher website which allow the Permutive SDK to run.
+This means that if GDPR enforcement is configured _and_ the user consent isn’t given for Permutive to fire, no cohorts will populate.
+As Prebid utilizes TCF vendor consent, for the Permutive RTD module to load, Permutive needs to be labeled within the Vendor Exceptions
+
+#### Instructions
+
+1. Publisher enables GDPR rules within Prebid.
+2. Label Permutive as an exception, as shown below.
+```javascript
+[
+  {
+    purpose: 'storage',
+    enforcePurpose: true,
+    enforceVendor: true,
+    vendorExceptions: ["permutive"]
+  },
+  {
+    purpose: 'basicAds',
+    enforcePurpose: true,
+    enforceVendor: true,
+    vendorExceptions: []
+  }
+]
+```
+
+Before making any updates to this configuration, please ensure that this approach aligns with internal policies and current regulations regarding consent.
+
+## Cohort Activation with Permutive RTD Module
+
+### _Enabling Standard Cohorts_
+
+**Note**: Publishers must be enabled on the above Permutive RTD Submodule to enable Standard Cohorts.
+
+The acbidders config in the Permutive RTD module allows publishers to determine which demand partners (SSPs) will receive standard cohorts via the <u>user.data</u> ortb2 object. Cohorts will be sent in the `p_standard` key-value.
+
+The Permutive RTD module sets standard cohort IDs as bidder-specific ortb2.user.data first-party data, following the Prebid ortb2 convention.
+
+There are **two** ways to assign which demand partner bidders (e.g. SSPs) will receive Standard Cohort information via the Audience Connector (acbidders) config:
+
+#### Option 1 - Automated
+
+New demand partner bidders may be added to the acbidders config directly within the Permutive Platform.
+
+**Permutive can do this on your behalf**. Simply contact your Permutive CSM with [email protected] on cc,
+indicating which bidders you would like added.
+
+Or, a publisher may do this themselves within the UI using the below instructions.
+
+##### Create Integration
+
+In order to update acbidders via the Permutive dashboard,
+it is necessary to first enable the prebid integration in 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 currently a multi-input free text.
+A valid “bidder code” needs to be entered in order to enable Standard 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")
+
+Acbidders can be added or removed from the list using this feature, however, this will not impact any acbidders that have been applied using the manual method below.
+
+#### Option 2 - Manual
+
+As a secondary option, new demand partner bidders may be added manually.
+
+To do so, a Publisher may define which bidders should receive Standard Cohorts by
+including the _bidder code_ of any bidder in the `acBidders` array.
+
+**Note:** If a Publisher ever needs to remove a manually-added bidder, the bidder will also need to be removed manually.
+
+### _Enabling Custom Cohort IDs for Targeting_
+
+Separately from Standard 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
 
+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.