Skip to content

WURFL RTD: zero-latency version update #6336

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

Merged
ChrisHuie merged 2 commits into from
Dec 4, 2025
Merged

WURFL RTD: zero-latency version update #6336

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6fd0266
WURFL RTD: zero-latency version update
lucor Nov 13, 2025
e270bf5
Merge branch 'master' into feat/wurfl-rtd-zero-latency
lucor Dec 2, 2025
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
204 changes: 156 additions & 48 deletions dev-docs/modules/wurflRtdProvider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,87 +22,136 @@ This module loads a dynamically generated JavaScript from prebid.wurflcloud.com

## Description

The WURFL RTD module enriches the Prebid.js bid request's OpenRTB 2.0 device data with [WURFL device data](https://www.scientiamobile.com/wurfl-js-business-edition-at-the-intersection-of-javascript-and-enterprise/). The module populates the `device` and `device.ext.wurfl` with WURFL device capabilities, ensuring that all bidder adapters have access to enriched device data. At a minimum, three WURFL capabilities are made available to all adapters: `is_mobile`, `complete_device_name` and `form_factor`.
The WURFL RTD module enriches Prebid.js bid requests with comprehensive device detection data, helping publishers maximize ad revenue through better device targeting. Publishers typically see improved CPM performance, particularly for mobile traffic where device signals provide valuable bidding context.

SSPs and other demand partners subscribed to this service with ScientiaMobile will also receive an expanded set of device properties, including more detailed detection for iOS devices (e.g., specific iPhone and iPad model information). For a comprehensive list of available device capabilities, please refer to the [WURFL device capabilities](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js) documentation.
The WURFL RTD module relies on localStorage caching and local client-side detection, providing instant device enrichment on every page load.

## A Note About User-Agent Client Hints
The module enriches `ortb2.device` with complete device information and adds extended WURFL capabilities to `device.ext.wurfl`, ensuring all bidder adapters have immediate access to enriched device data.

WURFL.js is fully compatible with Chromium's User-Agent Client Hints (UA-CH) device identification mechanisms. If the User-Agent string is generic and Client Hints are not available in the HTTP request, the service will automatically request and obtain [high entropy client hint values](https://wicg.github.io/ua-client-hints/#getHighEntropyValues) from the client.
### Key Features

However, it is still recommended to explicitly opt-in and declare support for User-Agent Client Hints on the publisher's website. Doing so improves performance and contributes to a faster user experience. For detailed instructions on implementing User-Agent Client Hint support, refer to the [relevant documentation here](https://docs.scientiamobile.com/guides/implementing-useragent-clienthints).
* **Instant Device Enrichment**: Device data is available immediately without auction delays
* First-time visitors: Instant basic device detection using Local Client-side Enrichment (LCE)
* Returning visitors: Full WURFL data from localStorage cache
* WURFL.js loads asynchronously in the background to refresh cache for future page loads

## Integration Notes
* **Comprehensive Device Detection**: Enriches `ortb2.device` with complete device information including:
* Standard OpenRTB 2.0 device fields: `make`, `model`, `devicetype`, `os`, `osv`, `ppi`, `pxratio`
* Full iPhone and iPad model recognition in `ortb2.device.hwv` (e.g., "iPhone 16 Pro", "iPad Pro 12.9-inch")

While the WURFL RTD module enriches the OpenRTB 2.0 payload, it is the responsibility of the SSP's adapter to access and pass the information to the auction endpoint. The auction endpoint must then use the new data to support its business logic.
* **Bot Detection**: Provides `is_robot` capability in `device.ext.wurfl` for easy bot filtering
* Additional `robot_family` capability available in paid tiers to identify specific bot types (Googlebot, Bingbot, etc.)

The following scenarios are possible:
* **Free Tier Available**: Full WURFL device enrichment for publishers. High-traffic sites and SSPs should contact ScientiaMobile to enable more properties and unlock volume.

{: .table .table-bordered .table-striped }
### Extended Capability Set

At a minimum, all adapters receive these WURFL capabilities:

* `brand_name`
* `model_name`
* `is_ott`
* `physical_form_factor`
* `is_console`
* `resolution_height`
* `resolution_width`
* `density_class`
* `is_full_desktop`
* `device_os`
* `device_os_version`
* `form_factor`
* `advertised_device_os`
* `advertised_device_os_version`
* `pixel_density`
* `is_robot`
* `complete_device_name`
* `is_mobile`
* `advertised_browser`
* `advertised_browser_version`

Publishers, SSPs and demand partners with a commercial license can receive up to 500+ additional [WURFL device capabilities](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js) based on their licensing agreement, including:

* Detailed iOS device models (specific iPhone/iPad variants)
* Physical device dimensions and screen properties
* Device pricing and release information
* Browser and OS version details
* Bot family identification (paid tier)

### User-Agent Client Hints Support

WURFL.js is fully compatible with Chromium's User-Agent Client Hints (UA-CH). If the User-Agent string is generic and Client Hints are not available, the service automatically requests and obtains [high entropy client hint values](https://wicg.github.io/ua-client-hints/#getHighEntropyValues) from the client.

For optimal performance, publishers should explicitly opt-in and declare User-Agent Client Hints support on their website. See the [UA-CH implementation documentation](https://docs.scientiamobile.com/guides/implementing-useragent-clienthints) for details.

## SSP/DSP Integration (IMPORTANT)

While the WURFL RTD module enriches the OpenRTB 2.0 payload, SSP adapters must access and pass this information to their auction endpoints. The endpoint must then utilize the enriched device data in its bidding logic.

| | SSP Adapter | SSP Server Side End-Point |
| :------------------------ | :------------ | :--------------------------------------------------------------- |
| SSP adapter is already passing the ORTB2 device to the server (auction endpoint). | No changes required. | Update backend logic to utilize the device data. |
| SSP adapter is not currently passing the data to server. | Update adapter to read `device` and/or `device.ext.wurfl` data and pass it to the endpoint. | Update backend logic to utilize the device data. |
| SSP doesn't have a Bidder Adapter. | Implement PreBid.js adapter and read `device` and/or `device.ext.wurfl` data and pass it to the endpoint. | Update end-point to read and utilize the data. |
### Integration Scenarios

## Usage
| SSP Adapter Status | Required Adapter Changes | Required Server Changes |
|-------------------|--------------------------|-------------------------|
| Already passing ORTB2 device to server | No changes required | Update backend logic to utilize device data |
| Not currently passing device data | Update adapter to read `device` and/or `device.ext.wurfl` and pass to endpoint | Update backend logic to utilize device data |
| No Bidder Adapter exists | Implement Prebid.js adapter to read and pass `device` and/or `device.ext.wurfl` | Implement endpoint logic to read and utilize data |

### Build
## Building the Module

To build the WURFL RTD module with Prebid.js, use the following command:
To build the WURFL RTD module with Prebid.js:

```bash
gulp build --modules="wurflRtdProvider,appnexusBidAdapter,..."
gulp build --modules="wurflRtdProvider,appnexusBidAdapter,..."
```

### Configuration
## Configuration

To initialize the WURFL RTD module in Prebid.js, use the `setConfig` function as shown below.
The module is configured within `realTimeData.dataProviders`.
Ensure `waitForIt` is set to `true`. We recommend setting `auctionDelay` to `500 ms` initially,
though lower values may be suitable with fine-tuning.
The module is configured within `realTimeData.dataProviders`.

### Basic Configuration

```javascript
pbjs.setConfig({
realTimeData: {
auctionDelay: 500,
dataProviders: [{
name: 'wurfl',
waitForIt: true,
params: {
debug: false
}
}]
}
realTimeData: {
dataProviders: [{
name: 'wurfl'
}]
}
});
```

### Parameters
### Configuration Parameters

{: .table .table-bordered .table-striped }

| Name | Type | Description | Default |
| :------------------------ | :------------ | :--------------------------------------------------------------- |:----------------------|
| name | String | Real time data module name | Always set to 'wurfl' |
| waitForIt | Boolean | Set to `true` if an `auctionDelay` is defined (required) | `false` |
| params | Object | Configuration parameters for the WURFL RTD module. | |
| params.altHost | String | Alternate host for connecting to WURFL.js | |
| params.debug | Boolean | Enable debug mode. | `false` |
| Name | Type | Description | Default |
|------|------|-------------|---------|
| `name` | String | Real time data module name | Always 'wurfl' |
| `waitForIt` | Boolean | Should be set to true for proper initialization | `false` |
| `params` | Object | Configuration parameters for WURFL RTD | |
| `params.altHost` | String | Alternate host for connecting to WURFL.js | |
| `params.debug` | Boolean | Enable debug mode for troubleshooting | `false` |
| `params.abTest` | Object | A/B testing configuration (optional) | |
| `params.abTest.enabled` | Boolean | Enable A/B testing | `false` |
| `params.abTest.testName` | String | Name identifier for the test | |
| `params.abTest.splitRatio` | Number | Ratio for treatment group (0.0-1.0) | `0.5` |

## Testing
## Testing

To test how the WURFL RTD module works, run the following command:
To test the WURFL RTD module locally:

`gulp serve --modules=wurflRtdProvider,appnexusBidAdapter`
```bash
gulp serve --modules=wurflRtdProvider,appnexusBidAdapter
```

Then, point your browser to:
Then navigate to:

`http://localhost:9999/integrationExamples/gpt/wurflRtdProvider_example.html`
```sh
http://localhost:9999/integrationExamples/gpt/wurflRtdProvider_example.html
```

## Expected Behavior
## Example Enriched Bid Request

WURFL RTD adds device information to the bidderRequest's `ortb2.device.ext.wurfl` object (enabled SSPs have access to an extended capability set).
WURFL RTD adds comprehensive device information to the bid request. The `ortb2.device` object is enriched with standard OpenRTB fields, and `device.ext.wurfl` contains extended WURFL capabilities:

```json
{
Expand Down Expand Up @@ -164,3 +213,62 @@ WURFL RTD adds device information to the bidderRequest's `ortb2.device.ext.wurfl
}
}
```

### Extended Capabilities in `device.ext.wurfl`

Licensed SSPs can receive up to 500+ additional capabilities based on their subscription, including:

**Device Identification:**

* `wurfl_id`: Unique WURFL device identifier
* `complete_device_name`: Full commercial device name
* `brand_name`: Device brand
* `model_name`: Device model
* `marketing_name`: Commercial marketing name

**Form Factor Detection:**

* `form_factor`: Device category (Smartphone, Tablet, Desktop, etc.)
* `is_mobile`, `is_smartphone`, `is_tablet`: Boolean form factor flags
* `is_full_desktop`, `is_connected_tv`, `is_smarttv`: Additional form factors

**Bot Detection:**

* `is_robot` (Boolean): Available to all publishers - simple true/false bot identification
* `robot_family` (Categorical): Paid tier feature - identifies specific bot types (Spider, Previewer, Fetcher, Health-Checker, Adbot, Headless Browser) for granular filtering and analytics

**Browser & OS:**

* `advertised_browser`, `advertised_browser_version`
* `advertised_device_os`, `advertised_device_os_version`

**Physical Properties:**

* `physical_screen_height`, `physical_screen_width`: Physical dimensions in mm
* `resolution_height`, `resolution_width`: Screen resolution in pixels
* `pixel_density`: Pixels per inch
* `pointing_method`: Input method (touchscreen, stylus, mouse, etc.)

For a complete list of available capabilities, see [WURFL Capabilities Documentation](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js).

## A/B Testing with ScientiaMobile

The WURFL RTD module includes built-in A/B testing capabilities to help publishers measure the impact of device enrichment on their revenue. When enabled, the module randomly assigns users to treatment (enriched) or control (not enriched) groups.

ScientiaMobile can assist with setting up and analyzing A/B tests to quantify the value of WURFL enrichment for your specific inventory. Contact [ScientiaMobile](https://www.scientiamobile.com/contact/) to discuss A/B testing collaboration.

## Getting Started

1. **Build** Prebid.js with the WURFL RTD module
2. **Configure** the module in your Prebid.js setup
3. **Test** locally to verify enrichment

## Privacy & Compliance

The WURFL RTD module processes minimal personal data under legitimate interest for technical service delivery:

* Device detection uses only HTTP headers (User-Agent, Client Hints)
* No user tracking or cross-site identification
* IP addresses processed transiently for service delivery only

For questions or support, visit [ScientiaMobile Support](https://support.scientiamobile.com).