Skip to content

Commit a6a60c9

Browse files
lucorlucor
authored
WURFL RTD: zero-latency version update (#6336)
See: prebid/Prebid.js#14115
1 parent 6c2e1f3 commit a6a60c9

File tree

1 file changed

+156
-48
lines changed

1 file changed

+156
-48
lines changed

‎dev-docs/modules/wurflRtdProvider.md‎

Lines changed: 156 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -22,87 +22,136 @@ This module loads a dynamically generated JavaScript from prebid.wurflcloud.com
2222

2323
## Description
2424

25-
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`.
25+
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.
2626

27-
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.
27+
The WURFL RTD module relies on localStorage caching and local client-side detection, providing instant device enrichment on every page load.
2828

29-
## A Note About User-Agent Client Hints
29+
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.
3030

31-
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.
31+
### Key Features
3232

33-
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).
33+
* **Instant Device Enrichment**: Device data is available immediately without auction delays
34+
* First-time visitors: Instant basic device detection using Local Client-side Enrichment (LCE)
35+
* Returning visitors: Full WURFL data from localStorage cache
36+
* WURFL.js loads asynchronously in the background to refresh cache for future page loads
3437

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

37-
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.
42+
* **Bot Detection**: Provides `is_robot` capability in `device.ext.wurfl` for easy bot filtering
43+
* Additional `robot_family` capability available in paid tiers to identify specific bot types (Googlebot, Bingbot, etc.)
3844

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

41-
{: .table .table-bordered .table-striped }
47+
### Extended Capability Set
48+
49+
At a minimum, all adapters receive these WURFL capabilities:
50+
51+
* `brand_name`
52+
* `model_name`
53+
* `is_ott`
54+
* `physical_form_factor`
55+
* `is_console`
56+
* `resolution_height`
57+
* `resolution_width`
58+
* `density_class`
59+
* `is_full_desktop`
60+
* `device_os`
61+
* `device_os_version`
62+
* `form_factor`
63+
* `advertised_device_os`
64+
* `advertised_device_os_version`
65+
* `pixel_density`
66+
* `is_robot`
67+
* `complete_device_name`
68+
* `is_mobile`
69+
* `advertised_browser`
70+
* `advertised_browser_version`
71+
72+
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:
73+
74+
* Detailed iOS device models (specific iPhone/iPad variants)
75+
* Physical device dimensions and screen properties
76+
* Device pricing and release information
77+
* Browser and OS version details
78+
* Bot family identification (paid tier)
79+
80+
### User-Agent Client Hints Support
81+
82+
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.
83+
84+
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.
85+
86+
## SSP/DSP Integration (IMPORTANT)
87+
88+
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.
4289

43-
| | SSP Adapter | SSP Server Side End-Point |
44-
| :------------------------ | :------------ | :--------------------------------------------------------------- |
45-
| SSP adapter is already passing the ORTB2 device to the server (auction endpoint). | No changes required. | Update backend logic to utilize the device data. |
46-
| 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. |
47-
| 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. |
90+
### Integration Scenarios
4891

49-
## Usage
92+
| SSP Adapter Status | Required Adapter Changes | Required Server Changes |
93+
|-------------------|--------------------------|-------------------------|
94+
| Already passing ORTB2 device to server | No changes required | Update backend logic to utilize device data |
95+
| 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 |
96+
| 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 |
5097

51-
### Build
98+
## Building the Module
5299

53-
To build the WURFL RTD module with Prebid.js, use the following command:
100+
To build the WURFL RTD module with Prebid.js:
54101

55102
```bash
56-
gulp build --modules="wurflRtdProvider,appnexusBidAdapter,..."
103+
gulp build --modules="wurflRtdProvider,appnexusBidAdapter,..."
57104
```
58105

59-
### Configuration
106+
## Configuration
60107

61-
To initialize the WURFL RTD module in Prebid.js, use the `setConfig` function as shown below.
62-
The module is configured within `realTimeData.dataProviders`.
63-
Ensure `waitForIt` is set to `true`. We recommend setting `auctionDelay` to `500 ms` initially,
64-
though lower values may be suitable with fine-tuning.
108+
The module is configured within `realTimeData.dataProviders`.
109+
110+
### Basic Configuration
65111

66112
```javascript
67113
pbjs.setConfig({
68-
realTimeData: {
69-
auctionDelay: 500,
70-
dataProviders: [{
71-
name: 'wurfl',
72-
waitForIt: true,
73-
params: {
74-
debug: false
75-
}
76-
}]
77-
}
114+
realTimeData: {
115+
dataProviders: [{
116+
name: 'wurfl'
117+
}]
118+
}
78119
});
79120
```
80121

81-
### Parameters
122+
### Configuration Parameters
82123

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

85-
| Name | Type | Description | Default |
86-
| :------------------------ | :------------ | :--------------------------------------------------------------- |:----------------------|
87-
| name | String | Real time data module name | Always set to 'wurfl' |
88-
| waitForIt | Boolean | Set to `true` if an `auctionDelay` is defined (required) | `false` |
89-
| params | Object | Configuration parameters for the WURFL RTD module. | |
90-
| params.altHost | String | Alternate host for connecting to WURFL.js | |
91-
| params.debug | Boolean | Enable debug mode. | `false` |
126+
| Name | Type | Description | Default |
127+
|------|------|-------------|---------|
128+
| `name` | String | Real time data module name | Always 'wurfl' |
129+
| `waitForIt` | Boolean | Should be set to true for proper initialization | `false` |
130+
| `params` | Object | Configuration parameters for WURFL RTD | |
131+
| `params.altHost` | String | Alternate host for connecting to WURFL.js | |
132+
| `params.debug` | Boolean | Enable debug mode for troubleshooting | `false` |
133+
| `params.abTest` | Object | A/B testing configuration (optional) | |
134+
| `params.abTest.enabled` | Boolean | Enable A/B testing | `false` |
135+
| `params.abTest.testName` | String | Name identifier for the test | |
136+
| `params.abTest.splitRatio` | Number | Ratio for treatment group (0.0-1.0) | `0.5` |
92137

93-
## Testing
138+
## Testing
94139

95-
To test how the WURFL RTD module works, run the following command:
140+
To test the WURFL RTD module locally:
96141

97-
`gulp serve --modules=wurflRtdProvider,appnexusBidAdapter`
142+
```bash
143+
gulp serve --modules=wurflRtdProvider,appnexusBidAdapter
144+
```
98145

99-
Then, point your browser to:
146+
Then navigate to:
100147

101-
`http://localhost:9999/integrationExamples/gpt/wurflRtdProvider_example.html`
148+
```sh
149+
http://localhost:9999/integrationExamples/gpt/wurflRtdProvider_example.html
150+
```
102151

103-
## Expected Behavior
152+
## Example Enriched Bid Request
104153

105-
WURFL RTD adds device information to the bidderRequest's `ortb2.device.ext.wurfl` object (enabled SSPs have access to an extended capability set).
154+
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:
106155

107156
```json
108157
{
@@ -164,3 +213,62 @@ WURFL RTD adds device information to the bidderRequest's `ortb2.device.ext.wurfl
164213
}
165214
}
166215
```
216+
217+
### Extended Capabilities in `device.ext.wurfl`
218+
219+
Licensed SSPs can receive up to 500+ additional capabilities based on their subscription, including:
220+
221+
**Device Identification:**
222+
223+
* `wurfl_id`: Unique WURFL device identifier
224+
* `complete_device_name`: Full commercial device name
225+
* `brand_name`: Device brand
226+
* `model_name`: Device model
227+
* `marketing_name`: Commercial marketing name
228+
229+
**Form Factor Detection:**
230+
231+
* `form_factor`: Device category (Smartphone, Tablet, Desktop, etc.)
232+
* `is_mobile`, `is_smartphone`, `is_tablet`: Boolean form factor flags
233+
* `is_full_desktop`, `is_connected_tv`, `is_smarttv`: Additional form factors
234+
235+
**Bot Detection:**
236+
237+
* `is_robot` (Boolean): Available to all publishers - simple true/false bot identification
238+
* `robot_family` (Categorical): Paid tier feature - identifies specific bot types (Spider, Previewer, Fetcher, Health-Checker, Adbot, Headless Browser) for granular filtering and analytics
239+
240+
**Browser & OS:**
241+
242+
* `advertised_browser`, `advertised_browser_version`
243+
* `advertised_device_os`, `advertised_device_os_version`
244+
245+
**Physical Properties:**
246+
247+
* `physical_screen_height`, `physical_screen_width`: Physical dimensions in mm
248+
* `resolution_height`, `resolution_width`: Screen resolution in pixels
249+
* `pixel_density`: Pixels per inch
250+
* `pointing_method`: Input method (touchscreen, stylus, mouse, etc.)
251+
252+
For a complete list of available capabilities, see [WURFL Capabilities Documentation](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js).
253+
254+
## A/B Testing with ScientiaMobile
255+
256+
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.
257+
258+
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.
259+
260+
## Getting Started
261+
262+
1. **Build** Prebid.js with the WURFL RTD module
263+
2. **Configure** the module in your Prebid.js setup
264+
3. **Test** locally to verify enrichment
265+
266+
## Privacy & Compliance
267+
268+
The WURFL RTD module processes minimal personal data under legitimate interest for technical service delivery:
269+
270+
* Device detection uses only HTTP headers (User-Agent, Client Hints)
271+
* No user tracking or cross-site identification
272+
* IP addresses processed transiently for service delivery only
273+
274+
For questions or support, visit [ScientiaMobile Support](https://support.scientiamobile.com).

0 commit comments

Comments
 (0)