Index Exchange

Features

Bidder CodeixPrebid.org Memberno
Media Typesdisplay, videoGDPR Supportyes
User IDsnoneCOPPA Supportno

"Send All Bids" Ad Server Keys

These are the bidder-specific keys that would be targeted within GAM in a Send-All-Bids scenario. GAM truncates keys to 20 characters.
hb_pb_ixhb_bidder_ixhb_adid_ix
hb_size_ixhb_source_ixhb_format_ix
hb_cache_host_ixhb_cache_id_ixhb_uuid_ix

"Deal ID" Ad Server Key

hb_deal_ix

Overview

Module Name: Index Exchange Adapter
Module Type: Bidder Adapter
Maintainer: prebid.support@indexexchange.com

Description

This module connects publishers to Index Exchange’s (IX) network of demand sources through Prebid.js. This module is GDPR compliant.

It is compatible with both the older ad unit format where the sizes and mediaType properties are placed at the top-level of the ad unit, and the newer format where this information is encapsulated within the mediaTypes object. We recommend that you use the newer format when possible as it will be better able to accommodate new feature additions.

If a mix of properties from both formats are present within an ad unit, the newer format’s properties will take precedence.

Here are examples of both formats.

Older Format
var adUnits = [{
    // ...

    sizes: [
        [300, 250],
        [300, 600]
    ]

    // ...
}];
Newer Format
var adUnits = [{
    // ...
    mediaTypes: {
        banner: {
            sizes: [
                [300, 250],
                [300, 600]
            ]
        },
        video: {
            context: 'instream',
            playerSize: [
                [1280, 720]
            ]
        }
    },
    // ...
}];

Supported Media Types

Type Support
Banner Fully supported for all IX approved sizes.
Video Fully supported for all IX approved sizes.
Native Not supported.

Bid Parameters

Each of the IX-specific parameters provided under the adUnits[].bids[].params object are detailed here.

Name Scope Description Example Type
siteId Required An IX-specific identifier that is associated with a specific size on this ad unit. This is similar to a placement ID or an ad unit ID that some other modules have. '3723' string
size Required for client-side serving The single size associated with the site ID. It should be one of the sizes listed in the ad unit under adUnits[].sizes or adUnits[].mediaTypes.banner.sizes. Note that the ‘ix’ Prebid Server bid adpater ignores this parameter. [300, 250] Array<integer>

Video

Name Scope Description Example Type
siteId Required An IX-specific identifier that is associated with a specific size on this ad unit. This is similar to a placement ID or an ad unit ID that some other modules have. '3723' string
size Required The single size associated with the site ID. It should be one of the sizes listed in the ad unit under adUnits[].sizes or adUnits[].mediaTypes.video.playerSize. [300, 600] Array<integer>
video Required The video object will serve as the properties of the video ad. You can create any field under the video object that is mentioned in the OpenRTB Spec v2.5. Some fields like mimes, protocols, minduration, maxduration are required. video: { startdelay: 0 } object
video.mimes Required Array list of content MIME types supported. ['video/mp4', 'video/x-flv'] Array<string>
video.minduration Required Minimum video ad duration in seconds. 0 integer
video.maxduration Required Maximum video ad duration in seconds. 300 integer
video.protocol / video.protocols Required Either a single protocol provided as an integer, or protocols provided as a list of integers. 2 - VAST 2.0, 3 - VAST 3.0, 5 - VAST 2.0 Wrapper, 6 - VAST 3.0 Wrapper [2,3,5,6] integer / Array<integer>

Setup Guide

Follow these steps to configure and add the IX module to your Prebid.js integration.

The examples in this guide assume the following starting configuration (you may remove banner or video, if either does not apply).

In regards to video, context can either be 'instream' or 'outstream'. Note that outstream requires additional configuration on the adUnit.

var adUnits = [{
    code: 'banner-div-a',
    mediaTypes: {
        banner: {
            sizes: [
                [300, 250],
                [300, 600]
            ]
        }
    },
    bids: []
},
{
    code: 'video-div-a',
    mediaTypes: {
        video: {
            context: 'instream',
            playerSize: [
                [1280, 720]
            ]
        }
    },
    bids: []
}];
1. Add IX to the appropriate ad units

For each size in an ad unit that IX will be bidding on, add one of the following bid objects under adUnits[].bids:

{
    bidder: 'ix',
    params: {
        siteId: '123456',
        size: [300, 250]
    }
}

Set params.siteId and params.size in each bid object to the values provided by your IX representative.

Examples

Banner:

var adUnits = [{
    code: 'banner-div-a',
    mediaTypes: {
        banner: {
            sizes: [
                [300, 250],
                [300, 600]
            ]
        }
    },
    bids: [{
        bidder: 'ix',
        params: {
            siteId: '123456',
            size: [300, 250]
        }
    }, {
        bidder: 'ix',
        params: {
            siteId: '123456',
            size: [300, 600]
        }
    }]
}];

Video (Instream):

var adUnits = [{
    code: 'video-request-a',
    mediaTypes: {
        video: {
            context: 'instream',
            playerSize: [
                [1280, 720]
            ]
        }
    },
    bids: [{
        bidder: 'ix',
        params: {
            siteId: '123456',
            size: [1280, 720],
            video: {
                skippable: false,
                mimes: [
                    'video/mp4',
                    'video/webm'
                ],
                minduration: 0,
                maxduration: 60,
                protocols: [6]
            }
        }
    }]
}];

Please note that you can re-use the existing siteId within the same flex position.

Video (Outstream): Note that currently, outstream video rendering must be configured by the publisher. In the adUnit, a renderer object must be defined, which includes a url pointing to the video rendering script, and a render function for creating the video player. See http://prebid.org/dev-docs/show-outstream-video-ads.html for more information.

var adUnits = [{
    code: 'video-div-a',
    mediaTypes: {
        video: {
            context: 'outstream',
            playerSize: [[640, 360]]
        }
    },
    renderer: {
        url: 'https://test.com/my-video-player.js',
        render: function (bid) {
            ...
        }
    },
    bids: [{
        bidder: 'ix',
        params: {
            siteId: '123456',
            size: [640, 360],
            video: {
                skippable: false,
                mimes: [
                    'video/mp4',
                    'video/webm'
                ],
                minduration: 0,
                maxduration: 60,
                protocols: [6]
            }
        }
    }]
}];
2. Include ixBidAdapter in your build process

When running the build command, include ixBidAdapter as a module, as well as dfpAdServerVideo if you require video support.

gulp build --modules=ixBidAdapter,dfpAdServerVideo,fooBidAdapter,bazBidAdapter

If a JSON file is being used to specify the bidder modules, add "ixBidAdapter" to the top-level array in that file.

[
    "ixBidAdapter",
    "dfpAdServerVideo",
    "fooBidAdapter",
    "bazBidAdapter"
]

And then build.

gulp build --modules=bidderModules.json

Setting First Party Data (FPD)

FPD allows you to specify key-value pairs which will be passed as part of the query string to IX for use in Private Marketplace Deals which rely on query string targeting for activation. For example, if a user is viewing a news-related page, you can pass on that information by sending category=news. Then in the IX Private Marketplace setup screens you can create Deals which activate only on pages which contain category=news. Please reach out to your IX representative if you have any questions or need help setting this up.

To include FPD in a bid request, it must be set before pbjs.requestBids is called. To set it, call pbjs.setConfig and provide it with a map of FPD keys to values as such:

pbjs.setConfig({
    ix: {
        firstPartyData: {
            '<key name>': '<key value>',
            '<key name>': '<key value>',
            // ...
        }
    }
});

The values can be updated at any time by calling pbjs.setConfig again. The changes will be reflected in any proceeding bid requests.

Setting a Server Side Timeout

Setting a server-side timeout allows you to control the max length of time the servers will wait on DSPs to respond before generating the final bid response and returning it to this module.

This is distinctly different from the global bidder timeout that can be set in Prebid.js in the browser.

To add a server-side timeout, it must be set before pbjs.requestBids is called. To set it, call pbjs.setConfig and provide it with a timeout value as such:

pbjs.setConfig({
    ix: {
        timeout: 500
    }
});

The timeout value must be a positive whole number in milliseconds.

Additional Information

Bid Request Limit

If a single bid request to IX contains more than 20 impression requests (i.e. more than 20 objects in bidRequest.imp), only the first 20 will be accepted, the rest will be ignored.

To avoid this situation, ensure that when pbjs.requestBid is invoked, that the number of bid objects (i.e. adUnits[].bids) with adUnits[].bids[].bidder set to 'ix' across all ad units that bids are being requested for does not exceed 20.

Time-To-Live (TTL)

All bids received from IX have a TTL of 35 seconds, after which time they become invalid.

If an invalid bid wins, and its associated ad is rendered, it will not count towards total impressions on IX’s side.

FAQs

Why do I have to input size in adUnits[].bids[].params for IX when the size is already in the ad unit?

There are two important reasons why we require it:

  1. An IX site ID maps to a single size, whereas an ad unit can have multiple sizes. To ensure that the right site ID is mapped to the correct size in the ad unit we require the size to be explicitly stated.

  2. An ad unit may have sizes that IX does not support. By explicitly stating the size, you can choose not to have IX bid on certain sizes that are invalid.

How do I view IX’s bid request in the network?

In your browser of choice, create a new tab and open the developer tools. In developer tools, select the network tab. Then, navigate to a page where IX is setup to bid. Now, in the network tab, search for requests to casalemedia.com/cygnus. These are the bid requests.