Specification Support

Guide Change Log

Current Guide Version

Historic

1. Introduction 

Prebid.js is an open-source header bidding solution that enables publishers to implement header bidding on their websites and applications. It serves as a crucial technology in the programmatic advertising ecosystem, particularly for video advertising.

Core Functionality

Prebid.js functions as a client-side JavaScript library that:

1. Facilitates header bidding auctions by sending bid requests to multiple demand partners (SSPs and ad exchanges) simultaneously
2. Collects bid responses from these partners
3. Passes the winning bids to the publisher's ad server for final decision-making

Key Features

• Header Bidding Integration: Allows publishers to conduct pre-auction bidding before making ad server calls
• Adapter System: Uses specialized adapters (like FreeWheel's fwssp adapter) to connect with different demand sources
• Format Support: Supports various ad formats including in-banner video and instream video ads
• Customization: Offers extensive configuration options for publishers to control bidding behavior

1.1 Integration Diagram

Pre-requisites 

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

• A working Prebid.js integration
• Expected QPS volumes (daily max and average)
• Estimated traffic per geo
• Ensure ads.txt and app ads.txt are up to date
• Must used adapter released in version 9.51.0 or above
• New endpoint url - see section below
• Freewheel account team to provide:
  • Profile ID
  • Network ID
  • Custom site section ID
  • Dedicated server url for the clients network

2. Technical Implementation

Publishers implementing FreeWheel's Prebid.js adapter need to:

1. Include the Prebid.js library along with the fwssp Bidder Adapter in their web pages
   1. First timers setting up Prebid.js can download the Prebid.js package along with the fwssp Bidder Adapter here. Assure to select FWSSP from the list of bidder adapters
      1. For more instructions on setting up Prebid.js on your endpoints see this
      2. For more information on how header bidding works see this
   2. For those with existing Prebid.js setups, you can find the fwssp Bidder Adapter code here to add to yours Predbid.js wrapper setup
2. Configure bid parameters including network ID, profile, site section ID, and other FreeWheel-specific parameters
3. Set up proper correlation between Prebid.js ad units and their ad server slots

3. fwssp Bidder Adapter Code

If you need access to the adapter code to add the fwssp Bidder Adapter to your Prebid.js setup or for something else, you can view it on the following Github repository.

4. How to add the new FW Prebid.js Bidder Adapter to Ad Units

You can use the fwssp bidder adapter by adding an Ad Unit with bidder code "fwssp". The following is the example of an in-banner ad request in its most minimal form, which can call found on Github.

var adUnits = [{
  code: 'div-target-name',          // target div where media will be render
  mediaTypes: {                        // mediatypes on the top level
    video: {
      context: 'instream',
      playerSize: [640, 480]
    }
  },
  bids: [{
    bidder: 'fwssp',                  
    params: {
      serverUrl: 'https://example.com/ad/g/1',
      networkId: '42015',
      profile: '42015:sample_profile',
      siteSectionId: 'sample_site_section_tag',
      videoAssetId: '0',
      flags: '+play-uapl',              //  missing comma
      mode: 'live',
      minD: 30,
      maxD: 60,
      adRequestKeyValues: {
        _fw_player_width: '1920',
        _fw_player_height: '1080'
      },
      format: 'inbanner'
    }
  }]
}];

You can find more indepth information Prebid Github Repository. 

5. Parameters to Include

The following are parameters that either are mandatory or optionally included the Prebid headers within ad requests.

6. Endpoint

Clients will be provided with a unique endpoint for which to send requests. Endpoints will have a variable prefix ID which is the Network ID in hexadecimal format. The Endpoint Prefix ID will need to be added as a prefix within the URL:

• Format
  • https://prefixID.v.fwmrm.net/ad/g/1
• Example with custom prefix ID included
  • https://83b96.v.fwmrm.net/ad/g/1

7. User Syncing/Cookie Syncing 

User/cookie syncing with Freewheel is available for Prebid.JS clients with the expectation that the client's cookies, if passed, will be included in the http headers of the ad request. When this is present, it will then be used downstream to check if we have a cookie match with the DSPs as we send outgoing bid requests. 

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

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:

• ads.txt setup please refer to this
• Sellers.json please refer to this

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 for JS - fwssp and not another adapter. 

The below code blocks are examples of the expected parameters as a guide and to sanity check the code 

9.1 Sample Ad Requests

9.1.1 Inbanner Ad request Config Example

{
        'bidder': 'fwssp',
        'adUnitCode': 'adunit-code',
        'mediaTypes': {
        'banner': {
          'sizes': [
            [300, 250], [300, 600]
          ]
        }
        },
        'sizes': [[300, 250], [300, 600]],
        'bidId': '30b31c1838de1e',
        'bidderRequestId': '22edbae2733bf6',
        'auctionId': '1d1a030790a475',
        'schain': {
          'ver': '1.0',
          'complete': 1,
          'nodes': [{
            'asi': 'example.com',
            'sid': '0',
            'hp': 1,
            'rid': 'bidrequestid',
            'domain': 'example.com'
          }]
        },
        'params': {
          'bidfloor': 2.00,
          'serverUrl': 'https://example.com/ad/g/1',
          'networkId': '42015',
          'profile': '42015:js_allinone_profile',
          'siteSectionId': 'js_allinone_demo_site_section',
          'flags': '+play',
          'videoAssetId': '0',
          'timePosition': 120,
          'adRequestKeyValues': {
            '_fw_player_width': '1920',
            '_fw_player_height': '1080'
          }
        }
      }

9.1.2 Instream Ad Request Config Example

{
        'bidder': 'fwssp',
        'adUnitCode': 'adunit-code',
        'mediaTypes': {
          'video': {
            'playerSize': [300, 600],
          }
        },
        'sizes': [[300, 250], [300, 600]],
        'bidId': '30b31c1838de1e',
        'bidderRequestId': '22edbae2733bf6',
        'auctionId': '1d1a030790a475',
        'schain': {
          'ver': '1.0',
          'complete': 1,
          'nodes': [{
            'asi': 'example.com',
            'sid': '0',
            'hp': 1,
            'rid': 'bidrequestid',
            'domain': 'example.com'
          }]
        },
        'params': {
          'bidfloor': 2.00,
          'serverUrl': 'https://example.com/ad/g/1',
          'networkId': '42015',
          'profile': '42015:js_allinone_profile',
          'siteSectionId': 'js_allinone_demo_site_section',
          'flags': '+play',
          'videoAssetId': '0',
          'mode': 'live',
          'timePosition': 120,
          'tpos': 300,
          'slid': 'Midroll',
          'slau': 'midroll',
          'minD': 30,
          'maxD': 60,
          'adRequestKeyValues': {
            '_fw_player_width': '1920',
            '_fw_player_height': '1080'
          },
          'gdpr_consented_providers': 'test_providers'
        }
      }

9.2 Troubleshooting Ad Rendering

• FWSSPAdapter will load the MRM AdManager SDK for ad rendering. Please see these Admanager pages for additional information https://hub.freewheel.tv/pages/viewpage.action?pageId=2267285912