AdButler Open RTB endpoints

With our Programmatic Add-on, you can use any of your AdButler zones, Standard or VAST, to bid on impressions via OpenRTB 2.5.

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

Please see the example below to get a comprehensive view of the fields that we support in the Bid Request.

Bid Request

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

{
    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. Please note that 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[]
}

Banner Object

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 coming 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 coming 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"
                }
            ]
        }
    ]
}

NOTE: 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 this is set we will add the IMPRESSION TRACKER to the adm field.

Getting Your Endpoints

Display

  • Navigate to your zone
  • Click the Get Zone Tags button in the top-right
  • Change the Type dropdown to "OpenRTB"

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

Video

  • Navigate to your VAST zone
  • Click the Get Zone Tags button in the top-right
  • Check the "OpenRTB Endpoint" box

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


Can't find what you're looking for?

Send us an email

hello@adbutler.com

Visit the blog

For more ad serving tips, industry news and AdButler insights.