rtb project - iab tech labiabtec5/wp-content/uploads/2016/07/openr… · types to bid request,...
TRANSCRIPT
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page1
RTB Project OpenRTB Dynamic Native Ads API Specification Version 1.2 Final Version July 2017
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page2
Introduction
TheNativeAdssub-committeeoftheIABOpenRTBProjectassembledinMay2014todevelopanewsupplementaryAPIspecificationforcompaniesinterestedinanopenprotocolfortheautomatedtradingofNativeAdsenabledmediaacrossabroaderrangeofplatforms,devices,andadvertisingsolutions.Thisdocumentistheculminationofthoseefforts.
ABOUTTHEIAB’STECHNOLOGYLAB
TheIABTechnologyLaboratoryisanonprofitresearchanddevelopmentconsortiumchargedwithproducingandhelpingcompaniesimplementglobalindustrytechnicalstandardsandsolutions.ThegoaloftheTechLabistoreducefrictionassociatedwiththedigitaladvertisingandmarketingsupplychainwhilecontributingtothesafegrowthofanindustry.
TheIABTechLabspearheadsthedevelopmentoftechnicalstandards,createsandmaintainsacodelibrarytoassistinrapid,cost-effectiveimplementationofIABstandards,andestablishesatestplatformforcompaniestoevaluatethecompatibilityoftheirtechnologysolutionswithIABstandards,whichfor18yearshavebeenthefoundationforinteroperabilityandprofitablegrowthinthedigitaladvertisingsupplychain.
FurtherdetailsabouttheIABTechnologyLabcanbefoundat:https://iabtechlab.com/.TheOpenRTBWorkGroupisaworkinggroupwithintheIABTechnologyLab.
Thisdocumentcanbefoundathttps://iabtechlab.com/specifications-guidelines/openrtb-dynamic-native-ads-api-1-2/
IABContactInformation:
License
OpenRTBSpecificationbyOpenRTBislicensedunderaCreativeCommonsAttribution3.0License,basedonaworkatopenrtb.info.Permissionsbeyondthescopeofthislicensemaybeavailableathttp://openrtb.info.Toviewacopyofthislicense,visithttp://creativecommons.org/licenses/by/3.0/orwritetoCreativeCommons,171SecondStreet,Suite300,SanFrancisco,CA94105,USA.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page3
TableofContentsChangeLog
BeforeYouGetStarted
1Introduction
1.1Mission/Overview
1.2Credits/ProjectHistory
1.3Resources
1.4VersionHistory
2NativeAdsBasics
2.1In-FeedAdUnits
2.2DataFormat
2.3Versioning
2.4CustomizationandExtensions
3BidRequestDetails
3.1NativeObjectHierarchy
4NativeAdRequestMarkupDetails
4.1NativeMarkupRequestObject
4.2AssetRequestObject
4.3TitleRequestObject
4.4ImageRequestObject
4.5VideoRequestObject
4.6DataRequestObject
4.7EventTrackersRequestObject
5NativeAdResponseMarkupDetails
5.1NativeMarkupResponseObject
5.2AssetResponseObject
5.3TitleResponseObject
5.4ImageResponseObject
5.5DataResponseObject
5.6VideoResponseObject
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page4
5.7LinkResponseObject
5.8EventTrackerResponseObject
6BidRequest/ResponseSamples
6.1SocialContext,ClickoutResponse
BidRequest
BidResponse
6.2ContentContext,VideoResponse
BidRequest
BidResponse
6.3Third-PartyAdServingExample
BidRequest
BidResponse
WhatShouldbeReturnedbytheAssetsURL
7ReferenceLists/Enumerations
7.1ContextTypeIDs
7.2ContextSubTypeIDs
7.3PlacementTypeIDs
7.4DataAssetTypes
7.5ImageAssetTypes
7.6EventTypesTable
7.7EventTrackingMethodsTable
8ImplementationNotes
8.1MultiPlacementBidRequests
ChangeLogVersion Date SectionLink Change
1.0 Jan2015 OriginalVersion
1.1 Oct2015 Variousclericalfixesandclarifications,standardizedcreativeelementlengths/sizes/aspectratiosintheassetsub-objects,addednewcontextandplacement
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page5
typestobidrequest,notedthatdirect-objectrepresentationissupportedalongwithstring-encoded.See1.1specforfurtherchangelogdetails.
1.2 Mar2017 Request Aspreviewedin1.1,deprecatingtheAdUnitandLayoutIDfields-theywerereplacedin1.1withPlacementandContext.
1.2 Mar2017 EventTrackersRequest,Response
Addnewsupportfordeclaredtypesofeventtrackinginthebidrequestandanarrayofresponsesfortrackingintheresponse.Markingpreviousimptrackersandjstrackerastobedeprecated.
1.2 Mar2017 Request,Response Addedsupportforsupplysourcetoindicatewhethertheysupportdisplayingalinktoacustomprivacynotice,andfortransmittingsaidURLintheresponse.
1.2 Mar2017 Request,Response,Title,Data,Image
Addedsupportforthird-partyadserving/dynamiccreativebyestablishingawaytorespondwithaURLtoretrievetheassetsratherthanincludingalltheassetsinline.
1.2 Mar2017 Examples Updatedexamplestoreflectallabovechanges
1.2 July2017 Request,Response AddedsupportforDynamicContentSpecificationasanalternatemethodforthird-partyadserving,inbeta.
BeforeYouGetStartedThisspecificationcontainsadetailedexplanationofasub-protocoloftheOpenRTBreal-timebiddinginterface.Notallobjectsarerequired,andeachobjectmaycontainanumberofoptionalparameters.Toassistafirsttimereaderofthespecification,wehaveindicatedwhichfieldsareessentialtosupportaminimumviablerealtimebiddinginterfaceforvariousscenarios.
Aminimalviableinterfaceshouldincludetherequiredandrecommendedparameters,butthescopefortheseparametersmaybelimitedtospecificscenarios.Inthesecases,thescopewillbequalifiedwiththeapplicablescenarios(e.g.,requiredfornativeimpressionsandrecommendedfornativeimpressions).Conversely,ifthescopeisnotqualified,itappliestoallscenarios.
Optionalparametersmaybeincludedtoensuremaximumvalueisderivedbytheparties.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page6
IMPORTANT:Sincerecommendedparametersarenotrequired,theymaynotbeavailablefromallsupplysources.ItissuggestedthatallpartiestoOpenRTBtransactioncompletetheintegrationchecklist(pleaserefertoOpenRTB)toidentifywhichparametersthesupplysidesupportsinthebidrequest,andwhichparametersthedemandsiderequiresforaddecisioning.
1Introduction
1.1Mission/OverviewThemissionoftheOpenRTBNativeprojectistospurstandardizationandgreatergrowthintheReal-TimeBidding(RTB)marketplaceforNativeAdsbyprovidingopenindustrystandardsforcommunicationbetweenbuyersofadvertisingandsellersofpublisherinventory.
Thisspecificationisasub-protocolofOpenRTBtoallowforthedeliveryofnativeadvertisingformats,astheirspecificsdifferfrompublishertopublisher.InMay2013,aseparateIABsubcommitteewasformedtodefinetherequestandresponsestructuresofnativeadunits;version1.0waspublishedinearly2015.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page7
Version1.1isdesignedtofixerrors,makeclarifications,andpromotefurtheradoptionthroughrefinedstandardizationofassetsandclassificationfields.
Version1.2addssupportforthird-party/dynamiccreatives,morerobustevent-trackingsupport,privacyopt-outinformationsharing,andmakesotherminorenhancementsasnotedinthechangelog.
1.2Credits/ProjectHistory ThisdocumenthasbeendevelopedbytheIABTechnologyLab’sOpenRTBNativeSubgroup.TheOpenRTBWorkingGroupmissionandparticipationlistcanbereviewedat:http://www.iab.com/guidelines/real-time-bidding-rtb-project/
NealRichter&AvinashShahdadpuri,RubiconProject
JimButler,Nexage
IlanaGrumer[current],AdamMorgenlender[former]&GaborCselle[former],Twitter
NarayananBalakrishnan&AnandNarayanan,InMobi
GiuseppeDiMauro,PubMatic
IlyaKaplun,VisibleMeasures
JenniferLum,Adelphic
WesleyBiggs,Byyd
BenoitGrouchko&ElisabethRotrou[former]&PierreNicolas,Criteo
DavidHernandez,AOL
RajaramanPeriasamy,RocketFuel
JinYu,OpenX
AntonRoslov,Phorm
AndražTori,Zemanta
OsvaldoDoederlein,Google
BenuShroff,Turn
CurtLarson,Sharethrough
KuldeepKapade,AdsNative
ByronEllis,Spongecell
MichaelFeeley,CoryLaMay&JayantKumar,Bidtellect
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page8
1.3Resources
Resource Location
OpenRTBWebsite ttps://iabtechlab.com/openrtb/
OpenRTBNativeAdsProjectPage http://github.com/openrtb/OpenRTB/NativeAds.html
Developer/ProductManagerMailingList
http://groups.google.com/group/openrtb-native
MakingSenseofProgrammaticNative(“OpenRTBfornativefordummies”)
http://www.sharethrough.com/guides/programmatic-native/
IABDeep-DiveonIn-FeedAds http://www.iab.net/media/file/IAB_Deep_Dive_on_InFeed_Ad_Units.pdf
IABNativeAdvertisingPlaybook http://www.iab.net/media/file/IAB-Native-Advertising-Playbook2.pdf
GuidetoNative1.1 http://nativeadvertising.com/openrtb-2-4-and-native-1-1-the-new-iab-standards-that-are-allowing-native-ads-to-scale/
1.4VersionHistoryVersion0.99.10.24PUBLICCOMMENTDRAFTOctober24,2014
Version0.99.10.27PUBLICCOMMENTDRAFTOctober27,2014
Version1.0.0.0EXTERNALDRAFTNovember19,2014
Version1.0.0.1EXTERNALDRAFTDecember14,2014
Version1.0.0.2FINALDRAFTJanuary23,2015
Version1.1FINALDRAFTMarch22,2015
Version1.2PUBLICCOMMENTDRAFTApril,2017
Version1.2FINALDRAFTJuly2017
2NativeAdsBasicsNativeadvertisingisanonlineadvertisingmethodinwhichtheadvertiserattemptstogainattentionbyprovidingcontentinthecontextoftheuser'sexperience.Nativeadformatsmatchboththeformandfunctionoftheuserexperienceinwhichitisplaced.Thisisincontrasttotraditionalbannerorinterstitialsads,whicharedisplayedinaseparatespaceofpredefinedanduniversalsize,withoutregardtotheirsurroundings.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page9
2.1In-FeedAdUnitsTohelpdefineandclarifythetypesandcategoriesofnativeadvertising,theIABpublishedaDeepDiveonIn-FeedAdUnitsinJuly2015.Version1.1andforwardoftheNativespecusetheseconceptstodefinethedefinitionsofadtypes,detailedbelowasContextandPlacementType,whicharereplacingthepreviousLayoutIDandAdUnitID,whichweredefinedinNative1.0andbasedontheoriginalNativeAdvertisingPlaybook.
Wherefound
Mostcommonadtypes/content
objects
Mostcommontypesoflinks
Representativefeedview
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page10
2.2DataFormatAsthisspecificationoutlinesanoptionalsub-protocolofthemainOpenRTBprotocolpayload,theformatmustfollowthatofitsparent.PleaserefertothemainOpenRTBspecificationfordetailsofvariousformatsthatmaybeused
2.3VersioningTheNativeObjectintheBidRequest(OpenRTBcontainsa“ver”fielddefiningtheversionoftheOpenRTBnativeextension.
2.4CustomizationandExtensionsTheOpenRTBNativeAdsspecallowsforexchangespecificcustomizationandextensionsofthespecification.Anyobjectmaycontainextensions.Inordertokeepextensionfieldsconsistentacrossplatforms,theyshouldconsistentlybenamed“ext”.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page11
3BidRequestDetailsRTBtransactionsareinitiatedwhenanexchangeorothersupplysourcesendsabidrequesttoabidder.Thebidrequestconsistsofabidrequestobject,atleastoneimpressionobject,andmayoptionallyincludeadditionalobjectsprovidingimpressioncontext.
3.1NativeObjectHierarchyFollowingistheobjecthierarchyforabidrequest.ThenewNativeObjectisanotheroptionalelementoftheimpressionobject,andcanbespecifiedasanalternativetoorinconjunctionwithabannerobjectorvideoobject.
4NativeAdRequestMarkupDetails
4.1NativeMarkupRequestObjectTheNativeObjectdefinesthenativeadvertisingopportunityavailableforbidviathisbidrequest.ItwillbeincludedasaJSON-encodedstringinthebidrequest’simp.nativefieldorasadirectJSONobject,dependingonthechoiceoftheexchange.WhileOpenRTB2.xofficiallysupportsonlyJSON-encodedstrings,manyexchangeshaveimplementedaformalobject.Checkwithyourintegrationdocs.
TheDefaultcolumndictateshowoptionalparametersshouldbeinterpretedifexplicitvaluesarenotprovided.
Field Scope Type Default Description
ver optional string 1.2 VersionoftheNativeMarkupversioninuse.
Bid Request Object
BannerObject
NativeObject
Video ObjectAND/
AND/ Banner
Impression Object
(other OpenRTB objects)
(other OpenRTB objects)
Request
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page12
context recommended integer - Thecontextinwhichtheadappears.SeeTableofContextIDsbelowforalistofsupportedcontexttypes.
contextsubtype optional integer - Amoredetailedcontextinwhichtheadappears.SeeTableofContextSubTypeIDsbelowforalistofsupportedcontextsubtypes.
plcmttype recommended integer - Thedesign/format/layoutoftheadunitbeingoffered.SeeTableofPlacementTypeIDsbelowforalistofsupportedplacementtypes.
plcmtcnt optional integer 1 ThenumberofidenticalplacementsinthisLayout.ReferSection8.1MultiplacementBidRequestsforfurtherdetail.
seq optional integer 0 0forthefirstad,1forthesecondad,andsoon.NotethiswouldgenerallyNOTbeusedincombinationwithplcmtcnt-eitheryouareauctioningmultipleidenticalplacements(inwhichcaseplcmtcnt>1,seq=0)oryouareholdingseparateauctionsfordistinctitemsinthefeed(inwhichcaseplcmtcnt=1,seq=>=1)
assets required arrayofobjects
- AnarrayofAssetObjects.Anybidresponsemustcomplywiththearrayofelementsexpressedinthebidrequest.
aurlsupport optional int 0 Whetherthesupplysource/impressionsupportsreturninganassetsurlinsteadofanassetobject.0ortheabsenceofthefieldindicatesnosuchsupport.
durlsupport optional int 0 Whetherthesupplysource/impressionsupportsreturningadcourlinsteadofanassetobject.0ortheabsenceofthefieldindicatesnosuchsupport.Beta
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page13
feature.
eventtrackers optional arrayofobjects
- Specifieswhattypeofeventtrackingissupported-seeEventTrackersRequestObject
privacy
recommended integer 0 Setto1whenthenativeadsupportsbuyer-specificprivacynotice.Setto0(orfieldabsent)whenthenativeaddoesn’tsupportcustomprivacylinksorifsupportisunknown.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
Note:PriortoVERSION1.1,thespecificationcouldbeinterpretedasrequiringthenativerequesttohavearootnodewithasinglefield“native”thatwouldcontaintheobjectaboveasitsvalue.TheNativeMarkupRequestObjectspecifiedaboveisnowtherootobject.
4.2AssetRequestObjectThemaincontainerobjectforeachassetrequestedorsupportedbyExchangeonbehalfoftherenderingclient.Anyobjectthatisrequiredistobeflaggedassuch.Onlyoneofthe{title,img,video,data}objectsshouldbepresentineachobject.Allothersshouldbenull/absent.TheidistobeuniquewithintheAssetObjectarraysothattheresponsecanbealigned.
Tobemoreexplicit,itistheIDofeachassetobjectthatmapstheresponsetotherequest.Soifarequestforatitleobjectissentwithid1,thentheresponsecontainingthetitleshouldhaveanidof1.
Sinceversion1.1ofthespec,therearerecommendedsizes/lengths/etcwithsomeoftheassettypes.ThegoalforassetrequirementsstandardizationistofacilitateadoptionofnativebyDSPsbylimitingthediversetypes/sizes/requirementsofassetstheymusthaveavailabletopurchaseanativeadimpression.Whilegreatdiversitymayexistinpublishers,advertisers/DSPscannotbeexpectedtoprovideinfiniteheadlinelengths,thumbnailaspectratios,etc.Whilewehavenotgoneasfarascreatingasinglestandard,we'vehonedinonafewoptionsthatcoverthemostcommoncases.SSPscandeviatefromthesestandards,butshouldunderstandtheymaylimitapplicableDSPdemandbydoingso.DSPsshouldfeelconfidentthatiftheysupportthesestandardsthey'llbeabletoaccessmostnativeinventory.
Field Scope Type Default Description
id required int - UniqueassetID,assignedbyexchange.Typicallyacounterfor
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page14
thearray.
required optional int 0 Setto1ifassetisrequired(exchangewillnotacceptabidwithoutit)
title recommended1
object - Titleobjectfortitleassets.SeeTitleObjectdefinition.
img recommended1
object - Imageobjectforimageassets.SeeImageObjectdefinition.
video optional1 object - Videoobjectforvideoassets.SeetheVideorequestobjectdefinition.Notethatin-stream(iepreroll,etc)videoadsarenotpartofNative.Nativeadsmaycontainavideoastheadcreativeitself.
data recommended1
object - Dataobjectforbrandname,description,ratings,pricesetc.SeeDataObjectdefinition.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
1:eachassetobjectmaycontainonlyoneoftitle,img,dataorvideo.
4.3TitleRequestObjectTheTitleobjectistobeusedfortitleelementoftheNativead.
Field Scope Type Default Description
len required integer - Maximumlengthofthetextinthetitleelement.Recommendedtobe25,90,or140.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page15
4.4ImageRequestObjectTheImageobjecttobeusedforallimageelementsoftheNativeadsuchasIcons,MainImage,etc.RecommendedsizesandaspectratiosareincludedintheImageAssetTypessection.
Field Scope Type Default Description
type optional integer - TypeIDoftheimageelementsupportedbythepublisher.Thepublishercandisplaythisinformationinanappropriateformat.SeeTableImageAssetTypes.
w optional integer - Widthoftheimageinpixels.
wmin recommended integer - Theminimumrequestedwidthoftheimageinpixels.Thisoptionshouldbeusedforanyrescalingofimagesbytheclient.Eitherworwminshouldbetransmitted.Ifonlywisincluded,itshouldbeconsideredanexactrequirement.
h optional integer - Heightoftheimageinpixels.
hmin recommended integer - Theminimumrequestedheightoftheimageinpixels.Thisoptionshouldbeusedforanyrescalingofimagesbytheclient.Eitherhorhminshouldbetransmitted.Ifonlyhisincluded,itshouldbeconsideredanexactrequirement.
mimes optional arrayofstrings
Alltypes
allowed
WhitelistofcontentMIMEtypessupported.PopularMIMEtypesinclude,butarenotlimitedto“image/jpg”“image/gif”.
EachimplementingExchangeshouldhavetheirownlistofsupportedtypesintheintegrationdocs.SeeWikipedia'sMIMEpageformoreinformationandlinkstoallIETFRFCs.
Ifblank,assumealltypesare
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page16
allowed.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
4.5VideoRequestObjectThevideoobjecttobeusedforallvideoelementssupportedintheNativeAd.ThiscorrespondstotheVideoobjectofOpenRTB.Exchangeimplementerscanimposetheirownspecificrestrictions.HerearetherequiredattributesoftheVideoObject.ForoptionalattributespleaserefertoOpenRTB.
Field Scope Type Default Description
mimes required array
of
string
ContentMIMEtypessupported.
PopularMIMEtypesinclude,butarenotlimitedto“video/x-ms-wmv”forWindowsMedia,and“video/x-flv”forFlashVideo,or“video/mp4”.Notethatnativefrequentlydoesnotsupportflash.
minduration required integer - Minimumvideoaddurationinseconds.
maxduration required integer - Maximumvideoaddurationinseconds.
protocols required arrayofintegers
- Anarrayofvideoprotocolsthepublishercanacceptinthebidresponse.SeeOpenRTBTable‘VideoBidResponseProtocols’foralistofpossiblevalues.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page17
4.6DataRequestObjectTheDataObjectistobeusedforallnon-coreelementsofthenativeunitsuchasBrandName,Ratings,ReviewCount,Stars,Downloadcount,descriptionsetc.Itisalsogenericforfuturenativeelementsnotcontemplatedatthetimeofthewritingofthisdocument.Insomecases,additionalrecommendationsarealsoincludedintheDataAssetTypestable.
Field Scope Type Default Description
type required integer - TypeIDoftheelementsupportedbythepublisher.Thepublishercandisplaythisinformationinanappropriateformat.SeeDataAssetTypestableforcommonlyusedexamples.
len optional integer - Maximumlengthofthetextintheelement’sresponse.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
4.7EventTrackersRequestObjectTheeventtrackersobjectspecifiesthetypesofeventsthebiddercanrequesttobetrackedinthebidresponse,andwhichtypesoftrackingareavailableforeacheventtype,andisincludedasanarrayintherequest.
Field Scope Type Default Description
event required integer - Typeofeventavailablefortracking.SeeEventTypestable.
methods required arrayofintegers
- Arrayofthetypesoftrackingavailableforthegivenevent.SeeEventTrackingMethodstable.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthis
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page18
specification
5NativeAdResponseMarkupDetailsThestructureandcontentsoftheBidResponsearethesameasintheOpenRTBstandard.Thedifferenceisinhowtheadcreativeisreturned.ThenativecreativeshallbereturnedasaJSON-encodedstringintheadmfieldoftheBidObject.NotesomeimplementershavechosentouseadirectobjectinanewfieldratherthanJSONencodedstring.
5.1NativeMarkupResponseObjectThenativeobjectisthetoplevelJSONobjectwhichidentifiesanativeresponse.Thenativeobjecthasfollowingattributes:Field Scope Type Default Description
ver recommended string “1.2” VersionoftheNativeMarkupversioninuse.
assets recommended arrayofobjects
- Listofnativead’sassets.Requiredifnoassetsurl.Recommendedasfallbackevenifassetsurlisprovided.
assetsurl1 optional string - URLofanalternatesourcefortheassetsobject.TheexpectedresponseisaJSONobjectmirroringtheassetsobjectinthebidresponse,subjecttocertainrequirementsasspecifiedintheindividualobjects.Wherepresent,overridestheassetobjectintheresponse.
dcourl optional string URLwhereadynamiccreativespecificationmaybefoundforpopulatingthisad,pertheDynamicContentAdsSpecification.NotethisisabetaoptionastheinterpretationoftheDynamicContentAds
1The provided “assetsurl” or “dcourl” should be expected to provide a valid response when called in any context, including importantly the brand name and example thumbnails and headlines (to use for reporting, blacklisting, etc), but it is understood the final actual call should come from the client device from which the ad will be rendered to give the buyer the benefit of the cookies and header data available in that context.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page19
SpecificationandhowtoassignthoseelementsintoanativeadisoutsidethescopeofthisspecandmustbeagreedofflinebetweenthepartiesorasmaybespecifiedinafuturerevisionoftheDynamicContentAdsspec.Wherepresent,overridestheassetobjectintheresponse.
link required object - DestinationLink.Thisisdefaultlinkobjectforthead.Individualassetscanalsohavealinkobjectwhichappliesiftheassetisactivated(clicked).Iftheassetdoesn’thavealinkobject,theparentlinkobjectapplies.SeeLinkObjectDefinition
imptrackers optional arrayofstrings
- ArrayofimpressiontrackingURLs,expectedtoreturna1x1imageor204response-typicallyonlypassedwhenusing3rdpartytrackers.Tobedeprecated-replacedwitheventtrackers.
jstracker optional string - OptionalJavaScriptimpressiontracker.ThisisavalidHTML,Javascriptisalreadywrappedin<script>tags.Itshouldbeexecutedatimpressiontimewhereitcanbesupported.Tobedeprecated-replacedwitheventtrackers.
eventtrackers optional Arrayofobjects
- Arrayoftrackingobjectstorunwiththead,inresponsetothedeclaredsupportedmethodsintherequest.Replacesimptrackersandjstracker,tobedeprecated.
privacy
optional string - Ifsupportwasindicatedintherequest,URLofapageinformingtheuseraboutthebuyer’stargetingactivity.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSON
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page20
agreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
Note:PriortoVERSION1.1,thenativeresponse’srootnodewasanobjectwithasinglefield“native”thatwouldcontaintheobjectaboveasitsvalue.TheNativeObjectspecifiedaboveisnowtherootobject.Note re: assetsurl format responses: In the case of assetsurl or dcourl (beta) bidding, since the ultimate buyer/creative engine cannot alter the assets response based on the details inside the assets request (as it does not receive said request), it is critical that all required assets are provided, and such communications will need to be handled offline for recommended/optional elements. In the normal embedded response, certain attributes of the response are assumed based on matching the ID of the asset object in the response to the ID of the asset object in the request. Since the asset response will not be reading the asset request directly in this implementation, that information is added as option in the below object definitions and marked for that use case. It is also recommended that where the standard specifies multiple options for an element, that all options be provided. IE all 4 supported thumbnail aspect ratios and all 3 supported title lengths. The ID component of the asset responses can be omitted. Note that this change to provide the metadata description of the asset in the response, rather than using the asset ID to implicitly specify that, may be reflected into the inline version of responses in a future version to align the two methods of replying. Making that change now would break backwards compatibility of the inline response mechanism.
5.2AssetResponseObjectCorrespondstotheAssetObjectintherequest.ThemaincontainerobjectforeachassetrequestedorsupportedbyExchangeonbehalfoftherenderingclient.Anyobjectthatisrequiredistobeflaggedassuch.Onlyoneofthe{title,img,video,data}objectsshouldbepresentineachobject.Allothersshouldbenull/absent.TheidistobeuniquewithintheAssetObjectarraysothattheresponsecanbealigned.
Field Scope Type Default Description
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page21
id optional int - Optionalifassetsurl/dcourlisbeingused;requiredifembeddedassetisbeingused.
required optional int 0 Setto1ifassetisrequired.(bidderrequiresittobedisplayed).
title optional1 object - Titleobjectfortitleassets.SeeTitleObjectdefinition.
img optional1 object - Imageobjectforimageassets.SeeImageObjectdefinition.
video optional1 object - Videoobjectforvideoassets.SeeVideoresponseobjectdefinition.Notethatin-streamvideoadsarenotpartofNative.Nativeadsmaycontainavideoastheadcreativeitself.
data optional1 object - Dataobjectforratings,pricesetc.
link optional object - Linkobjectforcalltoactions.Thelinkobjectappliesiftheassetitemisactivated(clicked).Ifthereisnolinkobjectontheasset,theparentlinkobjectonthebidresponseapplies.
ext2 optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
1:assetobjectmaycontainonlyoneoftitle,img,dataorvideo.2:Biddersareencouragednottouseasset.extforexchangingtextassets.Usedata.extwithcustomtypeinstead.
5.3TitleResponseObjectCorrespondstotheTitleObjectintherequest,withthevaluefilledin.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page22
Ifusingassetsurlordcourlresponseratherthanembeddedassetresponse,itisrecommendedthatthreetitleobjectsbeprovided,thelengthofeachofwhichislessthanorequaltothethreerecommendedmaximumtitlelengths(25,90,140).
Field Scope Type Default Description
text required String - Thetextassociatedwiththetextelement.
len optional integer - Thelengthofthetitlebeingprovided.Requiredifusingassetsurl/dcourlrepresentation,optionalifusingembeddedassetrepresentation.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
5.4ImageResponseObjectCorrespondstotheImageObjectintherequest.TheImageobjecttobeusedforallimageelementsoftheNativeadsuchasIcons,MainImage,etc.
Itisrecommendedthatifassetsurl/dcourlisbeingusedratherthanembeddedassets,thatanimageofeachrecommendedaspectratio(pertheImageTypestable)beprovidedforimagetype3.
Field Scope Type Default Description
type optional integer - Requiredforassetsurlordcourlresponses,notrequiredforembeddedassetresponses.ThetypeofimageelementbeingsubmittedfromtheImageAssetTypestable.
url required string - URLoftheimageasset.
w recommended integer - Widthoftheimageinpixels.Recommendedforembeddedassetresponses.Requiredforassetsurl/dcourlresponsesifmultipleassetsofsametypesubmitted.
h recommended integer Heightoftheimageinpixels.Recommendedforembedded
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page23
assetresponses.Requiredforassetsurl/dcourlresponsesifmultipleassetsofsametypesubmitted.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
5.5DataResponseObjectCorrespondstotheDataObjectintherequest,withthevaluefilledin.TheDataObjectistobeusedforallmiscellaneouselementsofthenativeunitsuchasBrandName,Ratings,ReviewCount,Stars,Downloads,Pricecountetc.Itisalsogenericforfuturenativeelementsnotcontemplatedatthetimeofthewritingofthisdocument.
Field Scope Type Default Description
type optional integer - Requiredforassetsurl/dcourlresponses,notrequiredforembeddedassetresponses.ThetypeofdataelementbeingsubmittedfromtheDataAssetTypestable.
len optional integer - Requiredforassetsurl/dcourlresponses,notrequiredforembeddedassetresponses.Thelengthofthedataelementbeingsubmitted.Whereapplicable,mustcomplywiththerecommendedmaximumlengthsintheDataAssetTypestable.
value required string - Theformattedstringofdatatobedisplayed.Cancontainaformattedvaluesuchas“5stars”or“$10”or“3.4starsoutof5”.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page24
5.6VideoResponseObjectCorrespondstotheVideoObjectintherequest,yetcontainingavalueofaconformingVASTtagasavalue.Field Scope Type Default Description
vasttag required string - vastxml.
5.7LinkResponseObjectUsedfor‘calltoaction’assets,orotherlinksfromtheNativead.ThisObjectshouldbeassociatedtoitspeerobjectintheparentAssetObjectorasthemasterlinkinthetoplevelNativeAdresponseobject.Whenthatpeerobjectisactivated(clicked)theactionshouldtaketheusertothelocationofthelink.
Field Scope Type Default Description
url required string - LandingURLoftheclickablelink.
clicktrackers optional arrayofstrings
- Listofthird-partytrackerURLstobefiredonclickoftheURL.
fallback optional string(URL)
- FallbackURLfordeeplink.TobeusediftheURLgiveninurlisnotsupportedbythedevice.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
5.8EventTrackerResponseObjectTheeventtrackersresponseisanarrayofobjectsandspecifiesthetypesofeventsthebidderwishestotrackandtheURLs/informationtotrackthem.Biddermustonlyrespondwithmethodsindicatedasavailableintherequest.Notethatmostjavascripttrackersexpecttobeloadedatimpressiontime,soit’snotgenerallyrecommendedforthebuyertorespondwithjavascripttrackersonotherevents,buttheappropriatenessofthisisuptoeachbuyer.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page25
Field Scope Type Default Description
event required integer - Typeofeventtotrack.SeeEventTypestable.
method required integer - Typeoftrackingrequested.SeeEventTrackingMethodstable.
url optional text - TheURLoftheimageorjs.Requiredforimageorjs,optionalforcustom.
customdata optional objectcontainingkey:valuepairs
- Tobeagreedindividuallywiththeexchange,anarrayofkey:valueobjectsforcustomtracking,forexampletheaccountnumberoftheDSPwithatrackingcompany.IE{“accountnumber”:”123”}.
ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification
6BidRequest/ResponseSamplesNote:forpurposesofreadability,theseexamplesarewrittenasJSONobjectsdirectlyandillegalstringsareNOTencodedforreadability,eventhoughtheymayormaynotbestring-encodedintheactualmessage.Alsonotethatonlythenativeportionoftherequest/responseisillustrated.Forfullexamples,pleaseseetheOpenRTB2.xparentdocument.
6.1SocialContext,ClickoutResponse The ad might look like -
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page26
Bid Request "native":{
"ver":”1.2”,
"context":2,
"contextsubtype":20,
"plcmttype":11,
"plcmtcnt":1,
“aurlsupport”:0,
“privacy”:1,
“eventrackers”: [
{
“event”:1,
“methods”: [1,2]
},
{
“event”:2,
“methods”: [1]
}
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page27
],
"assets":[
{
"id":123,
"required":1,
"title":{
"len":140
}
},
{
"id":128,
"required":0,
"img":{
"wmin":836,
"hmin":627,
"type":3
}
},
{
"id":124,
"required":1,
"img":{
"wmin":50,
"hmin":50,
"type":1
}
},
{
"id":126,
"required":1,
"data":{
"type":1,
"len":25
}
},
{
"id":127,
"required":1,
"data":{
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page28
"type":2,
"len":140
}
}
]
}
Bid Response
"native": {
"link": {
"url": "http: //i.am.a/URL"
},
"assets": [
{
"id": 123,
"required": 1,
"title": {
"text": "Learn about this awesome thing"
}
},
{
"id": 124,
"required": 1,
"img": {
"url":"http://www.myads.com/thumbnail1.png"
}
},
{
"id": 128,
"required": 1,
"img": {
"url":"http://www.myads.com/largethumb1.png"
}
},
{
"id": 126,
"required": 1,
"data": {
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page29
"value": "My Brand"
}
},
{
"id": 127,
"required": 1,
"data": {
"value": "Learn all about this awesome story of someone using
my product."
}
}
],
“eventtrackers”: [
{
“event”:1,
“method”:2,
“url”:”http://www.mytracker.com/tracker.js”
}
{
“event”:2,
“method”:1,
“url”:”http://www.mytracker.com/tracker.php”
}
],
“privacy”: “http://www.myprivacyurl.com”
}
6.2ContentContext,VideoResponse The ad might look like -
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page30
Bid Request "native":{
"ver":”1.2”,
"context":1,
"contextsubtype":10,
"plcmttype":11,
"plcmtcnt":1,
“aurlsupport”:0,
“privacy”:1,
“eventrackers”: [
{
“event”:1,
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page31
“methods”: [1,2]
},
{
“event”:2,
“methods”: [1]
}
],
"assets":[
{
"id": 4, "video": { "linearity": 1, "minduration": 15, "maxduration": 30, "protocols": [ 2,3 ],
“mimes”: [ “video/mp4”
] } }, {
"id":123,
"required":1,
"title":{
"len":140
}
},
{
"id":128,
"required":0,
"img":{
"wmin":836,
"hmin":627,
"type":3
}
},
{
"id":124,
"required":1,
"img":{
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page32
"wmin":50,
"hmin":50,
"type":1
}
},
{
"id":126,
"required":1,
"data":{
"type":1,
"len":25
}
},
{
"id":127,
"required":1,
"data":{
"type":2,
"len":140
}
}
],
“eventtrackers”: [
{
“event”:1,
“method”:2,
“url”:”http://www.mytracker.com/tracker.js”
}
{
“event”:2,
“method”:1,
“url”:”http://www.mytracker.com/tracker.php”
}
],
“privacy”: “http://www.myprivacyurl.com”
}
Bid Response
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page33
"native": {
"link": {
"url": "http: //i.am.a/URL"
},
"assets": [
{
"id": 4, "video": { "vasttag": "<VAST version=’2.0’></VAST>" } }, {
"id": 123,
"required": 1,
"title": {
"text": "Watch this awesome thing"
}
},
{
"id": 124,
"required": 1,
"img": {
"url":"http://www.myads.com/thumbnail1.png"
}
},
{
"id": 128,
"required": 1,
"img": {
"url":"http://www.myads.com/largethumb1.png"
}
},
{
"id": 126,
"required": 1,
"data": {
"value": "My Brand"
}
},
{
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page34
"id": 127,
"required": 1,
"data": {
"value": "Watch all about this awesome story of someone using
my product."
}
}
]
}
6.3Third-PartyAdServingExample
Bid Request "native":{
"ver":”1.2”,
"context":2,
"contextsubtype":20,
"plcmttype":11,
"plcmtcnt":1,
“aurlsupport”:1,
“durlsupport”:1,
"assets":[
{
"id":123,
"required":1,
"title":{
"len":140
}
},
{
"id":128,
"required":0,
"img":{
"wmin":836,
"hmin":627,
"type":3
}
},
{
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page35
"id":124,
"required":1,
"img":{
"wmin":50,
"hmin":50,
"type":1
}
},
{
"id":126,
"required":1,
"data":{
"type":1,
"len":25
}
},
{
"id":127,
"required":1,
"data":{
"type":2,
"len":140
}
}
]
}
Bid Response
"native": {
“assetsurl”: “http://www.myadserver.com/getad123nativejson.php”,
"link": {
"url": "http: //i.am.a/URL"
},
"assets": [
{
"id": 123,
"required": 1,
"title": {
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page36
"text": "Learn about this awesome thing"
}
},
{
"id": 124,
"required": 1,
"img": {
"url":"http://www.myads.com/thumbnail1.png"
}
},
{
"id": 128,
"required": 1,
"img": {
"url":"http://www.myads.com/largethumb1.png"
}
},
{
"id": 126,
"required": 1,
"data": {
"value": "My Brand"
}
},
{
"id": 127,
"required": 1,
"data": {
"value": "Learn all about this awesome story of someone using
my product."
}
}
]
}
WhatShouldbeReturnedbytheAssetsURL
Note:theassetsobjectmaystillbeincludedintheresponseasafallback,butthesupplysourcemustcalltheassetsurlandusetheprovidedresponseforthead.Theresponse
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page37
mustbeajsonassetsobjectlikeintheresponseitself,withthechangesasindicatedinthespec.AnexamplefollowsofwhatthatURLwouldreturn.{
"assets": [
{
"required": 1,
"title": {
"text": "Learn about this awesome thing",
“len”: 30
}
},
{
"link": {
"url": "http://brand.com/landingpage/"
},
}, 2 {
"img": {
“type”:1,
"url":"http://www.myads.com/icon.png",
“h”:50,
“w”:50
}
},
{
"img": {
“type”:3,
"url":"http://www.myads.com/largethumb11.png",
“h”:200,
“w”:200
}
},
{
"img": {
“type”:3,
2Inthecontextofthird-partyad-serving,includingalinkobjectintheassetsresponsewouldbeausefulwaytooverridethelinkobjectspecifiedbythebidderintheparentnativeobject.Theexchangecouldalsochoosetowrapthislinkinthebidresponselinktoallowbidderclicktrackingtowork.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page38
"url":"http://www.myads.com/largethumb43.png",
“h”:200,
“w”:267
}
},
{
"img": {
“type”:3,
"url":"http://www.myads.com/largethumb1911.png",
“h”:200,
“w”:382
}
},
{
"required": 1,
"data": {
“type”:1,
“len”:8,
"value": "My Brand"
}
},
{
"required": 1,
"data": {
“type”:2,
“len”:63,
"value": "Learn all about this awesome story of someone using
my product."
}
}
]
}
7ReferenceLists/Enumerations
7.1ContextTypeIDsThecontextinwhichtheadappears-whattypeofcontentissurroundingtheadonthepageatahighlevel.ThismapsdirectlytothenewDeepDiveonIn-FeedAdUnits.This
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page39
denotestheprimarycontext,butdoesnotimplyothercontentmaynotexistonthepage-forexampleit'sexpectedthatmostcontentplatformshavesomesocialcomponents,etc.
ContextTypeID Description
1 Content-centric context such as newsfeed, article, image gallery, video gallery, or similar.
2 Social-centric context such as social network feed, email, chat, or similar.
3 Product context such as product listings, details, recommendations, reviews, or similar.
500+ To be defined by the exchange.
7.2ContextSubTypeIDsNext-levelcontextinwhichtheadappears.Againthisreflectstheprimarycontext,anddoesnotimplynopresenceofotherelements.Forexample,anarticleislikelytocontainimagesbutisstillfirstandforemostanarticle.SubTypeshouldonlybecombinedwiththeprimarycontexttypeasindicated(ieforacontexttypeof1,onlycontextsubtypesthatstartwith1arevalid).
ContextSubTypeID Description
10 General or mixed content.
11 Primarily article content (which of course could include images, etc as part of the article)
12 Primarily video content
13 Primarily audio content
14 Primarily image content
15 User-generated content - forums, comments, etc
20 General social content such as a general social network
21 Primarily email content
22 Primarily chat/IM content
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page40
30 Content focused on selling products, whether digital or physical
31 Application store/marketplace
32 Product reviews site primarily (which may sell product secondarily)
500+ To be defined by the exchange
7.3PlacementTypeIDsTheFORMAToftheadyouarepurchasing,separatefromthesurroundingcontext
PlacementTypeID Description
1 In the feed of content - for example as an item inside the organic feed/grid/listing/carousel.
2 In the atomic unit of the content - IE in the article page or single image page
3 Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc.
4 Recommendation widget, most commonly presented below the article content.
500+ To be defined by the exchange
7.4DataAssetTypesBelowisalistofcommonassetelementtypesofnativeadvertisingatthetimeofwritingthisspec.Thislistisnon-exhaustiveandintendedtobeextendedbythebuyersandsellersastheformatevolves.
Animplementingexchangemaynotsupportallassetvariantsorintroducenewonesuniquetothatsystem.
TypeID
Name Description Format Recommendations
1 sponsored SponsoredBymessagewhereresponseshouldcontainthebrandnameofthesponsor.
text Required.Max25orlonger.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page41
2 desc Descriptivetextassociatedwiththeproductorservicebeingadvertised.Longerlengthoftextinresponsemaybetruncatedorellipsedbytheexchange.
text Recommended.Max140orlonger.
3 rating Ratingoftheproductbeingofferedtotheuser.Forexampleanapp’sratinginanappstorefrom0-5.
numberformattedasstring
Optional.0-5integerformattedasstring.
4 likes Numberofsocialratingsor“likes”oftheproductbeingofferedtotheuser.
numberformattedasstring
5 downloads Numberdownloads/installsofthisproduct
numberformattedasstring
6 price Priceforproduct/app/in-apppurchase.Valueshouldincludecurrencysymbolinlocalisedformat.
numberformattedasstring
7 saleprice Salepricethatcanbeusedtogetherwithpricetoindicateadiscountedpricecomparedtoaregularprice.Valueshouldincludecurrencysymbolinlocalisedformat.
numberformattedasstring
8 phone Phonenumber formattedstring
9 address Address text
10 desc2 Additionaldescriptivetextassociatedwiththeproductorservicebeingadvertised
text
11 displayurl DisplayURLforthetextad.Tobeusedwhensponsoringentitydoesn’townthecontent.IEsponsoredbyBRANDonSITE(whereSITEistransmittedinthisfield).
text
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page42
12 ctatext CTAdescription-descriptivetextdescribinga‘calltoaction’buttonforthedestinationURL.
text Optional.Max15orlonger.
500+ XXX ReservedforExchangespecificusagenumberedabove500
Unknown
7.5ImageAssetTypesBelowisalistofcommonimageassetelementtypesofnativeadvertisingatthetimeofwritingthisspec.Thislistisnon-exhaustiveandintendedtobeextendedbythebuyersandsellersastheformatevolves.
Animplementingexchangemaynotsupportallassetvariantsormayintroducenewonesuniquetothatsystem.
In order to facilitate adoption, recommendations are made for both minimum sizes and aspect ratios. We speak here of 'minimum maximum height' or ‘max height of at least’, which means the SSP should support a max height of at least this value. They are free to support larger, but the DSP knows that if they have an image of this size it will be accepted. Note that SSPs will be responsible for sizing image to exact size if min-max-height framework is used; exact size may not be available at bid request time. Width is calculated from the 3 supported aspect ratios. Note we merged the prior overlapping type 1 and type 2 as just type 1 - to be used for app icon, brand logo, or similar.
TypeID
Name Description Recommendations
1 Icon Iconimage Optional.
maxheight:atleast50
aspectratio:1:1
3 Main Largeimagepreviewforthead
Atleastoneof2sizevariantsrequired:
SmallVariant:
maxheight:atleast200
maxwidth:atleast200,267,or382
aspectratio:1:1,4:3,or1.91:1
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page43
LargeVariant:
maxheight:atleast627
maxwidth:atleast627,836,or1198
aspectratio:1:1,4:3,or1.91:1
500+ XXX ReservedforExchangespecificusagenumberedabove500
Norecommendations
7.6EventTypesTable
TypeID Name Description
1 impression Impression
2 viewable-mrc50 VisibleimpressionusingMRCdefinitionat50%inviewfor1second
3 viewable-mrc100 100%inviewfor1second(ieGroupMstandard)
4 viewable-video50 VisibleimpressionforvideousingMRCdefinitionat50%inviewfor2seconds
500+ exchange-specific
7.7EventTrackingMethodsTable
TypeID Name Description
1 img Image-pixeltracking-URLprovidedwillbeinsertedasa1x1pixelatthetimeoftheevent.
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page44
2 js Javascript-basedtracking-URLprovidedwillbeinsertedasajstagatthetimeoftheevent.
500+ exchange-specific
Couldincludecustommeasurementcompaniessuchasmoat,doubleverify,IAS,etc-inthiscaseadditionalelementswilloftenbepassed
8ImplementationNotes
8.1MultiPlacementBidRequestsIfthebidrequesthasaplacementcount(“plcmtcnt”)greaterthan1,thentheimplicationisthatthebidderissubmittingbidstoaGeneralizedSecondPriceauctionwheremultipleidenticalplacementsarebeingofferedinthesamecontentfeedorstream.
ExampleIfabidrequestisfor5adplacementswithinafeedbasedlayout.Thebiddercanreturn1-5bids.Theexchangerunsageneralizedsecondpriceauctionacrossthesebids.Thebiddercanpotentiallywinbetween0-5placementsintheauction.
Anexamplebidresponsewouldlooklike{
"id": "1234567890",
"seatbid": [{
"bid": [{
"id": "1",
"impid": "1",
"price": 10,
"nurl": "http://adserver.com/WinNoticeUrlThatReturnsNative1",
"adm":"<native response>"
},
"bid": [{
"id": "2",
"impid": "1",
"price": 20,
"nurl": "http://adserver.com/WinNoticeUrlThatReturnsNative2"
"adm":"<native response>"
}]
}]
}
OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject
Page45