Skip to content

Neuwo Rtd Module: Quality of life improvements and feautres documentation #6384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gregneuwo wants to merge 2 commits into
base: master
Choose a base branch
from
+162 −41
Open

Neuwo Rtd Module: Quality of life improvements and feautres documentation #6384

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1746a26
docs: update Neuwo RTD Module documentation with new features
grzgm Jan 9, 2026
fd8b441
style: apply formatting to Neuwo RTD Module markdown documentation
grzgm Jan 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 162 additions & 41 deletions dev-docs/modules/neuwoRtdProvider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,21 +81,21 @@ This module is configured as part of the `realTimeData.dataProviders` object.

```javascript
pbjs.setConfig({
realTimeData: {
auctionDelay: 500, // Value can be adjusted based on the needs
dataProviders: [
{
name: "NeuwoRTDModule",
waitForIt: true,
params: {
neuwoApiUrl: "<Your Neuwo Edge API Endpoint URL>",
neuwoApiToken: "<Your Neuwo API Token>",
iabContentTaxonomyVersion: "3.0",
enableCache: true, // Default: true. Caches API responses to avoid redundant requests
},
},
],
},
realTimeData: {
auctionDelay: 500, // Value can be adjusted based on the needs
dataProviders: [
{
name: "NeuwoRTDModule",
waitForIt: true,
params: {
neuwoApiUrl: "<Your Neuwo Edge API Endpoint URL>",
neuwoApiToken: "<Your Neuwo API Token>",
iabContentTaxonomyVersion: "3.0",
enableCache: true, // Default: true. Caches API responses to avoid redundant requests
},
},
],
},
});
```

Expand All @@ -113,6 +113,7 @@ pbjs.setConfig({
| `params.stripQueryParamsForDomains` | String[] | No | `[]` | List of domains for which to strip **all** query parameters. When a domain matches, all query params are removed for that domain and all its subdomains (e.g., `'example.com'` strips params for both `'example.com'` and `'sub.example.com'`). This option takes precedence over `stripQueryParams` for matching domains. |
| `params.stripQueryParams` | String[] | No | `[]` | List of specific query parameter names to strip from the URL (e.g., `['utm_source', 'fbclid']`). Other parameters are preserved. Only applies when the domain does not match `stripQueryParamsForDomains`. |
| `params.stripFragments` | Boolean | No | `false` | If `true`, strips URL fragments (hash, e.g., `#section`) from the URL before analysis. |
| `params.iabTaxonomyFilters` | Object | No | | Per-tier filtering configuration for IAB taxonomies. Allows filtering by relevance threshold and limiting the count of categories per tier. See [IAB Taxonomy Filtering](#iab-taxonomy-filtering) section below for details. |

### API Response Caching

Expand All @@ -126,35 +127,155 @@ The module provides optional URL cleaning capabilities to strip query parameters

```javascript
pbjs.setConfig({
realTimeData: {
auctionDelay: 500, // Value can be adjusted based on the needs
dataProviders: [
{
name: "NeuwoRTDModule",
waitForIt: true,
params: {
neuwoApiUrl: "<Your Neuwo Edge API Endpoint URL>",
neuwoApiToken: "<Your Neuwo API Token>",
iabContentTaxonomyVersion: "3.0",

// Option 1: Strip all query parameters from the URL
stripAllQueryParams: true,

// Option 2: Strip all query parameters only for specific domains
// stripQueryParamsForDomains: ['example.com', 'another-domain.com'],

// Option 3: Strip specific query parameters by name
// stripQueryParams: ['utm_source', 'utm_campaign', 'fbclid'],

// Optional: Strip URL fragments (hash)
stripFragments: true,
},
},
],
},
realTimeData: {
auctionDelay: 500, // Value can be adjusted based on the needs
dataProviders: [
{
name: "NeuwoRTDModule",
waitForIt: true,
params: {
neuwoApiUrl: "<Your Neuwo Edge API Endpoint URL>",
neuwoApiToken: "<Your Neuwo API Token>",
iabContentTaxonomyVersion: "3.0",

// Option 1: Strip all query parameters from the URL
stripAllQueryParams: true,

// Option 2: Strip all query parameters only for specific domains
// stripQueryParamsForDomains: ['example.com', 'another-domain.com'],

// Option 3: Strip specific query parameters by name
// stripQueryParams: ['utm_source', 'utm_campaign', 'fbclid'],

// Optional: Strip URL fragments (hash)
stripFragments: true,
},
},
],
},
});
```

### IAB Taxonomy Filtering

The module provides optional per-tier filtering for IAB taxonomies to control the quantity and quality of categories injected into bid requests. This allows you to limit categories based on their relevance score and restrict the maximum number of categories per tier.

**Filter Configuration:**

Each tier can have two optional parameters:

- `threshold` (Number): Minimum relevance score (0.0 to 1.0). Categories below this threshold are excluded.
- `limit` (Number): Maximum number of categories to include for this tier (after filtering and sorting by relevance).

**Available Tiers:**

| Tier Name | Description | API Response Key |
| :-------------- | :------------------ | :-------------------- |
| `ContentTier1` | IAB Content Tier 1 | `iab_tier_1` |
| `ContentTier2` | IAB Content Tier 2 | `iab_tier_2` |
| `ContentTier3` | IAB Content Tier 3 | `iab_tier_3` |
| `AudienceTier3` | IAB Audience Tier 3 | `iab_audience_tier_3` |
| `AudienceTier4` | IAB Audience Tier 4 | `iab_audience_tier_4` |
| `AudienceTier5` | IAB Audience Tier 5 | `iab_audience_tier_5` |

**Example with IAB taxonomy filtering:**

```javascript
pbjs.setConfig({
realTimeData: {
auctionDelay: 500,
dataProviders: [
{
name: "NeuwoRTDModule",
waitForIt: true,
params: {
neuwoApiUrl: "<Your Neuwo Edge API Endpoint URL>",
neuwoApiToken: "<Your Neuwo API Token>",
iabContentTaxonomyVersion: "3.0",

// Filter IAB taxonomies by tier
iabTaxonomyFilters: {
// Content Tier 1: Keep only the top category with at least 10% relevance
ContentTier1: { limit: 1, threshold: 0.1 },

// Content Tier 2: Keep top 2 categories with at least 10% relevance
ContentTier2: { limit: 2, threshold: 0.1 },

// Content Tier 3: Keep top 3 categories with at least 15% relevance
ContentTier3: { limit: 3, threshold: 0.15 },

// Audience Tier 3: Keep top 3 categories with at least 20% relevance
AudienceTier3: { limit: 3, threshold: 0.2 },

// Audience Tier 4: Keep top 5 categories with at least 20% relevance
AudienceTier4: { limit: 5, threshold: 0.2 },

// Audience Tier 5: Keep top 7 categories with at least 30% relevance
AudienceTier5: { limit: 7, threshold: 0.3 },
},
},
},
],
},
});
```

**How it works:**

1. Categories are first filtered by the `threshold` value (if specified)
2. Remaining categories are sorted by relevance score in descending order (highest first)
3. The top N categories are selected based on the `limit` value (if specified)
4. Tiers without filters configured will use all categories returned by the API

## Accessing Neuwo Data Outside Prebid.js

The Neuwo RTD module enriches bid requests with contextual data that can be accessed in application code for analytics, targeting, integration with Google Ad Manager as [Publisher Provided Signals (PPS)](https://support.google.com/admanager/answer/15287325) or other purposes. The enriched data is available through Prebid.js events.

### Example of Using the `bidRequested` Event

Listen to the `bidRequested` event to access the enriched ORTB2 data. This event fires early in the auction lifecycle and provides direct access to the Neuwo data:

```javascript
pbjs.que.push(function () {
pbjs.onEvent("bidRequested", function (bidRequest) {
// The ortb2 data is available directly on the bidRequest
const ortb2 = bidRequest.ortb2;

// Extract Neuwo-specific data (from www.neuwo.ai provider)
const neuwoSiteData = ortb2?.site?.content?.data?.find(
(d) => d.name === "www.neuwo.ai"
);
const neuwoUserData = ortb2?.user?.data?.find(
(d) => d.name === "www.neuwo.ai"
);

// Use the data in the application
console.log("Neuwo Site Content:", neuwoSiteData);
console.log("Neuwo User Data:", neuwoUserData);

// Example: Store in a global variable for later use
window.neuwoData = {
siteContent: neuwoSiteData,
user: neuwoUserData,
};
});
});
```

### Other Prebid.js Events

The Neuwo data is also available in other Prebid.js events:

| Order | Event | Fires Once Per | Data Location |
| :---- | :----------------- | :------------- | :----------------------------------- |
| 1 | `auctionInit` | Auction | `auctionData.bidderRequests[].ortb2` |
| 2 | `bidRequested` | Bidder | `bidRequest.ortb2` |
| 3 | `beforeBidderHttp` | Bidder | `bidRequests[].ortb2` |
| 4 | `bidResponse` | Bidder | `bidResponse.ortb2` |
| 5 | `auctionEnd` | Auction | `auctionData.bidderRequests[].ortb2` |

For more information on Prebid.js events, see the [Prebid.js Event API documentation](https://docs.prebid.org/dev-docs/publisher-api-reference/getEvents.html).

## Installation

### Step 1: Install Prebid.js
Expand Down