Sortable for Prebid – Adapter integration guide

This feature is in BETA. Reach out to your account manager for more information.

0. Prerequisites

Publisher must update to Prebid.js version 3.14 or later to access the Sortable adapter. If the publisher is not planning to update to this version, they need to speak to their Sortable Account Manager.

1. Sortable account setup

Publisher provides Sortable 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)
  • A list of advertiser URLs, IAB Categories, or IAB Creative Attributes to block from bidding on the inventory  

Sortable 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 Sortable to inject sync pixels in an iframe.

Prebid 1.x, 2.x, and 3.x

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

Prebid 0.34

In Prebid 0.34, the userSync config is slightly different. Setting iframeEnabled: true  enables iframe cookie sync for all enabled header bidders.

pbjs.setConfig({
  sortable: {
    siteId: 'example.com'
  },
  userSync: {
    iframeEnabled: true
  }
});

3.2 (Optional) Set up and enable the Analytics adapter

If you would like to enable Prebid Analytics, contact your Account Manager so that they can enable the report for your account. After they've enabled Prebid Analytics, add the Sortable configuration in a pbjs.que.push block using the provided siteId.

Prebid 2.11 or later

pbjs.que.push(function() {
        pbjs.enableAnalytics({
                provider: 'sortable',
                options: {
                        siteId: 'example.com'
                }        
       }); 
});

For more information on Prebid Analytics, see our Prebid Analytics – Integration Guide and Prebid Analytics – Quick Reference Guide.

3.3 Set Sortable tagId for each ad unit

Change the ad unit configuration (in the bids property of the adUnit you want to change to Sortable) to include the sortable bidder and a tagId as shown below.

Any publisher-defined string can be used as the tagId. Sortable 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.4 Optional parameters

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

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

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 Sortable. To onboard additional domains, the publisher should reach out to their Sortable Account Manager.

How is a tagId defined?

A publisher can use any string (characters, underscores) as a tagId. Sortable does not need to know the value ahead of time. Sortable 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?

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

Change log

Prebid.js
Version
Comment
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