Beruflich Dokumente
Kultur Dokumente
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