Specification Support

Guide Change Log

Current Guide Version

Historic

1. Introduction 

SFX has provided tech resources in order for publishers to integrate with the Prebid Server Framework. This is an open source framework that allows publishers to integrate with demand sources in a plug and play type fashion and with less complexities than other integration methods. 

With the sunsetting of SFX, any customers using an existing Prebid Server Integration will need to complete a new adaptor 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

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 adaptor 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 Adaptor

The new Freewheel adaptor is named fwssp. This new Prebid Adaptor will work in parallel to the existing SFX adaptors whilst the migration of clients is complete. Then the FW SSP Adaptor is going to replace the SFX instances of freewheel-ssp and freewheelssp adaptors in the future once SFX is deprecated.

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 Adaptor config file:

4. New Parameters

With the release of the new adaptors, 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

profile_id

network_id

custom_site_section_id

5. Config Code

If you need access to the adaptor 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 Adaptor. The code to manage this will be integrated into the adaptor 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

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.

8. Ads.txt/app ads.txt 

Link to the new Hub guide for FW SSP - still pending publication on https://hub.freewheel.tv/display/MUG/ads.txt+and+app-ads.txt+setup.

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

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

11. 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 adaptor - fwssp and not another adaptor. 

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

11.1.1 Prebid Received Request Sample

{
  "id": "fwssp-test",
  "site": {
    "page": "prebid.org"
  },
  "imp": [
    {
      "id": "imp-1",
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "w": 300,
        "h": 250,
        "maxduration": 30,
        "minduration": 5,
        "startdelay": -1,
        "minbitrate": 300,
        "maxbitrate": 1500,
        "maxseq": 5,
        "poddur": 120
      },
      "ext": {
        "prebid": {
          "bidder": {
            "fwssp": {
              "custom_site_section_id": "ss_12345",
              "network_id": "123456",
              "profile_id": "123456:prof_12345"
            }
          }
        }
      }
    }
  ],
  "ext": {
    "prebid": {
      "debug": true
    }
  }
}

11.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": "prebid.org",
    "ext": {
      "amp": 0
    }
  },
  "device": {
    "ua": "curl/8.7.1"
  },
  "at": 1,
  "source": {
    "tid": "d5e38b20-69d3-4a0a-bbc5-ebb523542062"
  },
  "ext": {
    "prebid": {
      "debug": true,
      "server": {
        "externalurl": "http://localhost:8000",
        "gvlid": 0,
        "datacenter": ""
      }
    }
  }
}

11.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"
}

11.1.4 Prebid Received Request 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"
}