---
title: "FreeWheel SSP Prebid Server Integration Guide"
canonical: "https://hub.freewheel.tv/space/RCS/114787014/FreeWheel%20SSP%20Prebid%20Server%20Integration%20Guide"
format: markdown
---
> ℹ️ This page is specifically written for FW SSP prebid customers integrating via a Server connection and should not be used for Streaming Hub customers.

> ℹ️ **For Prebid.JS**
> ℹ️ 
> ℹ️ This page is for the integration of Prebid Server connections only. For Prebid.js please consult the [Prebid.js Integration Guide](https://freewheel-knowledge-hub.atlassian.net/wiki/spaces/RCS/pages/115605528).

# **Specification Support**

| **Specification** | **Version** | **Last Update Date** | **Notes** |
| --- | --- | --- | --- |
| <span style="color: #000000">Prebid Server</span> | <span style="color: #000000">3.18.0 and above</span> | 7/2/2025<span style="color: #000000"> </span> | 3.18.0 is the minimum Prebid Server Version that embeds the fwssp adapter |
| <span style="color: #000000">IAB Content Category Taxonomy</span> | <span style="color: #000000">v1</span> | 7/2/2025<span style="color: #000000"> </span> | IAB Content Categories are mapped to FreeWheel Global Industries |
| <span style="color: #000000">OpenRTB Supply (ORTB-S)</span> | <span style="color: #000000">Refer to </span><span style="color: #000000">[OpenRTB Supply Integration Guide](https://freewheel-knowledge-hub.atlassian.net/wiki/pages/createpage.action?spaceKey=RCS&title=OpenRTB%20Supply%20Integration%20Guide&linkCreation=true&fromPageId=114787014)</span> |

# **Guide Change Log**

### Current Guide Version

| **Guide Version** | **Date** | **Author** | **Description** |
| --- | --- | --- | --- |
| v1.4 | 11/5/2025 | <span style="color: #000000">Admin</span> | Update section 4. Parameters to include more information on mandatory items for minimum functionality |

### Historic

---

> Macro (toc)

---

# 1. Introduction 

[Prebid Server](https://prebid.org/product-suite/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 <span style="color: #172b4d">(like FreeWheel's </span>***fwssp***<span style="color: #172b4d"> adapter)</span> to integrate demand sources, by translating bid requests and responses between different systems
- **OpenRTB Supply Integration Compatibility**: Supports the OpenRTB Supply Integration API built t<span style="color: #1d1c1d">o 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 </span><span style="color: #1d1c1d">[OpenRTB Supply Integration Guide](https://freewheel-knowledge-hub.atlassian.net/wiki/pages/createpage.action?spaceKey=RCS&title=OpenRTB%20Supply%20Integration%20Guide&linkCreation=true&fromPageId=114787014)</span><span style="color: #1d1c1d"> for more on specifications supported and other items.</span>
- **Media Type Support**: Can handle various media types


## 1.1 Integration Diagram

![image](media://5ac8af5f-b80b-4a8c-bd33-d99bfc1166b0)

## 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.<span style="color: #333333"> </span>
- 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
- <span style="color: #333333">New endpoint url - see section below</span>
- Freewheel account team to provide:
  - Profile ID
  - Network ID
  - Custom site section ID

---

# 2. Technical Implementation

Freewheel only offers a Go version of the **fwssp** Prebid Server Adapter, which can be used as a module for an ad server's Prebid Server instance built on Go.

1. If the ad server already has a Prebid Server setup via Go
  1. You can find our prebid server adapter module (the fwssp.go file) here: [https://github.com/prebid/prebid-server/tree/master/adapters/fwssp](https://github.com/prebid/prebid-server/tree/master/adapters/fwssp)
    1. Usage instructions can be found here: [https://go.dev/doc/tutorial/getting-started](https://go.dev/doc/tutorial/getting-started) and [https://go.dev/blog/using-go-modules](https://go.dev/blog/using-go-modules)
2. If the ad server doesn't have a Prebid Server set up
  1. See here on installing Prebid Server onto an ad server: [https://docs.prebid.org/prebid-server/developers/installing-go.html](https://docs.prebid.org/prebid-server/developers/installing-go.html)
    1. To note, we are linking the GO version of Prebid Server here, as we only offer a Go version/module of the ***fwssp*** Prebid Server Adapter
  2. You can find our ***fwssp*** Prebid Server Adapter module (the fwssp.go file) here: [https://github.com/prebid/prebid-server/tree/master/adapters/fwssp](https://github.com/prebid/prebid-server/tree/master/adapters/fwssp)
    1. Usage instructions can be found here: [https://go.dev/doc/tutorial/getting-started](https://go.dev/doc/tutorial/getting-started) and [https://go.dev/blog/using-go-modules](https://go.dev/blog/using-go-modules)

## 2.1 Updates to the fwssp Prebid Server Adapter

Freewheel may update the adapter to extend its capabilities or correct an issue. We are currently looking into the best way to relay to clients and ad servers when we make an update, so they can then update their local version of ***fwssp*** Prebid Server Adapter.

---

# 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:

|  |
| --- |
| <span style="color: #333333">**[https://prebid.v.fwmrm.net/ortb/ssp](https://prebid.v.fwmrm.net/ortb/ssp)**</span> |

## 3.1 Gzip Compression Support

The **fwssp** Prebid Server adapter can support gzip compression (declared via the endpointcompression attribute/kvp). For more information, please see section 4.6 in the [OpenRTB Supply Integration Guide](https://hub.freewheel.tv/space/RCS/114426134/OpenRTB+Supply+Integration+Guide#4.6-Gzip-Compression-Support). 

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](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's ability to target your network, along with additional attributes from the Video object. For a list of all ORTB-S parameters, please refer to the [OpenRTB Supply Integration Guide](https://freewheel-knowledge-hub.atlassian.net/wiki/pages/createpage.action?spaceKey=RCS&title=OpenRTB%20Supply%20Integration%20Guide&linkCreation=true&fromPageId=114787014). 

> ℹ️ **Items of Note**
> ℹ️ 
> ℹ️ - <span style="color: #323232">Depending on the ad server setup, you may have to just plug in the value itself in the UI</span>
> ℹ️ - <span style="color: #323232">Not all </span><span style="color: #323232">**mandatory**</span><span style="color: #323232"> </span><span style="color: #323232">**objects are attributes are listed in the table below**</span><span style="color: #323232">; please see the </span><span style="color: #323232">[OpenRTB Supply Integration Guide](https://freewheel-knowledge-hub.atlassian.net/wiki/pages/createpage.action?spaceKey=RCS&title=OpenRTB%20Supply%20Integration%20Guide&linkCreation=true&fromPageId=114787014)</span><span style="color: #323232"> for a list of all mandatory items. If a mandatory item is not included, it is likely that the </span><span style="color: #323232">**transaction will fail**</span>
> ℹ️   - <span style="color: #323232">**Mandatory ORTB-S objects at a high level: **</span>[5.3 AdRequest Object](https://freewheel-knowledge-hub.atlassian.net/wiki/pages/createpage.action?spaceKey=RCS&title=OpenRTB%20Supply%20Integration%20Guide&linkCreation=true&fromPageId=114787014)

| **Path** | **fwssp Adapter Parameter** | **Type** | **Description** | **Example** | **Scope** |
| --- | --- | --- | --- | --- | --- |
| <span style="color: #323232">bidrequest.imp.ext.prebid.bidder.fwssp</span> | profile_id | string | A profile is used to determine and control what types/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<br>The expected format is the name of the profile as a string and not a numerical ID | <span style="color: #323232">"profile_id": "12345:profile__name"</span> | 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 | <span style="color: #323232">"network_id": "12345"</span> |
| 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 | "custom_site_section_id": "ss_12345"<br>**or**<br>"custom_site_section_id": "12345" |
| <span style="color: #323232">bidrequest.imp.video</span><br>> ℹ️ **Required**
> ℹ️ 
> ℹ️ This video object is required, with mandatory fields(s).  Please refer to the [OpenRTB Supply Integration Guide](https://hub.freewheel.tv/space/RCS/114426134/OpenRTB+Supply+Integration+Guide#5.12-Video-Object) for the most up-to-date details of all the mandatory and optional fields for the video object. | Mimes | <span style="color: #000000">string array</span> | <span style="color: #000000">Supported content MIME types</span> | <span style="color: #000000">"mimes": ["video/mp4"]</span> | <span style="color: #000000">Mandatory</span> |
| <span style="color: #000000">startdelay</span> | <span style="color: #000000">integer</span> | <span style="color: #000000">Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements</span> | <span style="color: #000000">"startdelay": -1</span> | <span style="color: #000000">Recommended (Mandatory if placement [see next row] is not passed)</span> |
| <span style="color: #000000">placement</span> | <span style="color: #000000">integer</span> | <span style="color: #000000">1 In-Stream, 2 In-Banner, 3 In-Article, 4 In-Feed, 5 Interstitial/Slider/Floating</span> | <span style="color: #000000">"placement":1</span> | <span style="color: #000000">Recommended (Mandatory if startdelay is not passed)</span> |
| maxseq | integer | <span style="color: #000000">Indicates the maximum number of ads that may be served into a dynamic video ad pod</span> | <span style="color: #000000">"maxseq": 8</span> | <span style="color: #000000">Optional (Mandatory if using dynamic ad podding)</span> |
| poddur | integer | <span style="color: #000000">Indicates the total amount of time in seconds that advertisers may fill for a dynamic video ad pod</span> | <span style="color: #000000">"poddur": 145</span> |

## 4.2 ORTB Type Ad Request Body

Please refer to section 5 of our [OpenRTB Supply Integration Guide](https://hub.freewheel.tv/space/RCS/114426134/OpenRTB+Supply+Integration+Guide) for the current list of supported ORTB fields. Note that there will often be new fields added to this section. 

> ℹ️ **Additional Details of Passing of Standard Attributes**
> ℹ️ 
> ℹ️ <span style="color: #1d1c1d">For details of the passing of Standard Attributes such as Brand, Channel, IAB Category, Genre, Content title, etc., </span>see [Inventory Standardization from OpenRTB-S](https://hub.freewheel.tv/space/SHUG/116490984/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](https://hub.freewheel.tv/space/RCS/114426134/OpenRTB+Supply+Integration+Guide). 

---

# 5. Config Code

If you need access to the adapter code, you can view it on the following [GitHub repository](https://github.com/prebid/prebid-server/pull/4309).

---

# 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 an outgoing bid request. 

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

---

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

<span style="color: #333333">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 </span><span style="color: #333333">[ORTB-S Integration Guide](https://hub.freewheel.tv/space/SHUG/117997976/ads.txt+and+app-ads.txt+setup#FreeWheel-SSP)</span><span style="color: #333333"> section 5.10. If you are a Freewheel client and need more information on the ads.txt setup please refer to </span><span style="color: #333333">[here](https://hub.freewheel.tv/space/SHUG/117997976/ads.txt+and+app-ads.txt+setup#FreeWheel-SSP)</span><span style="color: #333333">.</span>

---

# 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**. This [page](https://hub.freewheel.tv/space/SHUG/116490984/Inventory+Standardization+from+OpenRTB-S) details the fields required to pass the needed information for ORTB ad requests. <span style="color: #1d1c1d">This document includes details of the passing of Standard Attributes such as Brand, Channel, IAB Category, Genre, Content title, etc.</span>

> ℹ️ 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 and 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 code blocks below, which pass the expected parameters as a guide, and to sanity check the code

### 9.1.1 Prebid Received Request Sample

<details>
<summary>Prebid Received Request</summary>

```javascript
{
  "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": ""
      }
    }
  }
}
```
</details>

### 9.1.2 Bidder Received Request Sample

<details>
<summary>Bidder Received Request</summary>

```javascript
{
  "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": ""
      }
    }
  }
}


```
</details>

### 9.1.3 Bidder Returned Response Sample

<details>
<summary>Bidder Returned Response</summary>

```javascript
{
  "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"
}
```
</details>

### 9.1.4 Prebid Returned Response Sample 

<details>
<summary>Prebid Received Response</summary>

```javascript
{
  "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"
}
```
</details>