This page is for the integration of Prebid Server connections only. For Prebid.js please consult the Prebid.js Integration Guide.

Specification Support

Specification	Version	Last Update Date	Notes
Prebid Server	3.18.0 and above	02 Jul 2025	3.18.0 is the minimum Prebid Server Version that embeds the fwssp adapter
IAB Content Category Taxonomy	v1	02 Jul 2025	IAB Content Categories are mapped to FreeWheel Global Industries
OpenRTB Supply (ORTB-S)	Refer to OpenRTB Supply Integration Guide

Guide Change Log

Current Guide Version

Guide Version	Date	Author	Description
v1.2	13 Aug 2025	Admin	Made adjustments to language around ORTB to further provide context on ORTB-S Added information on Gzip compression support (section 3.1) New Parameters section renamed to fwssp Adapter Parameter Highlights More context and line items added to fwssp Adapter Parameter Highlights Added ORTB-S line item to Specification Support Section Expanded the Passing Contextual Information Section (Standard Attributes)
v1.3	21 Aug 2025	PSE	Corrected typo in the 1.1 Integration Diagram section.

Historic

Version	Date	Author	Description
v1.1	27 Jun 2025	Admin	Added Standard Attribute information 4. New Parameters
v1	24 Jun 2025	Admin	Initial Release

1. Introduction

Prebid Server is an advanced ad serving technology that facilitates server-side header bidding. 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. 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's fwssp adapter) to integrate demand sources, by translating bid requests and responses between different systems
OpenRTB Supply Integration Compatibility: Supports 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

With the sunsetting of SFX, any customers using an existing Prebid Server Integration will need to complete a new adapter integration in order to migrate to their new FW SSP network. This page outlines the integration steps for publishers to complete these steps.

1.1 Integration Diagram

Resources > Prebid Server Integration Guide > image-2025-8-22_11-14-45.png

1.2 Pre-Requisites

Before starting this integration, please ensure you have the following to start:

Existing connection to a Prebid Server provider using PBS-Go
- There are two implementation types of Prebid Server: PBS-Go and PBS-Java. Freewheel currently does not support PBS-Java.
Expected QPS volumes (daily max and average)
Estimated traffic per geo
Ensure ads.txt and app ads.txt are up to date
Must use the adapter released in Prebid Server version 3.18.0 or above
New endpoint url - see section below
Freewheel account team to provide:
- Profile ID
- Network ID
- Custom site section ID

2. How to add the new FW Prebid Server adapter

The new Freewheel adapter is named fwssp and can be found in the Prebid Github Repository.

This new Prebid adapter will work in parallel to the existing SFX adapters whilst the migration of clients is complete. Then the fwssp adapter is going to replace the SFX instances of freewheel-ssp and freewheelssp adapters in the future once SFX is deprecated. Note that the SFX adapters will be deprecated later in 2025 once all clients have migrated to their new networks. After this date, clients will no longer be able to use the SFX adapters.

3. Endpoint

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

https://prebid.v.fwmrm.net/ortb/ssp

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.

Depending on ad server setup you may have to just plug in the value itself in the UI

Path

fwssp Adapter Parameter

Type

Description

Example

Scope

bidrequest.imp.ext.prebid.bidder.fwssp

profile_id

string

A profile is used to determine and control what type/formats of ads can serve into a particular inventory type e.g creative specs. This is set up on the backend and the value to implement will be provided by your Freewheel account team

The expected format is the name of the profile as a string and not a numerical ID

"profile_id": "12345:profile__name"

Mandatory

network_id

string

The network ID is the ID of the customer account or instance, known as a 'network'. The value to implement will be provided by your Freewheel account team. The expected format is a numerical string.

Networks are similar concept to SFX Private Exchanges (PX).

"network_id": "12345"

custom_site_section_id

string

The site section (id) determines the exact piece of inventory where the ad request is coming from as designed in your network design. You may have one or many different site sections breaking out inventory depending on what network design was agreed upon with your Freewheel account team. The value to implement will be provided by your Freewheel account team. The expected format is either the tag or the numerical ID of the site section.

Site Sections are a similar to the concept of SFX Zones, however unlike zones, the ad unit is separated from the site section and the site section agnostic of what type of ad unit is being used.

"custom_site_section_id": "ss_12345"

or

"custom_site_section_id": "12345"

bidrequest.imp.video

maxseq

integer

Indicates the maximum number of ads that may be served into a dynamic video ad pod

"maxseq": 8

Optional (Mandatory if using dynamic ad podding)

poddur

integer

Indicates the total amount of time in seconds that advertisers may fill for a dynamic video ad pod

"poddur": 145

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.

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

For the most optimal monetization, clients should pass at a minimum Programmer, Brand, Channel and Genre. If these aren't passed, Freewheel may not be able to effectively monetize the supply.

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",
      "userrating": "4.6",
      "producer": {
        "name": "prorducer-name"
      },
      "network": {
        "name": "network-name"
      },
      "channel": {
        "name": "channel-name"
      }
    }
  },
  "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.2 Bidder 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": {
      "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",
      "userrating": "4.6",
      "producer": {
        "name": "prorducer-name"
      },
      "network": {
        "name": "network-name"
      },
      "channel": {
        "name": "channel-name"
      }
    }
  },
  "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": [{
    "bid": [{
      "id": "12345_fwssp-test_1",
      "impid": "imp-1",
      "price": 1,
      "adid": "7857",
      "adm": "<VAST version='2.0'></VAST>",
      "cid": "4001",
      "crid": "7857"
    }],
    "seat": "FreeWheel"
  }],
  "bidid": "fwssp-test",
  "cur": "USD"
}

9.1.4 Prebid Returned Response Sample

{
  "id": "fwssp-test",
  "seatbid": [{
    "bid": [{
      "id": "12345_fwssp-test_1",
      "impid": "imp-1",
      "price": 1,
      "adm": "<VAST version='2.0'></VAST>",
      "adid": "7857",
      "cid": "4001",
      "crid": "7857",
      "ext": {
        "origbidcpm": 1,
        "origbidcur": "USD",
        "prebid": {
          "meta": {
            "adaptercode": "fwssp"
          },
          "type": "video",
          "video": {
            "duration": 0,
            "primary_category": ""
          }
        }
      }
    }],
    "seat": "fwssp"
  }],
  "cur": "USD"
}

Specification Support

Guide Change Log

Current Guide Version

Historic

Table of Contents

1. Introduction

Key Features

1.1 Integration Diagram

1.2 Pre-Requisites

2. How to add the new FW Prebid Server adapter

3. Endpoint

3.1 Gzip Compression Support

4. Parameters

4.1 fwssp Adapter Parameter Highlights

4.2 ORTB Type Ad Request Body

4.3 OpenRTB Supply Integration (ORTB-S) Extended Features

5. Config Code

6. User Syncing/Cookie Syncing

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

8. Passing Contextual Information (Standard Attributes)

9. Troubleshooting Tips

9.1 Sample ad requests and responses

9.1.1 Prebid Received Request Sample

9.1.2 Bidder Received Request Sample

9.1.3 Bidder Returned Response Sample

9.1.4 Prebid Returned Response Sample