How to use AdButler to bid on OpenRTB impressions

AdButler's Programmatic Solution add-on lets you use any of your AdButler zones to bid on impressions via OpenRTB 2.5.

You must add the Programmatic Solution add-on to your subscription to access AdButler's programmatic bidding features. For information on adding add-ons, read How to change your subscription.

All OpenRTB endpoints must be requested via HTTP POST, and all data must be passed in JSON format.

Bid Request

This is the main JSON object that will be passed into the OpenRTB endpoint. Any fields not marked 'required' are optional. However, the more data that is passed, the more accurate your targeting and scheduling options will be.

The example below shows the fields that we support in a bid request.

{
    id: string, //required
    at: 1 // Only first-price auctions supported right now
    imp: {
        id: string, //required
        video: {}, //Video Object
        banner: {}, //Banner Object
        ext: {
            keywords: string[] // For AdButler Keyword Targeting
        }
    },
    app: {}, // App Object
    site: {}, // Site Object
    device: {
        sh: int,
        sw: int,
        spr: float,
        aduid: string,
        dnt: int,
        geo: {
            lat: float,
            lon: float
        },
        language: string,
        os: string,
        osv: string,
        make: string,
        model: string,
        devicetype: int,
        connectiontype: int,
        carrier: string,
        mccmnc: string,
        ua: string,
        ip: string
    },
    user: {
        yob: int,
        gender: string,
    },
    source: {
        ext: {
            schain: [
                {} // Supply Chain Objects
            ]
        }
    },
    regs: {
        coppa: int
    },
    ext: {
        extra: string, // AdButler Extra Data
        customParam1: string,
        customParam2: string,
        customParam3: string,
        customParam4: string,
        customParam5: string, //AdButler Custom Click Tracking params
    }

}

Video Object

This object is passed in as part of the imp field above. It is required for Video zones. Any fields passed in this object will override any Video RTB settings that are already set in the zone.

{
    mimes: string[],
    minduration: int,
    maxduration: int,
    protocols: int[] // Only support 2 and 3 currently
    w: int,
    h: int,
    startdelay: int,
    skipmin: int,
    skipafter: int,
    minbitrate: int,
    maxbitrate: int,
    linearity: int,
    skip: int,
    boxingallowed: int,
    api: int[]
}

This object is passed in as part of the imp field above. It is required for Standard zones.

{
    format: [
        {
            w: int,
            h: int
        }
    ],
    api: int[]
}

App Object

This object is passed in as part of the bid request. It should be passed along when the traffic is from an app.

App Object
{
    cat: string[],
    bundle: string,
    domain: string,
    storeurl: string,
    ver: string,
    name: string
}

Site Object

This object is passed in as part of the bid request. It should be passed along when the traffic is from a website (both mobile and desktop).

Site Object
{
    cat: string[],
    name: string,
    ref: string
}

Examples

Example bid requests and response:

Example bid request

{
    "id": "63_85820_1571331626",
    "at": 1,
    "tmax": 800,
    "imp": [
        {
            "id": "1",
            "bidfloor": 0.5,
            "metric": [],
            "banner" : {
                "format" : [
                    {
                        "w" : 300,
                        "h" : 250
                    }
                ]
            },
            "secure": 0,
            "pmp": {}
        }
    ],
    "app": {
        "id": "com.example",
        "bundle": "com.example",
        "cat": [
            "IAB1",
            "IAB7"
        ],
        "content": {},
        "publisher": {
            "id": "1234"
        }
    },
    "device": {
        "geo": {},
        "dnt": 0,
        "lmt": 0,
        "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:71.0) Gecko/20100101 Firefox/71.0",
        "devicetype": 2,
        "ip": "1.1.1.1"
    },
    "user": {},
    "source": {
        "fd": 0,
        "ext": {
            "schain": {
                "ver": "1.0",
                "complete": 0,
                "nodes": [
                    {
                        "asi": "domain.com",
                        "sid": "1234",
                        "rid": "63_85820_1571331626",
                        "hp": 1
                    }
                ]
            }
        }
    },
    "regs": {
        "coppa": 0
    }
}

Example bid response

{
    "id": "63_85820_1571331626",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "18632_518889990",
                    "impid": "1",
                    "price": 1,
                    "w": "300",
                    "h": "250",
                    "adm": "AD_MARKUP",
                    "burl": "IMPRESSION_TRACKER"
                }
            ]
        }
    ]
}

If your service does not support the burl Billing Notice field, which was added in OpenRTB v2.5, you can add the ;rtbv=2.3 parameter to your OpenRTB endpoint. When that parameter is set, we will add the IMPRESSION TRACKER to the adm field instead.

How to get zone endpoints

Standard/Display

Go to the relevant zone (Your AdButler > Publishers > Your Publisher > Your Zone).
Click on Get Zone Tags/JSON Ad API on the right menu. The Zone Tags window will appear.
Select OpenRTB Endpoint in the Type dropdown menu.

Getting the OpenRTB endpoint of a standard zone

This tag serves as the endpoint for that zone. All other parameters that are passed in must be part of the POST body.

Video/VAST

Go to the relevant VAST zone (Your AdButler > Publishers > Your Publisher > Your VAST Zone).
Click Get Zone Link on the right menu. The Zone Link window will appear.
Click on the OpenRTB Endpoint checkbox. If this option was unchecked, a new tag will be generated.

Getting the OpenRTB endpoint of a VAST zone