OPENRTBINTEGRATIONGUIDE

REFERENCE
ThisarticlebrieflyexplainsOpenRTB,itspurpose,andhowbuyerscanusetheformattoperformrealtimebiddingwithinLiveRail.Afterreadingthisarticleyouwillknowif
usingOpenRTBisrightforyouandhowtoimplementit.

WHATISOPENRTB?
OpenRTBisanindustrystandardthataimstosimplifythebuyingandsellingofdigitalmedia.Thestandardsuggestsacommunicationformatthatcanbeusedto
communicateinformationabouttheavailableinventoryandalsoprovidestheabilityforbuyerstomakeabidontheinventory.OpenRTBwasbuilttoaddressthegrowing
needsofpublishersandadvertiserstosupportabroadrangeofadvertisingplatforms,devices,andadvertisingsolutions.Theimagebelowillustratesahighlevelworkflow
betweenapublisherandbuyerandtheinformationthatcanbeexchangedusingOpenRTB.

BENEFITSOFOPENRTB
Describesasingleformatthatcanbeusedtosupportmultipleadvertisingproductsincluding:display,video,andmobile.
BuyersarecertifiedtouseOpenRTBwithinLiveRail.ThisensurestheirOpenRTBimplementationworksacrossallLiveRailPublishers.
ForLiveRailpublishers,noadditionalintegrationisrequired.However,theOpenRTBbuyermustbecertifiedtoensureseamlessoperationontheLiveRailplatform.
TheOpenRTBbidrequestandbidresponsecommunicationincludesrichmetadatatoimprovetransparencyandwasdesignedspecificallyforrealtimebidding.

PREREQUISITES
1. DevelopmentResourcesBuyersimplementingOpenRTBshouldhavesufficientdevelopmentresources.
2. UnderstandingoftheOpenRTBspecificationThisdocumentfocusesontheareasofOpenRTBneededtointegratewithLiveRail.Asaresult,manyareasof
OpenRTBarenotaddressedhere.ItisrecommendtobeginbyunderstandingOpenRTBspecification2.2orabove.

STEPSTOIMPLEMENT

GETFAMILIARWITHOPENRTB
StartbyfamiliarizingyourselfwithOpenRTB2.2orhigher.Getasolidunderstandingofthebidrequestobjectandbidresponseobjectandtheirhierarchies.Also,see
chapter5oftheOpenRTBspecificationfordetailedjsonexamples.Afteryouarecomfortablewiththebidrequestandbidresponse,returntothisdocumenttoreview
whichobjectsandpropertiesareusedwhenintegratingwithLiveRail.

DATAFORMAT
LiveRailsupportsJSON(JavaScriptObjectNotation)astheformatforbidrequestandbidresponsedata.ThemimetypeforthestandardJSONrepresentationis
application/jsonandspecifiedinanHTTPheaderfieldas:
ContentType:application/json

RECEIVEANDPROCESSBIDREQUESTS
ArealtimebidopportunityisinitiatedwhenLiverailsendsabidrequesttoabuyerendpoint.Thisrequestindicatesthebuyerhasbeenselectedtoparticipateinan
auction.Thebidrequestobjectdescribestheadinventoryindetail.BuyersusetheinformationpassedintheBidRequesttodetermineiftheywanttobidontheinventory.

BidRequestObject
FIELD

TYPE

DESCRIPTION

id

string

ALiveRailgeneratedid.Thisidmustbereturnedinthebidresponseobject.

imp

arrayofobjects

LiveRailsupportsoneimpressionobjectperBidRequest.SeeImpressionobjectbelow.

at

integer

Theauctiontypeused.
1=FirstPrice
2=SecondPrice

site

object

Thesiteobjectisusedwheneveramobileappnameisnotprovided.Siteobjectissenttothebuyerwhen:
AURLisprovided,butnoappnameisprovided.
NeitheraURLorappnameisprovided.

app

object

Theappobjectisusedwheneveramobileappnameisprovided.Appobjectissenttothebuyerwhen:
AURLandappnamebothexist.
Appnameexists,butnoURLvalueexists.

device

object

Anobjectdescribingthedevice.SeeDeviceObjectbelow.

user

object

Anobjectdescribingtheuser.SeeUserObjectbelow.

ImpressionObject
FIELD

TYPE

VALUES

DESCRIPTION

Id

string

LiveRailsupportsasingleimpressionobjectperBidRequest.TheIdvaluewillalwaysbe1.

video

object

Avideoobjectisalwaysreturned.SeeVideoobjectbelowforacompletedescription.

displaymanager

string

LiveRail

Describesthesource

instl

integer

0,1

1indicatesinterstitial

pmp

object

0notinterstitial
Apmpobjectwillonlyexistiftherearedirectlynegotiateddeals.SeePMPobjectbelow.

VideoObject
FIELD

TYPE

VALUES

DESCRIPTION

mimes

arrayofstring

video/mp4,

Contentmimetypessupported.Mayincludeoneormoreofthe
acceptedvalues.

video/xflv,
video/webm,application/xshockwave,video/x
mswmv
minduration

integer

Minimumvideoaddurationinseconds.

maxduration

integer

Maximumvideoaddurationinseconds.

protocol

integer

Videobidresponseprotocolsupported.LiveRailsupportsVAST
2.0orVAST2.0Wrapper.
NOTE:Useprotocols
whenmultipleprotocolsare
supported.Itsuseisalsohighly
recommendedevenforonesince
thisprotocolattributeislikely
tobedeprecatedinafuture
version.

protocols

arrayofinteger

[2,5]

Videobidresponseprotocolsupported.LiveRailsupportsVAST
2.0andVAST2.0Wrapper.

integer

Widthofplayerinpixels.

integer

Heightofplayerinpixels.

startdelay

integer

0,1,2

Theoptionsforvideostartdelayvaluesasdefinedwithin
OpenRTB.
0=Preroll
1=Midroll

2=Postroll
linearity

integer

1,2

Indicatesifadmustbelinearornonlinear.
1=instream
2=overlay

minbitrate

integer

TheminimumbitraterequiredinKbps.Ifempty,thennominimum
hasbeenspecified.

playbackmethod

arrayofinteger

empty,1,2,3

Listofallowedplaybackmethods.Ifempty,thenallplayback
methodsareallowed.
1Autoplay,soundon
2Autoplay,soundoff
3Clicktoplay

companionad

arrayofobjects

Ifcompanionadsareavailable,theyareincludedasarrayof
bannerobjects.SeeBannerObjectbelow.

ext

customobject

0,1,2,3

Acustomobjectprovidingadditionaladtypeinformation.The
possiblevalueforkeyadtypeare:
0unknown
1Interstitial
2InBanner
3Instream

BannerObject
LiveRailonlysupportstheBannerObjectwhenembeddedwithintheVideoObject,whichrepresentsacompaniontothevideoad.TheBannerObjectuseddirectlywithin
theImpressionObjectwillbeignoredbyLiveRailasitisusedtorepresentadisplayorrichmediaad.
FIELD

TYPE

DESCRIPTION

integer

Widthofcompanionadinpixels.

integer

Heightofcompanionadinpixels.

id

integer

Identifierforthisbannerobject.Whenusingmultiplecompanionads,theidvaluebeginsat1andincrementsforeachobjectwithinthearrayofbannerobjects.

PMPObject
ThePMPObjectisonlyincludedwhentherearedirectdealsconfiguredfortheadsourceconnectionwithintheLiveRailplatform.
FIELD

TYPE

VALUES

DESCRIPTION

private_auction

integer

A1indicatesthereisadirectdealassociated
withthisbidder.
IftherearenodirectdealsthePMPobjectisnot
includedintheBidRequestobject.

deals

object

SeeDirectDealobject.

FIELD

TYPE

VALUES

DESCRIPTION

id

string

TheuniqueLiveRailidentifierofthisdirectly
negotiateddeal.SeeLiveRailDealIdformore
information.

bidfloor

float

Thebidfloor(cpm)forthisimpression.

bidfloorcur

string

USD

Currently,onlyusdcurrencyissupported.

at

integer

1,2

Theauctiontype.

DirectDealsObject

1=Firstprice
2=Secondprice

SiteObject
Thesiteobjectisincludedinthebidrequestwhentheadwillbeshownonawebsite.Thebidrequestincludeseitherasiteobjectoranappobjectbutnotboth.
FIELD

TYPE

VALUES

DESCRIPTION

id

string

TheuniqueidentifieroftheLiveRailpublisher.

domain

string

Thedomainofthewebsiteonwhichtheadwillbeshown.

cat

arrayofstring

IABdefinedcontent
categories.

Arrayofcontentcategoriesforthepublishersite.

page

string

URLofthepagetheimpressionwillbeshown.

publisher

object

SeePublisherobject.

content

object

SeeContentobject.

keywords

arrayofstring

Listofkeywordsdescribingthesite.

AppObject
Theappobjectisincludedinthebidrequestwhentheadwillbeshownwithinamobileapplication.Thebidrequestincludeseitherasiteobjectoranappobjectbutnot
both.
FIELD

TYPE

DESCRIPTION

id

string

TheuniqueidentifieroftheLiveRailpublisher.

name

string

Applicationname.

domain

string

Domainoftheapplication.

ver

string

Applicationversion.

bundle

string

Applicationbundleorpackagename.Intendedtobeauniqueidentifieracrossmultipleexchanges.

publisher

object

SeePublisherobject.

content

object

SeeContentobject.

keywords

arrayofstring

Listofkeywordsdescribingtheapp.

ContentObject
Describesthecontentinwhichtheadimpressionwillappear.
FIELD

TYPE

VALUES

DESCRIPTION

id

string

Contentidentifier.

title

string

Contenttitle.

url

string

TheURLofthecontent.

keywords

arrayofstring

Listofkeywordsdescribingthecontent.

string

SpecifiesthetypeofcontentasdescribedbytheIABQualityAssuranceGuidelines.

context

1. Video
2. Game
3. Music
4. Application
5. Text
6. Other
livestream

integer

0,1

Indicatesifcontentisalivestream.
0=Notalivestream
1=Livestream

len

integer

Lengthofcontentinseconds.

PublisherObject
FIELD

TYPE

VALUES

DESCRIPTION

id

string

TheuniqueidentifieroftheLiveRailpublisher.

cat

arrayofstring

TheidofanIABdefinedcontent
categories.

Arrayofcontentcategoriesforthepublisher.

domain

string

Publisherstopleveldomain(e.g.foo.com).

DeviceObject
FIELD

TYPE

VALUES

DESCRIPTION

ua

string

Browseruseragent.

ip

string

IPv4addressclosesttodevice.

dpidsha1

string

SHA1hashedplatformspecificID.ThisistheAndroidIDortheUDIDiniOS.

carrier

string

AValidMNCvalue.

CarrierorISPderivedfromtheIPaddress.SpecifiedusingtheMobileNetworkCode(MNC)

make

string

Devicemake.

model

string

Devicemodel.

os

string

Deviceoperatingsystem.

osv

string

Deviceoperatingsystemversion.

connectiontype

integer

0,1,2,3,4,5,6

Detecteddataconnectiontypeforthedevice.

0Unknown/Other
1Ethernet
2WirelessLAN
3CellulardataUnknownGeneration
4Cellulardata2G(Androidonly)
5Cellulardata3G(Androidonly)
6Cellulardata4G(Androidonly)
ext

customobject:

WillcontaintheAppleorGoogleIDFAvalueincleartext.

idfa
OnlysupportediniOS6oraboveandAndroidversionKitkatornewer.

*Note:Geoobject,achildofDevice,isnotcurrentlyused.BuyersmustuseI.P.toresolvelocation.

UserObject
FIELD

TYPE

DESCRIPTION

id

string

TheuniqueidentifierforthisuserinLiveRail.

buyeruid

string

Thebuyer'suserid(requiresacookiesyncwithLiveRail)

Note:LiveRailwillnotpassattributeswithnovalueswithinthebidrequest.
Forexample,withinthebidrequest,ifthe'connectiontype'attributeintheDeviceobjecthasnovalue,itwillnotbepassedinthebidrequest.

BIDRESPONSE
AfteryourapplicationreceivesthebidrequestfromLiveRail,yourapplicationmustreturnabidresponseorindicateanobid.
BidResponseStructure(LiveRailrequiredvaluesshowninred)

BidResponseObject
FIELD

TYPE

REQUIRED

VALUES

DESCRIPTION

Id

integer

Yes

Thisvalueshouldmatchthebidrequestid.Ifthisiddiffersfrom
BidRequest,thisresponsewillbeconsideredinvalidandbe
ignored.

seatbid

arrayofobjects

Yes

Multipleseatbidobjectsareallowedinaresponse,however,
LiveRailcurrentlyonlyusesoneseatbidobject.
Theseatbidobjectchosenwillcontain:bid.id=impression.id

Ifmultipleseatbidobjectsmeettheabovecriteriathenoneofthe
acceptableseatbidobjectsisselectedrandomly.

cur

string

Yes

USDonly

LiveRailcurrentlysupportsUSDonly.PleasespecifyUSD.Ifany
otherISOcurrencycodeisspecifiedthenthebidresponsewill
beignored.

nbr

integer

Seenobidreasoncodesforpossiblevalues.

Reasonfornotbidding.

SeatBidObject
FIELD

TYPE

REQUIRED

VALUES

DESCRIPTION

bid

arrayofobjects

Yes

seat

string

Yes

YourseatIDprovidedbyLiveRail.

Buyerswillreceivetheirseatidduringtheonboardingprocess.
Theseatvalueisrequiredandmustalwaysprovidedinthe
response.

FIELD

TYPE

REQUIRED

VALUES

DESCRIPTION

Id

string

Yes

Idofbidchosenbythebidderfortheirtrackingpurposes.
LiveRaildoesnotutilizethisvalue.

impid

string

Yes

Idoftheimpressiontowhichthisbidapplies.Thisvaluewill
matchtheimpressionidprovidedinthebidrequest.

price

float

Yes

Greaterthanzero.

Bidpriceincpm.

BidObject

Avalueequal,orlessthan,zerowillresultinthebidresponse
beingignored.
Theexceptionisifyou(forsomereason)haveafixedprice
agreementwiththepubliserinwhichcasethepriceprovidedwill
beignoredandthefixedpriceisusedinstead.
Bydefault,allpricesaresentintheclear.PleasecontactLiveRail
todiscussstepsforobfuscatingthepricevalue.
adm

string

Yes

ValidinlineVAST

ThisacompleteandvalidVASTXMLdocumentinline.
TheentireVASTresponseshouldbeencoded.
PleaserefertotheRTBIntegrationGuidefordetailedinstructions
onhowtoproperlyconfiguretheVASTresponseincludingthe
$WINNING_PRICEmacro.
Alsosupportedisthe${AUCTION_PRICE}macroasspecifiedby
theIABOpenRTBspecificationv2.2.Moredetailsinthe
SubstitutionMacrossectionbelow.

adomain

arrayofstring

Yes

Theadvertiserlandingpage.

dealid

string

Ifthebidrequestincludesadealidthenthisvalueisrequired
andmustmatchthedealidvalue.

ext

customobject:

LiveRailprovidedbuyerid.

ThisbuyeridisprovidedbyLiveRailaspartofaDeal.Thebuyer
idisusedforDealreportingwithinLiveRailandisrecommended
onlywhenusingtheDealfeature.

buyerid

SubstitutionMacros
BelowisalistofsubstitutionmacrosthatcanbepassedintheVASTXMLinlinewithinthe'adm'attribute.Thesemacros,ifpresentintheadmattribute,willbereplaced
withthecorrespondingvaluebelow.
${AUCTION_ID}:IDofthebidrequestfrom"id"attribute
${AUCTION_BID_ID}:IDofthebidfrom"bidid"attribute
${AUCTION_IMP_ID}:IDoftheimpressionjustwonfrom"impid"attribute
${AUCTION_SEAT_ID}:IDofthebidder'sseatforwhomthebidwasmade
${AUCTION_AD_ID}:IDoftheadmarkupthebidderwishestoservefrom"adid"attribute
${AUCTION_PRICE}:Settlementpriceusingthesamecurrencyandunitsasthebid
${AUCTION_CURRENCY}:Thecurrencyusedinthebid
Obfuscation
${AUCTION_PRICE}isobfuscatedbypassingaratioinsteadofthewinningpriceintheclear.
Ratio=ClearingPrice/BidPrice(sameasthe$(Winning_Price)macro)
ExampleBidResponse
{
"id":"1",
"seatbid":[
{
"bid":[
{
"id":"1",
"impid":"1",
"price":9.43,
"dealid":"1234",
"adm":"YOURENCODEDINLINEVASTXML",
"adomain":[
"advertiserdomain.com/"
],
"ext":{
"buyerid":"YOURBUYERIDPROVIDEDBYLIVERAIL"
}
}
],
"seat":"786"
}
],
"bidid":"t3456786",
"cur":"USD"
}

Let'sreviewafewkeypointswhenformingyourBidResponse:
"id"fieldneedstomatchtheidvaluefromtheBidRequest.
"impid"alsoneedstomatchtheimpressionidvaluefromtheBidRequest.
Ifusingadealid,youwillneedtoprovidethevalueofthedealasconfiguredinLiveRail.SeeDealId.

NOBIDRESPONSES
Bidderscanrespondwithanyofthefollowingthatwillbeconsidereda'nobid''withinLiveRail.Itisimportanttouseanyofthefollowingresponsestoexplicitlysignalyou
donotwanttobidontheimpression,otherwisetheresponsemaybeinterpretedasanerror.
HTTP204NoContent

AnemptyJSONobject:"{}"
Awellformednobidresponse:{"id":"1234567890","seatbid":[]}
Awellformednobidresponsewithareasoncode:{"id":"1234567890","seatbid":[],"nobid_code":2}
200OK
302Redirect

LIVERAILVALIDATION
ThisprocessisdesignedtoensureyourapplicationworkswithinLiveRailasexpected.PleasecontactyourLiveRailaccountmanagerformoreinformationoncertification
steps.

SEEALSO
IABRTBProject
OpenRTBrepositoryforlatestversion
LiveRailRTBIntegrationGuideline