Freestar for Prebid – Adapter integration guide

0. Prerequisites

Publisher must update to Prebid.js version 3.10+, 4.0+, or 5.5+ to access the "Sortable" adapter. If the publisher is not planning to update to these versions, they need to speak to their Freestar Account Manager.

1. Freestar account setup

Publisher provides Freestar with:

  • A list of sites to integrate the adapter on, and for each:
    • The domains to serve on, e.g. example.com
    • A link to the privacy policy of the site
    • The current ad quality solution being used (if applicable)
  • Blocklist: Including a list of advertiser URLs, IAB Categories, or IAB Creative Attributes to block from bidding on the inventory  

Freestar provides the publisher with:

  • The siteId for each site to use in the adapter
  • Lines to add to the publisher's ads.txt
  • A form to capture payment details

2. Ad server setup

If prebid.js has been configured to send the top bid to your ad server, there is no change required to enable the "Sortable" adapter.

If prebid.js has been configured to send all bids to the ad server, follow the prebid.js documentation to create new line items in the ad server using "sortable" as the BIDDERCODE.

3. Adapter configuration

3.1 Add the global configuration

Add the "Sortable" configuration in a setConfig block using the provided siteId. The userSync config allows us to inject sync pixels in an iframe.

Prebid 3.10+, 4.0+, or 5.5+

pbjs.setConfig({
  sortable: {
    siteId: 'example.com'
  },
  userSync: {
    filterSettings: {
      iframe: {
        bidders: ['sortable'],
        filter: 'include'
      }
    }
  }
});

3.2 Set "Sortable" tagId for each ad unit

Change the ad unit configuration in the bids property of the adUnit to include the "sortable" bidder and a "tagId" as shown below.

Any publisher-defined string can be used as the tagId. Freestar recommends using a unique tagId to represent each placement on your site. This tagId shows up in reports and is visible to buyers.

var adUnits = [{
  code: '/19968336/header-bid-tag-1',
  mediaTypes: {
    banner: {
      sizes: [[300, 250]]
    }
  },
  bids: [{
    bidder: 'sortable',
    params: {
      tagId: 'tag-1'
    }  
  }]
}];
pbjs.addAdUnits(adUnits);

For further information, see this Basic Prejbid.js example or the Prebid Quick Start.

3.3 Optional parameters

The "Sortable" adapter supports the following optional parameters. They can be specified in the params section of each ad unit:

Param Name
DescriptionExampleVersion support
floorThe minimum CPM (in USD) accepted for a bid. Please note, this should be a number, not a string.
0.25All
floorSizeMapIn a multi-size request, this sets the floor for each size. This overrides the floor param.
{"300x250": 1.25, "300x600": 5.50 }
Supported: 3.10+, 4.0+
Not Supported: 5.x+

4. Testing

Once the adapter is configured, use the ?sortable-prebid-test=true query parameter to test the adapter. Loading a page with this query parameter triggers "Sortable" to bid with a $100 bid. If the Sortable logo is visible, the successful bid won the auction and was rendered on the page.

FAQ

Can I use a siteId on any domain?

Each top-level domain must be whitelisted by Freestar. To onboard additional domains, the publisher should reach out to their Freestar Account Manager.

How is a tagId defined?

A publisher can use any string (characters, underscores) as a tagId. Freestar does not need to know the value ahead of time. Freestar recommends using a unique tagId to represent each placement on the site. This tagId shows up in reports and is visible to buyers.

How is the floor parameter used?

Freestar passes along the floor parameter to buyers in the auction. Bids that return below the floor are filtered out of the results. A bid is only returned if it is higher than the floor. 

Note: Setting a floor may decrease the number of eligible bids and overall revenue.

For industry insights and information about our product offerings, check out our blog!

Want to see our products in action? For a demo, fill out a form here.

Change log

Prebid.js
Version
Comment
5.5+Prebid 5.5+ details added
3.xPrebid 3.x details added
2.x and 2.11Prebid Analytics Adapter added
1.17.0Sortable Adapter added
1.18.0Added support for the floorSizeMap param
0.34.19Sortable Adapter added to the legacy release