rtb project - iab tech lab...openrtb dynamic native ads api specification version 1.2 rtb project...

OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject

Page1

RTB Project OpenRTB Dynamic Native Ads API Specification Version 1.2 Final Version July 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/specifications-guidelines/openrtb-dynamic-native-ads-api-1-2/

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

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


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


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.


Page6

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

1Introduction

1.1Mission/OverviewThemissionoftheOpenRTBNativeprojectistospurstandardizationandgreatergrowthintheReal-TimeBidding(RTB)marketplaceforNativeAdsbyprovidingopenindustrystandardsforcommunicationbetweenbuyersofadvertisingandsellersofpublisherinventory.

Thisspecificationisasub-protocolofOpenRTBtoallowforthedeliveryofnativeadvertisingformats,astheirspecificsdifferfrompublishertopublisher.InMay2013,aseparateIABsubcommitteewasformedtodefinetherequestandresponsestructuresofnativeadunits;version1.0waspublishedinearly2015.


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


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.


Page9

2.1In-FeedAdUnitsTohelpdefineandclarifythetypesandcategoriesofnativeadvertising,theIABpublishedaDeepDiveonIn-FeedAdUnitsinJuly2015.Version1.1andforwardoftheNativespecusetheseconceptstodefinethedefinitionsofadtypes,detailedbelowasContextandPlacementType,whicharereplacingthepreviousLayoutIDandAdUnitID,whichweredefinedinNative1.0andbasedontheoriginalNativeAdvertisingPlaybook.

Wherefound

Mostcommonadtypes/content

objects

Mostcommontypesoflinks

Representativefeedview


Page10

2.2DataFormatAsthisspecificationoutlinesanoptionalsub-protocolofthemainOpenRTBprotocolpayload,theformatmustfollowthatofitsparent.PleaserefertothemainOpenRTBspecificationfordetailsofvariousformatsthatmaybeused

2.3VersioningTheNativeObjectintheBidRequest(OpenRTBcontainsa“ver”fielddefiningtheversionoftheOpenRTBnativeextension.

2.4CustomizationandExtensionsTheOpenRTBNativeAdsspecallowsforexchangespecificcustomizationandextensionsofthespecification.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.

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


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


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.


id required int - UniqueassetID,assignedbyexchange.Typicallyacounterfor


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.


1:eachassetobjectmaycontainonlyoneoftitle,img,dataorvideo.

4.3TitleRequestObjectTheTitleobjectistobeusedfortitleelementoftheNativead.


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



Page15

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'sMIMEpageformoreinformationandlinkstoallIETFRFCs.

Ifblank,assumealltypesare


Page16

allowed.


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.



Page17

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


type required integer - TypeIDoftheelementsupportedbythepublisher.Thepublishercandisplaythisinformationinanappropriateformat.SeeDataAssetTypestableforcommonlyusedexamples.

len optional integer - Maximumlengthofthetextintheelement’sresponse.


4.7EventTrackersRequestObjectTheeventtrackersobjectspecifiesthetypesofeventsthebiddercanrequesttobetrackedinthebidresponse,andwhichtypesoftrackingareavailableforeacheventtype,andisincludedasanarrayintherequest.


event required integer - Typeofeventavailablefortracking.SeeEventTypestable.

methods required arrayofintegers

- Arrayofthetypesoftrackingavailableforthegivenevent.SeeEventTrackingMethodstable.

ext optional object - ThisobjectisaplaceholderthatmaycontaincustomJSONagreedtobythepartiestosupportflexibilitybeyondthestandarddefinedinthis


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.


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


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.



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.


Page22

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


text required String - Thetextassociatedwiththetextelement.

len optional integer - Thelengthofthetitlebeingprovided.Requiredifusingassetsurl/dcourlrepresentation,optionalifusingembeddedassetrepresentation.


5.4ImageResponseObjectCorrespondstotheImageObjectintherequest.TheImageobjecttobeusedforallimageelementsoftheNativeadsuchasIcons,MainImage,etc.

Itisrecommendedthatifassetsurl/dcourlisbeingusedratherthanembeddedassets,thatanimageofeachrecommendedaspectratio(pertheImageTypestable)beprovidedforimagetype3.


type optional integer - Requiredforassetsurlordcourlresponses,notrequiredforembeddedassetresponses.ThetypeofimageelementbeingsubmittedfromtheImageAssetTypestable.

url required string - URLoftheimageasset.

w recommended integer - Widthoftheimageinpixels.Recommendedforembeddedassetresponses.Requiredforassetsurl/dcourlresponsesifmultipleassetsofsametypesubmitted.

h recommended integer Heightoftheimageinpixels.Recommendedforembedded


Page23

assetresponses.Requiredforassetsurl/dcourlresponsesifmultipleassetsofsametypesubmitted.


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


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



Page24

5.6VideoResponseObjectCorrespondstotheVideoObjectintherequest,yetcontainingavalueofaconformingVASTtagasavalue.Field Scope Type Default Description

vasttag required string - vastxml.

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


url required string - LandingURLoftheclickablelink.

clicktrackers optional arrayofstrings

- Listofthird-partytrackerURLstobefiredonclickoftheURL.

fallback optional string(URL)

- FallbackURLfordeeplink.TobeusediftheURLgiveninurlisnotsupportedbythedevice.


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


Page25


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”}.


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

6.1SocialContext,ClickoutResponse The ad might look like -


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]

}


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


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


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 -


Page30


"ver":”1.2”,

"context":1,


"plcmttype":11,

"plcmtcnt":1,


“privacy”:1,

“eventrackers”: [

{

“event”:1,


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


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


Page33

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


}

},

{

"id": 126,

"required": 1,

"data": {

"value": "My Brand"

}

},

{


Page34

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


“durlsupport”:1,

"assets":[

{

"id":123,

"required":1,

"title":{

"len":140

}

},

{

"id":128,

"required":0,

"img":{

"wmin":836,

"hmin":627,

"type":3

}

},

{


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


},

"assets": [

{

"id": 123,

"required": 1,

"title": {


Page36

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

}

}

]

}

WhatShouldbeReturnedbytheAssetsURL

Note:theassetsobjectmaystillbeincludedintheresponseasafallback,butthesupplysourcemustcalltheassetsurlandusetheprovidedresponseforthead.Theresponse


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.


Page38


“h”:200,

“w”:267

}

},

{

"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.1ContextTypeIDsThecontextinwhichtheadappears-whattypeofcontentissurroundingtheadonthepageatahighlevel.ThismapsdirectlytothenewDeepDiveonIn-FeedAdUnits.This


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


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.


Page41

2 desc Descriptivetextassociatedwiththeproductorservicebeingadvertised.Longerlengthoftextinresponsemaybetruncatedorellipsedbytheexchange.

text Recommended.Max140orlonger.

3 rating Ratingoftheproductbeingofferedtotheuser.Forexampleanapp’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


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


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.


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

}]

}]

}


Page45

rtb project - iab tech lab...openrtb dynamic native ads api specification version 1.2 rtb project...

Documents