Skip to content
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

Jump to bottom

WURFL Rtd Provider: add integration notes #5662

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

WURFL Rtd Provider: add integration notes #5662

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be3a901
WURFL Rtd Provider: add integration notes
lucor Oct 18, 2024
181d062
WURFL Rtd Provider: parameters section - update wording
lucor Oct 18, 2024
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
48 changes: 31 additions & 17 deletions dev-docs/modules/wurflRtdProvider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,28 +22,42 @@ This module loads a dynamically generated JavaScript from prebid.wurflcloud.com

## Description

The WURFL RTD module enriches the OpenRTB 2.0 device data with [WURFL data](https://www.scientiamobile.com/wurfl-js-business-edition-at-the-intersection-of-javascript-and-enterprise/).
The module sets the WURFL data in `device.ext.wurfl` and all the bidder adapters will always receive the low entry capabilites like `is_mobile`, `complete_device_name` and `form_factor`.
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.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`.

For a more detailed analysis bidders can subscribe to detect iPhone and iPad models and receive additional [WURFL device capabilities](https://www.scientiamobile.com/capabilities/?products%5B%5D=wurfl-js).
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.

## User-Agent Client Hints
## A Note About User-Agent Client Hints

WURFL.js is fully compatible with Chromium's User-Agent Client Hints (UA-CH) initiative. If User-Agent Client Hints are absent in the HTTP headers that WURFL.js receives, the service will automatically fall back to using the User-Agent Client Hints' JS API to fetch [high entropy client hint values](https://wicg.github.io/ua-client-hints/#getHighEntropyValues) from the client device. However, we recommend that you explicitly opt-in/advertise support for User-Agent Client Hints on your website and delegate them to the WURFL.js service for the fastest detection experience. Our documentation regarding implementing User-Agent Client Hint support [is available here](https://docs.scientiamobile.com/guides/implementing-useragent-clienthints).
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.

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).

## Integration Notes

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.

The following scenarios are possible:

{: .table .table-bordered .table-striped }
| | 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.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.ext.wurfl` data and pass it to the endpoint. | Update end-point to read and utilize the data. |

## Usage

### Build

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

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

### Configuration

Use `setConfig` to instruct Prebid.js to initilize the WURFL RTD module, as specified below.

This module is configured as part of the `realTimeData.dataProviders`
To initialize the WURFL RTD module in Prebid.js, use the `setConfig` function as shown below. The module is configured as part of `realTimeData.dataProviders`

```javascript
var TIMEOUT = 1000;
Expand All @@ -64,20 +78,20 @@ pbjs.setConfig({
### Parameters

{: .table .table-bordered .table-striped }
| Name | Type | Description | Default |
| :------------------------ | :------------ | :--------------------------------------------------------------- |:----------------- |
| name | String | Real time data module name | Always 'wurfl' |
| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` |
| params | Object | | |
| params.altHost | String | Alternate host to connect to WURFL.js | |
| params.debug | Boolean | Enable debug | `false` |
| 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 (optional) | `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` |

## Testing

To view an example of how the WURFL RTD module works :
To test how the WURFL RTD module works, run the following command:

`gulp serve --modules=wurflRtdProvider,appnexusBidAdapter`

and then point your browser at:
Then, point your browser to:

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