Specification Support

Guide Change Log

Current Guide Version

Historic

Historic

...

Prebid Server is an advanced ad serving technology that facilitates server-side header bidding.  It It acts as a bridge between publishers and demand sources (DSPs, ad exchanges, or SSPs), enabling efficient ad auction processes by translating bid requests and responses into standardized formats.

Key Features

Our fwssp Prebid Server Adapter, adapts Prebid ORTB ad requests into OpenRTB Supply Integration ad requests and OpenRTB Supply Integration ad responses back to Prebid ORTB ad responses.

Key Features

• Adapter Integration: Prebid Server uses adapters (like FreeWheel'Adapter Integration: Prebid Server uses adapters (like FreeWheel's fwssp adapter) to integrate demand sources, which translate by translating bid requests and responses between different systems

• OpenRTB Supply Integration Compatibility: Supports OpenRTB protocol

• Media Type Support: Can handle various media types

1.1 Integration Diagram

• the OpenRTB Supply Integration API built to make it possible to deploy and maintain an effective OpenRTB supply integration with Freewheel to pass inventory to downstream demand sources to obtain incremental demand. Please refer to the OpenRTB Supply Integration Guide for more on specifications supported and other items.

• Media Type Support: Can handle various media types

1.1 Integration Diagram

Image AddedImage Removed

1.2 Pre-Requisites

...

...

3. Endpoint

The following dedicated endpoint is what will be used for Prebid Server traffic to Freewheel and is hardcoded into the fwssp Prebid  Prebid Server adapter config file:

4. New Parameters

With the release of the new adapters, there will be a need for certain parameters to change versus those used previously on SFX in order to meet the requisites of the new FW SSP platform. This is due to differences in architecture and concepts between the two platforms

3.1 Gzip Compression Support

The fwssp Prebid Server adapter can support gzip compression (declared via the endpointcompression attribute/kvp) and for more information on this please see section 4.6 in the OpenRTB Supply Integration Guide Gzip Compression support section. 

For documentation on how we declare this in our adapter please see: https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html#bidder-info

...

4. Parameters

4.1 fwssp Adapter Parameter Highlights

The following are highlights from the list of OpenRTB Supply Integration (ORTB-S) parameters relevant to the fwssp Prebid Server adapter. For a list of all ORTB-S parameters please refer to the OpenRTB Supply Integration Guide. 

profile_id

network_id

custom_site_section_id

...

This document includes details of the passing of Standard Attributes such as Brand, Channel, IAB Category, Genre, Content title, etc.

https://hub.freewheel.tv/display/MUG/Inventory+Standardization+from+OpenRTB-S

4.2 ORTB Type Ad Request Body

Please refer to section 5 of our OpenRTB Supply Integration Guide for the current list of supported ORTB fields. Note that there will often be new fields added to this section. 

4.3 OpenRTB Supply Integration (ORTB-S) Extended Features

For more on using ORTB-S extended features such as Multi-Bid, Multi-Imp (Structured Pods), and Dynamic Podding - please refer to section 1.2 in the OpenRTB Supply Integration Guide.

...

5. Config Code

If you need access to the adapter code, you can view it on the following Github repository.

...

6. User Syncing/Cookie Syncing

Starting from the 7.11 release on 8/25/2025, we'll have the ability to handle cookie syncing for Prebid Server clients, until then user/cookie sync will not be able to function via the fwssp Prebid Server adapter.
The code to manage this will be integrated into the adapter code including the sync pixel. Each Prebid Server instance will be able to retrieve the FW cookie ID via the sync pixel and use it to populate the user.buyerid in the outgoing ad request to Freewheel. This will then be used downstream to check if we have a cookie match with the DSPs as we send outgoing bid request. 

The expectation is the the upstream adserver will host the user match table in-between your cookie ID and the Freewheel cookie ID.

...

7. Schain/Sellers JSON/Ads.txt/app ads.txt

The populating of the Schain will be handled via the Prebid Server. Your Freewheel account representative will provide you with the required codes to enter in your ads.txt and ensure that your new publisher IDs are added into our sellers.JSON as an onboarding step. This schain object will be passed in the ext.schain object of the ORTB ad request - refer here to the ORTB-S Integration Guide section 5.10. If you are a Freewheel client and need more information on the ads.txt setup please refer to here.

...

8. Passing Contextual Information (Standard Attributes)

In order to successfully monetize your supply and align all relevant demand, we'll require clients to correctly pass contextual information around the supply also known as Standard Attributes. The page https://hub.freewheel.tv/display/MUG/Inventory+Standardization+from+OpenRTB-S details the fields required to pass the needed information for ORTB ad requests. This document includes details of the passing of Standard Attributes such as Brand, Channel, IAB Category, Genre, Content title, etc.

...

9. Troubleshooting Tips

Since integrations often break due to typos, errors in config, we highly recommend checking the format of your requests based on the samples below or the documentation housed on Github. Please also ensure that you use the correct adapter - fwssp and not another adapter. 

9.1 Sample ad requests and responses

Please refer to the below code blocks which pass the expected parameters as a guide and to sanity check the code

9.1.1 Prebid Received Request Sample

{
  "id": "fwssp-test",
  "imp": [{
    "id": "imp-1",
    "video": {
      "mimes": ["video/mp4"],
      "minduration": 5,
      "maxduration": 30,
      "startdelay": -1,
      "maxseq": 5,
      "poddur": 120,
      "w": 300,
      "h": 250,
      "minbitrate": 300,
      "maxbitrate": 1500
    },
    "secure": 1,
    "ext": {
      "prebid": {
        "bidder": {
          "fwssp": {
            "custom_site_section_id": "ss_12345",
            "network_id": "123456",
            "profile_id": "123456:prof_12345"
          }
        }
      }
    }
  }],
  "site": {
    "page": "https://prebid.org",
    "ext": {
      "amp": 0
    },
    "content": {
      "cat": ["IAB2"],
      "contentrating": "tv-14",
      "genre": "GV,Entertainment,Automotive,Talk Show",
      "keywords": "Entertainment",
      "language": "en",
      "len": 2700,
      "livestream": 1,
      "prodq": 1,
      "qagmediarating": 1,
      "series": "VOD",
      "title": "title-name"

5. Config Code

If you need access to the adapter code, you can view it on the following Github repository.

6. User Syncing/Cookie Syncing

Starting from the 7.11 release on 8/25/2025, we'll have the ability to handle cookie syncing for Prebid Server clients, until then user/cookie sync will not be able to function via the fwssp Prebid Server adapter. The code to manage this will be integrated into the adapter code including the sync pixel. Each Prebid Server instance will be able to retrieve the FW cookie ID via the sync pixel and use it to populate the user.buyerid in the outgoing ad request to Freewheel. This will then be used downstream to check if we have a cookie match with the DSPs as we send outgoing bid request. 

The expectation is the the upstream adserver will host the user match table in-between your cookie ID and the Freewheel Cooke ID.

7. Schain/Sellers JSON/Ads.txt/app ads.txt

The populating of the Schain will be handled via the Prebid Server. Your Freewheel account representative will provide you with the required codes to enter in your ads.txt and ensure that your new publisher IDs are added into our sellers.JSON as an onboarding step. This schain object will be passed in the ext.schain object of the ORTB ad request - refer here to the ORTB-S Integration Guide section 5.10. If you are a Freewheel client and need more information on the ads.txt setup please refer to here.

8. Passing Contextual Information 

In order to successfully monetize your supply and align all relevant demand, we'll require clients to correctly pass contextual information around the supply. The section below details the fields required to pass the needed information for ORTB ad requests: 

9. ORTB Type Ad Request Body

Please refer to section 5 of our OpenRTB Supply Integration Guide for the current list of supported ORTB fields. Note that there will often be new fields added to this section. 

10. Troubleshooting Tips

Since integrations often break due to typos, errors in config, we highly recommend checking the format of your requests based on the samples below or the documentation housed on Github. Please also ensure that you use the correct adapter - fwssp and not another adapter. 

10.1 Sample ad requests and responses

Please refer to the below code blocks which pass the expected parameters as a guide and to sanity check the code

10.1.1 Prebid Received Request Sample

{
  "id": "fwssp-test",
  "imp": [{
    "id": "imp-1",
    "video": {
      "mimes": ["video/mp4"],
      "mindurationuserrating": 5"4.6",
      "maxdurationproducer": 30,{
        "startdelayname": -1"prorducer-name"
      },
      "maxseqnetwork": 5,{
        "poddurname": 120,"network-name"
      "w": 300},
      "hchannel": 250,{
        "minbitratename": 300,"channel-name"
      "maxbitrate": 1500
}
    }
  },
  "device": {
    "secureua": 1,"curl/8.7.1"
  },
  "extat": {1,
      "prebidregs": {
        "biddercoppa": {0,
    "gdpr": 1,
     "fwsspgpp": {"DBABLA~BVQqAAAAAWA",
    "gpp_sid": [7],
       "custom_site_section_idus_privacy": "ss_12345"1---"
  },
  "user": {
    "ext": {
      "network_idconsent": "123456ABCDEF123456",
    }
  },
  "source": {
    "profile_idext": "123456:prof_12345"{
          }
"schain": {
         }"complete": 1,
      }
    }"nodes": [{
  }],
  "site": {
      "pageasi": "https://prebid.orglkqd.net",
          "exthp": {1,
          "ampsid": 0"1100053830"
    }
    }],
  "device": {
      "uaver": "curl/8.7.1"1.0"
      }
    }
  },
  "atext": 1,{
    "regskeywords": {
      "_fw_content_programmer_brand": "coppa"brand-name",
      "_fw_content_programmer_brand_channel": 0"channel-name",
    "gdpr  "_fw_content_genre": 1,
"comedy",
      "gpp_fw_content_category": "DBABLA~BVQqAAAAAWAcomedy",
    "gpp_sid  "_fw_content_rating": [7]"PG",
      "us_privacy_fw_content_language": "1---en"
    },
    "userprebid": {
      "extdebug": {true,
      "consentserver": "ABCDEF123456"{
    }
  },
  "source": {
    "extexternalurl": {
"http://localhost:8000",
        "schaingvlid": {0,
        "completedatacenter": 1,""
      }
    }
  }
}

9.1.2 Bidder Received Request Sample

{
  "id": "fwssp-test",
  "imp": [{"nodes": [{
          "asi": "lkqd.net",
          "hp": 1,
          "sid"id": "1100053830imp-1",
        }],"video": {
        "vermimes": "1.0"
      }["video/mp4"],
    }
  },
  "extminduration": {5,
      "keywordsmaxduration": {30,
      "_fw_content_programmer_brandstartdelay": "brand-name"1,
      "_fw_content_programmer_brand_channelmaxseq": "channel-name"5,
      "_fw_content_genrepoddur": "comedy"120,
      "_fw_content_categoryw": "comedy"300,
      "_fw_content_ratingh": "PG"250,
      "_fw_content_languageminbitrate": "en"300,
    },
    "prebidmaxbitrate": {1500
    },
    "debugsecure": true1,
      "serverext": {
        "externalurl"custom_site_section_id": "http://localhost:8000ss_12345",
        "gvlidnetwork_id": 0"123456",
        "datacenterprofile_id": "123456:prof_12345"
    }
  }],
    }"site": {
  }
}

10.1.2 Bidder Received Request Sample

{
  "idpage": "fwssp-testhttps://prebid.org",
    "impext": [{
      "idamp": "imp-1" 0
    },
    "videocontent": {
      "mimescat": ["video/mp4IAB2"],
      "minduration": 5"contentrating": "tv-14",
      "genre": "GV,Entertainment,Automotive,Talk Show",
      "maxdurationkeywords": 30"Entertainment",
      "startdelaylanguage": -1"en",
      "maxseqlen": 52700,
      "poddurlivestream": 1201,
      "wprodq": 3001,
      "hqagmediarating": 2501,
      "minbitrateseries": 300"VOD",
      "maxbitratetitle": 1500"title-name",
    },
    "secureuserrating": 1"4.6",
      "extproducer": {
      "custom_site_section_id": "ss_12345"  "name": "prorducer-name"
      },
      "network_id": "123456",{
        "profile_idname": "123456:prof_12345network-name"
    }
  }],
      "sitechannel": {
    "page": "https://prebid.org",
    "extname": {
  "channel-name"
    "amp": 0  }
    }
   },
  "device": {
    "ua": "curl/8.7.1"
  },
  "at": 1,
  "regs": {
    "coppa": 0,
    "gdpr": 1,
    "gpp": "DBABLA~BVQqAAAAAWA",
    "gpp_sid": [7],
    "us_privacy": "1---"
  },
  "user": {
    "ext": {
      "consent": "ABCDEF123456"
    }
  },
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "nodes": [{
          "asi": "lkqd.net",
          "hp": 1,
          "sid": "1100053830"
        }],
        "ver": "1.0"
      }
    }
  },
  "ext": {
    "keywords": {
      "_fw_content_programmer_brand": "brand-name",
      "_fw_content_programmer_brand_channel": "channel-name",
      "_fw_content_genre": "comedy",
      "_fw_content_category": "comedy",
      "_fw_content_rating": "PG",
      "_fw_content_language": "en"
    },
    "prebid": {
      "debug": true,
      "server": {
        "externalurl": "http://localhost:8000",
        "gvlid": 0,
        "datacenter": ""
      }
    }
  }
}

...

9.1.3 Bidder Returned Response Sample

{
  "id": "fwssp-test",
  "seatbid": [{
   "fwssp-test "bid": [{
      "id": "12345_fwssp-test_1",
      "impid": "imp-1",
  "seatbid": [
    {"price": 1,
      "bidadid": ["7857",
      "adm":  {
"<VAST version='2.0'></VAST>",
      "cid": "4001",
      "idcrid": "12345_fwssp-test_1"7857"
    }],
    "seat": "FreeWheel"
  }],
   "impidbidid": "impfwssp-1test",
          "pricecur": 1,"USD"
}

9.1.4 Prebid Returned Response Sample 

{
          "adid"id": "7857fwssp-test",
  "seatbid": [{
       "admbid": "<VAST version='2.0'></VAST>",
 [{
         "cidid": "400112345_fwssp-test_1",
          "cridimpid": "7857imp-1",
        }
      ]"price": 1,
      "seatadm": "FreeWheel"<VAST version='2.0'></VAST>",
    }
  ],
  "bididadid": "fwssp-test7857",
      "curcid": "USD"
}

10.1.4 Prebid Received Request Sample 

{
  "id4001",
      "crid": "fwssp-test7857",
      "seatbidext": [{
     {    "origbidcpm": 1,
        "bidorigbidcur": ["USD",
        "prebid": {
          "idmeta": "12345_fwssp-test_1",{
            "impidadaptercode": "imp-1fwssp",
          "price": 1  },
          "adidtype": "7857video",
          "admvideo": "<VAST version='2.0'></VAST>",
{
            "cidduration": "4001"0,
            "cridprimary_category": "7857"
          }
        ],}
      "seat": "FreeWheel"}
    }],
  ],
  "bididseat": "fwssp-test"
  }],
  "cur": "USD"
}