Skip to content

Commit b208f87

Browse files
lucorlucor
authored
docs: document WURFL Device Detection Module for Prebid Server (#6279)
* docs: document WURFL Device Detection Module for Prebid Server This commit adds documentation for the WURFL Device Module in Prebid Server (Go and Java). * docs: document WURFL module requires non-open source dependencies This commit adds documentation for the WURFL Device Module in Prebid Server (Go and Java). * docs: document WURFL module requires non-open source dependencies This commit adds documentation for the WURFL Device Module in Prebid Server (Go and Java).
1 parent aca17f3 commit b208f87

2 files changed

Lines changed: 328 additions & 0 deletions

File tree

‎prebid-server/pbs-modules/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ The full list of modules:
3737
| [**Request Correction**](/prebid-server/pbs-modules/request-correction.html) | Apply optional corrections to bid requests. | general | | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
3838
| [**Response Correction**](/prebid-server/pbs-modules/response-correction.html) | Apply optional corrections to bid responses. | general | | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
3939
| [**Optable Targeting**](/prebid-server/pbs-modules/optable-targeting.html) | Enrich `user.ext.eids`, `user.ext.data`. | general | | <img alt="check" src="/assets/images/icons/icon-check-green.png" width="30"> |
40+
| [**WURFL Device Detection**](/prebid-server/pbs-modules/wurfl-device-detection.html) | Enriches an incoming OpenRTB request with WURFL Device Data | <span style="color: green">✓</span> | <span style="color: green">✓</span> |
4041

4142
## Installing a PBS General Module
4243

‎prebid-server/pbs-modules/wurfl-device-detection.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
---
2+
layout: page_v2
3+
page_type: pbs-module
4+
title: WURFL Device Detection Module
5+
display_name : WURFL Device Detection
6+
sidebarType : 5
7+
---
8+
9+
# WURFL Device Detection Module
10+
{: .no_toc}
11+
12+
* TOC
13+
{:toc}
14+
15+
## Overview
16+
17+
The WURFL Device Detection Module for Prebid Server enriches an incoming OpenRTB request with comprehensive device detection data powered by [ScientiaMobile's WURFL device detection framework](https://www.scientiamobile.com/wurfl-overview/). The module provides accurate and comprehensive device-related information, enabling bidders to make better-informed targeting and optimization decisions.
18+
19+
The module operates using WURFL's on-premise device detection. For PBS-Java, it uses the WURFL OnSite Java API, while PBS-Go uses the WURFL Infuze API. The module operates fully autonomously and does not make any requests to any cloud services in real time to do device detection.
20+
21+
## Key Features
22+
23+
### Device Field Enrichment
24+
25+
The WURFL module populates **missing or empty fields** in `ortb2.device` with the following data:
26+
27+
* `make`: Manufacturer of the device (e.g., "Apple", "Samsung")
28+
* `model`: Device model (e.g., "iPhone 14", "Galaxy S22")
29+
* `os`: Operating system (e.g., "iOS", "Android")
30+
* `osv`: Operating system version (e.g., "16.0", "12.0")
31+
* `h`: Screen height in pixels
32+
* `w`: Screen width in pixels
33+
* `ppi`: Screen pixels per inch (PPI)
34+
* `pxratio`: Screen pixel density ratio
35+
* `devicetype`: Device type (e.g., mobile, tablet, desktop)
36+
* `js`: Support for JavaScript (0 = no, 1 = yes)
37+
38+
{: .alert.alert-info :}
39+
**Note**: If these fields are already populated in the bid request, the module will not overwrite them.
40+
41+
### Publisher-Specific Enrichment
42+
43+
Device enrichment is selectively enabled for publishers based on their account ID. The module identifies publishers through the following fields:
44+
45+
* `site.publisher.id` (for web environments)
46+
* `app.publisher.id` (for mobile app environments)
47+
* `dooh.publisher.id` (for digital out-of-home environments)
48+
49+
### Extended Capabilities
50+
51+
When `ext_caps` is enabled, the module adds the WURFL device ID and all licensed capabilities to `device.ext.wurfl`.
52+
53+
## Planning
54+
55+
This module supports running at two stages:
56+
57+
1. **entrypoint**: Called for all requests before they're validated
58+
2. **raw_auction_request**: Called for all valid requests before they're sent to bid adapters
59+
60+
We recommend defining the execution plan right in the account config so the module is only invoked for specific accounts.
61+
62+
## Setup
63+
64+
### Prerequisites
65+
66+
{: .alert.alert-info :}
67+
This module requires non-open source dependencies
68+
69+
* **PBS-Java**: [WURFL OnSite Java API](https://docs.scientiamobile.com/documentation/onsite/onsite-java-api) - A commercial Java library for on-premise device detection
70+
* **PBS-Go**: [WURFL Infuze (libwurfl)](https://docs.scientiamobile.com/documentation/infuze/infuze-c-api-user-guide) - A commercial C library for on-premise device detection
71+
72+
Both libraries require a license from ScientiaMobile for production use. Evaluation versions are available for testing purposes.
73+
74+
#### PBS-Java Prerequisites
75+
76+
In order to compile the WURFL module in the PBS Java server bundle using a licensed WURFL API, you must follow these steps:
77+
78+
1. Change the URL in the `<repository>` tag in the module's `pom.xml` file to the ScientiaMobile Maven repository URL:
79+
`https://maven.scientiamobile.com/repository/wurfl-onsite/`
80+
81+
The repository is private and requires authentication: to set it up please check the paragraph "Configuring your Builds to work with ScientiaMobile's Private Maven Repository" [on this page](https://docs.scientiamobile.com/documentation/onsite/onsite-java-api).
82+
83+
1. Change the `artifactId` value in the module's `pom.xml` from `wurfl-mock` to `wurfl`
84+
85+
1. Update the `wurfl.version` property value to the latest WURFL Onsite Java API version available.
86+
87+
When the `pom.xml` references the mock API artifact, the module will compile a demo version that returns sample data, allowing basic testing without a WURFL Onsite Java API license.
88+
89+
1. Build the Prebid Server Java bundle with the WURFL module:
90+
91+
```bash
92+
mvn clean package --file extra/pom.xml
93+
```
94+
95+
#### PBS-Go Prerequisites
96+
97+
To build the WURFL module for PBS-Go, you need to install the WURFL Infuze from ScientiaMobile.
98+
For more details, visit: [ScientiaMobile WURFL Infuze](https://docs.scientiamobile.com/documentation/infuze/infuze-c-api-user-guide).
99+
100+
{: .alert.alert-warning :}
101+
**Note**: The WURFL module requires CGO at compile time to link against the WURFL Infuze library.
102+
103+
To enable the WURFL module, the `wurfl` build tag must be specified:
104+
105+
```bash
106+
go build -tags wurfl .
107+
```
108+
109+
### WURFL Data File
110+
111+
A valid WURFL license must include all the required capabilities for device enrichment.
112+
113+
The WURFL module requires a WURFL data file. Commercial licensees of WURFL are granted access to "The Customer Vault", a personal virtual space containing purchased software licenses and weekly updated versions of the WURFL repository.
114+
115+
For evaluation purposes, you can use the sample `wurfl.zip` file included with the WURFL Infuze package (for PBS-Go) or the WURFL OnSite Java API package (for PBS-Java).
116+
117+
For more details, visit: [ScientiaMobile WURFL](https://docs.scientiamobile.com/documentation/).
118+
119+
## Configuration
120+
121+
### Host Company
122+
123+
There is no host-company level config for this module except the execution plan may optionally be at the host level.
124+
125+
### Account
126+
127+
#### PBS-Java Configuration
128+
129+
Here's a general template for the account config:
130+
131+
```yaml
132+
hooks:
133+
wurfl-devicedetection:
134+
enabled: true
135+
host-execution-plan: >
136+
{
137+
"endpoints": {
138+
"/openrtb2/auction": {
139+
"stages": {
140+
"entrypoint": {
141+
"groups": [
142+
{
143+
"timeout": 10,
144+
"hook-sequence": [
145+
{
146+
"module-code": "wurfl-devicedetection",
147+
"hook-impl-code": "wurfl-devicedetection-entrypoint-hook"
148+
}
149+
]
150+
}
151+
]
152+
},
153+
"raw-auction-request": {
154+
"groups": [
155+
{
156+
"timeout": 10,
157+
"hook-sequence": [
158+
{
159+
"module-code": "wurfl-devicedetection",
160+
"hook-impl-code": "wurfl-devicedetection-raw-auction-request"
161+
}
162+
]
163+
}
164+
]
165+
}
166+
}
167+
}
168+
}
169+
}
170+
modules:
171+
wurfl-devicedetection:
172+
file-dir-path: /path/to/wurfl_snapshot_dir
173+
file-snapshot-url: https://data.scientiamobile.com/<your_wurfl_snapshot_url>/wurfl.zip
174+
cache-size: 200000
175+
update-frequency-in-hours: 24
176+
allowed-publisher-ids: ["1", "3"]
177+
ext-caps: false
178+
```
179+
180+
#### PBS-Go Configuration
181+
182+
Here's the Go version in YAML format:
183+
184+
```yaml
185+
hooks:
186+
enabled: true
187+
modules:
188+
scientiamobile:
189+
wurfl_devicedetection:
190+
enabled: true
191+
wurfl_file_path: "/path/to/wurfl.zip"
192+
wurfl_snapshot_url: "<wurfl_snapshot_url>"
193+
wurfl_cache_size: 200000
194+
allowed_publisher_ids:
195+
- "1"
196+
- "3"
197+
ext_caps: true
198+
host_execution_plan:
199+
endpoints:
200+
/openrtb2/auction:
201+
stages:
202+
entrypoint:
203+
groups:
204+
- timeout: 10
205+
hook_sequence:
206+
- module_code: "scientiamobile.wurfl_devicedetection"
207+
hook_impl_code: "scientiamobile-wurfl_devicedetection-entrypoint-hook"
208+
raw_auction_request:
209+
groups:
210+
- timeout: 10
211+
hook_sequence:
212+
- module_code: "scientiamobile.wurfl_devicedetection"
213+
hook_impl_code: "scientiamobile-wurfl_devicedetection-raw-auction-request-hook"
214+
```
215+
216+
### Configuration Parameters
217+
218+
#### PBS-Java Parameters
219+
220+
{: .table .table-bordered .table-striped }
221+
222+
| Parameter | Required | Type | Default | Description |
223+
|-----------|----------|------|---------|-------------|
224+
| `file-dir-path` | Yes | string | - | Path to the directory where the WURFL file is downloaded. Directory must exist and be writable. |
225+
| `file-snapshot-url` | Yes | string | - | URL of the licensed WURFL snapshot file to be downloaded when PBS starts. |
226+
| `cache-size` | No | integer | WURFL default | Maximum number of devices stored in the WURFL cache. |
227+
| `ext-caps` | No | boolean | false | If `true`, adds all licensed capabilities to `device.ext`. |
228+
| `update-frequency-in-hours` | No | integer | 24 | Check interval (hours) for downloading updated WURFL file if modified. |
229+
| `allowed-publisher-ids` | No | array | All publishers | List of publisher IDs permitted to use the module. |
230+
231+
#### PBS-Go Parameters
232+
233+
{: .table .table-bordered .table-striped }
234+
235+
| Parameter | Required | Type | Default | Description |
236+
|-----------|----------|------|---------|-------------|
237+
| `wurfl_file_path` | Yes | string | - | Path to the WURFL file (e.g. /path/to/wurfl.zip). |
238+
| `wurfl_snapshot_url` | No | string | - | URL of the licensed WURFL snapshot. If set, periodically updates the WURFL file. |
239+
| `wurfl_cache_size` | No | integer | WURFL default | Maximum number of devices stored in the WURFL cache. |
240+
| `ext_caps` | No | boolean | false | If `true`, adds all licensed capabilities to `device.ext`. |
241+
| `allowed_publisher_ids` | No | array | All publishers | List of publisher IDs permitted to use the module. |
242+
243+
## Running Prebid Server
244+
245+
### PBS-Java
246+
247+
After configuring the module and successfully building the Prebid Server bundle:
248+
249+
```bash
250+
java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-with-wurfl.yaml
251+
```
252+
253+
When the server starts, it downloads the WURFL file from the `file-snapshot-url` and loads it into the module.
254+
255+
### PBS-Go
256+
257+
1. Download dependencies:
258+
259+
```bash
260+
go mod download
261+
```
262+
263+
2. Copy the WURFL file to the configured `wurfl_file_path` location
264+
265+
3. Start the server:
266+
267+
```bash
268+
go run -tags wurfl .
269+
```
270+
271+
When the server starts, it loads the WURFL file from `wurfl_file_path` into the module. To enable automatic updates, ensure that `wurfl_snapshot_url` is correctly configured.
272+
273+
#### Demo Mode (PBS-Go)
274+
275+
To test the WURFL module without an Infuze license:
276+
277+
```bash
278+
go run .
279+
```
280+
281+
## Sample Response
282+
283+
Using sample request data when the module is configured with `ext_caps` set to `false`:
284+
285+
```json
286+
"device": {
287+
"ua": "Mozilla/5.0 (Linux; Android 15; Pixel 9 Pro XL Build/AP3A.241005.015;) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36 EdgA/124.0.2478.64",
288+
"devicetype": 1,
289+
"make": "Google",
290+
"model": "Pixel 9 Pro XL",
291+
"os": "Android",
292+
"osv": "15",
293+
"h": 2992,
294+
"w": 1344,
295+
"ppi": 481,
296+
"pxratio": 2.55,
297+
"js": 1,
298+
"ext": {
299+
"wurfl": {
300+
"wurfl_id": "google_pixel_9_pro_xl_ver1_suban150"
301+
}
302+
}
303+
}
304+
```
305+
306+
When `ext_caps` is set to `true`, the response will include all licensed capabilities in `device.ext.wurfl`, such as:
307+
308+
* Device form factor information
309+
* Browser details
310+
* Hardware specifications
311+
* OS and app version details
312+
* Network capabilities
313+
* And many more device properties
314+
315+
## Analytics Tags
316+
317+
This module does not currently produce any analytics tags.
318+
319+
## Maintainer
320+
321+
For questions or support regarding the WURFL Device Detection module, please contact:
322+
[prebid@scientiamobile.com](mailto:prebid@scientiamobile.com)
323+
324+
## Further Reading
325+
326+
* [WURFL by ScientiaMobile](https://www.scientiamobile.com/)
327+
* [Prebid Server Module List](/prebid-server/pbs-modules/index.html)

0 commit comments

Comments
 (0)