New module: WURFL device enrichment

[andreacastello]

🔧 Type of changes

• new bid adapter
• bid adapter update
• new feature
• new analytics adapter
• new module
• module update
• bugfix
• documentation
• configuration
• dependency update
• tech debt (test coverage, refactorings, etc.)

✨ What's the context?

The module populates missing or empty fields in ortb2.device with WURFL device detection data

🧠 Rationale behind the change

The WURFL module populates missing or empty fields in ortb2.device with the following data:

• make: Manufacturer of the device (e.g., "Apple", "Samsung").
• model: Device model (e.g., "iPhone 14", "Galaxy S22").
• os: Operating system (e.g., "iOS", "Android").
• osv: Operating system version (e.g., "16.0", "12.0").
• h: Screen height in pixels.
• w: Screen width in pixels.
• ppi: Screen pixels per inch (PPI).
• pxratio: Screen pixel density ratio.
• devicetype: Device type (e.g., mobile, tablet, desktop).
• js: Support for JavaScript, where 0 = no, 1 = yes

Note: If these fields are already populated in the bid request, the module will not overwrite them.

Publisher-Specific Enrichment

Device enrichment is selectively enabled for publishers based on their account ID. The module identifies publishers through the following fields:

site.publisher.id (for web environments).
app.publisher.id (for mobile app environments).
dooh.publisher.id (for digital out-of-home environments).

For more info about the module build and configuration, please refer to the README.md under extra/modules/WURFL-devicedetection

🏎 Quality check

• Are your changes following our code style guidelines?
• Are there any breaking changes in your code?
• Does your test coverage exceed 90%?
• Are there any erroneous console logs, debuggers or leftover code in your changes?

Licensing Requirement for the WURFL Device Enrichment Module
To use the WURFL Device Enrichment Module for Prebid Server, you must have a valid license for the ScientiaMobile WURFL OnSite Java API. This API is a core dependency of the module and is responsible for performing device detection and enrichment operations by leveraging ScientiaMobile's comprehensive WURFL device database.
You can obtain the required license from ScientiaMobile’s official product page: WURFL OnSite API for Java

If the WURFL API dependency is not added, the module will compile a demo version that returns sample data, allowing basic testing without an WURFL Onsite Java API license. In this case the module code calls an internal mock of the WURFL Java API

Maintainer contact

[email protected]

[Net-burst]

Hello, @andreacastello . We discussed this PR in the PBS committee meeting and this the summary:

• we can't merge the code which is not proven to be building and working;
• we can't merge the code, that won't be an active part of a build/test lifecycle and can unpredictably and silently break as a result;

To unblock this PR, you will need to have a way to make this code compilable and unit testable. I see several possible options:

• make a substitute "mock" library that will expose all of the API in the same packages so that the code can be built and unit tested; (I personally don't like this approach, but it was voiced in the PBS committee meeting)
• split the library into a public and private counterpart so that all of the public API is exposed through the public library, but unless the private library is in the classpath, that API will just noop; (I find this approach much better and much more maintainable)
• in any case, you will also need to provide documentation for the end users about public PBS builds not having this module in working state (or even it being omitted from bundle entirely), how to abb/substitute the private library to the project and how to build the project with this module included.

Until this is done, we'll be leaving this project in do-not-merge state. Feel free to convert thus PR to draft for now.

@bretg @osulzhenko @AntoxaAntoxic @CTMBNara FYI

[Net-burst]

PBS-Go PR for reference: prebid/prebid-server#4158

[andreacastello]

Hello @Net-burst I've updated the PR so that the module can compile, run the module's unit tests and execute when there's not a dependency to the licensed WURFL Java API. In this case the module calls an internal API mock (packages com.scientiamobile.*) that provides sample data to the enrichment module.
This should make it compliant with your CI usage.

I've also modified the module REAME to explain how to switch from this demo version to a licensed WURFL API usage.

[Net-burst]

Thanks, @andreacastello! We'll take a look as soon as we have free cycles.

[Net-burst]

@andreacastello could you please move this code bundle into a publicly available library so that the end users will only need to change pom.xml dependency without the need to go into the code and risk breaking the project?

You can call that stub library wurlf-demo and add it as a pom.xml dependency. Then instruct users of the full version to just change the dependency from wurfl-demo to wurfl.

If you don't have a Maven repo set up, you can push it into Maven Central or use a GitHub Packages.