Skip to content

Commit b5d5380

Browse files
andreacastelloandreacastello
authored
New module: WURFL device enrichment (#3685)
1 parent 694b096 commit b5d5380

26 files changed

Lines changed: 2583 additions & 0 deletions

‎extra/bundle/pom.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,11 @@
6060
<artifactId>optable-targeting</artifactId>
6161
<version>${project.version}</version>
6262
</dependency>
63+
<dependency>
64+
<groupId>org.prebid.server.hooks.modules</groupId>
65+
<artifactId>wurfl-devicedetection</artifactId>
66+
<version>${project.version}</version>
67+
</dependency>
6368
</dependencies>
6469

6570
<build>

‎extra/modules/pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
<module>greenbids-real-time-data</module>
2626
<module>pb-request-correction</module>
2727
<module>optable-targeting</module>
28+
<module>wurfl-devicedetection</module>
2829
</modules>
2930

3031
<dependencyManagement>

‎extra/modules/wurfl-devicedetection/README.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
## WURFL Device Enrichment Module
2+
3+
### Overview
4+
5+
The **WURFL Device Enrichment Module** for Prebid Server enhances the OpenRTB 2.x payload
6+
with comprehensive device detection data powered by **ScientiaMobile**’s WURFL device detection framework.
7+
Thanks to WURFL's device knowledge, the module provides accurate and comprehensive device-related information,
8+
enabling bidders to make better-informed targeting and optimization decisions.
9+
10+
### Key features
11+
12+
#### Device Field Enrichment:
13+
14+
The WURFL module populates missing or empty fields in ortb2.device with the following data:
15+
- **make**: Manufacturer of the device (e.g., "Apple", "Samsung").
16+
- **model**: Device model (e.g., "iPhone 14", "Galaxy S22").
17+
- **os**: Operating system (e.g., "iOS", "Android").
18+
- **osv**: Operating system version (e.g., "16.0", "12.0").
19+
- **h**: Screen height in pixels.
20+
- **w**: Screen width in pixels.
21+
- **ppi**: Screen pixels per inch (PPI).
22+
- **pxratio**: Screen pixel density ratio.
23+
- **devicetype**: Device type (e.g., mobile, tablet, desktop).
24+
- **js**: Support for JavaScript, where 0 = no, 1 = yes
25+
- **Note**: If these fields are already populated in the bid request, the module will not overwrite them.
26+
27+
#### Publisher-Specific Enrichment:
28+
29+
Device enrichment is selectively enabled for publishers based on their account ID.
30+
The module identifies publishers through the following fields:
31+
32+
`site.publisher.id` (for web environments).
33+
`app.publisher.id` (for mobile app environments).
34+
`dooh.publisher.id` (for digital out-of-home environments).
35+
36+
37+
### Building WURFL Module with a licensed WURFL Onsite Java API
38+
39+
In order to compile the WURFL module in the PBS Java server bundle using a licensed WURFL API, you must follow these steps:
40+
41+
1 - Change the URL in the `<repository>` tag in the module's `pom.xml` file to the ScientiaMobile Maven repository URL:
42+
43+
`https://maven.scientiamobile.com/repository/wurfl-onsite/`
44+
45+
The repository is private and requires authentication: to set it up please check the paragraph
46+
"Configuring your Builds to work with ScientiaMobile's Private Maven Repository"
47+
[on this page](https://docs.scientiamobile.com/documentation/onsite/onsite-java-api).
48+
49+
2 - Change the `artfactId` value in the module's `pom.xml` from `wurfl-mock` to `wurfl`
50+
51+
3 - Update the `wurfl.version` property value to the latest WURFL Onsite Java API version available.
52+
53+
54+
When the `pom.xml` references the mock API artifact, the module will compile a demo version that returns sample data,
55+
allowing basic testing without an WURFL Onsite Java API license.
56+
57+
4 - Build the Prebid Server Java bundle with the WURFL module using the following command:
58+
59+
```bash
60+
mvn clean package --file extra/pom.xml
61+
```
62+
63+
### Configuring the WURFL Module
64+
65+
Below is a sample configuration for the WURFL module:
66+
67+
```yaml
68+
hooks:
69+
wurfl-devicedetection:
70+
enabled: true
71+
host-execution-plan: >
72+
{
73+
"endpoints": {
74+
"/openrtb2/auction": {
75+
"stages": {
76+
"entrypoint": {
77+
"groups": [
78+
{
79+
"timeout": 10,
80+
"hook_sequence": [
81+
{
82+
"module_code": "wurfl-devicedetection",
83+
"hook_impl_code": "wurfl-devicedetection-entrypoint-hook"
84+
}
85+
]
86+
}
87+
]
88+
},
89+
"raw_auction_request": {
90+
"groups": [
91+
{
92+
"timeout": 10,
93+
"hook_sequence": [
94+
{
95+
"module_code": "wurfl-devicedetection",
96+
"hook_impl_code": "wurfl-devicedetection-raw-auction-request"
97+
}
98+
]
99+
}
100+
]
101+
}
102+
}
103+
}
104+
}
105+
}
106+
modules:
107+
wurfl-devicedetection:
108+
file-dir-path: </path/to/wurfl_snapshot_dir>
109+
file-snapshot-url: https://data.scientiamobile.com/<your_wurfl_snapshot_url>/wurfl.zip
110+
cache-size: 200000
111+
update-frequency-in-hours: 24
112+
allowed-publisher-ids: 1
113+
ext-caps: false
114+
```
115+
116+
### Configuration Options
117+
118+
| Parameter | Requirement | Description |
119+
|---------------------------------|-------------|---------------------------------------------------------------------------------------------------|
120+
| **`file-dir-path`** | Mandatory | Path to the directory where the WURFL file is downloaded. Directory must exist and be writable. |
121+
| **`file-snapshot-url`** | Mandatory | URL of the licensed WURFL snapshot file to be downloaded when Prebid Server Java starts. |
122+
| **`cache-size`** | Optional | Maximum number of devices stored in the WURFL cache. Defaults to the WURFL cache's standard size. |
123+
| **`ext-caps`** | Optional | If `true`, the module adds all licensed capabilities to the `device.ext` object. |
124+
| **`update-frequency-in-hours`** | Optional | Check interval (hours) for downloading updated wurfl file if modified. Defaults to 24 hours |
125+
| **`allowed-publisher-ids`** | Optional | List of publisher IDs permitted to use the module. Defaults to all publishers. |
126+
127+
128+
A valid WURFL license must include all the required capabilities for device enrichment.
129+
130+
### Launching Prebid Server Java with the WURFL Module
131+
132+
After configuring the module and successfully building the Prebid Server bundle, start the server with the following command:
133+
134+
```bash
135+
java -jar target/prebid-server-bundle.jar --spring.config.additional-location=sample/configs/prebid-config-with-wurfl.yaml
136+
```
137+
138+
This sample configuration contains the module hook basic configuration.
139+
140+
When the server starts, it downloads the WURFL file from the `wurfl-snapshot-url` and loads it into the module.
141+
142+
Sample request data for testing is available in the module's `sample` directory. Using the `auction` endpoint,
143+
you can observe WURFL-enriched device data in the response.
144+
145+
### Sample Response
146+
147+
Using the sample request data via `curl` when the module is configured with `ext-caps` set to `false` (or no value)
148+
149+
```bash
150+
curl http://localhost:8080/openrtb2/auction --data @extra/modules/wurfl-devicedetection/sample/request_data.json
151+
```
152+
153+
the device object in the response will include WURFL device detection data:
154+
155+
```json
156+
"device": {
157+
"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",
158+
"devicetype": 1,
159+
"make": "Google",
160+
"model": "Pixel 9 Pro XL",
161+
"os": "Android",
162+
"osv": "15",
163+
"h": 2992,
164+
"w": 1344,
165+
"ppi": 481,
166+
"pxratio": 2.55,
167+
"js": 1,
168+
"ext": {
169+
"wurfl": {
170+
"wurfl_id": "google_pixel_9_pro_xl_ver1_suban150"
171+
}
172+
}
173+
}
174+
```
175+
176+
When `ext_caps` is set to `true`, the response will include all licensed capabilities:
177+
178+
```json
179+
"device":{
180+
"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",
181+
"devicetype":1,
182+
"make":"Google",
183+
"model":"Pixel 9 Pro XL",
184+
"os":"Android",
185+
"osv":"15",
186+
"h":2992,
187+
"w":1344,
188+
"ppi":481,
189+
"pxratio":2.55,
190+
"js":1,
191+
"ext":{
192+
"wurfl":{
193+
"wurfl_id":"google_pixel_9_pro_xl_ver1_suban150",
194+
"mobile_browser_version":"",
195+
"resolution_height":"2992",
196+
"resolution_width":"1344",
197+
"is_wireless_device":"true",
198+
"is_tablet":"false",
199+
"physical_form_factor":"phone_phablet",
200+
"ajax_support_javascript":"true",
201+
"preferred_markup":"html_web_4_0",
202+
"brand_name":"Google",
203+
"can_assign_phone_number":"true",
204+
"xhtml_support_level":"4",
205+
"ux_full_desktop":"false",
206+
"device_os":"Android",
207+
"physical_screen_width":"71",
208+
"is_connected_tv":"false",
209+
"is_smarttv":"false",
210+
"physical_screen_height":"158",
211+
"model_name":"Pixel 9 Pro XL",
212+
"is_ott":"false",
213+
"density_class":"2.55",
214+
"marketing_name":"",
215+
"device_os_version":"15.0",
216+
"mobile_browser":"Chrome Mobile",
217+
"pointing_method":"touchscreen",
218+
"is_app_webview":"false",
219+
"advertised_app_name":"Edge Browser",
220+
"is_smartphone":"true",
221+
"is_robot":"false",
222+
"advertised_device_os":"Android",
223+
"is_largescreen":"true",
224+
"is_android":"true",
225+
"is_xhtmlmp_preferred":"false",
226+
"device_name":"Google Pixel 9 Pro XL",
227+
"is_ios":"false",
228+
"is_touchscreen":"true",
229+
"is_wml_preferred":"false",
230+
"is_app":"false",
231+
"is_mobile":"true",
232+
"is_phone":"true",
233+
"is_full_desktop":"false",
234+
"is_generic":"false",
235+
"advertised_browser":"Edge",
236+
"complete_device_name":"Google Pixel 9 Pro XL",
237+
"advertised_browser_version":"124.0.2478.64",
238+
"is_html_preferred":"true",
239+
"is_windows_phone":"false",
240+
"pixel_density":"481",
241+
"form_factor":"Smartphone",
242+
"advertised_device_os_version":"15"
243+
}
244+
}
245+
}
246+
```
247+
248+
## Maintainer
249+
250+
prebid@scientiamobile.com

‎extra/modules/wurfl-devicedetection/pom.xml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.prebid.server.hooks.modules</groupId>
7+
<artifactId>all-modules</artifactId>
8+
<version>3.30.0-SNAPSHOT</version>
9+
</parent>
10+
11+
<artifactId>wurfl-devicedetection</artifactId>
12+
13+
<name>wurfl-devicedetection</name>
14+
<description>WURFL device detection and data enrichment module</description>
15+
16+
<properties>
17+
<wurfl.version>1.0.0.0</wurfl.version>
18+
</properties>
19+
20+
<repositories>
21+
<repository>
22+
<id>com.scientiamobile.wurfl</id>
23+
<url>https://maven.scientiamobile.com/repository/wurfl-onsite-tools/</url>
24+
</repository>
25+
</repositories>
26+
27+
<dependencies>
28+
<dependency>
29+
<groupId>com.scientiamobile.wurfl</groupId>
30+
<artifactId>wurfl-mock</artifactId>
31+
<version>${wurfl.version}</version>
32+
</dependency>
33+
</dependencies>
34+
</project>

0 commit comments

Comments
 (0)