Index Exchange
Features
Bidder Code | ix | Prebid.org Member | yes |
---|---|---|---|
Media Types | display, video, native | GDPR TCF Support | yes |
User IDs | identityLink, netId, fabrickId, zeotapIdPlus, uid2, unifiedId, id5Id, lotamePanoramaId, publinkId, hadronId, pubcid | USP/CCPA Support | yes |
Supply Chain Support | yes | COPPA Support | yes |
Demand Chain Support | no | Safeframes OK | check with bidder |
Supports Deals | check with bidder | Prebid.js Adapter | yes |
IAB GVL ID | 10 | Prebid Server Adapter | yes |
Floors Module Support | yes | First Party Data Support | yes |
Multi Format Support | check with bidder | ORTB Blocking Support | check with bidder |
"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_ix |
hb_bidder_ix |
hb_adid_ix |
hb_size_ix |
hb_source_ix |
hb_format_ix |
hb_cache_host_ix |
hb_cache_id_ix |
hb_uuid_ix |
hb_cache_path_ix |
hb_deal_ix |
Overview
Module Name: Index Exchange Adapter
Module Type: Bidder Adapter
Maintainer: prebid.support@indexexchange.com
Description
Publishers may access Index Exchange’s (IX) network of demand sources through our Prebid.js and Prebid Server adapters. Both of these modules are GDPR and CCPA compliant.
IX Prebid.js Adapter
This module connects publishers to Index Exchange’s (IX) network of demand sources through Prebid.js. This module is GDPR and CCPA compliant.
It is compatible with the new Prebid.js 5.0 ad unit format where banner and video properties, including the size parameter, are stored in the adUnits[].mediaTypes
object. IX still supports both size as an optional parameter and the Missing Sizes feature, but we recommend upgrading to the Prebid.js 5.0 format.
For more information about how the adUnits[].mediaTypes
object is formatted in Prebid.js 5.0, refer to the following example.
var adUnits = [{
// ...
mediaTypes: {
banner: {
sizes: [
[300, 250],
[300, 600]
]
},
video: {
context: 'instream',
playerSize: [300, 250]
}
},
// ...
}];
Supported Media Types (Prebid.js)
Type | Support |
---|---|
banner |
Fully supported for all IX approved sizes |
video |
Fully supported for all IX approved sizes |
native |
Supported |
Supported Media Types (Prebid Server)
Type | Support |
---|---|
banner |
Fully supported |
video |
Fully supported, including ad pods for OTT |
native |
Supported |
Ad Unit or Bidder Parameters
These params can be specified in the ad unit level, which will be the preferred way going forward with PBJS 5.0
Each of the IX-specific parameters provided under the object are detailed here.
The following parameters are specified in the ad unit adUnits[].mediaTypes
. This includes each of the IX-specific parameters provided under adUnits[].bids[].params
.
In Prebid.js versions 5.0 and above, mediaType and sizes are not required to be defined at the ad unit level.
Banner
Key | Scope | Type | Description |
---|---|---|---|
siteId |
Required | String | An IX-specific identifier that is associated with this ad unit. It will be associated to the single size, if the size provided. This is similar to a placement ID or an ad unit ID that some other modules have. For example, '3723' , '6482' , '3639' |
sizes |
Optional | Number[Number[]] | The size/sizes associated with the site ID, as listed in the ad unit under adUnits[].mediaTypes.banner.sizes . For example, [300, 250], [300, 600], [728, 90] |
Video
Key | Scope | Type | Description |
---|---|---|---|
siteId |
Required | String | An IX-specific identifier that is associated with this ad unit. It will be associated to the single size, if the size is provided. This is similar to a placement ID or an ad unit ID that some other modules have. For example, '3723' , '6482' , '3639' |
size |
Optional | Number[] | The single size that is associated with the site ID, as listed in the ad unit under adUnits[].sizes or adUnits[].mediaTypes.video.playerSize . For example, [300, 250], [300, 600]. This parameter is optional in Prebid.js versions 5.0 and above. Versions prior to 5.0 will still require a size parameter. |
video |
Optional | Hash | 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. Properties not defined at this level, will be pulled from the Adunit level. |
video.w |
Required | Integer | The width of the video player in pixels that will be passed to demand partners. *If you are using Index’s outstream player and have placed the video object at the bidder level, this is a required field. You must define the size of the video player using the video.w and video.h parameters, with a minimum video player size of 300 x 250. |
video.h |
Required | Integer | The height of the video player in pixels that will be passed to demand partners. *If you are using Index’s outstream player and have placed the video object at the bidder level, this is a required field. You must define the size of the video player using the video.w and video.h parameters, with a minimum video player size of 300 x 250. |
video.playerSize |
Optional* | Integer | The video player size that will be passed to demand partners. *If you are using Index’s outstream player and have placed the video object at the adUnit level, this is a required field. You must define the size of the video player using this parameter, with a minimum video player size of 300 x 250. |
video.mimes |
Required | String[] | If you are using Index’s outstream video player and want to learn more about what is supported, see List of supported OpenRTB bid request fields for Sellers. |
video.minduration |
Required | Integer | Minimum video ad duration in seconds. |
video.maxduration |
Required | Integer | Maximum video ad duration in seconds. |
video.protocol / video.protocols |
Required | Integer / Integer[] | 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 |
video.playerConfig |
Optional | Hash | The Index specific outstream player configurations. |
video.playerConfig.floatOnScroll |
Optional | Boolean | A boolean specifying whether you want to use the player’s floating capabilities, where: - true : Use the Index player’s float capabilities.Note: If you set floatOnScroll to true , Index updates the placement value to 5 . Note: We do not recommend using the player’s default float capabilities if you have more than one outstream ad unit per page. - false : Do not use the Index player’s float capabilities (default). |
video.playerConfig.floatSize |
Optional | Integer[] | The height and width of the floating player in pixels. If you do not specify a float size, the player adjusts to the aspect ratio of the player size that is defined when it is not floating. Index recommends that you review and test the float size to your user experience preference. |
Native
Index supports the native assets that Prebid.js recognizes. For the list of native assets, see Prebid.js Native Implementation Guide on the Prebid site.
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'
.
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'
}
}
Set params.siteId
in the 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'
}
}, {
bidder: 'ix',
params: {
siteId: '123456'
}
}]
}];
Video (Instream):
var adUnits = [{
code: 'video-div-a',
mediaTypes: {
video: {
// Preferred location for openrtb v2.5 compatible video obj
context: 'instream',
playerSize: [300, 250],
api: [2],
protocols: [2, 3, 5, 6],
minduration: 5,
maxduration: 30,
mimes: ['video/mp4', 'application/javascript'],
placement: 3
}
},
bids: [{
bidder: 'ix',
params: {
siteId: '12345'
}
}, {
bidder: 'ix',
params: {
siteId: '12345',
video: {
// openrtb v2.5 compatible video obj
// If required, use this to override mediaTypes.video.XX properties
}
}
}]
}];
Please note that you can re-use the existing siteId
within the same flex
position.
Video (Outstream): Publishers have two options to receive outstream video demand from Index:
- Using Index’s outstream video player
- In an outstream video configuration set up by the publisher. For more information, see Prebid’s documentation on how to show video ads.
Index’s outstream video player Publishers who are using Index as a bidding adapter in Prebid.js can show outstream video ads on their site from us by using Index’s outstream video player. This allows a video ad to display inside of a video player and can be placed anywhere on a publisher’s site, such as in-article, in-feed, and more.
Define a new video
object for our outstream video player at either the adUnit level or the bidder
level. If you are setting it at the bidder level, define the size of the video player using the parameters video.h
and video.w
. If you are setting it at the adUnit
level, define the size using video.playerSize
.</br>Note: The bidder level video configurations override the adunit level configurations. The playerConfig
is only a bidder level configuration.
For more information on how to structure the video
object, refer to the following code example:
var adUnits = [{
code: 'div-gpt-ad-1571167646410-1',
mediaTypes: {
video: {
playerSize: [640, 360],
context: 'outstream',
api: [2],
protocols: [2, 3, 5, 6],
minduration: 5,
maxduration: 30,
mimes: ['video/mp4', 'application/javascript'],
placement: 5
}
},
bids: [{
bidder: 'ix',
params: {
siteId: '715964'
video: {
playerConfig: {
floatOnScroll: true,
floatSize: [300,250]
}
}
}
}]
}];
Please note that your use of the outstream video player will be governed by and subject to the terms and conditions of i) any master services or license agreement entered into by you and Index Exchange; ii) the information provided on our knowledge base linked here and here, and iii) our Privacy Policy. Your use of Index’s outstream video player constitutes your acknowledgement and acceptance of the foregoing.
Video Caching
Note that the IX adapter expects a client-side Prebid Cache to be enabled for instream video bidding.
pbjs.setConfig({
usePrebidCache: true,
cache: {
url: 'https://prebid.adnxs.com/pbc/v1/cache'
}
});
Native
We support the three native template rendering options that are provided in the Setting up Prebid Native in Google Ad Manager. The following code is an example of a Prebid native set up using Google Ad Manager, but the concept and implementation should be similar for other ad servers.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
native: {
image: {
required: true,
sizes: [150, 50]
},
title: {
required: true,
len: 80
},
sponsoredBy: {
required: true
},
clickUrl: {
required: true
},
privacyLink: {
required: false
},
body: {
required: true
len: 90
},
icon: {
required: true,
sizes: [50, 50]
}
}
},
bids: [{
bidder: 'ix',
params: {
siteId: '715966'
}
}]
});
User Sync
Add the following code to enable user sync. IX strongly recommends enabling user syncing through iFrames. This functionality improves DSP user match rates and increases the IX bid rate and bid price. Be sure to call pbjs.setConfig()
only once.
Note: While we recommend iframe-based user syncing, we also support image-based user syncing. If both are enabled, we will default to using iframe, because it allows us more flexibility to optimize the frequency, timing, and coverage for syncing.
pbjs.setConfig({
userSync: {
iframeEnabled: true,
filterSettings: {
iframe: {
bidders: ['ix'],
filter: 'include'
}
}
}
});
The detectMissingSizes feature
By default, the IX bidding adapter bids on all banner sizes available in the ad unit when configured to at least one banner size. If you want the IX bidding adapter to only bid on the banner size it’s configured to, switch off this feature using detectMissingSizes
.
pbjs.setConfig({
ix: {
detectMissingSizes: false
}
});
OR
pbjs.setBidderConfig({
bidders: ["ix"],
config: {
ix: {
detectMissingSizes: false
}
}
});
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)
As a part of 4.30, IX will start to pick up FPD in the global FPD module, as well as continue to pick up IX bidder-specific FPD. Previous versions of IX Bid Adapter will only support the IX bidder-specific FPD.
Global FPD
As of Prebid.js 4.30, use the more generic ortb2
interface, which can be used for more than just First Party Data.
The First Party Data feature allows publishers to specify key/value data in one place where each compatible bid adapter can read it.
To supply global data, use the setConfig()
function as illustrated below:
pbjs.setConfig({
ortb2: {
site: {
...
},
user: {
...
}
}
});
Use the setBidderConfig()
function to supply bidder-specific data.
For more information about the standard or more detailed examples, refer to First Party Data Feature.
IX bidder-specific FPD
FPD allows you to specify key-value pairs that are 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 that 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.
Continue to use IX bidder-specific First Party Data for IX deals. Global First Party Data is not yet supported in IX deals. Consult your IX representative with any questions.
Setting a Server Side Timeout
Setting a server-side timeout allows you to control the max length of time taken to connect to the server. The default value when unspecified is 50ms.
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: 50
}
});
The timeout value must be a positive whole number in milliseconds.
IX Prebid Server Adapter
Publishers who would like to retrieve IX demand via a Prebid Server instance can do so by adding IX to the list of bidders for a Prebid Server bid request, with a valid site ID. For example:
"imp": [
{
"id": "test2",
"banner": {
"format": [
{
"w": 300,
"h": 600
}
]
},
"ext": {
"ix": {
"siteId": "12345"
}
}
}
]
Important Prebid Server Note
Any party operating their own hosted Prebid Server instances must reach out to IX (prebid.support@indexexchange.com) to receive approval and customized setup instructions. Please do not send Prebid Server requests without first contacting us – you will not receive bid responses.
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)
Banner bids from Index have a TTL of 600 seconds while video bids have a TTL of 3 hours, after which time they become invalid.</br>
Note: Index supports the bid.exp
attribute in the bid response which allows our adapter to specify the maximum number of seconds allowed between the auction and billing notice. In the absence of the bid.exp
attribute, the TTL provided above applies.
FAQs
Why do I have to input size in adUnits[].bids[].params
for IX when the size is already in the ad unit?
If you are using Prebid.js version 5.0 and above, the size
parameter is not a required field. Only the siteID
is required, and it is stored with the sizes in the ad unit.
How can I view the bid request sent to IX by Prebid.js?
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
set up to bid. Now, in the network tab, search for requests to
casalemedia.com/cygnus
. These are the bid requests.