From 38c8fa902c5b83904de2a8e18823f7c9914c3a55 Mon Sep 17 00:00:00 2001 From: Romain Lofaso Date: Mon, 8 Aug 2022 13:51:30 +0200 Subject: [PATCH] Add the OneKey Id sub-module and the OneKey RTD module User Id sub-module: https://github.com/prebid/Prebid.js/pull/8685 RTD module: https://github.com/prebid/Prebid.js/pull/8686 --- dev-docs/modules/oneKeyRtdProvider.md | 147 ++++++++++++++++++++++++++ dev-docs/modules/userId.md | 43 ++++++++ 2 files changed, 190 insertions(+) create mode 100644 dev-docs/modules/oneKeyRtdProvider.md diff --git a/dev-docs/modules/oneKeyRtdProvider.md b/dev-docs/modules/oneKeyRtdProvider.md new file mode 100644 index 0000000000..f26f5c6700 --- /dev/null +++ b/dev-docs/modules/oneKeyRtdProvider.md @@ -0,0 +1,147 @@ +--- +layout: page_v2 +title: OneKey RTD Module +display_name: OneKey RTD Module +description: OneKey Real Time Data Module +page_type: module +module_type: rtd +module_code : oneKeyRtdProvider +enable_download : false +vendor_specific: true +sidebarType : 1 +--- + +# OneKey Data Provider + +{:.no_toc} + +* TOC +{:toc} + +## Overview + +The OneKey real-time data module in Prebid has been built so that publishers +can quickly and easily setup the OneKey Addressability Framework. +This module is used along with the oneKeyIdSystem to pass OneKey data to your partners. +Both modules are required. This module will pass transmission requests to your partners +while the oneKeyIdSystem will pass the oneKeyData. + +Background information: +- [prebid/addressability-framework](https://github.com/prebid/addressability-framework) +- [prebid/paf-mvp-implementation](https://github.com/prebid/paf-mvp-implementation) + + +## Implementation for Publishers + +### Integration + +1) Compile the OneKey RTD Provider and the OneKey UserID sub-module into your Prebid build. + +{: .alert.alert-info :} +gulp build --modules=rtdModule,oneKeyRtdProvider + +2) Publishers must register OneKey RTD Provider as a Real Time Data provider by using `setConfig` +to load a Prebid Config containing a `realTimeData.dataProviders` array: + +```javascript +pbjs.setConfig({ + ..., + realTimeData: { + auctionDelay: 100, + dataProviders: [ + { + name: 'oneKey', + waitForIt: true + } + ] + } +}); +``` + +3) Configure the OneKey RTD Provider with the bidders that are part of the OneKey community. If there is no bidders specified, the RTD provider +will share OneKey data with all adapters. + +⚠️ This module works with a User Id sub-module. Both must be configured. See the [OneKey Id Sub-Module](/dev-docs/modules/userId.html#onekey-ids--preferences). + +### Parameters + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Always 'oneKey' | +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| params | Object | | Optional | +| params.bidders | Array | List of bidders to restrict the data to. | Optional | + +## Implementation for Bidders + +### Bidder Requests + +The data will provided to the bidders using the `ortb2` object. +The following is an example of the format of the data: + +```json +"user": { + "ext": { + "paf": { + "transmission": { + "seed": { + "version": "0.1", + "transaction_ids": ["06df6992-691c-4342-bbb0-66d2a005d5b1", "d2cd0aa7-8810-478c-bd15-fb5bfa8138b8"], + "publisher": "cmp.pafdemopublisher.com", + "source": { + "domain": "cmp.pafdemopublisher.com", + "timestamp": 1649712888, + "signature": "turzZlXh9IqD5Rjwh4vWR78pKLrVsmwQrGr6fgw8TPgQVJSC8K3HvkypTV7lm3UaCi+Zzjl+9sd7Hrv87gdI8w==" + } + } + } + } + } +} +``` + +```json +"ortb2Imp": { + "ext": { + "data": { + "paf": { + "transaction_id": "52d23fed-4f50-4c17-b07a-c458143e9d09" + } + } + } +} +``` + +### Bidder Responses + +Bidders who are part of the OneKey Addressability Framework and receive OneKey +transmissions are required to return transmission responses as outlined in +[prebid/addressability-framework](https://github.com/prebid/addressability-framework/blob/main/mvp-spec/ad-auction.md). Transmission responses should be appended to bids +along with the releveant content_id using the meta.paf field. The paf-lib will +be responsible for collecting all of the transmission responses. + +Below is an example of setting a transmission response: + +```javascript +bid.meta.paf = { + content_id: "90141190-26fe-497c-acee-4d2b649c2112", + transmission: { + version: "0.1", + contents: [ + { + transaction_id: "f55a401d-e8bb-4de1-a3d2-fa95619393e8", + content_id: "90141190-26fe-497c-acee-4d2b649c2112" + } + ], + status: "success", + details: "", + receiver: "dsp1.com", + source: { + domain: "dsp1.com", + timestamp: 1639589531, + signature: "d01c6e83f14b4f057c2a2a86d320e2454fc0c60df4645518d993b5f40019d24c" + }, + children: [] + } +} +``` diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 07d6c72733..e2099b2807 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -2337,6 +2337,49 @@ pbjs.setConfig({ }); {% endhighlight %} +### OneKey IDs & Preferences + +The OneKey real-time data module in Prebid has been built so that publishers +can quickly and easily setup the OneKey Addressability Framework. +This module is used along with the oneKeyRtdProvider to pass OneKey data to your partners. +Both modules are required. This module will pass oneKeyData to your partners +while the oneKeyRtdProvider will pass the transmission requests. + +Background information: +- [prebid/addressability-framework](https://github.com/prebid/addressability-framework) +- [prebid/paf-mvp-implementation](https://github.com/prebid/paf-mvp-implementation) + +It can be added to you Prebid.js package with: + +{: .alert.alert-info :} +gulp build –modules=userId,oneKeyIdSystem + +⚠️ This module works with a RTD module. Both must be configured. See the [OneKey RTD Module](/dev-docs/modules/oneKeyRtdProvider.html). + +#### OneKey Registration + +OneKey is a community based Framework with a decentralized approach. +Go to [onekey.community](https://onekey.community/) for more details. + +#### OneKey Configuration + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module | `"oneKeyData"` | + + +#### OneKey Exemple + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'oneKeyData' + }] + } +}); +{% endhighlight %} ## Adapters Supporting the User ID Sub-Modules