OneKey RTD Module: initial release

[RomainLofaso]

Type of change

• Feature

Description of change

This PR adds an RTD module for OneKey. The demo currently uses changes that are a superset of this PR.

Other information

It doesn't appear in history due to reworks, squashes, and splits of branches but a significant contribution has been done by @bwschmidt on those changes. The current proposal basically renames PAF to OneKey, uses Previd V7 API and uses asynchronous API on top of #8367

Pull Request for the documentation: prebid/prebid.github.io#3948

[Rothalack]

Hey @RomainLofaso, do you have any suggestions on how to test this? I was thinking about pulling in the OneKeyID PR as well to be able to run a build with both since they are dependent. Which is another consideration, we would want to make sure both of these PR's make it into the same release, right?

[patmmccann]

@Rothalack feel free to review the other pr as well if you want to coordinate the release, that is a great point, thanks!

[RomainLofaso]

Hey @RomainLofaso, do you have any suggestions on how to test this? I was thinking about pulling in the OneKeyID PR as well to be able to run a build with both since they are dependent. Which is another consideration, we would want to make sure both of these PR's make it into the same release, right?

Hey @Rothalack,

Thanks for those first questions. First, my team thinks we should introduce to you the OneKey project so that you get the big picture. i will reach you on Slack to see if it makes sense to you and to schedule a session.

Yes, it makes a lot of sense to merge those PR together: the enriched data of both modules are mandatory in the OneKey Ad Auction protocol.

For testing, it is better indeed to use both PR. This [branch|https://github.com/criteo-forks/pull/9] has already accumulated them. The simplest way to test it is to run the OneKey Demo. The demo uses the last version of the OneKey Lib and a prebid.js built on the branch shared above with Criteo Adapter that fully implemented OneKey and with OpenX that partially implemented it. Prebid.js is made with the following command:

gulp build --modules=userId,oneKeyIdSystem,rtdModule,oneKeyRtdProvider,criteoBidAdapter,openxOrtbBidAdapter

Here is a scenario that would help you to see that the modules work correctly:

1. Run the OneKey demo or use the version available online directly
2. Go to http://www.pafdemopublisher.com/ (A fake publisher)
3. A CMP prompt appears. Select "Turn on personalized marketing" and "Save". Under the hood, the publisher generates Ids and Preferences that will be shared later with the adapters via the OneKey Id submodule.
4. Reload the page with the browser inspector. It triggers bids with Prebid.js. The OneKey id submodule retrieves Ids and Preferences. The Onekey RTD module fetches an object called a Seed.
5. Check the Network section of your inspector and look for the Criteo CDB call (filter with "cdb"). In the Bid Request, data generated by the module are present (POST content). See the following annotated example.

Request (some fields and object has been removed to focus on what matter)

{
  "slots": [
    {
      "slotid": "ecdccc34975d4921af9c43f7899c1476",
      "impid": "div-1",
      "ext": {
        "data": {        <------------------ ADDED BY THE ONEKEY RTD MODULE. PAF IS THE TECHNICAL NAME FOR ONEKEY.
          "paf": {
            "transaction_id": "c573c901-4947-48a6-b485-66f85add6bdf" <------------------ GUID GENERATED BY THE RTD MODULE
          }
        }
      }
    },
    {
      "slotid": "43d9c415e5a7479dba8d00a4b8b3b7f8",
      "impid": "div-2",
      "ext": {
        "data": {
          "paf": {
            "transaction_id": "79055a76-92b6-4812-a391-cfcb66abf217"
          }
        }
      }
    }
  ],
  "user": {
    "ext": {
      "paf": {.  <--------------------- ADDED BY THE RTD MODULE
        "transmission": {
          "seed": {.  <------------------ A SEED IS AN OBJECT FETCHED BY THE RTD MODULE VIA THE ONEKEY API
            "version": "0.1",
            "transaction_ids": [
              "c573c901-4947-48a6-b485-66f85add6bdf",
              "79055a76-92b6-4812-a391-cfcb66abf217"
            ],
            "publisher": "cmp.pafdemopublisher.com",
            "source": {
              "domain": "cmp.pafdemopublisher.com",
              "timestamp": 1659082191,
              "signature": "ftK389Ws64KonSVuXH6ymXzFdKxPeq/+7Ic9Z1NomYVbYRkOVfmQHb+vP7Zo1MdKLJfKo7Pd2pRZr1KfGm6FnA=="
            }
          }
        }
      }
  }
  "eids": [
    {
      "source": "paf",
      "uids": [
        {    <---- ADDED BY THE ONEKEY SUB ID MODULE
          "id": "c1d8d735-6582-4215-bb21-af9b3e29a42a", 
          "atype": 1,
          "ext": {
            "version": "0.1",
            "type": "paf_browser_id", 
            "source": {
              "domain": "crto-poc-1.onekey.network",
              "timestamp": 1659081463,
              "signature": "L7roch6Smm/HpNgOZDgb1iJ4CZi58MjoSCpCklHS5DYi1iOV/AIRDBk9HcUda4U9kWWSaQEfoU+Fd/ohpL3WOA=="
            }
          }
        }
      ],
      "ext": {
        "preferences": {. <---- NOTE THAT PREFERENCES ARE LINKED TO THE ONEKEY ID.
          "version": "0.1",
          "data": {
            "use_browsing_for_personalization": true
          },
          "source": {
            "domain": "cmp.pafdemopublisher.com",
            "timestamp": 1659082184,
            "signature": "s+0CBatrw1+8HZzE5BFIhNcaZbS43kHYUsvHww/oYZbz0k1lkTpy33yNaAyUIqAzc3LSffpSY7j9KtmyoEsa0g=="
          }
        }
      }
    }
  ]
}

The response of the Criteo Bidder (some fields and object has been removed to focus on what matter):

{
    "slots": [
        {
            "impid": "div-1",
            "creative": "<iframe id='b1548829' ...></iframe>",
            "paf_extension": {
                "content_id": "cfeb061b-9268-47de-95cb-11fef5243cb4" <--- ADD FOR ONEKEY
            }
        },
        {
            "impid": "div-2",
            "creative": "<iframe ...></iframe>",
            "paf_extension": {
                "content_id": "e8de62e9-0b46-44d3-a88d-5081965e9baf" <--- ADD FOR ONEKEY
            }
        }
    ],
    "ext": {
        "paf": { <--- ADD FOR ONEKEY
            "transmission": {
                "version": "0.1",
                "receiver": "criteo.com",
                "contents": [
                    {
                        "content_id": "cfeb061b-9268-47de-95cb-11fef5243cb4",
                        "transaction_id": "c573c901-4947-48a6-b485-66f85add6bdf"
                    },
                    {
                        "content_id": "e8de62e9-0b46-44d3-a88d-5081965e9baf",
                        "transaction_id": "79055a76-92b6-4812-a391-cfcb66abf217"
                    }
                ],
                "status": "Success", <--- NOTE THE SUCCESS STATUS
                "details": "",
                "source": {
                    "timestamp": 1659082192,
                    "domain": "criteo.com",
                    "signature": "MEQCIH/C3PpazY/GP0gTsMGbm1CWPzZvJGFgx8glY065F0WoAiB/PmKqQSvHnMjky5JAavCya4U2iIhMbTY7eACKoA5Eqw=="
                },
                "children": []
            }
        }
    }
}

[patmmccann]

I don't believe these are stable locations, please link to the new locations or delete temporarily until the location is determined

[RomainLofaso]

Hi @patmmccann,

For now, there is no other location. As far as I know, nothing is planned for changing them. If later, those locations change, we will update this document accordingly.

Thanks

[patmmccann]

If you don't move the repo, i don't plan to merge, sorry but this is the result of the prebid board vote.

[RomainLofaso]

Ok, my team wasn't aware of this aspect of the vote. Following your feedback and some clarifications, @BasileLeparmentier has just done the necessary and moved the repositories to another workspace.

I have just updated the locations in this PR accordingly.

Thanks

[ChrisHuie]

@RomainLofaso I don't see any docs for this module or the other module in our docs repo (https://github.com/prebid/prebid.github.io). Can you please add?

[RomainLofaso]

Please see the pull request with the documentation updated: prebid/prebid.github.io#3948