RTB Project - IAB Tech Lab...OpenRTB Dynamic Native Ads API Specification Version 1.2 RTB Project...

OpenRTBDynamicNativeAdsAPISpecificationVersion1.2 RTBProject

RTB Project OpenRTB Dynamic Native Ads API Specification Version 1.2 Final Version July 2017

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:

JenniferDerkeIABTechnologyLaboratoryjennifer@iabtechlab.com

License

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

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

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

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.

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

1Introduction

1.1Mission/OverviewThemissionoftheOpenRTBNativeprojectistospurstandardizationandgreatergrowthintheReal-TimeBidding(RTB)marketplaceforNativeAdsbyprovidingopenindustrystandardsforcommunicationbetweenbuyersofadvertisingandsellersofpublisherinventory.

Thisspecificationisasub-protocolofOpenRTBtoallowforthedeliveryofnativeadvertisingformats,astheirspecificsdifferfrompublishertopublisher.InMay2013,aseparateIABsubcommitteewasformedtodefinetherequestandresponsestructuresofnativeadunits;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[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

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.

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

Wherefound

Mostcommonadtypes/content

objects

Mostcommontypesoflinks

Representativefeedview

2.2DataFormatAsthisspecificationoutlinesanoptionalsub-protocolofthemainOpenRTBprotocolpayload,theformatmustfollowthatofitsparent.PleaserefertothemainOpenRTBspecificationfordetailsofvariousformatsthatmaybeused

2.3VersioningTheNativeObjectintheBidRequest(OpenRTBcontainsa“ver”fielddefiningtheversionoftheOpenRTBnativeextension.

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

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)

Request

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

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

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.

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

allowed.

4.5VideoRequestObjectThevideoobjecttobeusedforallvideoelementssupportedintheNativeAd.ThiscorrespondstotheVideoobjectofOpenRTB.Exchangeimplementerscanimposetheirownspecificrestrictions.HerearetherequiredattributesoftheVideoObject.ForoptionalattributespleaserefertoOpenRTB.

mimes required array

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.

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

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.

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

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.

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.

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

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

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.

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 -

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]

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

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

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

"ver":”1.2”,

"context":1,

"plcmttype":11,

"plcmtcnt":1,

“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

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

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

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

“durlsupport”: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

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

"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

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.

“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

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

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.

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

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

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

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.

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

RTB Project - IAB Tech Lab...OpenRTB Dynamic Native Ads API Specification Version 1.2 RTB Project...

Documents

Transcript of RTB Project - IAB Tech Lab...OpenRTB Dynamic Native Ads API Specification Version 1.2 RTB Project...

RTB Project OpenRTB API Specification Version 2.3 · RTB Project OpenRTB API Specification Version 2.3.1 November 2014 Revised June 2015 . OpenRTB API Specification Version 2.3.1

IAB Open RTB Project - Native Ads Specification - Version1 - Feb 2015

OpenRTB Mobile

OpenRTB Ad Management API Specification - IAB Tech Lab · PDF file · 2017-11-13Ad management occurs when a buyer ... analysts or automated processes check the ad’s landing page,

RTB ecosystem

Libro blanco de Compra Programatica y RTB | IAB Spain

OpenRTB for Programmatic Digital Out of Home

RTB Glossary

rtB - pref.toyama.jp

RTB - Final

RTB Project OpenRTB Dynamic Native Ads API Specification ... › wp-content › uploads › 2016 › 02 › OpenRTB-… · OpenRTB Dynamic Native Ads API Specification Version 1.

Real Time Bidding (RTB) Project OpenRTB API Specification ... · chain while contributing to the safe growth of an industry. The IAB Tech Lab spearheads the development of technical

„RTB BOR” D.O.O. BOR RTB BOR LTD., BORdocuments.rec.org/publications/09_EMC_posters_feb_2012_RTBBor.… · „RTB BOR” D.O.O. BOR RTB BOR LTD., BOR Copper mining and smelting

RTB Study Case: Antevenio Smart AdServer RTB+2014

RTB Manual

RTB Research - Realizing the RTB Video Opportunity for Brand Marketers - Forrester

Open RTB native-ads-specification-1-0-final (IAB)

RTB Project OpenRTB API Specification Version 2...OpenRTB API Specification Version 2.4 - DRAFT IAB Technology Lab Page ii Introduction The RTB Project, formerly known as the OpenRTB

RTB Project OpenRTB API Specification Version 2.2 - IAB · OPENRTB API Specification Version 2.2 RTB Project Page 1 Before You Get Started This specification contains a very detailed

RTB Project OpenRTB API Specification Version 2 · 2017-11-13 · Introduction The RTB Project, formerly known as the OpenRTB Consortium, assembled in November 2010 to develop a new