Prebid SDK rendering API protocol

[github-lucas-bon]

Hello,

I am part of a task force to implement a new feature on prebid mobile that we call Custom Plugin Renderers, as you can see here. So it requires us to send new fields in the bid request. Implementation/documentation for the prebid adapter is ongoing as well.

So this issue is to ask your validation regarding this change in the bid request json we are submitting in the prebid android sdk repo: prebid/prebid-mobile-android#648

We have these alternatives so far. Can we follow with any of them? Let me know WDYT, please.

1. *.ext.prebid.data.plugin_renderers

   "ext":{
      "prebid":{
         "storedrequest":{
            "id":"0689a263-318d-448b-a3d4-b02e8a709d9d"
         },
         "targeting":{ }
         "data": {
              "plugin_renderers":[
                 {
                    "name":"PrebidRenderer",
                    "version":"2.1.1"
                 },
                 {
                    "name":"SampleRenderer",
                    "version":"1.0.0"
                 }
              ]
         }
      }
   }

2. *.ext.data.plugin_renderers

   "ext":{
      "prebid":{
         "storedrequest":{
            "id":"0689a263-318d-448b-a3d4-b02e8a709d9d"
         },
         "targeting":{ }
      },
      "data": {
        "plugin_renderers":[
           {
              "name":"PrebidRenderer",
              "version":"2.1.1"
           },
           {
              "name":"SampleRenderer",
              "version":"1.0.0"
           }
        ]      
      }
   }

3. *.ext.plugin_renderers

   "ext":{
      "prebid":{
         "storedrequest":{
            "id":"0689a263-318d-448b-a3d4-b02e8a709d9d"
         },
         "targeting":{
            
         }
      },
      "plugin_renderers":[
         {
            "name":"PrebidRenderer",
            "version":"2.1.1"
         },
         {
            "name":"SampleRenderer",
            "version":"1.0.0"
         }
      ]
   }

[bretg]

Here's a proposal for how this could work at a protocol level:

1. the SDK places the available rendering APIs and versions in $.ext.prebid.sdk.renderers

ext.prebid.sdk.renderers: [
         {
            "name":"PrebidRenderer",
            "version":"2.1.1"
         },
         {
            "name":"SampleRenderer",
            "version":"1.0.0"
         }
      ]

2. If there's a requirement that certain rendering APIs are available only to certain bid adapters, the mobile committee can write a module that plugs into the bidder-request hook and does any necessary filtering.
3. Bid adapters can inspect the available rendering APIs and decide whether to bid or not.
4. If they bid and want to use a specific rendering API, they can set a new piece of metadata similar to NetworkID as described in https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html#metadata. e.g. .RendererName and .RendererVersion. These get passed back to the SDK in ORTB seatbid.bid.ext.prebid.meta.{renderingapiname,renderingapiversion}. (Our standard is all lowercase, no separators in ORTB extensions)
5. The SDK can use the fields in seatbid.bid.ext.prebid.meta to know how to render

Notes:

• Using seatbid.bid.ext.prebid.meta is better than setting hb_ targeting values because this doesn't need to go to the ad server.
• Having the protocol 'handshake' is helpful for two scenarios. First, if a bidder sees an auction that can't be rendered with a required API, they can skip the auction and save everyone the money. Second, if they see an older version of their API, they can be sure to bid with an appropriate creative.

[github-maxime-liege]

Thank you for the proposal !

For the point 4/5, we no longer use targeting object to passback the datas, we continue to use ext but currently not in a meta object in the current implementation of the adapter neither our AdServer.

We can do the modification in the corresponding object if you feel it mandatory tho, we will anyway change the naming for plugin_renderers to comply with OpenRTB.

[bretg]

@github-maxime-liege - my understanding is that this proposal is still under discussion.

It's generally a good idea to give these things a little time. I'll bring it up in the next Prebid Server committee meeting, which is in a week.

[github-maxime-liege]

@github-maxime-liege - my understanding is that this proposal is still under discussion.

It's generally a good idea to give these things a little time. I'll bring it up in the next Prebid Server committee meeting, which is in a week.

No worries, i can wait on this side, we have a default configuration, but we are flexible according to your decision

[bretg]

discussed in committee. @SyntaxNode offered to do a review of the proposal here.

[github-lucas-bon]

Okay @SyntaxNode, let us know if you have what you need in order to review it.
Thanks.

[SyntaxNode]

The proposal from @bretg looks good. I would like to add stronger symmetry between the request parameters and response meta. If we use $.ext.prebid.sdk.renderers on the request please consider using RendererName and RendererVersion for response meta.

[bretg]

Ok, proposal updated. Thanks @SyntaxNode

[github-maxime-liege]

Thank you for the update, will follow this proposal then !

[github-lucas-bon]

Thanks, this pull request will be updated accordingly
prebid/prebid-mobile-android#648

[github-lucas-bon]

The proposal from @bretg looks good. I would like to add stronger symmetry between the request parameters and response meta. If we use $.ext.prebid.sdk.renderers on the request please consider using RendererName and RendererVersion for response meta.

@SyntaxNode could you clarify more what you expect us to change on the bid response?

The current state was

...
"ext": {
            "prebid": {
              "type": "video",
              "targeting": {
                "hb_pb": "0.10",
                "hb_env": "mobile-app",
                "hb_size_prebid": "300x250",
                "hb_pb_prebid": "0.10",
                "hb_bidder_prebid": "prebid",
                "hb_size": "300x250",
                "hb_bidder": "prebid",
                "hb_env_prebid": "mobile-app"
              },
              "meta": {
                "renderer_name": "SamplePluginRenderer",       
                "renderer_version": "1.0.0"       
              }
            },
            ...

But are you suggesting something like this?

...
"ext": {
            "prebid": {
              "type": "video",
              "targeting": {
                "hb_pb": "0.10",
                "hb_env": "mobile-app",
                "hb_size_prebid": "300x250",
                "hb_pb_prebid": "0.10",
                "hb_bidder_prebid": "prebid",
                "hb_size": "300x250",
                "hb_bidder": "prebid",
                "hb_env_prebid": "mobile-app"
              },
              "meta": {
                "renderer": {
                  "name": "SamplePluginRenderer",
                  "version": "2.1.1"
                }
            }
         },
         ...

Let me know, thanks!

[bretg]

Right - @github-lucas-bon - you don't care about how it's represented in the Go code. In the ORTB, our standard is lower case with no separators:

...
     "ext": {
            "prebid": {
              "type": "video",
              "targeting": {
                "hb_pb": "0.10",
                "hb_env": "mobile-app",
                "hb_size_prebid": "300x250",
                "hb_pb_prebid": "0.10",
                "hb_bidder_prebid": "prebid",
                "hb_size": "300x250",
                "hb_bidder": "prebid",
                "hb_env_prebid": "mobile-app"
              },
              "meta": {
                "rendererName": "SamplePluginRenderer",       
                "rendererVersion": "1.0.0"       
              }
            },
            ...

[bretg]

@github-lucas-bon - note - changed the case of the meta fields after discussion in committee

[bretg]

Here's the summary of the PBS work:

1. Extend the ORTB request to support passing ext.prebid.sdk.renderers to adapters
2. Extend the ORTB response to support seatbid.bid.ext.prebid.meta.{rendererName, rendererVersion}
3. Support 2 new meta fields that can be set by bid adapters: .RendererName, .RendererVersion
4. Documentation

Flipping to ready-for-dev.

[github-lucas-bon]

Hello @bretg as the pull request is now updated with the output we had here, our stored response prebid-stored-request-custom-rendering-test should be updated accordingly to comply with the new fields below.

Is here the right place to request it?

*.bid.seatbid.ext.prebid.
                          "meta":{
                            "renderername":"SampleCustomRenderer",
                            "rendererversion":"1.0"      
                          }

[bretg]

@github-lucas-bon - where is your stored response? Is that in Prebid's test PBS? I guess wherever it is, you would the body of the stored response to something like

[
    {
        "bid": [
            {
                "ext": {
                    "prebid": {
                        "meta": {
                            "rendererName":"SampleCustomRenderer",
                            "rendererVersion":"1.0"      
                         }
                    }
                },
                "h": 50,
                "w": 320,
                "id": "f227a07f-1579-4465-bc5e-5c5b02a0c180",
                "adm": "<img src=\"https://files.prebid.org/creatives/prebid320x50.png\">",
                "ext": 
                {
                    "prebid": 
                    {
                        "type": "banner"
                    }
                },
                "crid": "11111",
                "impid": "a",
                "price": 1
            }
        ],
        "seat": "rubicon",
        "group": 0
    }
]

[SyntaxNode]

Please use rendererName and rendererVersion casing, this matches the naming pattern used by the meta object.

[bretg]

fixed

[github-lucas-bon]

Okay, keys from meta were updated in the pull request to camel case.
Regarding where is the stored response I'm checking with Yuri since he help me with that.

[YuriyVelichkoPI]

Hi @bretg ! In the draft implementation of this feature, we used the stored request to add the targeting keyword to (any) response.

... 
"ext": {
    "prebid": {
      "adservertargeting": [
        {
          "key": "plugin_renderer_key",
          "source": "static",
          "value": "SampleCustomRenderer"
        }
      ]
    }
  }
...

Now we should add the meta object to the responses.

Can we utilize the stored request for this purpose as well, or should we add the meta directly into each stored response that we need for tests?

[bretg]

@YuriyVelichkoPI - you can add the meta fields to the stored responses.

[bretg]

fair warning that the PBS teams are backed up right now with privacy efforts, so it may take a while for the central teams to get to this. community input would be welcomed.

1. Extend the ORTB request to support passing ext.prebid.sdk.renderers to adapters
2. Extend the ORTB response to support seatbid.bid.ext.prebid.meta.{rendererName, rendererVersion}
3. Support 2 new meta fields that can be set by bid adapters: .RendererName, .RendererVersion
4. Documentation

[SyntaxNode]

Implemented in PBS-Go 0.267.0.

[github-maxime-liege]

Hey everyone,

I noticed that you remove the field token, is this an unwanted feature ?
Because we may see a utility in our case for this field, it could also be useful for other providers

Thanks a lot again for you support !

[bretg]

@github-maxime-liege - that word didn't appear in this issue until you mentioned it. But I looked over in the android repo issue and see it there. Is it a request field only? i.e. does token exist in the response?

[github-maxime-liege]

It could be existing on the response yes

[bretg]

@github-maxime-liege - what is a token? Are there any concerns about where this value gets sent?

[github-maxime-liege]

it is a simple string value that could be filled by the custom renderer with any data that it wants, we could rename it to data or something, the initial proposal was token

[SyntaxNode]

@github-maxime-liege Thank you for the explanation. I like your suggestion to rename to data, as the token name can imply a security or authorization context which doesn't make much sense here.

I've edited the most recent comment from to @bretg to rename token to data.

[SyntaxNode]

Effects of this change:

fair warning that the PBS teams are backed up right now with privacy efforts, so it may take a while for the central teams to get to this. community input would be welcomed.

1. Extend the ORTB request to support passing ext.prebid.sdk.renderers.data to adapters.
2. Extend the ORTB response to support seatbid.bid.ext.prebid.meta.rendererData.
3. Support 1 new meta fields that can be set by bid adapters: .RendererData

[github-maxime-liege]

Thank you for your answer @SyntaxNode, i'll try to get into this to do the corresponding change.

Thanks again

[github-maxime-liege]

Looks like i don't have rights to push a new branch on this repository

[SyntaxNode]

Looks like i don't have rights to push a new branch on this repository

You're contribution would certainly be welcomed. Most of us fork this repository, create a branch on our fork, and open a pull request from there. Please message me on Prebid Slack if you prefer otherwise.

[github-lucas-bon]

Everything is done here, thanks everybody

[bretg]

Not done on PBS-Java. #8 on Magnite's list.

[bretg]

resolved with PBS-Java 2.2