OpenRTB-Native-Ads-Specification-Draft 1.2 2017-04 supplementary API specification for companies interested in an open protocol for the automated trading of Native Ads enabled media

OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject

Page1

RTB Project OpenRTB Dynamic Native Ads API Specification Version 1.2 Draft for Public Comment April 2017


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/[email protected]

IABContactInformation:

[email protected]

License

OpenRTBSpecificationbyOpenRTBislicensedunderaCreativeCommonsAttribution3.0License,basedonaworkatopenrtb.info.Permissionsbeyondthescopeofthislicensemaybeavailableathttp://openrtb.info.Toviewacopyofthislicense,visithttp://creativecommons.org/licenses/by/3.0/orwritetoCreativeCommons,171SecondStreet,Suite300,SanFrancisco,CA94105,USA.


Page3

TableofContentsChangeLog 5

BeforeYouGetStarted

1Introduction 6

1.1Mission/Overview

1.2Credits/ProjectHistory

1.3Resources

1.4VersionHistory

2NativeAdsBasics 8

2.1IABCoreSix

2.2DeepDiveonIn-FeedAdUnits

2.3DataFormat

2.4Versioning

2.5CustomizationandExtensions

3BidRequestDetails 11

3.1NativeObjectHierarchy

4NativeAdRequestMarkupDetails 11

4.1NativeMarkupRequestObject

4.2AssetRequestObject

4.3TitleRequestObject

4.4ImageRequestObject

4.5VideoRequestObject

4.6DataRequestObject

4.7EventTrackersRequestObject

5NativeAdResponseMarkupDetails 18

5.1NativeMarkupResponseObject

5.2AssetResponseObject

5.3TitleResponseObject

5.4ImageResponseObject

5.5DataResponseObject


Page4

5.6VideoResponseObject

5.7LinkResponseObject

5.8EventTrackerResponseObject

6BidRequest/ResponseSamples 25

6.1SocialContext,ClickoutResponse

BidRequest

BidResponse

6.2ContentContext,VideoResponse

BidRequest

BidResponse

6.3Third-PartyAdServingResponse

BidRequest

BidResponse

7ReferenceLists/Enumerations 37

7.1NativeLayoutIDs-ToBeDeprecated

7.2NativeAdUnitIDs-ToBeDeprecated

7.3ContextTypeIDs

7.4ContextSubTypeIDs

7.5PlacementTypeIDs

7.6DataAssetTypes

7.7ImageAssetTypes

7.8EventTypesTable

7.9EventTrackingMethodsTable

8ImplementationNotes 44

8.1MultiPlacementBidRequests


Page5

ChangeLogVersion Date SectionLink Change

1.0 Jan2015 OriginalVersion

1.1 Oct2015 Variousclericalfixesandclarifications,standardizedcreativeelementlengths/sizes/aspectratiosintheassetsub-objects,addednewcontextandplacementtypestobidrequest,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

BeforeYouGetStartedThisspecificationcontainsadetailedexplanationofasub-protocoloftheOpenRTBreal-timebiddinginterface.Notallobjectsarerequired,andeachobjectmaycontainanumberofoptionalparameters.Toassistafirst-timereaderofthespecification,wehaveindicatedwhichfieldsareessentialtosupportaminimumviablerealtimebiddinginterfaceforvariousscenarios.

Aminimalviableinterfaceshouldincludetherequiredandrecommendedparameters,butthescopefortheseparametersmaybelimitedtospecificscenarios.Inthesecases,thescopewillbequalifiedwiththeapplicablescenarios(e.g.,requiredfornativeimpressionsandrecommendedfornativeimpressions).Conversely,ifthescopeisnotqualified,itappliestoallscenarios.


Page6

Optionalparametersmaybeincludedtoensuremaximumvalueisderivedbytheparties.

IMPORTANT:Sincerecommendedparametersarenotrequired,theymaynotbeavailablefromallsupplysources.ItissuggestedthatallpartiestoOpenRTBtransactioncompletetheintegrationchecklist(pleaserefertoOpenRTB)toidentifywhichparametersthesupplysidesupportsinthebidrequest,andwhichparametersthedemandsiderequiresforaddecisioning.

1Introduction

1.1Mission/Overview

ThemissionoftheOpenRTBNativeprojectistospurstandardizationandgreatergrowthintheReal-TimeBidding(RTB)marketplaceforNativeAdsbyprovidingopenindustrystandardsforcommunicationbetweenbuyersofadvertisingandsellersofpublisherinventory.

Thisspecificationisasub-protocolofOpenRTBtoallowforthedeliveryofnativeadvertisingformats,astheirspecificsdifferfrompublishertopublisher.InMay2013,aseparateIAB


Page7

subcommitteewasformedtodefinetherequestandresponsestructuresofnativeadunits;version1.0waspublishedinearly2015.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,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


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

2NativeAdsBasicsNativeadvertisingisanonlineadvertisingmethodinwhichtheadvertiserattemptstogainattentionbyprovidingcontentinthecontextoftheuser'sexperience.Nativeadformatsmatchboththeformandfunctionoftheuserexperienceinwhichitisplaced.Thisisincontrasttotraditionalbannerorinterstitialsads,whicharedisplayedinaseparatespaceofpredefinedanduniversalsize,withoutregardtotheirsurroundings.


Page9

2.1IABCoreSixTheIABNativeAdvertisingPlaybooklistssixtypesofnativeadunits:

● InFeedUnits● PaidSearchUnits● RecommendationWidgets● PromotedListings● IABStandardwithNativeElements● Custom/“Can’tbecontained”

2.2DeepDiveonIn-FeedAdUnitsTohelpfurtherdefineandclarifythetypesandcategoriesofnativeadvertising,theIABpublishedaDeepDiveonIn-FeedAdUnitsinJuly2015.Version1.1oftheNativespecusestheseconceptstorefinethedefinitionsofadtypes,detailedbelowasContextandPlacementType,whicharereplacingthepreviousLayoutIDandAdUnitID,whichweredefinedinNative1.0andbasedontheoriginalNativeAdvertisingPlaybookreferencedabove.

Wherefound

Mostcommonadtypes/contentobjects

Mostcommontypesoflinks

Representativefeedview


Page10

2.3DataFormatAsthisspecificationoutlinesanoptionalsub-protocolofthemainOpenRTBprotocolpayload,theformatmustfollowthatofitsparent.PleaserefertothemainOpenRTBspecificationfordetailsofvariousformatsthatmaybeused

2.4VersioningTheNativeObjectintheBidRequest(OpenRTBcontainsa“ver”fielddefiningtheversionoftheOpenRTBnativeextension.

2.5CustomizationandExtensionsTheOpenRTBNativeAdsspecallowsforexchangespecificcustomizationandextensionsofthespecification.Anyobjectmaycontainextensions.Inordertokeepextensionfieldsconsistentacrossplatforms,theyshouldconsistentlybenamed“ext”.


Page11

3BidRequestDetailsRTBtransactionsareinitiatedwhenanexchangeorothersupplysourcesendsabidrequesttoabidder.Thebidrequestconsistsofabidrequestobject,atleastoneimpressionobject,andmayoptionallyincludeadditionalobjectsprovidingimpressioncontext.

3.1NativeObjectHierarchyFollowingistheobjecthierarchyforabidrequest.ThenewNativeObjectisanotheroptionalelementoftheimpressionobject,andcanbespecifiedasanalternativetoorinconjunctionwithabannerobjectorvideoobject.

4NativeAdRequestMarkupDetails

4.1NativeMarkupRequestObjectTheNativeObjectdefinesthenativeadvertisingopportunityavailableforbidviathisbidrequest.ItwillbeincludedasaJSON-encodedstringinthebidrequest’simp.nativefieldorasadirectJSONobject,dependingonthechoiceoftheexchange.WhileOpenRTB2.xofficiallysupportsonlyJSON-encodedstrings,manyexchangeshaveimplementedaformalobject.Checkwithyourintegrationdocs.

TheDefaultcolumndictateshowoptionalparametersshouldbeinterpretedifexplicitvaluesarenotprovided.

Bid Request Object

BannerObject

NativeObject

Video ObjectAND/

AND/ Banner

Impression Object

(other OpenRTB objects)

(other OpenRTB objects)

Request


Page12

Field Scope Type Default Description

Ver optional string 1.2 VersionoftheNativeMarkupversioninuse.

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.

urlsupport optional int 0 Whetherthesupplysource/impressionsupportsreturninganasseturlinsteadofanassetobject.0ortheabsenceofthefieldindicatesnosuchsupport.


Page13

eventtrackers optional arrayofobjects

- Specifieswhattypeofeventtrackingissupported–seeEventTrackersRequestObject

privacy recommended integer 0 Setto1whenthenativeadsupportsbuyer-specificprivacynotice(seehttp://youradchoices.com/forexample).Setto0(orfieldabsentwhenthenativeaddoesn’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.

Newinversion1.1ofthespec,therearerecommendedsizes/lengths/etcwithsomeoftheassettypes.ThegoalforassetrequirementsstandardizationistofacilitateadoptionofnativebyDSPsbylimitingthediversetypes/sizes/requirementsofassetstheymusthaveavailabletopurchaseanativeadimpression.Whilegreatdiversitymayexistinpublishers,advertisers/DSPscannotbeexpectedtoprovideinfiniteheadlinelengths,thumbnailaspectratios,etc.Whilewehavenotgoneasfarascreatingasinglestandard,we'vehonedinonafewoptionsthatcoverthemostcommoncases.SSPscandeviatefromthesestandards,butshouldunderstandtheymaylimitapplicableDSPdemandbydoingso.DSPsshouldfeelconfidentthatiftheysupportthesestandardsthey'llbeabletoaccessmostnativeinventory.



Page14

id required int - UniqueassetID,assignedbyexchange.Typicallyacounterforthearray.

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.


1:eachassetobjectmaycontainonlyoneoftitle,img,dataorvideo.

4.3TitleRequestObjectTheTitleobjectistobeusedfortitleelementoftheNativead.


len required integer - Maximumlengthofthetextinthetitleelement.Recommendedtobe25,90,or140.

ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthe


Page15

standarddefinedinthisspecification

4.4ImageRequestObjectTheImageobjecttobeusedforallimageelementsoftheNativeadsuchasIcons,MainImage,etc.RecommendedsizesandaspectratiosareincludedintheImageAssetTypessection.


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'sMIMEpageformore


Page16

informationandlinkstoallIETFRFCs.

Ifblank,assumealltypesareallowed.


4.5VideoRequestObjectThevideoobjecttobeusedforallvideoelementssupportedintheNativeAd.ThiscorrespondstotheVideoobjectofOpenRTB.Exchangeimplementerscanimposetheirownspecificrestrictions.HerearetherequiredattributesoftheVideoObject.ForoptionalattributespleaserefertoOpenRTB.


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 - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthe


Page17


4.6DataRequestObjectTheDataObjectistobeusedforallnon-coreelementsofthenativeunitsuchasBrandName,Ratings,ReviewCount,Stars,Downloadcount,descriptionsetc.Itisalsogenericforfuturenativeelementsnotcontemplatedatthetimeofthewritingofthisdocument.Insomecases,additionalrecommendationsarealsoincludedintheDataAssetTypestable.


type required integer - TypeIDoftheelementsupportedbythepublisher.Thepublishercandisplaythisinformationinanappropriateformat.SeeDataAssetTypestableforcommonlyusedexamples.

Len optional integer - Maximumlengthofthetextintheelement’sresponse.

Ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthisspecification

4.7EventTrackersRequestObjectTheeventtrackersobjectspecifiesthetypesofeventsthebiddercanrequesttobetrackedinthebidresponse,andwhichtypesoftrackingareavailableforeacheventtype,andisincludedasanarrayintherequest.


event required integer - Typeofeventavailablefortracking.SeeEventTypestable.


Page18

methods required arrayofintegers

- Arrayofthetypesoftrackingavailableforthegivenevent.SeeEventTrackingMethodstable.


5NativeAdResponseMarkupDetailsThestructureandcontentsoftheBidResponsearethesameasintheOpenRTBstandard.Thedifferenceisinhowtheadcreativeisreturned.ThenativecreativeshallbereturnedasaJSON-encodedstringintheadmfieldoftheBidObject.NotesomeimplementershavechosentouseadirectobjectinanewfieldratherthanJSONencodedstring.

5.1NativeMarkupResponseObjectThenativeobjectisthetoplevelJSONobjectwhichidentifiesanativeresponse.Thenativeobjecthasfollowingattributes:


ver optional string “1.2” VersionoftheNativeMarkupversioninuse.

assets recommended arrayofobjects

- Listofnativead’sassets.Requiredifnoasseturl.Recommendedasfallbackevenifasseturlisprovided.

asseturl1 optional string - URLofanalternatesourcefortheassetsobject.TheexpectedresponseisaJSONobjectmirroringtheassetsobjectinthe

11The provided “assetsurl” 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.


Page19

bidresponse,subjecttocertainrequirementsasspecifiedintheindividualobjects.

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.


- Arrayoftrackingobjectstorunwiththead,inresponsetothedeclaredsupportedmethodsintherequest.Replacesimptrackersandjstracker,tobedeprecated.


- Arrayoftrackingobjectstorunwiththead,inresponsetothedeclaredsupportedmethodsintherequest.Replacesimptrackersandjstracker,tobedeprecated.

privacy optional string - Ifsupportwasindicatedintherequest,URLofapageinformingtheuseraboutthebuyer’stargetingactivity.

Ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthe


Page20


Note:PriortoVERSION1.1,thenativeresponse’srootnodewasanobjectwithasinglefield“native”thatwouldcontaintheobjectaboveasitsvalue.TheNativeObjectspecifiedaboveisnowtherootobject.Noteregardingasseturlformatresponses:Inthecaseofasseturlbidding,sincetheultimatebuyer/creativeenginecannotaltertheassetsresponsebasedonthedetailsinsidetheassetsrequest(asitdoesnotreceivesaidrequest),itiscriticalthatallrequiredassetsareprovided,andsuchcommunicationswillneedtobehandledofflineforrecommended/optionalelements.Inthenormalembeddedresponse,certainattributesoftheresponseareassumedbasedonmatchingtheIDoftheassetobjectintheresponsetotheIDoftheassetobjectintherequest.Sincetheassetresponsewillnotbereadingtheassetrequestdirectlyinthisimplementation,thatinformationisaddedasoptioninthebelowobjectdefinitionsandmarkedforthatusecase.Itisalsorecommendedthatwherethestandardspecifiesmultipleoptionsforanelement,thatalloptionsbeprovided.IEall4supportedthumbnailaspectratiosandall3supportedtitlelengths.TheIDcomponentoftheassetresponsescanbeomitted.Notethatthischangetoprovidethemetadatadescriptionoftheassetintheresponse,ratherthanusingtheassetIDtoimplicitlyspecifythat,maybereflectedintotheinlineversionofresponsesinafutureversiontoalignthetwomethodsofreplying.Makingthatchangenowwouldbreakbackwardscompatibilityoftheinlineresponsemechanism.

5.2AssetResponseObjectCorrespondstotheAssetObjectintherequest.ThemaincontainerobjectforeachassetrequestedorsupportedbyExchangeonbehalfoftherenderingclient.Anyobjectthatisrequiredistobeflaggedassuch.Onlyoneofthe{title,img,video,data}objectsshouldbepresentineachobject.Allothersshouldbenull/absent.TheidistobeuniquewithintheAssetObjectarraysothattheresponsecanbealigned.


id optional int - Optionalifasseturlisbeingused;requiredifembeddedassetisbeingused.

required optional int 0 Setto1ifassetisrequired.(bidderrequiresittobedisplayed).


Page21

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.

Ifusingasseturlresponseratherthanembeddedassetresponse,itisrecommendedthatthreetitleobjectsbeprovided,thelengthofeachofwhichislessthanorequaltothethreerecommendedmaximumtitlelengths(25,90,140).


text required String - Thetextassociatedwiththetextelement.

len optional integer - Thelengthofthetitlebeingprovided.Requiredifusing


Page22

asseturlrepresentation,optionalifusingembeddedassetrepresentation.


5.4ImageResponseObjectCorrespondstotheImageObjectintherequest.TheImageobjecttobeusedforallimageelementsoftheNativeadsuchasIcons,MainImage,etc.

Itisrecommendedthatifasseturlisbeingusedratherthanembeddedassets,thatanimageofeachrecommendedaspectratio(pertheImageTypestable)beprovidedforimagetype3.


type optional integer - Requiredforasseturlresponses,notrequiredforembeddedassetresopnses.ThetypeofimageelementbeingsubmittedfromtheImageAssetTypestable.

url required string - URLoftheimageasset.

W recommended integer - Widthoftheimageinpixels.

H recommended integer Heightoftheimageinpixels.


5.5DataResponseObjectCorrespondstotheDataObjectintherequest,withthevaluefilledin.TheDataObjectistobeusedforallmiscellaneouselementsofthenativeunitsuchasBrandName,Ratings,ReviewCount,Stars,Downloads,Pricecountetc.Itisalsogenericforfuturenativeelementsnotcontemplatedatthetimeofthewritingofthisdocument.


type optional integer - Requiredforasseturlresponses,notrequiredforembeddedasset


Page23

responses.ThetypeofdataelementbeingsubmittedfromtheDataAssetTypestable.

len optional integer - Requiredforasseturlresponses,notrequiredforembeddedassetresponses.Thelengthofthedataelementbeingsubmitted.Whereapplicable,mustcomplywiththerecommendedmaximumlengthsintheDataAssetTypestable.

value required string - Theformattedstringofdatatobedisplayed.Cancontainaformattedvaluesuchas“5stars”or“$10”or“3.4starsoutof5”.


5.6VideoResponseObjectCorrespondstotheVideoObjectintherequest,yetcontainingavalueofaconformingVASTtagasavalue.


vasttag required string - vastxml.

5.7LinkResponseObjectUsedfor‘calltoaction’assets,orotherlinksfromtheNativead.ThisObjectshouldbeassociatedtoitspeerobjectintheparentAssetObjectorasthemasterlinkinthetoplevelNativeAdresponseobject.Whenthatpeerobjectisactivated(clicked)theactionshouldtaketheusertothelocationofthelink.


url required string - LandingURLoftheclickablelink.


Page24

clicktrackers optional arrayofstrings

- Listofthird-partytrackerURLstobefiredonclickoftheURL.

fallback optional string(URL)

- FallbackURLfordeeplink.TobeusediftheURLgiveninurlisnotsupportedbythedevice.


5.8EventTrackerResponseObjectTheeventtrackersresponseisanarrayofobjectsandspecifiesthetypesofeventsthebidderwishestotrackandtheURLs/informationtotrackthem.Biddermustonlyrespondwithmethodsindicatedasavailableintherequest.Notethatmostjavascripttrackersexpecttobeloadedatimpressiontime,soit’snotgenerallyrecommendedforthebuyertorespondwithjavascripttrackersonotherevents,buttheappropriatenessofthisisuptoeachbuyer.


event required integer - Typeofeventtotrack.SeeEventTypestable.

method required integer - Typeoftrackingrequested.SeeEventTrackingMethodstable.

url optional text - TheURLoftheimpageorjs.Requiredforimageorjs,optionalforcustom.

customdata optional Objectcontainingkey:valuepairs

- Tobeagreedindividuallywiththeexchange,anarrayofkey:valueobjectsforcustomtracking,forexampletheaccountnumberoftheDSPwithatrackingcompany.IE{“accountnumber”:”123”}.



Page25

6BidRequest/ResponseSamplesNote:forpurposesofreadability,theseexamplesarewrittenasJSONobjectsdirectlyandillegalstringsareNOTencodedforreadability,eventhoughtheymayormaynotbestring-encodedintheactualmessage.Alsonotethatonlythenativeportionoftherequest/responseisillustrated.Forfullexamples,pleaseseetheOpenRTB2.xparentdocument.

6.1SocialContext,ClickoutResponse The ad might look like -

Bid Request "native":{

"ver":”1.2”,

"context":2,

"contextsubtype":20,


Page26

"plcmttype":11,

"plcmtcnt":1,

“urlsupport”:0,

“privacy”:1,

“eventrackers”: [

{

“event”:1,

“methods”: [1,2]

},

{

“event”:2,

“methods”: [1]

}

],

"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

}


Page27

},

{

"id":126,

"required":1,

"data":{

"type":1,

"len":25

}

},

{

"id":127,

"required":1,

"data":{

"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"


Page28

}

},

{

"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."

}

}

],

“eventtrackers”: [

{

“event”:1,

“method”:2,

“url”:”http://www.mytracker.com/tracker.js”

}

{

“event”:2,

“method”:1,

“url”:”http://www.mytracker.com/tracker.php”

}

],


Page29

“privacy”: “http://www.myprivacyurl.com”

}

6.2ContentContext,VideoResponse The ad might look like -


"ver":”1.2”,

"context":1,


"plcmttype":11,


Page30

"plcmtcnt":1,

“urlsupport”:0,

“privacy”:1,

“eventrackers”: [

{

“event”:1,

“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


Page31

}

},

{

"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

}

}

],

“eventtrackers”: [

{

“event”:1,

“method”:2,

“url”:”http://www.mytracker.com/tracker.js”

}

{

“event”:2,

“method”:1,

“url”:”http://www.mytracker.com/tracker.php”

}


Page32

],

“privacy”: “http://www.myprivacyurl.com”

}

Bid Response

"native": {

"link": {


},

"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": {


}

},

{

"id": 128,

"required": 1,

"img": {


}

},

{


Page33

"id": 126,

"required": 1,

"data": {

"value": "My Brand"

}

},

{

"id": 127,

"required": 1,

"data": {

"value": "Watch all about this awesome story of someone using

my product."

}

}

]

}

6.3Third-PartyAdServingExample


"ver":”1.2”,

"context":2,


"plcmttype":11,

"plcmtcnt":1,

“urlsupport”:1,

"assets":[

{

"id":123,

"required":1,

"title":{

"len":140

}

},

{

"id":128,

"required":0,

"img":{


Page34

"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":{

"type":2,

"len":140

}

}

]

}

Bid Response

"native": {

“assetsurl”: “http://www.myadserver.com/getad123nativejson.php”,

"link": {



Page35

},

"assets": [

{

"id": 123,

"required": 1,

"title": {

"text": "Learn about this awesome thing"

}

},

{

"id": 124,

"required": 1,

"img": {


}

},

{

"id": 128,

"required": 1,

"img": {


}

},

{

"id": 126,

"required": 1,

"data": {

"value": "My Brand"

}

},

{

"id": 127,

"required": 1,

"data": {


my product."

}

}

]


Page36

}

What Should be Returned by the Assets URL

Note:theassetsobjectmaystillbeincludedintheresponseasafallback,butthesupplysourcemustcalltheassetsurlandusetheprovidedresponseforthead.Theresponsemustbeajsonassetsobjectlikeintheresponseitself,withthechangesasindicatedinthespec.AnexamplefollowsofwhatthatURLwouldreturn.{

"assets": [

{

"required": 1,

"title": {

"text": "Learn about this awesome thing",

“len”: 30

}

},

{

"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,


“h”:200,

“w”:267

}


Page37

},

{

"img": {

“type”:3,


“h”:200,

“w”:382

}

},

{

"required": 1,

"data": {

“type”:1,

“len”:8,

"value": "My Brand"

}

},

{

"required": 1,

"data": {

“type”:2,

“len”:63,


my product."

}

}

]

}

7ReferenceLists/Enumerations

7.1NativeLayoutIDs–Deprecated

7.2NativeAdUnitIDs-Deprecated

7.3ContextTypeIDsThecontextinwhichtheadappears-whattypeofcontentissurroundingtheadonthepageatahighlevel.ThismapsdirectlytothenewDeepDiveonIn-FeedAdUnits.Thisdenotestheprimarycontext,butdoesnotimplyothercontentmaynotexistonthe


Page38

page-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.4ContextSubTypeIDsNext-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

30 Content focused on selling products, whether digital or physical


Page39

31 Application store/marketplace

32 Product reviews site primarily (which may sell product secondarily)

500+ To be defined by the exchange

7.5PlacementTypeIDsTheFORMAToftheadyouarepurchasing,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.6DataAssetTypesBelowisalistofcommonassetelementtypesofnativeadvertisingatthetimeofwritingthisspec.Thislistisnon-exhaustiveandintendedtobeextendedbythebuyersandsellersastheformatevolves.

Animplementingexchangemaynotsupportallassetvariantsorintroducenewonesuniquetothatsystem.

TypeID

Name Description Format Recommendations

1 sponsored SponsoredBymessagewhereresponseshouldcontainthebrandnameofthesponsor.

text Required.Max25orlonger.


Page40

2 desc Descriptivetextassociatedwiththeproductorservicebeingadvertised.Longerlengthoftextinresponsemaybetruncatedorellipsedbytheexchange.

text Recommended.Max140orlonger.

3 rating Ratingoftheproductbeingofferedtotheuser.Forexample,anapp’sratinginanappstorefrom0-5.

numberformattedasstring

Optional.0-5integerformattedasstring.

4 likes Numberofsocialratingsor“likes”oftheproductbeingofferedtotheuser.


5 downloads Numberdownloads/installsofthisproduct


6 price Priceforproduct/app/in-apppurchase.Valueshouldincludecurrencysymbolinlocalisedformat.


7 saleprice Salepricethatcanbeusedtogetherwithpricetoindicateadiscountedpricecomparedtoaregularprice.Valueshouldincludecurrencysymbolinlocalisedformat.


8 phone Phonenumber formattedstring

9 address Address text

10 desc2 Additionaldescriptivetextassociatedwiththeproductorservicebeingadvertised

text

11 displayurl DisplayURLforthetextad.Tobeusedwhensponsoringentitydoesn’townthecontent.IEsponsoredbyBRANDonSITE(whereSITEistransmittedinthisfield).

text


Page41

12 ctatext CTAdescription-descriptivetextdescribinga‘calltoaction’buttonforthedestinationURL.

text Optional.Max15orlonger.

500+ XXX ReservedforExchangespecificusagenumberedabove500

Unknown

7.7ImageAssetTypesBelowisalistofcommonimageassetelementtypesofnativeadvertisingatthetimeofwritingthisspec.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


Page42

LargeVariant:

maxheight:atleast627

maxwidth:atleast627,836,or1198

aspectratio:1:1,4:3,or1.91:1

500+ XXX ReservedforExchangespecificusagenumberedabove500

Norecommendations

7.8EventTypesTable

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


Page43

7.9EventTrackingMethodsTable

TypeID Name Description

1 img Image-pixeltracking–URLprovidedwillbeinsertedasa1x1pixelatthetimeoftheevent.

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": [{


Page44

"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>"

}]

}]

}

Documents

OpenRTB-Native-Ads-Specification-Draft 1.2 2017-04 supplementary API specification for companies interested in an open protocol for the automated trading of Native Ads enabled media