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 behaviour

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 use adapter version 10.10.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 your existing Prebid.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. 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

4. 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, under Prebid.js/modules/fwsspBidAdapter.js

5. 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 be found on Github.

var adUnits = [
  {
    code: 'adunit-code',
      mediaTypes: {
              video: {
                      playerSize: [640, 480],
                      minduration: 30,
                      maxduration: 60
              }
      },
      bids: [
              {
                           bidder: 'fwssp',    // or use alias 'freewheel-mrm'
                           params: {
                                   serverUrl: 'https://example.com/ad/g/1',
                                   networkId: '42015',
                                   profile: '42015:js_allinone_profile',
                                   siteSectionId: 'js_allinone_demo_site_section',
                                   videoAssetId: '0',
                                   flags: '+play-uapl'    // optional: users may include capability if needed
                                   mode: 'live',
                                   adRequestKeyValues: {    // optional: users may include adRequestKeyValues if needed
                                           _fw_player_width: '1920',
                                           _fw_player_height: '1080'
                                   },
                                   format: 'inbanner'
                           }
              }
      ]
}
];

You can find more indepth information Prebid Github Repository. 

6. Parameters

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

7. Passing Contextual Information via 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+with+FreeWheel+Custom+Key+Values details the fields required to pass the needed information within your ad requests. This document includes details of the passing of Standard Attributes such as Brand, Channel, IAB Category, Genre, Content title, etc.

Mandatory Standard Attributes are typically Brand and Genre, however, this may change depending on your inventory. Please work with your account manager for what is required for you.

8. User Syncing/Cookie Syncing 

*This section is only necessary for web inventory

User Syncing, also known as Cookie Syncing, is the process of sharing and matching HTTP cookies between various partners. The concept of Cookie Tracking is restrictive in the amount of information that can be collected and actioned upon for advertisers. This is because cookies are limited to domain and have varying expiration dates. In order for Freewheel to be able to identify, target and frequency cap across various digital properties in accordance with campaign KPI's, Freewheel needs to know how to distinguish one user from another that are sent to us in the publisher's bid request.

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.

9. 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 - please refer to ORTB-S Integration Guide section 5.10 for further information on this.

If you are a Freewheel client and need more information on:

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

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

10.1 Sample Ad Requests

10.1.1 Inbanner Ad request Config Example

{
        'bidder': 'fwssp',
        'adUnitCode': 'adunit-code',
        'mediaTypes': {
        'banner': {
          'sizes': [
            [300, 250], [300, 600]
          ]
        }
        },
        'sizes': [[300, 250], [300, 600]],
        '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',
            '_fw_content_programmer_brand': 'NEEDS_TO_REPLACE_BY_BRAND_NAME',
            '_fw_content_programmer_brand_channel': 'NEEDS_TO_REPLACE_BY_CHANNEL_NAME',
            '_fw_content_genre': 'NEEDS_TO_REPLACE_BY_CONTENT_GENRE'
          }
        }
      }

10.1.2 Instream Ad Request Config Example

{
        'bidder': 'fwssp',
        'adUnitCode': 'adunit-code',
        'mediaTypes': {
          'video': {
            'playerSize': [300, 600],
          }
        },
        'sizes': [[300, 250], [300, 600]],
        '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',
            '_fw_content_programmer_brand': 'NEEDS_TO_REPLACE_BY_BRAND_NAME',
            '_fw_content_programmer_brand_channel': 'NEEDS_TO_REPLACE_BY_CHANNEL_NAME',
            '_fw_content_genre': 'NEEDS_TO_REPLACE_BY_CONTENT_GENRE'
          },
          'gdpr_consented_providers': 'test_providers'
        }
      }

10.2 Troubleshooting Ad Rendering

• fwssp Prebid.js Adapter 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