From 67c52025451ea1706272044a4b72301cf72ad3da Mon Sep 17 00:00:00 2001 From: Federico Bartolomei Date: Mon, 25 Jul 2022 13:42:20 +0100 Subject: [PATCH 1/5] Merge upstream (#1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update firstPartyData.md (#3660) * Conversant adapter now supports the supply chain module (#3655) * Updated list of parameters for nextMillennium (#3654) * Add dacid user id module (#3644) * Feature/esp (#3643) * ESP: encryptedSignalSources key added under userSync object * ESP: Description changed * Docs updated for ESP in user id module section * Docs updated for ESP in user id module section * Docs updated for ESP in user id module section * Docs updated for ESP in user id module section * Section related to ESP moved at the end of basic configuration * ESP documentation: Few corrections * ESP: Added few more details and link to google beta documentation * ESP documentation: Note classes added and few changes * ESP configs and its description is updated * Config changes doc updated * Allow configuration of the sync URL and to allow callbacks for specific custom partner integrations (#3586) * Update userId.md Included novatiq snowflake id submodule specifications * Update download.md Added novatiq snowflake id submodule * Revert "Update userId.md" This reverts commit 556d56a11608135b5abcbe73755bb9b3b8be7308. * Update userId.md Novatiq ID System: updated product description as per request * fix layout and format as per other examples * tables still broken, missed markup line just before the close div - try again * whitespace? * Document "Allow configuration of the sync URL and to allow callbacks for specific custom partner integrations" functionality * typos Co-authored-by: novatiq <79258366+novatiq@users.noreply.github.com> * Add banner support (#3638) * SA Lunamedia Bidder Adapter: fix markdown (#3637) * New adapter "SA Lunamedia" * New adapter "SA Lunamedia" 2 * add userSync * remove gdpr tag since gdpr_supported is included * schain * fix markdown Co-authored-by: Chris Huie * Open8 Bid Adapter: update docs for added back (#3634) * JDB-496: adding ftrack to the Prebid website (#3627) Co-authored-by: Jason Lydon * add imuid userId Module download (#3624) * readme file for idWardRtdProvider (#3578) Co-authored-by: Pavlo * Vendor Billing in Prebid.js (#3533) * auction delay and timeout * removing common RTD params from params table * Vendor Billing in Prebid.js * Update vendor-billing.md * wordsmithing Co-authored-by: bretg Co-authored-by: MartianTribe * added renderer config (#3531) * Bump url-parse from 1.5.7 to 1.5.10 (#3604) Bumps [url-parse](https://github.com/unshiftio/url-parse) from 1.5.7 to 1.5.10. - [Release notes](https://github.com/unshiftio/url-parse/releases) - [Commits](https://github.com/unshiftio/url-parse/compare/1.5.7...1.5.10) --- updated-dependencies: - dependency-name: url-parse dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump ssri from 6.0.1 to 6.0.2 (#3601) Bumps [ssri](https://github.com/npm/ssri) from 6.0.1 to 6.0.2. - [Release notes](https://github.com/npm/ssri/releases) - [Changelog](https://github.com/npm/ssri/blob/v6.0.2/CHANGELOG.md) - [Commits](https://github.com/npm/ssri/compare/v6.0.1...v6.0.2) --- updated-dependencies: - dependency-name: ssri dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * mediafuse md file change (#3585) * removed mediafuse md files as we are deploying new pull request we wanted to remove the existing bidders list on the name mediafuse * created mediafuse bidder md file * Revert "created mediafuse bidder md file" This reverts commit fb49c32fc9ac746a3f7d02e4cd357bf7c5229cab. * Created MediaFuse bidder md file * updated test parameters Co-authored-by: rn * PBS deals update (#3679) explaining the difference in what's sent to the ad server based on whether PBJS is present. * PBS FAQ: SSL support (#3680) * PBS Hosting update (#3681) adding note about SSL * mobile config id (#3682) Added note about config ID being the stored request id * mobile config ID clarification (#3683) * rubicon: added PBS host instructions (#3684) * PBS coop-sync doc (#3685) * Update PBS adapter documentation (#3662) * Update PBS documentation Unify PBS documentation as a module (not a bidder); remove duplication about it from `setConfig`; add stored impression examples PBJS PR: https://github.com/prebid/Prebid.js/pull/8154 * wordsmithing Co-authored-by: bretg * YahooSSP added video support. (#3664) Co-authored-by: oath-jac * init (#3661) * PBS-Go: Remove User Sync Default + Update Features (#3656) * add Yandex Bidder Adapter (#3641) Co-authored-by: Taras Saveliev * PubMatic: add "acat" parameter (#3657) * PubMatic: add "acat" parameter * use IAB catagories for acat * Biddo Bid Adapter: add dev docs for biddo adapter (#3659) * Added dev docs for invamia bid adapter * Add dev docs for biddo adapter Co-authored-by: Andrew Lays * Add DistroScale Bid Adapter (#3665) * prebidServer module updates (#3697) added TOC, changed heading levels * Fix #3327 add multiformat_supported field (#3694) * Fix #3327 add multiformat_supported field * Add new field in pbs java/go docs as well * Update google.md * adapter notice added (#3692) * GA doc - add instructions (#3703) * fix interstitial nav entry (#3704) * GA docs: clarify cpmDistribution (#3706) * enhanced load-cookie docs (#3707) * add JANet doc (#3591) remove some aliases' docs * Bump minimist from 1.2.5 to 1.2.6 (#3702) Bumps [minimist](https://github.com/substack/minimist) from 1.2.5 to 1.2.6. - [Release notes](https://github.com/substack/minimist/releases) - [Commits](https://github.com/substack/minimist/compare/1.2.5...1.2.6) --- updated-dependencies: - dependency-name: minimist dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Updating pulsepoint config related to userIds support (#3689) * docs: update AudienceRun adapter doc (#3687) * Nexx360 - Video added to nexx360 bid adapter (#3686) * video added * video added to nexx360 * Remove useridtargeting (#3677) * add PGAM doc (#3675) * Yahoo Branding (#3674) Updated Yahoo Brand from VerizonMedia Co-authored-by: ed * Fix SmartHub documentation (#3672) Make pbjs: true * Remove outdated information for PubMatic bidder (#3671) * floor support (#3670) * USP API Doc was wrong (#3667) * Update consentManagementUsp.md * fixing table Co-authored-by: bretg * add parameters in Fabrick ID by Neustar section. (#3668) * add parameters in Fabrick ID by Neustar section. * add parameters in Fabrick ID by Neustar section. * Glimpse: add usp support, update params and fpd setup (#3669) - Add usp support - Remove demand and keywords bidder params - Update example on setting up adapter with first party data - Rename placementId to pid - Update fpd section description - remove user.ext.keywords from example - update contact email address * [:art:] fix: publisherPath typo (#4) (#3705) * Update documentation for publisher userID api (#3698) * Update documentation for publisher userID api * Update dev-docs/modules/userId.md Fix backtick Co-authored-by: Scott Menzer Co-authored-by: Scott Menzer * added multiformat support (#3712) * Update documentation for RampID module (#3695) * Update userId module Add storage.refreshInSeconds to example implementations * Update userId.md * Update ATS Analytics documentation Provide extra information how to configure. * Update ats.md * Update about.md (#3717) * Remove Reference Supporting Dynamic Domains (#3724) * Remove Reference Supporting Dynamic Domains * Grammar Fix * Build package info for pubProvidedIdSystem fix (#3710) pubProvidedIdSystem instead of pubProvidedId * Fix janet server flag (#3716) * Update cwire.md (#3676) Add `enable_download: true` to cwire.md to enable download link for cwire adapter. * PBS Floor documentation (#3733) * pbs floors early draft * first draft * 2nd review * added beta notice * Fix Rise doc (#3678) * Update Rise readme * fix rise doc * change rise docs * PBJ: Add IPF feature to bid adapter (#3735) * PBJ: Add IPF feature to bid adapter * wordsmithing What's the difference between mediaType and format? The PRD outlines mediaType and size. * wordsmithing, cont. * fixed classes used in getfloors Co-authored-by: Serhii Nahornyi Co-authored-by: bretg * fixed cwire md file (#3737) * Evolution Bid Adapter: add id5id (#3728) * e-volution doc update * updates for Prebid v5 * add id5id Co-authored-by: bretg * PBS native - adding asset.id (#3746) * AudienceRun bid adapter: update doc (#3718) * docs: update AudienceRun adapter doc * docs: update AudienceRun bid params, floors support and registration * fix md (#3729) * fix for jekyll not starting with ruby 3 (#3740) https://github.com/jekyll/jekyll/issues/8523 Co-authored-by: Michele Nasti * Added doc for acat field priority (#3709) Co-authored-by: Kapil Tuptewar * Show ATS Analytics on download page (#3747) set enable_download to true * Prebid mobile release 2 0 (#3732) * remove some mopub files * remove some mopub files * setup max network * multiformat * rendering controls * max integration for android * android: Customization Controls * android: rendering controls * corrections for the new version * corrections according to the review * corrections for the 2.0 version * changes for 2.0 * corrections for 2.0 * corrections for 2.0 * fix typo Co-authored-by: Yuriy Velichko * removed PubNX bid adaptor (#3748) Co-authored-by: Mohit Patil * FTrack User Id submodule: making the IDs dynamic (#3690) * JDB-253: making the IDs dynamic * JDB-523: updating documentation for household ID * PR cleanup Co-authored-by: Jason Lydon * feat: updated insticator.md (#3738) * Triplelift: update bidder params page (#3722) * fix adapter name (#3699) * Automatad Bid Adapter: update doc to reflect placementId as optional parameter for adapter (#3693) * added automatad openRTB adapter doc * Update automatad documentation with first party data support status * remove duplicate file * make placementId optional * Mediasniper bid adapter (#3652) * Mediasniper bidder adapter * fix placement -> placementId * update docs to indicate native support (#3714) * Criteo: Updated document regarding first party data support (#3739) * MimuteMedia - Add support for Banner (#3708) * Update Rise readme * Add support for banner * fix doc * fix rise doc * roll * cr * Initial GAM Yield Group FAQ (#3750) * Initial GAM Yield Group FAQ * Update faq.md Co-authored-by: MartianTribe * adds cids (#3744) * Add 33Across user id sub-module (#3736) * Add 33across id section to user id documentation * apply CR feedback to 33across ID documentation * Switch AppNexus AMP RTC Mentions To PSP (#3723) * MobfoxPB Adapter: ported adapter to v5 (#3713) * initial * Update mobfoxpb.md * Update mobfoxpb.md * Update mobfoxpb.md * Update mobfoxpb.md Add `key` parameter * updates for prebid v5 Co-authored-by: Aiholkin * PBS troubleshooting debug flag update (#3755) * Incorrect module code (#3758) * Added documentation for allowAlternateBidderCodes property (#3721) * Added documentation * more explanation about bidderSetting Co-authored-by: pm-azhar-mulla * added renaming FAQ entry (#3752) * Fix `modulecode` for the ATS analytics adapter (#3756) * PBS auction endpoint fix (#3764) * Add Professor Prebid user guide (#3753) * Add Professor Prebid User Guide * wordsmithing added alt text, related reading, minor wordsmithing * wordsmithing added alt text, related reading, minor wordsmithing Co-authored-by: Allan Jun Hirata Co-authored-by: bretg * Fix wrong formatting of 33Across configuration params (#3757) * chore: update AirGrid docs, typos and link fixes (#3759) * Update talkads.md (#3767) * updated Invibes documentation to reflect the latest updates on Local Storage usage (#3769) * Updated the TTL for banner and video bids (#3771) * Colossus Bid Adapter: add new param (#3663) * Updated docs Colossusssp Adapter * Update colossusssp.md Add media types * Update colossusssp.md add usp consent support * adding schain flag * gdpr and user ids * id5id support * Prebid server info * Remove PBS params * Add colossus PBS docs * Add short note for pbs adapter parametres * Add note for pbjs parametres * Fix * remove duplicate string * Update colossusssp.md Ad biddflorr parameter * add uid2 * fix * fix * add group_id * add groupId Co-authored-by: Vladislav Isaiko Co-authored-by: bretg Co-authored-by: Aiholkin * Adding Aax bidder adapter doc (#3696) * Adding Aax bidder adapter doc * recommended flags added * added support for video * rectified gvl id * Update naming of RampID user id module (#3726) * Alkimi Bid Adapter (#3730) * Alkimi bid adapter * Alkimi adapter docs Co-authored-by: Alexander Bogdanov * Jx userids (#3734) * as we are adding the prebid-server adaptor and introduced a few extra params , they are added here too (note: those 3 new params would also reach the headerbid adserver in the case of prebid "clientside HB" too. So all good) * added quotes around string params * added userids entry Co-authored-by: bretg * Hadron analytics adapter (#3741) * documenting hadronAnalyticsAdapter * Changed the text * Renamed to Audigent analytics adapter Co-authored-by: Abhinav Bondalapati <1435575+abhibond@users.noreply.github.com> * Change macro resolution langauge (#3743) * Update faq.md * Update faq.md * Adman Bid Adapter: add idx (UserID Module) (#3751) * Add adman dev doc * Change params Params required by new adapter setup * Edit docs Fix naming, use quotes around example * adding quotes to string param * Update adman.md * tcf2_supported: true * Update adman.md add usp support * Add api param for prebid servr adapter * updates for prebid 5.0, and support uid2 * add Lotame Panorama ID * add idx (UserID Module) Co-authored-by: minoru katogi Co-authored-by: ADman Media Co-authored-by: bretg Co-authored-by: Aiholkin * Updated adf docs (#3754) Co-authored-by: Justas Pupelis * Add CPEx ID (#3768) * Add CPEx ID * Add cpexId adapter line * Update tpmn.md (#3775) Co-authored-by: changjun * Add PGAM client side support (#3778) * Improve Digital adapter: Extend mode (#1) (#3782) * Richaudience BidAdapter: Add new info to .md (#3783) * Add Documentation For Prebid Server Adapter * Richaudience BidAdapter: Add new info to .md * Fix/bliink documentation (#3784) * fix: bliink.md updated * docs: bliink.md updated Co-authored-by: louisbillaut * outstream docs update (#3777) Co-authored-by: Love Sharma * Removed GroupM as alias of PubMatic (#3761) * removed groupm docs * Updated docs for groupm * adding version note header Co-authored-by: pm-azhar-mulla Co-authored-by: bretg * Add BidWatch Analytics Adapter (#3715) * Add new Analytics Adapter: bidwatch * change enable download * Update weborama RTD submodule doc for specify list of bidders to share data (#3745) * update doc * update docs * update doc * add mentions to sfbx-lite * update docs * Update oftmedia.md (#3774) Update with corrections and up-to-date data. * PBS auction doc updates (#3787) * PBS auction doc updates added a new deals targeting option and revised the bid caching section * updated summary table * oftmedia doesn't support PBS (#3801) * Add Gravito Id in prebid documentation (#3789) * remove onevideo adapter details (#3790) Co-authored-by: dsravana * Add comma to code examples for RampID (#3791) * Automatad adapter documentation update (#3793) * Automatad adapter documentation update * Modified the automatad's bidder docs to support prebid server documentation. * Modified the automatad adapter's documentation to removed siteId and made position an optional field * Sortable Adapter Removal (#3795) * Rename id to aoneId from dacId (#3796) * Update adsolut.md (#3798) Add media types, add privacy compliance * Remove notice of support of custom clientID (#3800) Co-authored-by: Erik Hummel * Add new docs for our Taboola adapter (#3760) * create new adapter docs for taboola bidder * small fixes * small fixes * Reposition the CSS directive Reposition the styling directive. Split the 'Note' into 2 sections. Make minor textual tweaks. * create new adapter docs for taboola bidder * small fixes * small fixes * Reposition the CSS directive Reposition the styling directive. Split the 'Note' into 2 sections. Make minor textual tweaks. * Update taboola.md disable the support of: schain_supported Co-authored-by: pcimring-taboola <57901387+pcimring-taboola@users.noreply.github.com> * Akamai RTD: Updated the taxonomy value and signature version (#3700) * Updated the taxonomy value and signature version * Updating documentation around dapFpUrl and dapFpTimeout * Changed the entropy variable names and script location * Fixing review comments - correcting the table * AdYouLike BidderAdapter schain support (#3804) * add getfloor support for adyoulike * add userId support on adyoulike bidder * removed obsolete pubCommonId * remove user ids * fix schain after merge * updated aax adapter title (#3806) * zeta_global_ssp docs (#3797) Co-authored-by: Surovenko Alexey * Updated docs for Kobler adapter (#3794) * Updated docs for Kobler adapter. * Added more details about page URL. * Update stroeerCore.md (#3781) * Update stroeerCore.md * add fields * Add piano dmp analytics adapter docs (#3772) Co-authored-by: Dmitriy Mishutin * IncrementX Bid Adapter: vertoz adapter renamed to IncrementX (#3725) * IncrementX Bid Adapter: vertoz adapter renamed to IncrementX * IncrementX Bid Adapter: bidder flags updated * IncrementX Bid Adapter: bidder flags updated Co-authored-by: Mohit Patil * added videoHeroes spec to docs (#3720) * added brave bidder docs * added quotes around the string parameter * added videoHeroes spec to docs Co-authored-by: bretg * Bump eventsource from 1.0.7 to 1.1.1 (#3817) Bumps [eventsource](https://github.com/EventSource/eventsource) from 1.0.7 to 1.1.1. - [Release notes](https://github.com/EventSource/eventsource/releases) - [Changelog](https://github.com/EventSource/eventsource/blob/master/HISTORY.md) - [Commits](https://github.com/EventSource/eventsource/compare/v1.0.7...v1.1.1) --- updated-dependencies: - dependency-name: eventsource dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Magnite adapters still require legacy GVL IDs (#3810) * PBS: added endpoint-compression config (#3828) * appnexus First Party Data updates (#3832) * appnexus First Party Data updates * typo * Update appnexus.md Co-authored-by: bretg * fixed silly typo (#3834) * Require supply chain module in mediakeys adapter (#3821) Co-authored-by: François Maturel * update to HB yield group FAQ (#3829) * Prebid 7: update docs on refererInfo, publisherDomain (#3799) Co-authored-by: Chris Huie * Removed akamaiUserID documentation (#3813) * feat: updated insticator.md (#3807) * test * feat: added description for video * feat: fix README.md * feat: added multiformat_supported Co-authored-by: Sergey Derbush * Updated merkleId parameters (#3809) Co-authored-by: Nick Curry * Remove adlive bidder (PBJS 7) (#3765) Per https://github.com/prebid/Prebid.js/issues/8394 * fixing bidder code for incrementx (#3837) * download page doesn't like 7.0 * download page doesn't like 7.0 (#3840) * Create pb7-notes.md (#3779) * Create pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update pb7-notes.md * Update sharethrough.md * Update rubicon.md * Update ttd.md * Update colossus.md * Update appnexus.md * Update kargo.md * Update colossus.md * Update dev-docs/pb7-notes.md Co-authored-by: Nepomuk Seiler * Update dev-docs/pb7-notes.md Co-authored-by: Nepomuk Seiler * Update dev-docs/pb7-notes.md Co-authored-by: Nepomuk Seiler * Update dev-docs/pb7-notes.md Co-authored-by: Nepomuk Seiler * Update dev-docs/pb7-notes.md Co-authored-by: Nepomuk Seiler * Update pb7-notes.md * Update pb7-notes.md * wordsmithing Great draft Patrick. Added pub summary, PBS versions, general minor tweaks. Q: what is the "UserID Targeting" module? Co-authored-by: Nepomuk Seiler Co-authored-by: bretg * linking PBJS 7 notes (#3846) * feature/blueconicRtdProvider (#3812) * add dev docs for blueconic Rtd provider * update table structure * review comments * Added documentation for FPD (#3842) Co-authored-by: pm-azhar-mulla * [Criteo] Add documentation on "publisherSubId" bid param (#3843) * removing FPD support flag (issue 3444) (#3833) * TrustX: make trustx as alias of gridBidAdapter (#3727) * Added doc file for Grid Bid Adapter * update doc for TheMediaGrid Bid Adapter * Added video support in Grid doc file * removing unnecessary front matter * Update doc file for TheMediaGrid Bid Adapter * Added doc file for TheMediaGridNM Bid Adapter * Update doc file for TheMediaGrid Bid Adapter * Update doc file for The Media Grid Bid Adapter * Update THeMediaGrid doc to support TCF 2.0 * Update doc for TheMediaGrid Bid Adapter * Update doc file for TheMediaGrid Bid Adapter * Update doc for TheMediaGrid Bid Adapter * Update TheMediaGrid doc to support coppa * Update GridNM Bid Adapter doc file * TheMediaGrid: update doc * Added alias playewire for TheMediaGrid Bid Adapter * Added some description in TheMediaGrid doc * Added alias adlivetech for TheMediaGrid Bid Adapter * TheMediaGrid: update doc * TheMediaGrid: update docs for gridNM, grid and aliases to support FPD * TrustX: update doc to support FPD * TrustX: make trustx as alias of gridBidAdapter * TheMediaGrid: update doc - multiformat_supported flag added * TrustX: update doc Co-authored-by: bretg * Add first-party data support to Beachfront doc (#3853) * update beachfront doc * update * update * update Co-authored-by: John Salis * Update consentManagementUsp.md (#3822) * Update consentManagementUsp.md * Update consentManagementUsp.md * Prebid 7: update docs for `allowAlternateBidderCodes` and related fields (#3762) * Prebid 7: update docs for `allowAlternateBidderCodes` and related fields PBJS PR: https://github.com/prebid/Prebid.js/pull/8373 * Reintroduce 6.x - 7.x difference in default for `allowAlternateBidderCodes` * NextRoll ID: Remove NextRoll ID module (#3619) * Change storagemanager default access (#3780) * Update bidderSettings.md * clarifying storageAllowed default Co-authored-by: bretg * Remove references to TCFv1 and update examples to use TCFv2 (#3749) PBJS PR: https://github.com/prebid/Prebid.js/pull/8356 * districtm version notes (#3855) * Update pbs-endpoint-auction.md (#3856) * AdUp Technology Adapter update docs (#3816) * add floors_supported: true * IX Bid Adapter: Outstream Floating Support (#3826) * updated ix docs for outstream float support * minor verbiage fix * included floating support content (#4) * included floating support content * Update ix.md * Update ix.md Co-authored-by: Love Sharma Co-authored-by: rimaburder-index <55195208+rimaburder-index@users.noreply.github.com> * Prebid 7: update docs related to first-party data (#3823) * Prebid 7: update docs related to first-party data * Update add-rtd-submodule.md * Update bidder-adaptor.md * Update add-rtd-submodule.md * Update huaweiads.md (#3854) add gdpr and coppa support Co-authored-by: Ho Chia Leung * PBS doc location fix (#3858) * updating hbyg faq entry (#3848) * add kueez adapter docs (#3845) * updates appnexus keywords param to include kv limit (#3824) * Add new Adapter: TrafficGate (#3711) * Add new Adapter: TrafficGate * New Adapter: TrafficGate * TrafficGate adapter: add pbjs * TrafficGate adapter: add flags Co-authored-by: vlad * Add AudienceOne ID and modify name to YieldOne from YIELDONE in yieldone.md (#3819) * add AudienceOneID to userIds in yieldoneBidAdapter * modify name to YieldOne from YIELDONE * add multiformat_supported field * Alkimi bid adapter: added features (#3814) * Alkimi bid adapter * Alkimi adapter docs * features support added * multiformat_supported feature Co-authored-by: Alexander Bogdanov Co-authored-by: alexander bogdanov Co-authored-by: Alexander <32703851+pro-nsk@users.noreply.github.com> Co-authored-by: Nikulin Mikhail Co-authored-by: mihanikw2g <92710748+mihanikw2g@users.noreply.github.com> Co-authored-by: motors * PBS feature update (#3869) * ZetaSspBidAdapter docs: Add contacts (#3868) * Fix video examples overflowing container (#3866) Co-authored-by: Andrew Fowler * Triplelift: Update typo in Triplelift Bidder Params (#3861) * Triplelift: update bidder params page * Fixed inventoryCode typo in bidder param documentation * add finative Adapter (#3844) * updated docs with documentaion on how to configure new skin product (#3839) Co-authored-by: John Bauzon * idx bidder adapter docs (#3827) * idx bidder adapter docs * IDX Bid Adapter: rename md file and bidder code * Dianomi bid adapter: new bid adapter (#3825) * Adding dianomi.md * removed trailing comma * Criteo - State more explicitly that our bidder automatically includes our user id module (#3815) * Lasso bid adapter (#3811) * Lasso bid adapter * Lasso adapter documentation update * Lasso adapter documentation update * Lasso prebid adapter Co-authored-by: Victor Romasenco * Add missing slash for internal link * MobfoxPB Adapter: update header value (#3867) * initial * Update mobfoxpb.md * Update mobfoxpb.md * Update mobfoxpb.md * Update mobfoxpb.md Add `key` parameter * updates for prebid v5 * update enable_download Co-authored-by: Aiholkin * removing rivr analytics (#3870) * Sspbc adapter (#3763) * add sspbc adapter * add sspbc adapter * sspBC adaptor: update bidder description * Update dev docs for v4.7 of sspBC adaptor; change name of the doc; change id/siteid parameters to optional * sspBC bid adapter: update documentation (publisherId optional parameter), remove duplicate md (sspBC.md) * sspBC bid adapter: revert to old md name (sspBC.md) * sspBC bid adapter: fix typo * sspBC bid adapter: fix typo * sspBC bid adapter: change example value Co-authored-by: Wojciech Biały * PBS auction endpoint: ext.prebid.targeting (#3803) Co-authored-by: Nepomuk Seiler * New doc for Shinez Prebid adapter (#3808) * New doc for Shinez Prebid adapter * Shinez adapter doc fixed according to reviewer comments * IX Bid Adapter: Documentation for Native Support (#3831) * added native support * Update ix.md (#3) added content for native support Co-authored-by: Love Sharma Co-authored-by: rimaburder-index <55195208+rimaburder-index@users.noreply.github.com> * update OpenX docw with video changes and adapter specifics (#3836) * Added information about first party data. (#3835) Co-authored-by: bretg * [Criteo] Add mention of hashed email collection in bidder documentation (#3859) * feat: updated insticator.md (#3864) * test * feat: added video placement param * fix readme.md Co-authored-by: Sergey Derbush Co-authored-by: Ilya Stalmahov * Adding infytv adapter document (#3865) * Add working outstream with mediaType renderer example (#3871) * Add working outstream with mediaType renderer example * Expand appnexus renderer example * Fix html formatting * PBS storedbidresponse update (#3880) * PBS storedbidresponse update * Update pbs-endpoint-auction.md * Update pbs-endpoint-auction.md * updating Taboola adapter documentation (#3874) * create new adapter docs for taboola bidder * small fixes * small fixes * Reposition the CSS directive Reposition the styling directive. Split the 'Note' into 2 sections. Make minor textual tweaks. * create new adapter docs for taboola bidder * small fixes * small fixes * Reposition the CSS directive Reposition the styling directive. Split the 'Note' into 2 sections. Make minor textual tweaks. * Update taboola.md disable the support of: schain_supported * update taboola prebid documentation Co-authored-by: Michael Co-authored-by: pcimring-taboola <57901387+pcimring-taboola@users.noreply.github.com> Co-authored-by: mikiz <31058500+mikizi@users.noreply.github.com> * PBS feature list: host schain (#3885) * Updated user sync content (#3887) Updated user sync content to include iframe and img based syncing support * Nexx360 Bid Adapter - Additional documentation (#3701) * video added * additional parameters added * Fix currency to string format As discussed, I've fix the string to currency issue * Fix update * New Adapter: Adtargetme docs (#3888) * Updated support flags (#3851) * Make thank you message in template a comment * Add comment on how to handle the checklists * PBJS: document the NATIVE feature flag for bid adapters (#3862) * Kargo Analytics Adapter: Docs update (#3818) * Kargo Analytics Adapter: Update to docs * Spellcheck * Styling suggestion Co-authored-by: Nepomuk Seiler Co-authored-by: Nepomuk Seiler * Add ras bid adapter docs (#3838) * Add ras bid adapter docs * Add ras bid adapter docs Co-authored-by: skoklowski * New Bid Adapter Dev Docs: newspassid (#3849) * Dev Documents for New Bid Adapter NewsPassId Prebid JS dev documents for Dev Documents for New Bid Adapter NewspassId * Dev Doc for new bidder: newspassid correct floor price module support flag. * dev docs for new bid adapter newspassid Updated dev docs * newspass dev docs updated updated error in bidder code in test params * Delete newspassid.md removing file at the root of the repo * Update newspassid.md * Update newspassid.md * Update newspassid.md * updating list of reserved words that cannot be bidder names (#3902) * update selectmedia gvlid (#3900) * 1plusX RTD submodule docs (#3873) * WIP prebid.github.io doc * Add more details * Update contact email + fix typo on param name + made supported bidders table better * add some white space in the table so it's readable even in plain text * Oops * Change customerId param type to string in doc * Remove supported bidders from docs * Adkernel: updating andbeyond alias (#3876) * Docs for imp-level floorMin (#3877) * imp-level floorMin * responding to feedback added actual default data, re-labeled 'publisher interface' to 'in-page interface' * Adnuntius Bid Adapter: Documentation for video (#3878) * Use cookie information. * Adnuntius RTD Provider documentation * Video documentation update * Relaido Bid Adapter: Add documentation for bids[].params.video.playerSize (#3879) * add relaido adapter * Add support for bids[].params.video.playerSize Co-authored-by: ishigami_shingo Co-authored-by: cmertv-sishigami Co-authored-by: n.maeura * adding partnerId and changing publisherId by partnerId (#3881) * update seedtag bidder doc for usp/ccpa compliance (#3882) * Fix ccpa (#3884) * Lasso bid adapter * Lasso adapter documentation update * Lasso adapter documentation update * Lasso prebid adapter * fix for usp / ccpa * fix ccpa and remove old value Co-authored-by: Victor Romasenco * Added descriptions of ID5 and Criteo to AdGenerationDoc. (#3886) * update AdGeneration Doc: add novatiq * Added descriptions of ID5 and Criteo to AdGenerationDoc. Co-authored-by: banakemi * chore: upgrade flowplayer to v3 (#3891) * [DSP-3690] feature: Add schain & pubProvidedId (#5) (#3894) * update Consumable Bid Adapter features (#3901) * registerDelay of ESP is actually milliseconds (#3896) * Update descriptions for notUse3P param (#3895) * Remove additional tcf 1.1 references (#3904) * Update consentManagement.md * Update consentManagement.md * pbs ortb-block fix formatting (#3909) a couple of tables were missing a cell * add ortb-blocking metadata (#3908) * PubMatic: add ORTB blocking & multi-bid info (#3912) * add doc: imRtdModule (#3911) * add imRtdProvider doc * add corp link * nextMillennium: adding scope flag (#3918) * Update bucksense.md (#3850) * support for ID5 (#3914) * BLIINK Doc : Update doc by removing placement, adding optional imageUrl and setting pbs to true (#3907) * fix: bliink.md updated * fix(bliink doc) remove placement param * fix(bliink doc) add optional imageUrl Co-authored-by: louisbillaut Co-authored-by: samous * add schain and coppa to Consumable docs (#3906) * Smartx does support floors (#3917) * Prisma Bid Adapter: add new bid adapter (#3898) * Prisma Bid Adapter: add new bid adapter * Update prisma.md * Add support for price floors and schain in onetag.md (#3893) Co-authored-by: federico * Update doc for 1plusX RTD Provider (#3915) * Add native handling for PBS only (#3883) * Fix domain sample * Add HTTPS sample for domain parameter * Add HTTPS sample for domain parameter * Add Smart AdServer in the index and download list * Add currency parameter documentation * Revert "Merge remote-tracking branch 'refs/remotes/prebid/master'" This reverts commit 099edc2d8e4e993406c2cb89612ff6d297b4515b, reversing changes made to 07ce9fd7e2f3a2f11f6caf82e24c1f636fd91d03. * Update documentation Specify "target" parameter development status * Adding documentation for bidfloor parameter. * [SIM-1517] Update doc Co-authored-by: Mordhak Co-authored-by: Mordhak Co-authored-by: Sébastien Ferry Co-authored-by: gcarnec Co-authored-by: Yuriy Tyukhnin Co-authored-by: tadam Co-authored-by: krzysztof <88041828+krysztal-smart@users.noreply.github.com> Co-authored-by: Spacedragoon Co-authored-by: Patrick McCann Co-authored-by: johnwier <49074029+johnwier@users.noreply.github.com> Co-authored-by: Malkov Mikhail Co-authored-by: kyoya-takei <50602864+kyoya-takei@users.noreply.github.com> Co-authored-by: Nitin Nimbalkar <96475150+nitin0610@users.noreply.github.com> Co-authored-by: rajsidhunovatiq <79534312+rajsidhunovatiq@users.noreply.github.com> Co-authored-by: novatiq <79258366+novatiq@users.noreply.github.com> Co-authored-by: readpeaktuomo <66239046+readpeaktuomo@users.noreply.github.com> Co-authored-by: lunamedia <73552749+lunamedia@users.noreply.github.com> Co-authored-by: Chris Huie Co-authored-by: Jason Lydon <95770514+ftxmoJason@users.noreply.github.com> Co-authored-by: Jason Lydon Co-authored-by: eknis Co-authored-by: Pavlo Kyrylenko Co-authored-by: Pavlo Co-authored-by: omerBrowsi <54346241+omerBrowsi@users.noreply.github.com> Co-authored-by: bretg Co-authored-by: MartianTribe Co-authored-by: Jozef Bartek <31618107+jbartek25@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: balajimediafuse <87535823+balajimediafuse@users.noreply.github.com> Co-authored-by: rn Co-authored-by: Demetrio Girardi Co-authored-by: oath-jac <45564796+oath-jac@users.noreply.github.com> Co-authored-by: oath-jac Co-authored-by: supadm <98890970+supadm@users.noreply.github.com> Co-authored-by: Scott Kay Co-authored-by: Saveliev Taras Co-authored-by: Taras Saveliev Co-authored-by: Nilesh Chate <97721111+pm-nilesh-chate@users.noreply.github.com> Co-authored-by: llays Co-authored-by: Andrew Lays Co-authored-by: duancg Co-authored-by: Nepomuk Seiler Co-authored-by: Gena Co-authored-by: Anand Venkatraman Co-authored-by: Audiencerun <57719351+audiencerun@users.noreply.github.com> Co-authored-by: Gabriel Chicoye Co-authored-by: ebrandmark2 <73907684+ebrandmark2@users.noreply.github.com> Co-authored-by: ed Co-authored-by: SmartHubSolutions <87376145+SmartHubSolutions@users.noreply.github.com> Co-authored-by: Mike Chowla Co-authored-by: Mark Kuhar Co-authored-by: nsrhls <78580780+nsrhls@users.noreply.github.com> Co-authored-by: EddieYu <32135564+eddieyu1998@users.noreply.github.com> Co-authored-by: ramyferjaniadot <90328697+ramyferjaniadot@users.noreply.github.com> Co-authored-by: Demetrio Girardi Co-authored-by: Scott Menzer Co-authored-by: Daniël Hoeksema <37441336+danielsao@users.noreply.github.com> Co-authored-by: bozghiyy Co-authored-by: Espen <2290914+espen-j@users.noreply.github.com> Co-authored-by: Noam Tzuberi Co-authored-by: SerhiiNahornyi Co-authored-by: Serhii Nahornyi Co-authored-by: e-volution-tech <61746103+e-volution-tech@users.noreply.github.com> Co-authored-by: Hashiomoto <50349637+HashimotoLogly@users.noreply.github.com> Co-authored-by: Michele Nasti Co-authored-by: Michele Nasti Co-authored-by: kapil-tuptewar <91458408+kapil-tuptewar@users.noreply.github.com> Co-authored-by: Kapil Tuptewar Co-authored-by: Yuriy Velichko Co-authored-by: Yuriy Velichko Co-authored-by: PubNX <44992681+prebid-pubnx@users.noreply.github.com> Co-authored-by: Mohit Patil Co-authored-by: Eugene Vigonny <79149590+EugeneVigonny@users.noreply.github.com> Co-authored-by: Patrick Loughrey Co-authored-by: puhiza-d <103563100+puhiza-d@users.noreply.github.com> Co-authored-by: Kanchika - Automatad Co-authored-by: Oleg Romanenko Co-authored-by: Nick Jacob Co-authored-by: Léonard Labat Co-authored-by: MartianTribe Co-authored-by: Karim Mourra Co-authored-by: Carlos Felix Co-authored-by: mobfxoHB <74364234+mobfxoHB@users.noreply.github.com> Co-authored-by: Aiholkin Co-authored-by: pm-azhar-mulla <75726247+pm-azhar-mulla@users.noreply.github.com> Co-authored-by: pm-azhar-mulla Co-authored-by: allanjun Co-authored-by: Allan Jun Hirata Co-authored-by: Carlos Felix Co-authored-by: Dennis Co-authored-by: natexo-technical-team <91968830+natexo-technical-team@users.noreply.github.com> Co-authored-by: mihaisandu07 <102022853+mihaisandu07@users.noreply.github.com> Co-authored-by: rimaburder-index <55195208+rimaburder-index@users.noreply.github.com> Co-authored-by: Bill Newman Co-authored-by: Vladislav Isaiko Co-authored-by: product-aax <103228925+product-aax@users.noreply.github.com> Co-authored-by: Alexander <32703851+pro-nsk@users.noreply.github.com> Co-authored-by: Alexander Bogdanov Co-authored-by: jxdeveloper1 <71084096+jxdeveloper1@users.noreply.github.com> Co-authored-by: joseluis laso Co-authored-by: Abhinav Bondalapati <1435575+abhibond@users.noreply.github.com> Co-authored-by: SmartyAdman <59048845+SmartyAdman@users.noreply.github.com> Co-authored-by: minoru katogi Co-authored-by: ADman Media Co-authored-by: Justas Pupelis Co-authored-by: Justas Pupelis Co-authored-by: David Spohr Co-authored-by: TPMN Admin Co-authored-by: changjun Co-authored-by: Rich Audience Co-authored-by: Louis Billaut Co-authored-by: louisbillaut Co-authored-by: Love Sharma Co-authored-by: Love Sharma Co-authored-by: matthieularere-msq <63732822+matthieularere-msq@users.noreply.github.com> Co-authored-by: Tiago Peczenyj Co-authored-by: 152Media <54035983+152Media@users.noreply.github.com> Co-authored-by: rahulgravito <105201950+rahulgravito@users.noreply.github.com> Co-authored-by: DeepthiNeeladri Co-authored-by: dsravana Co-authored-by: Akanksh Jagadish <101392232+akanksh97@users.noreply.github.com> Co-authored-by: Nic G Co-authored-by: haruka-yamashita2 <39541428+haruka-yamashita2@users.noreply.github.com> Co-authored-by: Matt F <47011386+MattAdkernel@users.noreply.github.com> Co-authored-by: Erik Hummel Co-authored-by: Erik Hummel Co-authored-by: mikiz <31058500+mikizi@users.noreply.github.com> Co-authored-by: pcimring-taboola <57901387+pcimring-taboola@users.noreply.github.com> Co-authored-by: Vikas Srivastava <30315503+visrivastava@users.noreply.github.com> Co-authored-by: guiann Co-authored-by: asurovenko-zeta <80847074+asurovenko-zeta@users.noreply.github.com> Co-authored-by: Surovenko Alexey Co-authored-by: Bendegúz Ács <30595431+acsbendi@users.noreply.github.com> Co-authored-by: Philip Watson Co-authored-by: DmitriyMishutin <105477277+DmitriyMishutin@users.noreply.github.com> Co-authored-by: Dmitriy Mishutin Co-authored-by: Prebid-Team Co-authored-by: Sacha <35510349+thebraveio@users.noreply.github.com> Co-authored-by: jsnellbaker <31102355+jsnellbaker@users.noreply.github.com> Co-authored-by: MK Platform <88486298+mediakeys-platform@users.noreply.github.com> Co-authored-by: François Maturel Co-authored-by: Sergey Derbush Co-authored-by: Nick-Merkle <105746498+Nick-Merkle@users.noreply.github.com> Co-authored-by: Nick Curry Co-authored-by: Soni-Goyal Co-authored-by: Florent DANCY Co-authored-by: TheMediaGrid <44166371+TheMediaGrid@users.noreply.github.com> Co-authored-by: John Salis Co-authored-by: John Salis Co-authored-by: Abimael Martinez Co-authored-by: Michael Ermer Co-authored-by: Ho Chia Leung Co-authored-by: Ho Chia Leung Co-authored-by: lasloche <62240785+lasloche@users.noreply.github.com> Co-authored-by: tiffthai <79564969+tiffthai@users.noreply.github.com> Co-authored-by: Vladyslav Laktionov Co-authored-by: vlad Co-authored-by: kalidas-alkimi <92875788+kalidas-alkimi@users.noreply.github.com> Co-authored-by: alexander bogdanov Co-authored-by: Nikulin Mikhail Co-authored-by: mihanikw2g <92710748+mihanikw2g@users.noreply.github.com> Co-authored-by: motors Co-authored-by: orazumov-zeta <99964372+orazumov-zeta@users.noreply.github.com> Co-authored-by: Andrew Co-authored-by: Andrew Fowler Co-authored-by: Hendrick Musche <107099114+sag-henmus@users.noreply.github.com> Co-authored-by: John Ivan Bauzon Co-authored-by: John Bauzon Co-authored-by: ffqs <47789178+ffqs@users.noreply.github.com> Co-authored-by: DianomiJH <84312830+DianomiJH@users.noreply.github.com> Co-authored-by: victorlassomarketing <103455651+victorlassomarketing@users.noreply.github.com> Co-authored-by: Victor Romasenco Co-authored-by: wojciech-bialy-wpm <67895844+wojciech-bialy-wpm@users.noreply.github.com> Co-authored-by: Wojciech Biały Co-authored-by: Serhii Kozlov Co-authored-by: Brian Schmidt Co-authored-by: Mikael Lundin Co-authored-by: StalmIlya <102592784+StalmIlya@users.noreply.github.com> Co-authored-by: Ilya Stalmahov Co-authored-by: InfyTV <104983807+infytvcode@users.noreply.github.com> Co-authored-by: jennylt <48404417+jennylt@users.noreply.github.com> Co-authored-by: Michael Co-authored-by: Volodymyr Pavlov <48243894+grakholsky@users.noreply.github.com> Co-authored-by: vrtcal-dev <50931150+vrtcal-dev@users.noreply.github.com> Co-authored-by: Jeremy Sadwith Co-authored-by: wsusrasp <106743463+wsusrasp@users.noreply.github.com> Co-authored-by: skoklowski Co-authored-by: newspassid-prebid <107485317+newspassid-prebid@users.noreply.github.com> Co-authored-by: Anass Seddiki Co-authored-by: Denis Logachov Co-authored-by: relaido <63339139+relaido@users.noreply.github.com> Co-authored-by: ishigami_shingo Co-authored-by: cmertv-sishigami Co-authored-by: n.maeura Co-authored-by: Yohan Boutin Co-authored-by: Keisuke Kakinuma Co-authored-by: banakemi Co-authored-by: Niklas Närhinen Co-authored-by: ako-adot <90328748+ako-adot@users.noreply.github.com> Co-authored-by: Jason Piros Co-authored-by: stefanogabri <84040306+stefanogabri@users.noreply.github.com> Co-authored-by: Ibrahima Niass <48965172+Niass@users.noreply.github.com> Co-authored-by: samous Co-authored-by: onetag-dev <38786435+onetag-dev@users.noreply.github.com> Co-authored-by: federico Co-authored-by: Anass Seddiki Co-authored-by: odureleau <101274264+odureleau@users.noreply.github.com> Co-authored-by: Mordhak Co-authored-by: Mordhak Co-authored-by: Sébastien Ferry Co-authored-by: gcarnec Co-authored-by: Yuriy Tyukhnin Co-authored-by: tadam Co-authored-by: krzysztof <88041828+krysztal-smart@users.noreply.github.com> Co-authored-by: Spacedragoon --- .github/pull_request_template.md | 18 + .gitignore | 6 + Gemfile | 4 +- README.md | 24 +- _assets/sass/base/_base.scss | 6 + _assets/sass/components/_pb.scss | 4 + _data/partners.yml | 75 +- _data/sidebar.yml | 463 +- _includes/adops/adops-gam-video-setup.html | 14 +- _includes/footer.html | 2 +- _includes/video/head.html | 2 +- _includes/video/pb-cp-fp.html | 2 +- _includes/video/pb-cp-jw.html | 10 +- _includes/video/pb-cp-kl.html | 12 +- _includes/video/pb-cp-vjs.html | 10 +- _includes/video/pb-cp.html | 10 +- _includes/video/pb-is-amp.html | 2 +- _includes/video/pb-is-app.html | 2 +- _includes/video/pb-is-bc.html | 8 +- _includes/video/pb-is-br.html | 36 +- _includes/video/pb-is-fp.html | 161 +- _includes/video/pb-is-jw01.html | 28 +- _includes/video/pb-is-jw02.html | 22 +- _includes/video/pb-is-kl.html | 34 +- _includes/video/pb-is-ol.html | 14 +- _includes/video/pb-is-rd.html | 8 +- _includes/video/pb-is-vjs.html | 14 +- _includes/video/pb-lf-fw.html | 34 +- _includes/video/pb-os-app.html | 4 +- _includes/video/pb-os-dfp.html | 22 +- _includes/video/pb-os-nas-renderer.html | 91 + _includes/video/pb-os-nas.html | 16 +- _includes/video/pb-os-rd.html | 8 +- _includes/video/pb-ve-lf-fw.html | 34 +- _includes/video/pbs-br.html | 12 +- _includes/video/pbs-jw01.html | 4 +- _includes/video/pbs-jw02.html | 12 +- _includes/video/pbs-kl.html | 12 +- _includes/video/pbs-oy.html | 12 +- _includes/video/pbs-rd.html | 10 +- _includes/video/pbs-vjs.html | 10 +- _layouts/bidder.html | 22 +- _layouts/example.html | 18 +- _layouts/home.html | 8 + _layouts/video_sample.html | 2 + about.md | 2 +- adops/before-you-start.md | 1 + adops/send-all-bids-adops.md | 2 +- adops/setting-up-prebid-for-amp-in-dfp.md | 9 +- adops/setting-up-prebid-video-in-freewheel.md | 7 +- assets/css/main-bundle.css | 10043 +++++++++++++++- .../dfp-creative-setup/appnexus_vast_tag.png | Bin 66292 -> 69120 bytes .../mopub/full/mopub-lineitem-full-adunit.png | Bin 67422 -> 0 bytes .../full/mopub_lineitem_full_vasttag.png | Bin 108554 -> 0 bytes .../rewarded/mopub-lineitem-advanced.png | Bin 53591 -> 0 bytes .../rewarded/mopub-lineitem-rewarded copy.png | Bin 95893 -> 0 bytes .../rewarded/mopub-lineitem-rewarded.png | Bin 209705 -> 0 bytes .../mopub/rewarded/mopub_lineitem_vasttag.png | Bin 145266 -> 0 bytes .../rewarded/mopub_lineitem_vasttag2.png | Bin 72420 -> 0 bytes assets/images/logos/criteo-logo.png | Bin 17601 -> 46836 bytes assets/images/partners/publisher/sortable.png | Bin 26132 -> 0 bytes assets/images/partners/tech/criteo.png | Bin 31206 -> 46836 bytes .../adops-line-item-setup-mopub/mopub1.png | Bin 209705 -> 0 bytes .../adops-line-item-setup-mopub/mopub2.png | Bin 108288 -> 0 bytes .../adops-line-item-setup-mopub/mopub3.png | Bin 63677 -> 0 bytes .../adops-line-item-setup-mopub/mopub4.png | Bin 138184 -> 0 bytes .../prebid-mobile/modularity-architecture.png | Bin 0 -> 20540 bytes .../prebid-mobile/modules/modularity.png | Bin 0 -> 142540 bytes .../rendering/In-App-Bidding-Integration.png | Bin 0 -> 124636 bytes .../rendering/Native-Styles-Prebid.png | Bin 0 -> 101301 bytes .../Native-Styles-Primary-Ad-Server.png | Bin 0 -> 112854 bytes .../Prebid-In-App-Bidding-Overview-GAM.png | Bin 0 -> 135080 bytes ...id-In-App-Bidding-Overview-Pure-Prebid.png | Bin 0 -> 106707 bytes ...ndroid-close-button-possition-top-left.png | Bin 0 -> 492916 bytes ...android-skip-button-possition-top-left.png | Bin 0 -> 565227 bytes ...ce-ios-close-button-possition-top-left.png | Bin 0 -> 215939 bytes ...nce-ios-skip-button-possition-top-left.png | Bin 0 -> 595619 bytes .../modules/rendering/max-ad-unit-setup.png | Bin 0 -> 228464 bytes .../rendering/max-cusom-network-setup.png | Bin 0 -> 183228 bytes .../rendering/order-admob-create-ad-units.png | Bin 0 -> 110788 bytes .../order-admob-create-add-ad-sources.png | Bin 0 -> 205689 bytes ...b-create-add-custom-event-adapter-name.png | Bin 0 -> 117820 bytes ...der-admob-create-add-custom-event-name.png | Bin 0 -> 77671 bytes .../order-admob-create-list-custom-events.png | Bin 0 -> 167377 bytes .../order-admob-create-properties.png | Bin 0 -> 235859 bytes .../modules/rendering/order-admob-create.png | Bin 0 -> 104861 bytes .../rendering/order-gam-ad-settings.png | Bin 0 -> 127055 bytes .../rendering/order-gam-create-native-ad.png | Bin 0 -> 80442 bytes .../modules/rendering/order-gam-create.png | Bin 0 -> 45610 bytes .../rendering/order-gam-creative-banner.png | Bin 0 -> 183237 bytes ...eative-custom-template-format-variable.png | Bin 0 -> 57254 bytes ...er-gam-creative-custom-template-format.png | Bin 0 -> 74152 bytes .../order-gam-creative-custom-template.png | Bin 0 -> 32521 bytes .../rendering/order-gam-creative-rewarded.png | Bin 0 -> 194077 bytes .../order-gam-creative-unified-ad.png | Bin 0 -> 65740 bytes .../modules/rendering/order-gam-li-create.png | Bin 0 -> 81051 bytes .../modules/rendering/order-gam-li-price.png | Bin 0 -> 77016 bytes .../rendering/order-gam-li-targeting.png | Bin 0 -> 64286 bytes .../rendering/order-gam-style-native-ad.png | Bin 0 -> 534398 bytes .../order-gam-ways-to-create-native-ad.png | Bin 0 -> 282200 bytes .../prebid-in-app-bidding-overview-admob.png | Bin 0 -> 99263 bytes .../prebid-in-app-bidding-overview-max.png | Bin 0 -> 121225 bytes assets/images/prebid-server/module-atags.png | Bin 0 -> 34988 bytes .../images/prebid-server/module-example.png | Bin 0 -> 38702 bytes .../images/prebid-server/pbs-floors-basic.png | Bin 0 -> 29873 bytes .../prebid-server/pbs-floors-detailed.png | Bin 0 -> 62157 bytes assets/images/prebid-server/pg/pg-arch-1.png | Bin 0 -> 69094 bytes assets/images/prebid-server/pg/pg-arch-2.png | Bin 0 -> 684029 bytes .../prebid-server/pg/pg-bad-delivery.png | Bin 0 -> 199068 bytes .../prebid-server/pg/pg-good-delivery.png | Bin 0 -> 160354 bytes assets/images/prebid-server/pg/pg-metrics.png | Bin 0 -> 377756 bytes .../prebid-server/stored-requests-amp.png | Bin 0 -> 113746 bytes .../prebid-server/stored-requests-app.png | Bin 0 -> 177868 bytes assets/images/sharedid5.png | Bin 0 -> 24563 bytes assets/images/tools/professor-prebid-10.png | Bin 0 -> 277677 bytes assets/images/tools/professor-prebid-2.png | Bin 0 -> 82813 bytes assets/images/tools/professor-prebid-3.png | Bin 0 -> 76492 bytes assets/images/tools/professor-prebid-4.png | Bin 0 -> 22251 bytes assets/images/tools/professor-prebid-5.png | Bin 0 -> 216516 bytes assets/images/tools/professor-prebid-6.png | Bin 0 -> 49643 bytes assets/images/tools/professor-prebid-7.png | Bin 0 -> 216495 bytes assets/images/tools/professor-prebid-8.png | Bin 0 -> 117508 bytes assets/images/tools/professor-prebid-9.png | Bin 0 -> 120439 bytes assets/images/tools/professor-prebid-icon.png | Bin 0 -> 4365 bytes assets/images/user-identity.png | Bin 0 -> 30162 bytes debugging/debugging.md | 3 +- dev-docs/add-rtd-submodule.md | 43 +- dev-docs/adunit-reference.md | 30 +- dev-docs/analytics/ats.md | 30 +- dev-docs/analytics/audigent.md | 40 + dev-docs/analytics/bidwatch.md | 35 + dev-docs/analytics/bydata.md | 32 + dev-docs/analytics/google.md | 2 +- dev-docs/analytics/kargo.md | 12 +- dev-docs/analytics/malltv.md | 33 + dev-docs/analytics/pianoDmp.md | 24 + dev-docs/analytics/rivr.md | 11 - dev-docs/analytics/sortable.md | 11 - dev-docs/analytics/zeta_global_ssp.md | 39 + dev-docs/bidder-adaptor.md | 208 +- dev-docs/bidder-data.csv | 4 +- dev-docs/bidders.md | 19 +- dev-docs/bidders/1ad4good.md | 3 +- dev-docs/bidders/33across.md | 15 +- dev-docs/bidders/7xbid.md | 3 +- dev-docs/bidders/aardvark.md | 3 +- dev-docs/bidders/aax.md | 123 + dev-docs/bidders/aceex.md | 27 + dev-docs/bidders/acuityads.md | 2 +- dev-docs/bidders/adagio.md | 12 +- dev-docs/bidders/adbite.md | 2 +- dev-docs/bidders/adblender.md | 7 +- dev-docs/bidders/adbutler.md | 3 +- dev-docs/bidders/adf.md | 24 +- dev-docs/bidders/adfinity.md | 3 +- dev-docs/bidders/adform.md | 5 +- dev-docs/bidders/adgeneration.md | 2 +- dev-docs/bidders/adglare.md | 3 +- dev-docs/bidders/adhash.md | 4 +- dev-docs/bidders/adhese.md | 1 - dev-docs/bidders/adlive.md | 15 - dev-docs/bidders/adlivetech.md | 70 + dev-docs/bidders/adman.md | 4 +- dev-docs/bidders/admaru.md | 43 + dev-docs/bidders/admedia.md | 3 +- dev-docs/bidders/admixer.md | 11 +- dev-docs/bidders/adnuntius.md | 114 +- dev-docs/bidders/adot.md | 12 +- dev-docs/bidders/adpartner.md | 7 +- dev-docs/bidders/adplus.md | 19 + dev-docs/bidders/adpone.md | 2 +- dev-docs/bidders/adprime.md | 5 +- dev-docs/bidders/adquery.md | 20 + dev-docs/bidders/adrelevantis.md | 9 +- dev-docs/bidders/adrino.md | 56 + dev-docs/bidders/adriver.md | 6 +- dev-docs/bidders/adsolut.md | 3 + dev-docs/bidders/adspend.md | 3 +- dev-docs/bidders/adsyield.md | 18 + dev-docs/bidders/adtargetme.md | 25 + dev-docs/bidders/aduptech.md | 1 + dev-docs/bidders/advangelists.md | 1 - dev-docs/bidders/advenue.md | 3 +- dev-docs/bidders/advertly.md | 3 +- dev-docs/bidders/adview.md | 34 + dev-docs/bidders/adxcg.md | 2 +- dev-docs/bidders/adyoulike.md | 8 +- dev-docs/bidders/afp.md | 201 + dev-docs/bidders/aja.md | 23 +- dev-docs/bidders/algorix.md | 16 +- dev-docs/bidders/alkimi.md | 27 + dev-docs/bidders/amx.md | 43 +- dev-docs/bidders/aniview.md | 30 +- dev-docs/bidders/aol.md | 15 +- dev-docs/bidders/apacdex.md | 24 +- dev-docs/bidders/appnexus.md | 82 +- dev-docs/bidders/aseal.md | 53 + dev-docs/bidders/aso.md | 58 + dev-docs/bidders/atomx.md | 3 +- dev-docs/bidders/audiencerun.md | 64 +- dev-docs/bidders/automatad.md | 16 +- dev-docs/bidders/avantisvideo.md | 6 +- dev-docs/bidders/axonix.md | 2 + dev-docs/bidders/beachfront.md | 82 +- dev-docs/bidders/beop.md | 15 + dev-docs/bidders/between.md | 5 +- dev-docs/bidders/biddo.md | 23 + dev-docs/bidders/bidfluence.md | 3 +- dev-docs/bidders/bidlab.md | 3 +- dev-docs/bidders/bidmachine.md | 2 +- dev-docs/bidders/bidmyadz.md | 22 + dev-docs/bidders/bidphysics.md | 3 +- dev-docs/bidders/big-richmedia.md | 55 + dev-docs/bidders/bizzclick.md | 6 +- dev-docs/bidders/bliink.md | 22 + dev-docs/bidders/bmtm.md | 3 +- dev-docs/bidders/boldwin.md | 5 +- dev-docs/bidders/brave.md | 26 + dev-docs/bidders/bucksense.md | 1 + dev-docs/bidders/byplay.md | 3 +- dev-docs/bidders/c1x.md | 3 +- dev-docs/bidders/catapultx.md | 23 + dev-docs/bidders/cedato.md | 3 +- dev-docs/bidders/clickforce.md | 1 - dev-docs/bidders/clicktripz.md | 3 +- dev-docs/bidders/codefuel.md | 35 + dev-docs/bidders/coinzilla.md | 1 + dev-docs/bidders/collectcent.md | 1 + dev-docs/bidders/colombia.md | 3 +- dev-docs/bidders/colossus.md | 11 +- dev-docs/bidders/colossusssp.md | 6 +- dev-docs/bidders/compass.md | 28 + dev-docs/bidders/connectad.md | 2 +- dev-docs/bidders/consumable.md | 4 + dev-docs/bidders/contentexchange.md | 21 + dev-docs/bidders/converge.md | 26 +- dev-docs/bidders/conversant.md | 59 +- dev-docs/bidders/cosmos.md | 3 +- dev-docs/bidders/cpmstar.md | 1 - dev-docs/bidders/criteo.md | 28 +- dev-docs/bidders/cwire.md | 24 + dev-docs/bidders/dailyhunt.md | 3 +- dev-docs/bidders/decenterads.md | 3 +- dev-docs/bidders/deepintent.md | 56 +- dev-docs/bidders/deltaprojects.md | 54 + dev-docs/{ => bidders}/denakop.md | 4 +- dev-docs/bidders/dgads.md | 3 +- dev-docs/bidders/dianomi.md | 95 + dev-docs/bidders/didnavideo.md | 45 + dev-docs/bidders/displayio.md | 37 + dev-docs/bidders/districtm.md | 1 + dev-docs/bidders/districtmdmx.md | 4 +- dev-docs/bidders/distroscale.md | 50 + dev-docs/bidders/djax.md | 3 +- dev-docs/bidders/dmx.md | 1 + dev-docs/bidders/doceree.md | 4 + dev-docs/bidders/duration.md | 86 + dev-docs/bidders/e_volution.md | 3 +- dev-docs/bidders/ebdr.md | 1 - dev-docs/bidders/edgequeryx.md | 3 +- dev-docs/bidders/emoteev.md | 3 +- dev-docs/bidders/emx_digital.md | 1 + dev-docs/bidders/engageya.md | 1 - dev-docs/bidders/envivo.md | 3 +- dev-docs/bidders/epom.md | 2 +- dev-docs/bidders/ergadx.md | 27 + dev-docs/bidders/etarget.md | 69 +- dev-docs/bidders/feedad.md | 1 + dev-docs/bidders/felixads.md | 28 + dev-docs/bidders/fidelity.md | 3 +- dev-docs/bidders/finative.md | 17 + dev-docs/bidders/fluct.md | 1 - dev-docs/bidders/futureads.md | 24 + dev-docs/bidders/gamma.md | 1 - dev-docs/bidders/getintent.md | 20 +- dev-docs/bidders/glimpse.md | 141 +- dev-docs/bidders/gmossp.md | 1 + dev-docs/bidders/gnet.md | 7 +- dev-docs/bidders/go2net.md | 7 +- dev-docs/bidders/goldbach.md | 199 + dev-docs/bidders/gothamads.md | 2 +- dev-docs/bidders/grid.md | 70 +- dev-docs/bidders/gridNM.md | 7 + dev-docs/bidders/groupm.md | 93 + dev-docs/bidders/growads.md | 18 + dev-docs/bidders/gumgum.md | 17 +- dev-docs/bidders/haxmedia.md | 3 +- dev-docs/bidders/hpmdnetwork.md | 3 +- dev-docs/bidders/huaweiads.md | 36 + dev-docs/bidders/idx.md | 25 + dev-docs/bidders/imonomy.md | 3 +- dev-docs/bidders/impactify.md | 4 +- dev-docs/bidders/improvedigital.md | 46 +- dev-docs/bidders/incrementx.md | 21 + dev-docs/bidders/infytv.md | 26 + dev-docs/bidders/inmar.md | 3 +- dev-docs/bidders/inmobi.md | 9 +- dev-docs/bidders/innity.md | 1 - dev-docs/bidders/insticator.md | 35 + dev-docs/bidders/integr8.md | 17 + dev-docs/bidders/interactiveOffers.md | 6 +- dev-docs/bidders/invibes.md | 10 +- dev-docs/bidders/iprom.md | 3 +- dev-docs/bidders/iqm.md | 80 +- dev-docs/bidders/iqzone.md | 25 + dev-docs/bidders/ironsource.md | 3 +- dev-docs/bidders/ix.md | 317 +- dev-docs/bidders/{navelix.md => janet.md} | 25 +- dev-docs/bidders/jcm.md | 3 +- dev-docs/bidders/jixie.md | 3 +- dev-docs/bidders/justpremium.md | 1 + dev-docs/bidders/kargo.md | 4 + dev-docs/bidders/kobler.md | 35 +- dev-docs/bidders/komoona.md | 3 +- dev-docs/bidders/krushmedia.md | 1 - dev-docs/bidders/kubient.md | 56 +- dev-docs/bidders/kueez.md | 82 + dev-docs/bidders/lasso.md | 28 + dev-docs/bidders/lemma.md | 3 +- dev-docs/bidders/lifestreet.md | 3 +- dev-docs/bidders/limelightDigital.md | 18 + dev-docs/bidders/lkqd.md | 33 +- dev-docs/bidders/logan.md | 1 - dev-docs/bidders/logicad.md | 3 +- dev-docs/bidders/loglylift.md | 27 + dev-docs/bidders/loopme.md | 3 +- dev-docs/bidders/lunamedia.md | 3 +- dev-docs/bidders/lunamediahb.md | 3 +- dev-docs/bidders/luponmedia.md | 2 +- dev-docs/bidders/madvertise.md | 7 +- dev-docs/bidders/mantis.md | 1 - dev-docs/bidders/marsmedia.md | 2 +- dev-docs/bidders/mathildeads.md | 20 + dev-docs/bidders/meazy.md | 3 +- dev-docs/bidders/mediafuse.md | 194 +- dev-docs/bidders/mediafuseLift.md | 22 - dev-docs/bidders/mediago.md | 3 +- dev-docs/bidders/mediakeys.md | 428 + dev-docs/bidders/medianet.md | 3 +- dev-docs/bidders/mediasniper.md | 21 + dev-docs/bidders/mediasquare.md | 1 + dev-docs/bidders/mgid.md | 1 - dev-docs/bidders/microad.md | 1 - dev-docs/bidders/minutemedia.md | 83 + dev-docs/bidders/missena.md | 2 +- dev-docs/bidders/mobfox.md | 3 +- dev-docs/bidders/mobfoxpb.md | 2 +- dev-docs/bidders/mobsmart.md | 3 +- dev-docs/bidders/motionspots.md | 30 + dev-docs/bidders/mytarget.md | 1 - dev-docs/bidders/nafdigital.md | 3 +- dev-docs/bidders/nanointeractive.md | 3 +- dev-docs/bidders/nasmediaAdmixer.md | 3 +- dev-docs/bidders/nativo.md | 2 +- dev-docs/bidders/newborntownWeb.md | 3 +- dev-docs/bidders/newspassid.md | 76 + dev-docs/bidders/nextMillennium.md | 23 +- dev-docs/bidders/nextroll.md | 14 +- dev-docs/bidders/nexx360.md | 68 + dev-docs/bidders/oftmedia.md | 8 +- dev-docs/bidders/oftmediahb.md | 20 - dev-docs/bidders/ogury.md | 3 +- dev-docs/bidders/oneVideo.md | 21 - dev-docs/bidders/onedisplay.md | 12 + dev-docs/bidders/onemobile.md | 12 + dev-docs/bidders/onetag.md | 2 + dev-docs/bidders/open8.md | 3 +- dev-docs/bidders/openweb.md | 64 + dev-docs/bidders/openwebvideo.md | 45 + dev-docs/bidders/openx.md | 140 +- dev-docs/bidders/operaads.md | 31 + dev-docs/bidders/optout.md | 18 + dev-docs/bidders/otm.md | 4 +- dev-docs/bidders/ottadvisors.md | 45 + dev-docs/bidders/outbrain.md | 5 +- dev-docs/bidders/outbrain_old.md | 2 +- dev-docs/bidders/outcon.md | 3 +- dev-docs/bidders/ozone.md | 7 +- dev-docs/bidders/pangle.md | 2 +- dev-docs/bidders/performax.md | 3 +- dev-docs/bidders/{appaloosa.md => pgam.md} | 41 +- dev-docs/bidders/pilotx.md | 15 + dev-docs/bidders/pixfuture.md | 19 + dev-docs/bidders/piximedia.md | 3 +- dev-docs/bidders/platformio.md | 3 +- dev-docs/bidders/playwire.md | 71 + dev-docs/bidders/prebidServer.md | 131 - dev-docs/bidders/prisma.md | 65 + ...oject-limelight.md => projectLimelight.md} | 9 +- dev-docs/bidders/proxistore.md | 1 - dev-docs/bidders/pubgenius.md | 2 +- dev-docs/bidders/pubmatic.md | 51 +- dev-docs/bidders/pubnx.md | 17 - dev-docs/bidders/pubx.md | 1 - dev-docs/bidders/pulsepoint.md | 2 +- dev-docs/bidders/pwbid.md | 2 +- dev-docs/bidders/quantumdex.md | 6 +- dev-docs/bidders/rads.md | 1 + dev-docs/bidders/ras.md | 35 + dev-docs/bidders/readpeak.md | 2 +- dev-docs/bidders/reklamstore.md | 3 +- dev-docs/bidders/relaido.md | 2 + dev-docs/bidders/reload.md | 3 +- dev-docs/bidders/resultsmedia.md | 3 +- dev-docs/bidders/revcontent.md | 1 - dev-docs/bidders/richaudience.md | 7 +- dev-docs/bidders/rise.md | 83 +- dev-docs/bidders/roundel.md | 2 +- .../{converge_digital.md => rtbanalytica.md} | 11 +- dev-docs/bidders/rtbdemand.md | 3 +- dev-docs/bidders/rtbhouse.md | 12 +- dev-docs/bidders/rtbsape.md | 1 - dev-docs/bidders/rtbsolutions.md | 3 +- dev-docs/bidders/rubicon.md | 90 +- dev-docs/bidders/sa_lunamedia.md | 23 + dev-docs/bidders/saambaa.md | 1 - dev-docs/bidders/seedingAlliance.md | 1 - dev-docs/bidders/seedtag.md | 5 +- dev-docs/bidders/segmento.md | 3 +- dev-docs/bidders/sekindoUM.md | 3 +- dev-docs/bidders/selectmedia.md | 1 + dev-docs/bidders/selectmediavideo.md | 8 +- dev-docs/bidders/sharethrough.md | 21 +- dev-docs/bidders/shinez.md | 124 +- dev-docs/bidders/slimcut.md | 4 +- dev-docs/bidders/smaato.md | 91 +- dev-docs/bidders/smartadserver.md | 23 +- dev-docs/bidders/smarthub.md | 34 + dev-docs/bidders/smartico.md | 1 - dev-docs/bidders/smartrtb.md | 2 + dev-docs/bidders/smartx.md | 18 +- dev-docs/bidders/smartyads.md | 2 +- dev-docs/bidders/smilewanted.md | 9 +- dev-docs/bidders/smms.md | 3 +- dev-docs/bidders/somo.md | 3 +- dev-docs/bidders/somoaudience.md | 5 +- .../bidders/{andbeyond.md => sonic_twist.md} | 8 +- dev-docs/bidders/sortable.md | 69 - dev-docs/bidders/sovrn.md | 160 +- dev-docs/bidders/spotx.md | 11 +- dev-docs/bidders/sspBC.md | 4 +- .../{onefiftytwomedia.md => streamkey.md} | 27 +- dev-docs/bidders/stroeerCore.md | 11 +- dev-docs/bidders/stv.md | 3 +- dev-docs/bidders/synacormedia.md | 2 +- dev-docs/bidders/taboola.md | 59 + dev-docs/bidders/talkads.md | 74 + dev-docs/bidders/taphype.md | 3 +- dev-docs/bidders/tappx.md | 12 +- dev-docs/bidders/targetvideo.md | 17 + dev-docs/bidders/teads.md | 3 +- dev-docs/bidders/telaria.md | 28 +- dev-docs/bidders/tim.md | 3 +- dev-docs/bidders/topRTB.md | 3 +- dev-docs/bidders/tpmn.md | 37 +- dev-docs/bidders/trafficgate.md | 33 + dev-docs/bidders/trendqube.md | 3 +- dev-docs/bidders/triplelift.md | 115 +- dev-docs/bidders/triplelift_native.md | 29 +- dev-docs/bidders/trustx.md | 96 +- dev-docs/bidders/trustxstandalone.md | 48 + dev-docs/bidders/ttd.md | 181 + dev-docs/bidders/turktelekom.md | 24 +- dev-docs/bidders/ucfunnel.md | 15 +- dev-docs/bidders/undertone.md | 1 + dev-docs/bidders/unibots.md | 27 + dev-docs/bidders/unicorn.md | 2 - dev-docs/bidders/unruly.md | 21 +- dev-docs/bidders/uol.md | 3 +- dev-docs/bidders/valueimpression.md | 5 +- dev-docs/bidders/vdoai.md | 1 - dev-docs/bidders/ventes.md | 94 + dev-docs/bidders/vertoz.md | 19 - dev-docs/bidders/vi.md | 3 +- dev-docs/bidders/vibrantmedia.md | 103 + dev-docs/bidders/vidazoo.md | 1 - dev-docs/bidders/vidcrunch.md | 45 + dev-docs/bidders/videobyte.md | 32 + dev-docs/bidders/videofy.md | 3 +- dev-docs/bidders/videoheroes.md | 26 + dev-docs/bidders/videonow.md | 3 +- dev-docs/bidders/videoreach.md | 1 - dev-docs/bidders/vidoomy.md | 32 + dev-docs/bidders/viewdeos.md | 39 + dev-docs/bidders/viewdeosDX.md | 8 +- dev-docs/bidders/visx.md | 28 +- dev-docs/bidders/vlyby.md | 24 + dev-docs/bidders/vmg.md | 3 +- dev-docs/bidders/vrtcal.md | 8 +- dev-docs/bidders/vuble.md | 3 +- dev-docs/bidders/weborama.md | 15 - dev-docs/bidders/welect.md | 3 +- dev-docs/bidders/windtalker.md | 3 +- dev-docs/bidders/winr.md | 29 + dev-docs/bidders/wipes.md | 1 - dev-docs/bidders/xhb.md | 3 +- dev-docs/bidders/yahoossp.md | 64 + dev-docs/bidders/yandex.md | 39 + dev-docs/bidders/yieldlab.md | 27 +- dev-docs/bidders/yieldmo.md | 34 +- dev-docs/bidders/yieldone.md | 182 +- dev-docs/bidders/zedo.md | 3 +- dev-docs/bidders/zeroclickfraud.md | 2 +- dev-docs/bidders/zeta_global.md | 2 +- dev-docs/bidders/zeta_global_ssp.md | 9 +- dev-docs/common-issues.md | 2 +- dev-docs/examples/adunit-refresh.md | 2 +- dev-docs/examples/basic-example.md | 2 +- dev-docs/examples/custom-price-buckets.md | 2 +- dev-docs/examples/instream-banner-mix.md | 2 +- dev-docs/examples/legacy-browser-example.md | 19 + dev-docs/examples/meta-bid-filtering.md | 15 + dev-docs/examples/multi-format-example.md | 2 +- dev-docs/examples/native-ad-example.md | 2 +- dev-docs/examples/postbid.md | 2 +- dev-docs/examples/size-mapping.md | 2 +- .../use-prebid-with-appnexus-ad-server.md | 2 +- dev-docs/faq.md | 47 +- dev-docs/getting-started.md | 4 +- ...integrate-with-the-prebid-analytics-api.md | 3 + dev-docs/modules/1plusXRtdProvider.md | 67 + dev-docs/modules/adnuntiusRtdProvider.md | 65 + dev-docs/modules/adpod.md | 2 +- dev-docs/modules/airgridRtdProvider.md | 102 + dev-docs/modules/akamaiDapRtdProvider.md | 82 + dev-docs/modules/bidViewable.md | 35 +- dev-docs/modules/bidViewableIO.md | 66 + dev-docs/modules/blueconicRtdProvider.md | 85 + dev-docs/modules/brandmetricsRtdProvider.md | 76 + dev-docs/modules/browsiRtdProvider.md | 1 + dev-docs/modules/categoryTranslation.md | 2 +- dev-docs/modules/cleanioRtdProvider.md | 67 + dev-docs/modules/consentManagement.md | 121 +- dev-docs/modules/consentManagementUsp.md | 54 +- dev-docs/modules/currency.md | 2 +- dev-docs/modules/dchain.md | 89 + dev-docs/modules/debugging.md | 153 + dev-docs/modules/dfp_express.md | 3 +- dev-docs/modules/dfp_video.md | 13 +- dev-docs/modules/dgkeywordRtdProvider.md | 1 + dev-docs/modules/enrichmentFpdModule.md | 18 +- dev-docs/modules/floors.md | 550 +- dev-docs/modules/freewheel.md | 5 +- dev-docs/modules/gdprEnforcement.md | 3 +- dev-docs/modules/geoedgeRtdProvider.md | 1 + dev-docs/modules/gpt-pre-auction.md | 128 +- dev-docs/modules/hadronRtdProvider.md | 142 + dev-docs/modules/haloRtdProvider.md | 140 +- dev-docs/modules/iabCatagoryTranslation.md | 73 - dev-docs/modules/iasRtdProvider.md | 1 + dev-docs/modules/idLibrary.md | 2 +- dev-docs/modules/idWardRtdProvider.md | 61 + dev-docs/modules/imRtdProvider.md | 73 + dev-docs/modules/index.md | 119 +- dev-docs/modules/instreamTracking.md | 2 +- dev-docs/modules/intersectionRtdProvider.md | 75 + dev-docs/modules/jwplayerRtdProvider.md | 58 +- dev-docs/modules/konduit.md | 3 +- dev-docs/modules/mass.md | 42 +- dev-docs/modules/medianetRtdProvider.md | 116 + dev-docs/modules/multibid.md | 2 +- dev-docs/modules/optimeraRtdProvider.md | 11 +- dev-docs/modules/permutiveRtdProvider.md | 76 + dev-docs/modules/prebidServer.md | 262 + dev-docs/modules/pubCommonId.md | 2 +- dev-docs/modules/reconciliationRtdProvider.md | 3 +- dev-docs/modules/schain.md | 2 +- dev-docs/modules/sirdataRtdProvider.md | 3 +- dev-docs/modules/sizeMappingV2.md | 6 +- dev-docs/modules/timeoutRtdProvider.md | 159 + dev-docs/modules/userId.md | 1195 +- dev-docs/modules/validationFpdModule.md | 4 +- dev-docs/modules/viewability.md | 99 + dev-docs/modules/weboramaRtdProvider.md | 605 + .../yieldmoSyntheticInventoryModule.md | 80 + dev-docs/pb7-notes.md | 81 + dev-docs/pbs-bidders.md | 7 +- .../bc/bc-prebid-plugin-prebid-options.md | 4 +- .../cross-player-config.md | 6 +- dev-docs/prebid-troubleshooting-guide.md | 111 +- .../publisher-api-reference/addAdUnits.md | 4 +- .../publisher-api-reference/bidderSettings.md | 65 +- dev-docs/publisher-api-reference/getConfig.md | 10 +- .../getConsentMetadata.md | 25 + dev-docs/publisher-api-reference/getEvents.md | 95 +- dev-docs/publisher-api-reference/getNoBids.md | 4 +- .../getUserIdsAsync.md | 18 + .../mergeBidderConfig.md | 20 + .../publisher-api-reference/mergeConfig.md | 10 + dev-docs/publisher-api-reference/offEvent.md | 52 +- dev-docs/publisher-api-reference/onEvent.md | 61 +- .../publisher-api-reference/readConfig.md | 18 + .../publisher-api-reference/refreshUserIds.md | 2 +- .../publisher-api-reference/requestBids.md | 1 + .../setBidderConfig.md | 4 +- dev-docs/publisher-api-reference/setConfig.md | 253 +- dev-docs/release-notes.md | 4 + dev-docs/show-outstream-video-ads.md | 9 +- dev-docs/show-prebid-ads-on-amp-pages.md | 108 +- dev-docs/show-video-with-a-dfp-video-tag.md | 2 + dev-docs/troubleshooting-tips.md | 222 +- dev-docs/vendor-billing.md | 55 + download.md | 263 +- examples/index.md | 2 +- .../legacy/modules/pub_common_id_optout.html | 36 - examples/legacy/multi-format/index.md | 12 - .../multi-format/multi_format_example.html | 205 - examples/legacy/native/index.md | 12 - examples/legacy/native/native-demo.html | 158 - examples/legacy/pbjs_demo.html | 153 - examples/legacy/simple.html | 83 - .../flowplayer/pb-cp-flowplayer.html | 30 +- .../crossplayer/jwplayer/pb-cp-jwplayer.html | 42 +- .../crossplayer/kaltura/pb-cp-kaltura.html | 2 +- .../crossplayer/videojs/pb-cp-videojs.html | 42 +- .../adplayerpro/pb-ve-adplayerpro.html | 134 +- examples/video/instream/akamai/pb-ve-amp.html | 153 +- examples/video/instream/brid/pb-ve-brid.html | 57 +- .../instream/brightcove/pb-ve-brightcove.html | 326 +- .../instream/flowplayer/pb-ve-flowplayer.html | 136 +- .../jwplayer/pb-ve-jwplayer-hosted.html | 204 +- .../jwplayer/pb-ve-jwplayer-platform.html | 55 +- .../video/instream/ooyala/pb-ve-ooyala.html | 66 +- .../video/instream/radiant/pb-ve-radiant.html | 297 +- .../video/instream/videojs/pb-ve-videojs.html | 74 +- .../long-form-video-with-freewheel.html | 12 +- .../video/long-form/pb-ve-lf-freewheel.html | 22 +- .../video/outstream/pb-ve-outstream-app.html | 156 +- .../video/outstream/pb-ve-outstream-dfp.html | 28 +- ...-outstream-no-server-specify-renderer.html | 145 + .../outstream/pb-ve-outstream-no-server.html | 32 +- .../outstream/pb-ve-outstream-radiant.html | 162 +- examples/video/pb-video-template.html | 37 +- examples/video/server/brid/pbs-ve-brid.html | 53 +- .../jwplayer/pbs-ve-jwplayer-hosted.html | 56 +- .../jwplayer/pbs-ve-jwplayer-platform.html | 189 +- .../video/server/kaltura/pbs-ve-kaltura.html | 34 +- .../video/server/ooyala/pbs-ve-ooyala.html | 35 +- .../video/server/radiant/pbs-ve-radiant.html | 43 +- .../video/server/videojs/pbs-ve-videojs.html | 32 +- faq/prebid-server-faq.md | 48 + features/InterstitialAds.md | 23 +- features/adServerKvps.md | 243 + features/firstPartyData.md | 136 +- features/pbAdSlot.md | 213 +- features/timeouts.md | 2 +- formats/native.md | 13 +- guide.md | 49 +- identity/prebid-identity.md | 63 + identity/sharedid.md | 376 + mix-manifest.json | 4 + overview/ga-analytics.md | 65 +- overview/intro.md | 2 +- overview/prebid-management-committees.md | 112 +- overview/prebid-universal-creative.md | 87 +- overview/what-is-prebid-org.md | 3 +- package-lock.json | 221 +- package.json | 2 +- partners/partners.md | 53 +- prebid-mobile/adops-line-item-setup-mopub.md | 70 - .../adops-setup-full-screen-video-mopub.md | 57 - .../adops-setup-rewarded-video-mopub.md | 55 - prebid-mobile/modules/modules-overview.md | 47 + .../android-sdk-customization-controls.md | 76 + .../android-sdk-integration-admob.md | 411 + .../android-sdk-integration-gam-native.md | 166 + .../rendering/android-sdk-integration-gam.md | 330 + .../rendering/android-sdk-integration-max.md | 347 + .../android-sdk-integration-pb-native.md | 159 + .../rendering/android-sdk-integration-pb.md | 186 + .../rendering/android-sdk-integration.md | 81 + .../rendering/android-sdk-parameters.md | 81 + .../modules/rendering/ios-sdk-Integration.md | 57 + .../ios-sdk-customization-controls.md | 72 + .../rendering/ios-sdk-integration-admob.md | 428 + .../ios-sdk-integration-gam-native.md | 180 + .../rendering/ios-sdk-integration-gam.md | 305 + .../rendering/ios-sdk-integration-max.md | 300 + .../ios-sdk-integration-pb-native.md | 174 + .../rendering/ios-sdk-integration-pb.md | 187 + .../modules/rendering/ios-sdk-parameters.md | 88 + .../modules/rendering/modules-rendering.md | 120 + .../rendering-admob-line-item-setup.md | 94 + .../rendering/rendering-deeplinkplus.md | 76 + .../rendering-gam-line-item-setup.md | 206 + .../rendering-impression-tracking.md | 58 + .../rendering-max-line-item-setup.md | 51 + .../rendering-native-ad-configuration.md | 122 + .../rendering/rendering-native-guidelines.md | 74 + .../android/code-integration-android.md | 29 +- .../pbm-api/android/pbm-adunit-android.md | 42 +- .../android/pbm-banneradunit-android.md | 4 +- .../pbm-bannerinterstitialadunit-android.md | 2 +- .../android/pbm-native-inapp-android.md | 20 +- .../android/pbm-nativeadunit-android.md | 2 +- .../android/pbm-targeting-params-android.md | 9 +- .../android/pbm-video-instream-android.md | 2 +- .../pbm-video-rewarded-adunit-android.md | 2 +- .../pbm-videointerstitialadunit-android.md | 2 +- .../pbm-videooutstreamadunit-android.md | 2 +- .../android/prebidmobile-object-android.md | 13 + .../pbm-api/ios/code-integration-ios.md | 107 +- prebid-mobile/pbm-api/ios/pbm-adunit-ios.md | 54 +- .../pbm-api/ios/pbm-banneradunit-ios.md | 4 +- .../ios/pbm-bannerinterstitialadunit-ios.md | 2 +- .../pbm-api/ios/pbm-code-integration-ios.md | 2 +- .../pbm-api/ios/pbm-native-inapp-ios.md | 21 +- .../pbm-api/ios/pbm-nativeadunit-ios.md | 2 +- .../pbm-api/ios/pbm-targeting-ios.md | 8 +- .../pbm-api/ios/pbm-video-instream-ios.md | 2 +- .../ios/pbm-video-rewarded-adunit-ios.md | 4 +- .../ios/pbm-videointerstitialadunit-ios.md | 4 +- .../ios/pbm-videooutstreamadunit-ios.md | 4 +- .../pbm-api/ios/prebidmobile-object-ios.md | 27 +- prebid-mobile/prebid-mobile-pbs.md | 23 +- prebid-server/developers/add-a-module-java.md | 229 + prebid-server/developers/add-a-module.md | 190 + prebid-server/developers/add-new-bidder-go.md | 577 +- .../developers/add-new-bidder-java.md | 326 +- prebid-server/developers/module-atags.md | 233 + prebid-server/developers/pbs-cookie-sync.md | 89 +- .../endpoints/openrtb2/pbs-endpoint-amp.md | 191 +- .../openrtb2/pbs-endpoint-auction.md | 914 +- prebid-server/endpoints/pbs-endpoint-admin.md | 1 + .../endpoints/pbs-endpoint-cookieSync.md | 108 +- prebid-server/endpoints/pbs-endpoint-event.md | 2 +- .../endpoints/pbs-endpoint-overview.md | 4 +- .../endpoints/pbs-endpoint-setuid.md | 12 +- prebid-server/features/pbs-currency.md | 22 +- prebid-server/features/pbs-deals.md | 11 +- prebid-server/features/pbs-default-request.md | 2 +- prebid-server/features/pbs-feature-idx.md | 63 +- prebid-server/features/pbs-floors.md | 371 + prebid-server/features/pbs-fpd.md | 3 + prebid-server/features/pbs-native.md | 20 + prebid-server/features/pbs-privacy.md | 2 +- prebid-server/features/pbs-storedreqs-go.md | 16 +- prebid-server/features/pbs-storedreqs-java.md | 298 + prebid-server/features/pbs-storedreqs.md | 22 +- prebid-server/features/pg/pbs-pg-bidder.md | 141 + prebid-server/features/pg/pbs-pg-glossary.md | 80 + prebid-server/features/pg/pbs-pg-host.md | 67 + prebid-server/features/pg/pbs-pg-idx.md | 67 + prebid-server/features/pg/pbs-pg-plan.md | 284 + prebid-server/features/pg/pbs-pg-targeting.md | 177 + prebid-server/hosting/pbs-database.md | 4 +- prebid-server/hosting/pbs-hosting.md | 4 +- prebid-server/pbs-modules/index.md | 131 + prebid-server/pbs-modules/ortb2-blocking.md | 565 + prebid-server/use-cases/pbs-amp.md | 38 +- prebid-server/versions/pbs-versions-go.md | 2 +- prebid-server/versions/pbs-versions-java.md | 2 +- prebid-video/video-getting-started.md | 4 +- prebid-video/video-overview.md | 11 +- prebid/native-implementation.md | 8 +- prebid/prebidjs.md | 14 +- prebid/prebidjsReleases.md | 12 + principles.md | 2 +- tools/professor-prebid.md | 114 + troubleshooting/pbs-troubleshooting.md | 18 +- troubleshooting/troubleshooting-guide.md | 38 +- wrapper_code_of_conduct.md | 80 +- 762 files changed, 35893 insertions(+), 7341 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 _includes/video/pb-os-nas-renderer.html delete mode 100644 assets/images/ad-ops/mopub/full/mopub-lineitem-full-adunit.png delete mode 100644 assets/images/ad-ops/mopub/full/mopub_lineitem_full_vasttag.png delete mode 100644 assets/images/ad-ops/mopub/rewarded/mopub-lineitem-advanced.png delete mode 100644 assets/images/ad-ops/mopub/rewarded/mopub-lineitem-rewarded copy.png delete mode 100644 assets/images/ad-ops/mopub/rewarded/mopub-lineitem-rewarded.png delete mode 100644 assets/images/ad-ops/mopub/rewarded/mopub_lineitem_vasttag.png delete mode 100644 assets/images/ad-ops/mopub/rewarded/mopub_lineitem_vasttag2.png delete mode 100644 assets/images/partners/publisher/sortable.png delete mode 100644 assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub1.png delete mode 100644 assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub2.png delete mode 100644 assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub3.png delete mode 100644 assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub4.png create mode 100644 assets/images/prebid-mobile/modularity-architecture.png create mode 100644 assets/images/prebid-mobile/modules/modularity.png create mode 100644 assets/images/prebid-mobile/modules/rendering/In-App-Bidding-Integration.png create mode 100644 assets/images/prebid-mobile/modules/rendering/Native-Styles-Prebid.png create mode 100644 assets/images/prebid-mobile/modules/rendering/Native-Styles-Primary-Ad-Server.png create mode 100644 assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-GAM.png create mode 100644 assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-Pure-Prebid.png create mode 100644 assets/images/prebid-mobile/modules/rendering/ad-experience-android-close-button-possition-top-left.png create mode 100644 assets/images/prebid-mobile/modules/rendering/ad-experience-android-skip-button-possition-top-left.png create mode 100644 assets/images/prebid-mobile/modules/rendering/ad-experience-ios-close-button-possition-top-left.png create mode 100644 assets/images/prebid-mobile/modules/rendering/ad-experience-ios-skip-button-possition-top-left.png create mode 100644 assets/images/prebid-mobile/modules/rendering/max-ad-unit-setup.png create mode 100644 assets/images/prebid-mobile/modules/rendering/max-cusom-network-setup.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-ad-units.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-add-ad-sources.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-add-custom-event-adapter-name.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-add-custom-event-name.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-list-custom-events.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create-properties.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-admob-create.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-ad-settings.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-create-native-ad.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-create.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-banner.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-custom-template-format-variable.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-custom-template-format.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-custom-template.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-rewarded.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-creative-unified-ad.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-li-create.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-li-price.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-li-targeting.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-style-native-ad.png create mode 100644 assets/images/prebid-mobile/modules/rendering/order-gam-ways-to-create-native-ad.png create mode 100644 assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-admob.png create mode 100644 assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-max.png create mode 100644 assets/images/prebid-server/module-atags.png create mode 100644 assets/images/prebid-server/module-example.png create mode 100644 assets/images/prebid-server/pbs-floors-basic.png create mode 100644 assets/images/prebid-server/pbs-floors-detailed.png create mode 100644 assets/images/prebid-server/pg/pg-arch-1.png create mode 100644 assets/images/prebid-server/pg/pg-arch-2.png create mode 100644 assets/images/prebid-server/pg/pg-bad-delivery.png create mode 100644 assets/images/prebid-server/pg/pg-good-delivery.png create mode 100644 assets/images/prebid-server/pg/pg-metrics.png create mode 100644 assets/images/prebid-server/stored-requests-amp.png create mode 100644 assets/images/prebid-server/stored-requests-app.png create mode 100644 assets/images/sharedid5.png create mode 100644 assets/images/tools/professor-prebid-10.png create mode 100644 assets/images/tools/professor-prebid-2.png create mode 100644 assets/images/tools/professor-prebid-3.png create mode 100644 assets/images/tools/professor-prebid-4.png create mode 100644 assets/images/tools/professor-prebid-5.png create mode 100644 assets/images/tools/professor-prebid-6.png create mode 100644 assets/images/tools/professor-prebid-7.png create mode 100644 assets/images/tools/professor-prebid-8.png create mode 100644 assets/images/tools/professor-prebid-9.png create mode 100644 assets/images/tools/professor-prebid-icon.png create mode 100644 assets/images/user-identity.png create mode 100644 dev-docs/analytics/audigent.md create mode 100644 dev-docs/analytics/bidwatch.md create mode 100644 dev-docs/analytics/bydata.md create mode 100644 dev-docs/analytics/malltv.md create mode 100644 dev-docs/analytics/pianoDmp.md delete mode 100644 dev-docs/analytics/rivr.md delete mode 100644 dev-docs/analytics/sortable.md create mode 100644 dev-docs/analytics/zeta_global_ssp.md create mode 100644 dev-docs/bidders/aax.md create mode 100644 dev-docs/bidders/aceex.md delete mode 100644 dev-docs/bidders/adlive.md create mode 100644 dev-docs/bidders/adlivetech.md create mode 100644 dev-docs/bidders/admaru.md create mode 100644 dev-docs/bidders/adplus.md create mode 100644 dev-docs/bidders/adquery.md create mode 100644 dev-docs/bidders/adrino.md create mode 100644 dev-docs/bidders/adsyield.md create mode 100644 dev-docs/bidders/adtargetme.md create mode 100644 dev-docs/bidders/adview.md create mode 100644 dev-docs/bidders/afp.md create mode 100644 dev-docs/bidders/alkimi.md create mode 100644 dev-docs/bidders/aseal.md create mode 100644 dev-docs/bidders/aso.md create mode 100644 dev-docs/bidders/beop.md create mode 100644 dev-docs/bidders/biddo.md create mode 100644 dev-docs/bidders/bidmyadz.md create mode 100644 dev-docs/bidders/big-richmedia.md create mode 100644 dev-docs/bidders/bliink.md create mode 100644 dev-docs/bidders/brave.md create mode 100644 dev-docs/bidders/catapultx.md create mode 100644 dev-docs/bidders/codefuel.md create mode 100644 dev-docs/bidders/compass.md create mode 100644 dev-docs/bidders/contentexchange.md create mode 100644 dev-docs/bidders/cwire.md create mode 100644 dev-docs/bidders/deltaprojects.md rename dev-docs/{ => bidders}/denakop.md (90%) create mode 100644 dev-docs/bidders/dianomi.md create mode 100644 dev-docs/bidders/didnavideo.md create mode 100644 dev-docs/bidders/displayio.md create mode 100644 dev-docs/bidders/distroscale.md create mode 100644 dev-docs/bidders/duration.md create mode 100644 dev-docs/bidders/ergadx.md create mode 100644 dev-docs/bidders/felixads.md create mode 100644 dev-docs/bidders/finative.md create mode 100644 dev-docs/bidders/futureads.md create mode 100644 dev-docs/bidders/goldbach.md create mode 100644 dev-docs/bidders/groupm.md create mode 100644 dev-docs/bidders/growads.md create mode 100644 dev-docs/bidders/huaweiads.md create mode 100644 dev-docs/bidders/idx.md mode change 100644 => 100755 dev-docs/bidders/improvedigital.md create mode 100644 dev-docs/bidders/incrementx.md create mode 100644 dev-docs/bidders/infytv.md create mode 100644 dev-docs/bidders/insticator.md create mode 100644 dev-docs/bidders/integr8.md create mode 100644 dev-docs/bidders/iqzone.md rename dev-docs/bidders/{navelix.md => janet.md} (79%) create mode 100644 dev-docs/bidders/kueez.md create mode 100644 dev-docs/bidders/lasso.md create mode 100644 dev-docs/bidders/limelightDigital.md create mode 100644 dev-docs/bidders/loglylift.md create mode 100644 dev-docs/bidders/mathildeads.md delete mode 100644 dev-docs/bidders/mediafuseLift.md create mode 100644 dev-docs/bidders/mediakeys.md create mode 100644 dev-docs/bidders/mediasniper.md create mode 100644 dev-docs/bidders/minutemedia.md create mode 100644 dev-docs/bidders/motionspots.md create mode 100644 dev-docs/bidders/newspassid.md create mode 100644 dev-docs/bidders/nexx360.md delete mode 100644 dev-docs/bidders/oftmediahb.md delete mode 100644 dev-docs/bidders/oneVideo.md create mode 100644 dev-docs/bidders/openweb.md create mode 100644 dev-docs/bidders/openwebvideo.md create mode 100644 dev-docs/bidders/operaads.md create mode 100644 dev-docs/bidders/optout.md create mode 100644 dev-docs/bidders/ottadvisors.md rename dev-docs/bidders/{appaloosa.md => pgam.md} (64%) create mode 100644 dev-docs/bidders/pilotx.md create mode 100644 dev-docs/bidders/pixfuture.md create mode 100644 dev-docs/bidders/playwire.md delete mode 100644 dev-docs/bidders/prebidServer.md create mode 100644 dev-docs/bidders/prisma.md rename dev-docs/bidders/{project-limelight.md => projectLimelight.md} (51%) delete mode 100644 dev-docs/bidders/pubnx.md create mode 100644 dev-docs/bidders/ras.md rename dev-docs/bidders/{converge_digital.md => rtbanalytica.md} (60%) create mode 100644 dev-docs/bidders/sa_lunamedia.md create mode 100644 dev-docs/bidders/smarthub.md rename dev-docs/bidders/{andbeyond.md => sonic_twist.md} (71%) delete mode 100644 dev-docs/bidders/sortable.md rename dev-docs/bidders/{onefiftytwomedia.md => streamkey.md} (65%) create mode 100644 dev-docs/bidders/taboola.md create mode 100644 dev-docs/bidders/talkads.md create mode 100644 dev-docs/bidders/targetvideo.md create mode 100644 dev-docs/bidders/trafficgate.md create mode 100644 dev-docs/bidders/trustxstandalone.md create mode 100644 dev-docs/bidders/ttd.md create mode 100644 dev-docs/bidders/unibots.md create mode 100644 dev-docs/bidders/ventes.md delete mode 100644 dev-docs/bidders/vertoz.md create mode 100644 dev-docs/bidders/vibrantmedia.md create mode 100644 dev-docs/bidders/vidcrunch.md create mode 100644 dev-docs/bidders/videobyte.md create mode 100644 dev-docs/bidders/videoheroes.md create mode 100644 dev-docs/bidders/vidoomy.md create mode 100644 dev-docs/bidders/viewdeos.md create mode 100644 dev-docs/bidders/vlyby.md delete mode 100644 dev-docs/bidders/weborama.md create mode 100644 dev-docs/bidders/winr.md create mode 100644 dev-docs/bidders/yahoossp.md create mode 100644 dev-docs/bidders/yandex.md create mode 100644 dev-docs/examples/legacy-browser-example.md create mode 100644 dev-docs/examples/meta-bid-filtering.md create mode 100644 dev-docs/modules/1plusXRtdProvider.md create mode 100644 dev-docs/modules/adnuntiusRtdProvider.md create mode 100644 dev-docs/modules/airgridRtdProvider.md create mode 100644 dev-docs/modules/akamaiDapRtdProvider.md create mode 100644 dev-docs/modules/bidViewableIO.md create mode 100644 dev-docs/modules/blueconicRtdProvider.md create mode 100644 dev-docs/modules/brandmetricsRtdProvider.md create mode 100644 dev-docs/modules/cleanioRtdProvider.md create mode 100644 dev-docs/modules/dchain.md create mode 100644 dev-docs/modules/debugging.md create mode 100644 dev-docs/modules/hadronRtdProvider.md delete mode 100644 dev-docs/modules/iabCatagoryTranslation.md create mode 100644 dev-docs/modules/idWardRtdProvider.md create mode 100644 dev-docs/modules/imRtdProvider.md create mode 100644 dev-docs/modules/intersectionRtdProvider.md create mode 100644 dev-docs/modules/medianetRtdProvider.md create mode 100644 dev-docs/modules/permutiveRtdProvider.md create mode 100644 dev-docs/modules/prebidServer.md create mode 100644 dev-docs/modules/timeoutRtdProvider.md create mode 100644 dev-docs/modules/viewability.md create mode 100644 dev-docs/modules/weboramaRtdProvider.md create mode 100644 dev-docs/modules/yieldmoSyntheticInventoryModule.md create mode 100644 dev-docs/pb7-notes.md create mode 100644 dev-docs/publisher-api-reference/getConsentMetadata.md create mode 100644 dev-docs/publisher-api-reference/getUserIdsAsync.md create mode 100644 dev-docs/publisher-api-reference/mergeBidderConfig.md create mode 100644 dev-docs/publisher-api-reference/mergeConfig.md create mode 100644 dev-docs/publisher-api-reference/readConfig.md create mode 100644 dev-docs/vendor-billing.md delete mode 100644 examples/legacy/modules/pub_common_id_optout.html delete mode 100644 examples/legacy/multi-format/index.md delete mode 100644 examples/legacy/multi-format/multi_format_example.html delete mode 100644 examples/legacy/native/index.md delete mode 100644 examples/legacy/native/native-demo.html delete mode 100644 examples/legacy/pbjs_demo.html delete mode 100644 examples/legacy/simple.html create mode 100644 examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html create mode 100644 features/adServerKvps.md create mode 100644 identity/prebid-identity.md create mode 100644 identity/sharedid.md create mode 100644 mix-manifest.json delete mode 100644 prebid-mobile/adops-line-item-setup-mopub.md delete mode 100644 prebid-mobile/adops-setup-full-screen-video-mopub.md delete mode 100644 prebid-mobile/adops-setup-rewarded-video-mopub.md create mode 100644 prebid-mobile/modules/modules-overview.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-customization-controls.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-admob.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-gam-native.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-gam.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-max.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-pb-native.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration-pb.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-integration.md create mode 100644 prebid-mobile/modules/rendering/android-sdk-parameters.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-Integration.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-customization-controls.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-admob.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-gam-native.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-gam.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-max.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-pb-native.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-integration-pb.md create mode 100644 prebid-mobile/modules/rendering/ios-sdk-parameters.md create mode 100644 prebid-mobile/modules/rendering/modules-rendering.md create mode 100644 prebid-mobile/modules/rendering/rendering-admob-line-item-setup.md create mode 100644 prebid-mobile/modules/rendering/rendering-deeplinkplus.md create mode 100644 prebid-mobile/modules/rendering/rendering-gam-line-item-setup.md create mode 100644 prebid-mobile/modules/rendering/rendering-impression-tracking.md create mode 100644 prebid-mobile/modules/rendering/rendering-max-line-item-setup.md create mode 100644 prebid-mobile/modules/rendering/rendering-native-ad-configuration.md create mode 100644 prebid-mobile/modules/rendering/rendering-native-guidelines.md create mode 100644 prebid-server/developers/add-a-module-java.md create mode 100644 prebid-server/developers/add-a-module.md create mode 100644 prebid-server/developers/module-atags.md create mode 100644 prebid-server/features/pbs-floors.md create mode 100644 prebid-server/features/pbs-native.md create mode 100644 prebid-server/features/pbs-storedreqs-java.md create mode 100644 prebid-server/features/pg/pbs-pg-bidder.md create mode 100644 prebid-server/features/pg/pbs-pg-glossary.md create mode 100644 prebid-server/features/pg/pbs-pg-host.md create mode 100644 prebid-server/features/pg/pbs-pg-idx.md create mode 100644 prebid-server/features/pg/pbs-pg-plan.md create mode 100644 prebid-server/features/pg/pbs-pg-targeting.md create mode 100644 prebid-server/pbs-modules/index.md create mode 100644 prebid-server/pbs-modules/ortb2-blocking.md create mode 100644 tools/professor-prebid.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..d744f1ccdb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ + + +## 🏷 Type of documentation + +- [ ] new bid adapter +- [ ] update bid adapter +- [ ] new feature +- [ ] text edit only (wording, typos) +- [ ] bugfix (code examples) +- [ ] new examples + +## 📋 Checklist + +- [ ] Related pull requests in prebid.js or server are linked +- [ ] For new adapters check [submitting your adapter docs](https://docs.prebid.org/dev-docs/bidder-adaptor.html#submitting-your-adapter) diff --git a/.gitignore b/.gitignore index c300c925e6..d096d0e1d7 100755 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,9 @@ Gemfile.lock .jekyll-metadata *ads.txt.bkp* .sass-cache + +# Files generated by `npm install` +node_modules/ +/.vs/prebid.github.io/v17/.suo +/.vs/slnx.sqlite +/.vs diff --git a/Gemfile b/Gemfile index a0483f2507..0fb51bf388 100755 --- a/Gemfile +++ b/Gemfile @@ -1,2 +1,4 @@ source 'https://rubygems.org' -gem 'github-pages', '>= 30' \ No newline at end of file +gem 'github-pages', '>= 30' + +gem "webrick", "~> 1.7" diff --git a/README.md b/README.md index 8bf538b48f..86b59bade2 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ This repository contains the source files for the Prebid.js documentation site at [Prebid.org](https://prebid.org). -Please see the sections below for more information. +Please see the sections below for more information: + [Contributing](#contributing) + [License](#license) @@ -14,7 +14,7 @@ Please see the sections below for more information. ## Contributing -Thanks in advance for your contribution! Contributors are listed in the **Thanks** section below. +Thanks in advance for your contribution! For smaller changes, such as fixing a typo or adding a new section to an existing page, submit a pull request. @@ -33,7 +33,7 @@ All docs are under the license shown in the `LICENSE` file in this directory. ## Prerequisites -The site uses [Jekyll](https://jekyllrb.com/), which is written in the [Ruby](https://www.ruby-lang.org/en/) language. +The site is hosted on GitHub pages, and uses [Jekyll](https://jekyllrb.com/) to generate the HTML. Jekyll is written in the [Ruby](https://www.ruby-lang.org/en/) language. 1. follow the instructions at https://jekyllrb.com/docs/installation/ for your OS 1. gem install github-pages @@ -42,7 +42,7 @@ The site uses [Jekyll](https://jekyllrb.com/), which is written in the [Ruby](ht For CSS, the site uses Laravel Mix to build CSS from Sass (scss-flavored) source files. Under the hood Laravel Mix uses Webpack. 1. follow the instructions at https://nodejs.dev to install Node.js for your OS -1. `npm install` to install packages for building assets +1. `npm ci` to install packages for building assets 1. build assets as described below @@ -53,20 +53,22 @@ Before submitting a pull request, you should run the site locally to make sure y To get started editing the site and seeing your changes, clone this repo and enter the following commands in your terminal: -- `cd path/to/prebid.github.io` -- `bundle exec jekyll serve` +```bash +$ JEKYLL_ENV=production bundle exec jekyll serve --watch --incremental +``` + You should see output that looks something like this: ``` -Configuration file: /Users/rloveland/Dropbox/Code/prebid.github.io/_config.yml - Source: /Users/rloveland/Dropbox/Code/prebid.github.io - Destination: /Users/rloveland/Dropbox/Code/prebid.github.io/_site +Configuration file: /Users/me/git/prebid.github.io/_config.yml + Source: /Users/me/git/prebid.github.io + Destination: /Users/me/git/prebid.github.io/_site Incremental build: disabled. Enable with --incremental Generating... done in 13.596 seconds. - Auto-regeneration: enabled for '/Users/rloveland/Dropbox/Code/prebid.github.io' -Configuration file: /Users/rloveland/Dropbox/Code/prebid.github.io/_config.yml + Auto-regeneration: enabled for '/Users/me/git/prebid.github.io' +Configuration file: /Users/me/git/prebid.github.io/_config.yml Server address: http://127.0.0.1:8080/ Server running... press ctrl-c to stop. ... diff --git a/_assets/sass/base/_base.scss b/_assets/sass/base/_base.scss index e2718bac06..9bb6378853 100644 --- a/_assets/sass/base/_base.scss +++ b/_assets/sass/base/_base.scss @@ -1,3 +1,9 @@ img { max-width: 100%; } + +div { + min-width: 0; +} + + diff --git a/_assets/sass/components/_pb.scss b/_assets/sass/components/_pb.scss index a16c1b2217..a6024cc1da 100644 --- a/_assets/sass/components/_pb.scss +++ b/_assets/sass/components/_pb.scss @@ -99,6 +99,10 @@ } } + .pb-code-hl-wrap { + width: 100%; + } + .highlight, .pb-code-hl { margin-top: 20px; margin-bottom: 20px; diff --git a/_data/partners.yml b/_data/partners.yml index 8a606fc372..5aae2d17c1 100644 --- a/_data/partners.yml +++ b/_data/partners.yml @@ -2,33 +2,33 @@ link: https://www.indexexchange.com/ imgURL: /assets/images/partners/leader/IX-logo.png type: leader - + - company: Magnite link: https://www.magnite.com/ imgURL: /assets/images/partners/leader/Magnite_logo.png type: leader - -- company: MediaMath + +- company: MediaMath link: https://www.mediamath.com/ imgURL: /assets/images/partners/leader/MediaMath-wordmark.png type: leader - -- company: OpenX + +- company: OpenX link: https://www.openx.com/ imgURL: /assets/images/partners/leader/openx.png type: leader - -- company: Pubmatic + +- company: Pubmatic link: https://pubmatic.com/products/header-bidding/ imgURL: /assets/images/partners/leader/pubmatic.png type: leader -- company: SpotX +- company: SpotX link: https://spotx.tv imgURL: /assets/images/partners/leader/spotx_logo.png type: leader -- company: theTradeDesk +- company: theTradeDesk link: https://www.thetradedesk.com/ imgURL: /assets/images/partners/leader/TTD_logo.png type: leader @@ -37,38 +37,38 @@ link: https://www.xandr.com/platform/ imgURL: /assets/images/partners/founders/xandr.png type: leader - + - company: Beachfront Media link: https://www.beachfront.com/ imgURL: /assets/images/partners/tech/beachfront_logo.png type: technology - -- company: Conversant + +- company: Conversant link: https://www.conversantmedia.com/ imgURL: /assets/images/partners/tech/conversant_logo.png type: technology - -- company: Criteo + +- company: Criteo link: https://www.criteo.com/for-publishers/products/criteo-direct-bidder/ imgURL: /assets/images/partners/tech/criteo.png type: technology - -- company: Datablocks + +- company: Datablocks link: https://datablocks.net/ imgURL: /assets/images/partners/tech/datablocks_logo.png type: technology - -- company: LiveRamp + +- company: LiveRamp link: https://liveramp.com/ imgURL: /assets/images/partners/tech/LiveRamp-Logo.png type: technology - -- company: Marfeel + +- company: Marfeel link: https://www.marfeel.com/ imgURL: /assets/images/partners/tech/marfeel.png type: technology - -- company: PubNative + +- company: PubNative link: https://pubnative.net/ imgURL: /assets/images/partners/tech/Pubnative-RGB-Logo.png type: technology @@ -78,27 +78,27 @@ imgURL: /assets/images/partners/tech/rakuten_logo.png type: technology -- company: StreamAMP +- company: StreamAMP link: https://streamamp.com/ imgURL: /assets/images/partners/tech/StreamAMP_logo.png type: technology -- company: Tapad +- company: Tapad link: https://tapad.com/ imgURL: /assets/images/partners/tech/tapad_logo.png type: technology -- company: Verizon Media +- company: Verizon Media link: https://www.verizonmedia.com/advertising imgURL: /assets/images/partners/tech/verizon_logo.png type: technology - -- company: Advance Local Media + +- company: Advance Local Media link: https://advancelocal.com imgURL: /assets/images/partners/publisher/advancelocal_logo.png type: publisher -- company: CafeMedia +- company: CafeMedia link: https://www.cafemedia.com/ imgURL: /assets/images/partners/publisher/cafemedia.png type: publisher @@ -107,28 +107,28 @@ link: https://www.chegg.com/ imgURL: /assets/images/partners/publisher/chegg.png type: publisher - + - company: diDNA link: https://didna.io/ imgURL: /assets/images/partners/publisher/didna-logo.png type: publisher - + - company: Freestar link: https://freestar.com/ imgURL: /assets/images/partners/publisher/freestar-logo.png type: publisher - + - company: Glewed TV link: https://www.glewed.tv/ imgURL: /assets/images/partners/publisher/glewed_logo.png type: publisher - + - company: Hive Media link: https://www.hivemedia.com imgURL: /assets/images/partners/publisher/Hive-Media-Group-Stacked-Color-web.png type: publisher - -- company: Insider, Inc. + +- company: Insider, Inc. link: https://www.insider-inc.com/ imgURL: /assets/images/partners/publisher/Insider_Inc_logo.png type: publisher @@ -163,12 +163,7 @@ imgURL: /assets/images/partners/publisher/SHE_Media_Logo.png type: publisher -- company: Sortable - link: https://www.sortable.com/ - imgURL: /assets/images/partners/publisher/sortable.png - type: publisher - -- company: Havas +- company: Havas link: https://havasmedia.com/ imgURL: /assets/images/partners/buyer/Havas_Media_Logo.png type: buyer diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 1e5e598541..97b9747c92 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -53,7 +53,7 @@ - sbSecId: 0 title: Header Bidding - link: /wrapper_code_of_conduct.html + link: https://prebid.org/code-of-conduct/ isHeader: 0 isSectionHeader: 0 sectionTitle: @@ -202,6 +202,14 @@ sectionTitle: subgroup: 1 +- sbSecId: 1 + title: Legacy Browser Example + link: /dev-docs/examples/legacy-browser-example.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + - sbSecId: 1 title: Using Prebid.js with AppNexus Publisher Ad Server link: /dev-docs/examples/use-prebid-with-appnexus-ad-server.html @@ -235,6 +243,15 @@ sectionTitle: subgroup: 1 +- sbSecId: 1 + title: Meta Bid Filtering + link: /dev-docs/examples/meta-bid-filtering.html + Item: 1 + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + - sbSecId: 1 title: Troubleshooting link: @@ -342,6 +359,8 @@ sectionTitle: subgroup: 4 + + - sbSecId: 1 title: How to Add an Analytics Adapter link: /dev-docs/integrate-with-the-prebid-analytics-api.html @@ -359,7 +378,15 @@ subgroup: 4 - sbSecId: 1 - title: Prebid Modules + title: Vendor Billing in Prebid.js + link: /dev-docs/vendor-billing.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 4 + +- sbSecId: 1 + title: Prebid.js Modules link: isHeader: 1 headerId: pbjsmodules @@ -376,32 +403,24 @@ subgroup: 5 - sbSecId: 1 - title: General Modules - link: /dev-docs/modules/index.html#general-modules + title: Recommended Modules + link: /dev-docs/modules/index.html#recommended-modules isHeader: 0 isSectionHeader: 0 sectionTitle: subgroup: 5 - sbSecId: 1 - title: Real Time Data Providers - link: /dev-docs/modules/index.html#real-time-data-providers - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 5 - -- sbSecId: 1 - title: Video Modules - link: /dev-docs/modules/index.html#video-modules + title: General Modules + link: /dev-docs/modules/index.html#general-modules isHeader: 0 isSectionHeader: 0 sectionTitle: subgroup: 5 - sbSecId: 1 - title: Testing and Debug Modules - link: /dev-docs/modules/index.html#testing-and-debug-modules + title: Vendor-Specific Modules + link: /dev-docs/modules/index.html#vendor-specific-modules isHeader: 0 isSectionHeader: 0 sectionTitle: @@ -458,6 +477,14 @@ sectionTitle: subgroup: 8 +- sbSecId: 1 + title: Ad Server Key Values + link: /features/adServerKvps.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 8 + - sbSecId: 1 title: Native Ads link: /prebid/native-implementation.html @@ -491,7 +518,7 @@ subgroup: 8 - sbSecId: 1 - title: Prebid Ad Slot + title: Prebid Ad Slot and GPID link: /features/pbAdSlot.html isHeader: 0 isSectionHeader: 0 @@ -506,6 +533,14 @@ sectionTitle: subgroup: 8 +- sbSecId: 1 + title: Interstitial Ads + link: /features/InterstitialAds.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 8 + - sbSecId: 1 title: Timeouts link: /features/timeouts.html @@ -576,6 +611,213 @@ sectionTitle: subgroup: 0 +- sbSecId: 2 + title: Rendering API + link: + isHeader: 1 + headerId: rendering + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Rendering Overview + link: /prebid-mobile/modules/rendering/modules-rendering.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: "iOS" + link: + isHeader: 0 + isSectionHeader: 0 + isCatHeader: 1 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: SDK Integration + link: /prebid-mobile/modules/rendering/ios-sdk-Integration.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Custom or No mediation + link: /prebid-mobile/modules/rendering/ios-sdk-integration-pb.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with GAM + link: /prebid-mobile/modules/rendering/ios-sdk-integration-gam.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with AdMob + link: /prebid-mobile/modules/rendering/ios-sdk-integration-admob.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with AppLovin MAX + link: /prebid-mobile/modules/rendering/ios-sdk-integration-max.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Targeting + link: /prebid-mobile/modules/rendering/ios-sdk-parameters.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Ad Experience Controls + link: /prebid-mobile/modules/rendering/ios-sdk-customization-controls.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: "Android" + link: + isHeader: 0 + isSectionHeader: 0 + isCatHeader: 1 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: SDK Integration + link: /prebid-mobile/modules/rendering/android-sdk-integration.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Custom or No mediation + link: /prebid-mobile/modules/rendering/android-sdk-integration-pb.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with GAM + link: /prebid-mobile/modules/rendering/android-sdk-integration-gam.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with AdMob + link: /prebid-mobile/modules/rendering/android-sdk-integration-admob.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Integration with AppLovin MAX + link: /prebid-mobile/modules/rendering/android-sdk-integration-max.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Targeting + link: /prebid-mobile/modules/rendering/android-sdk-parameters.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Ad Experience Controls + link: /prebid-mobile/modules/rendering/android-sdk-customization-controls.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: "Ad Server" + link: + isHeader: 0 + isSectionHeader: 0 + isCatHeader: 1 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Rendering Order - GAM + link: /prebid-mobile/modules/rendering/rendering-gam-line-item-setup.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Mediation Group - AdMob + link: /prebid-mobile/modules/rendering/rendering-admob-line-item-setup.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 2 + title: Custom Network - MAX + link: /prebid-mobile/modules/rendering/rendering-max-line-item-setup.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +# - sbSecId: 2 +# title: Modules +# link: +# isHeader: 1 +# headerId: pbsdkmodules +# isSectionHeader: 0 +# sectionTitle: +# subgroup: 1 +# +# - sbSecId: 2 +# title: Modules Overview +# link: /prebid-mobile/modules/modules-overview.html +# isHeader: 0 +# isSectionHeader: 0 +# sectionTitle: +# subgroup: 1 +# +# +# - sbSecId: 2 +# title: Rendering Modules +# link: /prebid-mobile/modules/rendering/modules-rendering.html +# isHeader: 0 +# isSectionHeader: 0 +# hasSubMenus: 1 +# sectionTitle: +# subgroup: 1 + - sbSecId: 2 title: For iOS link: @@ -583,7 +825,7 @@ headerId: ios isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Code Integration @@ -591,7 +833,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: iOS Mobile API @@ -599,7 +841,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Ad Unit @@ -607,7 +849,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Banner Ad Unit @@ -615,7 +857,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Banner Interstitial Ad Unit @@ -623,7 +865,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Native Ad Unit @@ -631,7 +873,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: In App Native Ad Unit @@ -639,7 +881,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Video Outstream Ad Unit @@ -647,7 +889,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Video Instream Ad Unit @@ -655,7 +897,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Video interstitial Ad Unit @@ -663,7 +905,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Video Rewarded Ad Unit @@ -671,7 +913,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Targeting Parameters @@ -679,7 +921,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Result Codes @@ -687,7 +929,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Prebid Mobile Object @@ -695,7 +937,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: Prebid Utilities @@ -703,7 +945,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 1 + subgroup: 2 - sbSecId: 2 title: For Android @@ -712,7 +954,7 @@ headerId: android isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Code Integration @@ -720,7 +962,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Android Mobile API @@ -728,7 +970,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Ad Unit @@ -736,7 +978,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Banner Ad Unit @@ -744,7 +986,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Native Ad Unit @@ -752,7 +994,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: In App Native Ad Unit @@ -760,7 +1002,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Banner Interstitial Ad Unit @@ -768,7 +1010,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Video Outstream Ad Unit @@ -776,7 +1018,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Video Intream Ad Unit @@ -784,7 +1026,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Video Interstitial Ad Unit @@ -792,7 +1034,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Video Rewarded Ad Unit @@ -800,7 +1042,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 @@ -809,7 +1051,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Result Codes @@ -817,7 +1059,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Prebid Mobile Object @@ -825,7 +1067,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: Prebid Utility Functions @@ -833,7 +1075,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 2 title: For Contributors @@ -1039,30 +1281,6 @@ sectionTitle: subgroup: 0 -- sbSecId: 3 - title: Setup Line Items For MoPub - link: /prebid-mobile/adops-line-item-setup-mopub.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 0 - -- sbSecId: 3 - title: Setup Rewarded Video Line Items For MoPub - link: /prebid-mobile/adops-setup-rewarded-video-mopub.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 0 - -- sbSecId: 3 - title: Setup Full Screen Video Line Items For MoPub - link: /prebid-mobile/adops-setup-full-screen-video-mopub.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 0 - - sbSecId: 3 title: Setup Native Ads link: /prebid-mobile/adops-native-setup.html @@ -1512,6 +1730,14 @@ sectionTitle: subgroup: 1 +- sbSecId: 4 + title: 'No Server (Specify Renderer)' + link: /examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + - sbSecId: 4 title: "Long-Form (Ad Pods)" link: @@ -1657,6 +1883,14 @@ sectionTitle: subgroup: 3 +- sbSecId: 5 + title: Native + link: /prebid-server/features/pbs-native.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + - sbSecId: 5 title: Caching link: /prebid-server/features/pbs-caching.html @@ -1674,8 +1908,8 @@ subgroup: 3 - sbSecId: 5 - title: Interstitials - link: /prebid-server/features/pbs-interstitials.html + title: Floors + link: /prebid-server/features/pbs-floors.html isHeader: 0 isSectionHeader: 0 sectionTitle: @@ -1689,6 +1923,14 @@ sectionTitle: subgroup: 3 +- sbSecId: 5 + title: Interstitials + link: /prebid-server/features/pbs-interstitials.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + - sbSecId: 5 title: Stored Requests link: /prebid-server/features/pbs-storedreqs.html @@ -1713,6 +1955,23 @@ sectionTitle: subgroup: 3 +- sbSecId: 5 + title: Programmatic Guaranteed + link: /prebid-server/features/pg/pbs-pg-idx.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + + +- sbSecId: 5 + title: Modules + link: /prebid-server/pbs-modules/ + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + - sbSecId: 5 title: Developers link: @@ -1746,6 +2005,14 @@ sectionTitle: subgroup: 5 +- sbSecId: 5 + title: Building a Module + link: /prebid-server/developers/add-a-module.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 5 + - sbSecId: 5 title: Code Reviews link: /prebid-server/developers/code-reviews.html @@ -2022,3 +2289,49 @@ isSectionHeader: 0 sectionTitle: subgroup: 0 + +- sbSecId: 8 + title: Professor Prebid + link: /tools/professor-prebid.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + + #-------------- Prebid Identity --------------| + +- sbSecId: 9 + title: + link: + isHeader: 0 + isSectionHeader: 1 + sectionTitle: Prebid Identity + sectionId: prebid-identity + subgroup: 1000 + sbCollapseId: prebid-identity + +- sbSecId: 9 + title: invis + link: + isHeader: 1 + headerId: invis + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + +- sbSecId: 9 + title: Identity Overview + link: /identity/prebid-identity.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + +- sbSecId: 9 + title: SharedID + link: /identity/sharedid.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + diff --git a/_includes/adops/adops-gam-video-setup.html b/_includes/adops/adops-gam-video-setup.html index b8091311fc..1825186ccd 100644 --- a/_includes/adops/adops-gam-video-setup.html +++ b/_includes/adops/adops-gam-video-setup.html @@ -39,16 +39,11 @@

Line Item Setup

Creative Setup

When setting up video creatives, it's important to understand where the VAST XML is stored for each of your bidders. The most common place to store VAST XML is AppNexus' cache, but some bidders (such as RubiconProject and SpotX) use their own cache services. To support such -bidders, you will need to choose one of the following approaches: - +bidders, see the Multiple Cache Locations instructions below.

Single Cache Location

-If you only use bidders that provide full VAST responses, no special setup is needed. Otherwise, do the following: +If you only use bidders that provide full VAST responses, do the following:

1. For each line item you create, click on the Creatives tab, click the ADD CREATIVE button, and choose the size you're entering.

@@ -75,12 +70,15 @@

Single Cache Location

URL failed. This is expected, since the creative URL above points to a server-side asset cache hosted by Prebid Server.

-

4. Set the Duration to 1.

+

4. Set the Duration to the max length of video ads you serve. If you don't know what the max length is, set it to 30.

+ +

In the past Prebid used to recommend setting duration to 0 or 1, but GAM now requires that this field reflect the actual video ad length. Since ads flowing through header bidding are going to differ in length, choose a value that matches a common ad length like 15 or 30.

The resulting creative should look something like the following:

Google Ad Manager Video Creative Setup

+

Multiple Cache Locations

If you're utilizing any bidders that cache their own VAST, you have two options: diff --git a/_includes/footer.html b/_includes/footer.html index 04ccfbc31f..7e04247fd6 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -5,7 +5,7 @@

All demos, instructions, documentation and code included on the Prebid.org website are released under the {{site.license}}.

-

Copyright© {{site.time | date: "%Y" }} Prebid.org | Privacy Policy

+

Copyright© {{site.time | date: "%Y" }} Prebid.org | Privacy Policy

diff --git a/_includes/video/head.html b/_includes/video/head.html index 135969ba37..ca70580114 100644 --- a/_includes/video/head.html +++ b/_includes/video/head.html @@ -5,7 +5,7 @@ {% include head--common.html %} - + - + diff --git a/_includes/video/pb-cp-kl.html b/_includes/video/pb-cp-kl.html index 424012f23b..03bcb25673 100644 --- a/_includes/video/pb-cp-kl.html +++ b/_includes/video/pb-cp-kl.html @@ -2,11 +2,11 @@ -{% include head--common.html %} - +{% include head--common.html %} + - - + + - + diff --git a/_includes/video/pb-cp-vjs.html b/_includes/video/pb-cp-vjs.html index 3e7689ac10..d58887cab2 100644 --- a/_includes/video/pb-cp-vjs.html +++ b/_includes/video/pb-cp-vjs.html @@ -2,10 +2,10 @@ -{% include head--common.html %} +{% include head--common.html %} - - + + @@ -13,7 +13,7 @@ - + diff --git a/_includes/video/pb-cp.html b/_includes/video/pb-cp.html index 3033a22d12..a3f41c4c6d 100644 --- a/_includes/video/pb-cp.html +++ b/_includes/video/pb-cp.html @@ -2,10 +2,10 @@ -{% include head--common.html %} +{% include head--common.html %} - - + + - + diff --git a/_includes/video/pb-is-amp.html b/_includes/video/pb-is-amp.html index b3cc436870..6d96feda5c 100644 --- a/_includes/video/pb-is-amp.html +++ b/_includes/video/pb-is-amp.html @@ -4,7 +4,7 @@ {% include head--common.html %} - + + diff --git a/_includes/video/pb-is-bc.html b/_includes/video/pb-is-bc.html index 0c53878f4a..8390b15f9e 100644 --- a/_includes/video/pb-is-bc.html +++ b/_includes/video/pb-is-bc.html @@ -2,10 +2,10 @@ -{% include head--common.html %} +{% include head--common.html %} - - + + - + diff --git a/_includes/video/pb-is-br.html b/_includes/video/pb-is-br.html index 57f9c2ca54..b4af9383f6 100644 --- a/_includes/video/pb-is-br.html +++ b/_includes/video/pb-is-br.html @@ -2,28 +2,28 @@ -{% include head--common.html %} +{% include head--common.html %} - - + + - - + + - + diff --git a/_includes/video/pb-is-fp.html b/_includes/video/pb-is-fp.html index 8f79f4f4f8..8fceac5010 100644 --- a/_includes/video/pb-is-fp.html +++ b/_includes/video/pb-is-fp.html @@ -2,107 +2,110 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - - - - + + + + + + + - + - + - + diff --git a/_includes/video/pb-is-jw01.html b/_includes/video/pb-is-jw01.html index ce30dd1c7e..8679a4d5d7 100644 --- a/_includes/video/pb-is-jw01.html +++ b/_includes/video/pb-is-jw01.html @@ -2,24 +2,24 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - - + + + + + - + diff --git a/_includes/video/pb-is-jw02.html b/_includes/video/pb-is-jw02.html index 09c498ba4a..e3307fe040 100644 --- a/_includes/video/pb-is-jw02.html +++ b/_includes/video/pb-is-jw02.html @@ -2,28 +2,28 @@ -{% include head--common.html %} +{% include head--common.html %} - - - + + + - + - + diff --git a/_includes/video/pb-is-kl.html b/_includes/video/pb-is-kl.html index 3aa790f73c..479b1e2ed0 100644 --- a/_includes/video/pb-is-kl.html +++ b/_includes/video/pb-is-kl.html @@ -2,42 +2,42 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + - + - + diff --git a/_includes/video/pb-is-ol.html b/_includes/video/pb-is-ol.html index 8508fc3d19..4535432ceb 100644 --- a/_includes/video/pb-is-ol.html +++ b/_includes/video/pb-is-ol.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + - - + + - + diff --git a/_includes/video/pb-is-vjs.html b/_includes/video/pb-is-vjs.html index 1d928f4bc4..0eefc25fb9 100644 --- a/_includes/video/pb-is-vjs.html +++ b/_includes/video/pb-is-vjs.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + @@ -70,8 +70,8 @@ }); }); - - + + diff --git a/_includes/video/pb-lf-fw.html b/_includes/video/pb-lf-fw.html index c47ec1c709..1381371a66 100644 --- a/_includes/video/pb-lf-fw.html +++ b/_includes/video/pb-lf-fw.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + @@ -16,10 +16,10 @@ - + - + - + + diff --git a/_includes/video/pb-os-app.html b/_includes/video/pb-os-app.html index ad8d7977ae..f2ce3f0774 100644 --- a/_includes/video/pb-os-app.html +++ b/_includes/video/pb-os-app.html @@ -4,8 +4,8 @@ {% include head--common.html %} - - + + diff --git a/_includes/video/pb-os-dfp.html b/_includes/video/pb-os-dfp.html index 39dd69f517..492e622be1 100644 --- a/_includes/video/pb-os-dfp.html +++ b/_includes/video/pb-os-dfp.html @@ -2,13 +2,13 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - - + + + + + + + + + + + diff --git a/_includes/video/pb-os-nas.html b/_includes/video/pb-os-nas.html index 51bebd75aa..26addc2a63 100644 --- a/_includes/video/pb-os-nas.html +++ b/_includes/video/pb-os-nas.html @@ -2,17 +2,17 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - - + + + + + - + diff --git a/_includes/video/pb-os-rd.html b/_includes/video/pb-os-rd.html index 3c93ee2988..ad413f9ce8 100644 --- a/_includes/video/pb-os-rd.html +++ b/_includes/video/pb-os-rd.html @@ -2,11 +2,11 @@ -{% include head--common.html %} +{% include head--common.html %} - - - + + + diff --git a/_includes/video/pb-ve-lf-fw.html b/_includes/video/pb-ve-lf-fw.html index 751f45dbb2..d115fc14cd 100644 --- a/_includes/video/pb-ve-lf-fw.html +++ b/_includes/video/pb-ve-lf-fw.html @@ -2,13 +2,13 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - - + + + + + @@ -17,10 +17,10 @@ - + - + - + - - - + + + + + diff --git a/_includes/video/pbs-jw01.html b/_includes/video/pbs-jw01.html index bd40af8000..ec62750962 100644 --- a/_includes/video/pbs-jw01.html +++ b/_includes/video/pbs-jw01.html @@ -2,9 +2,9 @@ -{% include head--common.html %} +{% include head--common.html %} - + - - - + + + + - + diff --git a/_includes/video/pbs-kl.html b/_includes/video/pbs-kl.html index 19d842bc59..719e88ca59 100644 --- a/_includes/video/pbs-kl.html +++ b/_includes/video/pbs-kl.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + + diff --git a/_includes/video/pbs-oy.html b/_includes/video/pbs-oy.html index 73a73206aa..bdc1ba2a94 100644 --- a/_includes/video/pbs-oy.html +++ b/_includes/video/pbs-oy.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + - - - - + + + + diff --git a/_includes/video/pbs-vjs.html b/_includes/video/pbs-vjs.html index 4619df3be2..1263e59a09 100644 --- a/_includes/video/pbs-vjs.html +++ b/_includes/video/pbs-vjs.html @@ -2,12 +2,12 @@ -{% include head--common.html %} +{% include head--common.html %} - - - - + + + + diff --git a/_layouts/bidder.html b/_layouts/bidder.html index 35f39c9de1..71c36e9696 100644 --- a/_layouts/bidder.html +++ b/_layouts/bidder.html @@ -35,9 +35,15 @@

{{ page.title }}

+ {% if page.enable_download == false %} +
+

Note:

This adapter is not available in current versions of Prebid.js. Reason: {{page.pbjs_version_notes}} +
+ {% endif %} + {% if page.s2s_only == true %}
-

Note:

This is a S2S adapter only. +

Note:

This is a Prebid Server adapter only.
{% endif %} @@ -76,7 +82,7 @@

Features

Supports Deals - {% if page.bidder_supports_deals == false %}no{% elsif page.bidder_supports_deals == true %}yes{% else %}check with bidder{% endif %} + {% if page.deals_supported == false %}no{% elsif page.deals_supported == true %}yes{% else %}check with bidder{% endif %} Prebid.js Adapter yes @@ -88,9 +94,15 @@

Features

Floors Module Support - {% if page.getFloor == true %}yes{% else %}no{% endif %} - - + {% if page.floors_supported == true %}yes{% else %}no{% endif %} + First Party Data Support + {% if page.fpd_supported == true %}yes{% elsif page.fpd_supported == false %}no{% else %}check with bidder{% endif %} + + + Multi Format Support + {% if page.multiformat_supported %}{{page.multiformat_supported}}{% else %}check with bidder{% endif %} + ORTB Blocking Support + {% if page.ortb_blocking_supported == true %}yes{% elsif page.ortb_blocking_supported == false %}no{% elsif page.ortb_blocking_supported == 'partial' %}partial{% else %}check with bidder{% endif %} diff --git a/_layouts/example.html b/_layouts/example.html index dc97cef97a..c917458838 100644 --- a/_layouts/example.html +++ b/_layouts/example.html @@ -43,19 +43,11 @@

This page contains:

-

- On the JSFiddle example below, click Result to see the result. -

- -

- Click Edit in JSFiddle to open the example in a new tab. -

-

For tips and troubleshooting info, see:

@@ -52,7 +55,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "b" or firstletter == "c" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -63,7 +66,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "d" or firstletter == "e" or firstletter == "f" or firstletter == "g" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -74,7 +77,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "h" or firstletter == "i" or firstletter == "j" or firstletter == "k" or firstletter == "l" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -85,7 +88,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "m" or firstletter == "n" or firstletter == "o" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -96,7 +99,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "p" or firstletter == "q" or firstletter == "r" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -107,7 +110,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "s" or firstletter == "t" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} @@ -118,7 +121,7 @@ var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }} {% assign firstletter = page.title | slice:0 | downcase %} {% unless firstletter == "u" or firstletter == "v" or firstletter == "w" or firstletter == "x" or firstletter == "y" or firstletter == "z" %}{% continue %}{% endunless %}
  • - {{ page.title }} + {{ page.title }}
    • {% endfor %} diff --git a/dev-docs/bidders/1ad4good.md b/dev-docs/bidders/1ad4good.md index eb05910d97..ce869099b1 100644 --- a/dev-docs/bidders/1ad4good.md +++ b/dev-docs/bidders/1ad4good.md @@ -4,7 +4,8 @@ title: 1ad4good description: Prebid One Ad for Good(1ad4good.org) Bidder Adaptor pbjs: true biddercode: 1ad4good -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/33across.md b/dev-docs/bidders/33across.md index 17d07de9f0..ceed5753a3 100644 --- a/dev-docs/bidders/33across.md +++ b/dev-docs/bidders/33across.md @@ -7,7 +7,7 @@ pbs: true biddercode: 33across media_types: banner, video gdpr_supported: true -getFloor: true +floors_supported: true schain_supported: true usp_supported: true userIds: all @@ -156,4 +156,15 @@ var adUnits = [ ... } ``` - +### SRA Mode +We recommend using SRA mode to optimize the bidding process as this allows our adapter to group together bid requests for Ad Units pertaining to the same product and site ID thereby minimizing the number of http requests made to our endpoint. To enable SRA set the following bidder specific config under 33Across +``` +pbjs.setBidderConfig({ + bidders: ['33across'], + config: { + ttxSettings: { + enableSRAMode: true + } + } +}); +``` \ No newline at end of file diff --git a/dev-docs/bidders/7xbid.md b/dev-docs/bidders/7xbid.md index 64e6abf1f4..75b539fdd3 100644 --- a/dev-docs/bidders/7xbid.md +++ b/dev-docs/bidders/7xbid.md @@ -5,7 +5,8 @@ description: Prebid 7xbid Bidder Adaptor pbjs: true biddercode: 7xbid media_types: banner, native -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/aardvark.md b/dev-docs/bidders/aardvark.md index 685014b350..a435711ff4 100644 --- a/dev-docs/bidders/aardvark.md +++ b/dev-docs/bidders/aardvark.md @@ -9,7 +9,8 @@ usp_supported: true schain_supported: true userIds: unifiedId gvl_id: 52 -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/aax.md b/dev-docs/bidders/aax.md new file mode 100644 index 0000000000..909101d40e --- /dev/null +++ b/dev-docs/bidders/aax.md @@ -0,0 +1,123 @@ +--- +layout: bidder +title: AAX +description: Prebid Aax Bidder Adaptor +biddercode: aax +gdpr_supported: true +media_types: banner,native,video +usp_supported: true +userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +prebid_member: false +pbjs: false +gvl_id: 720 +schain_supported: true +floors_supported: true +fpd_supported: true +pbs: true +safeframes_ok: true +multiformat_supported: will-not-bid +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------|----------|----------------------------------------|---------------|----------| +| `cid` | required | The customer id provided by Aax. | `'aax_test_customer'` | `string` | +| `crid` | required | The placement id provided by Aax. | `'aax_crid'` | `string` | +| `video` | required for video Ad units | Object containing video targeting parameters. See [Video Object](#aax-video-object) for details.|`video: { maxduration: 60 }` | `object` | + + + +#### Video Object + +{: .table .table-bordered .table-striped } +| Name | Type | Description | Example| +|------------|----------|--------------|--------| +|mimes|array of strings|(Recommended) Specifies the video content MIME types supported; for example, video/x-ms-wmv and video/x-flv.|["video/x-ms-wmv","video/x-flv"]| +|minduration|integer|(Recommended) Specifies the minimum video ad duration, in seconds.|10| +|maxduration|integer|(Recommended) Specifies the maximum video ad duration, in seconds.|60| +|w|integer|(Recommended) Specifies the width of the video player, in pixels. Required if playerSize not present in `mediaTypes.video`|640| +|h|integer|(Recommended) Specifies the height of the video player, in pixels. Required if playerSize not present in `mediaTypes.video`|480| +|startdelay |integer | (Recommended) Specifies the start delay of the video ad|0| +|battr| array of integers|Specifies the video creative attributes to block. Refer to section 5.3 of the IAB specification for a list of attributes.| [ 13, 14 ]| +playbackmethod| array of integers| Specifies the allowed playback methods. If not specified, all are assumed to be allowed. Currently supported values are: `1: Autoplay, sound on`; `2: Autoplay, sound off`; `3: Click to play`; `4: Mouse over to play`|[1, 3]| +|api| array of integers| Specifies the supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. Currently supported values are: `1: VPAID 1.0`; `2: VPAID 2.0`; `3: MRAID-1`; `4: ORMMA`; `5: MRAID-2`|[1, 2]| +|protocols |array of integers| Array of supported video protocols. Currently supported values are: `1: VAST 1.0`; `2: VAST 2.0`; `3: VAST 3.0`; `4: VAST 1.0 Wrapper`; `5: VAST 2.0 Wrapper`; `6: VAST 3.0 Wrapper`; `7: VAST 4.0`|[1, 2]| +|placement |integer|Placement type for the impression. Possible options: `1: In-Stream`; `2: In-banner`; `3: Outstream/In-article`; `4: In-feed`; `5: Interstitial/Slider/Floating`; `6: Long-Form`;|1| + +Besides the above-mentioned parameters, we support all other OpenRTB 2.x video objects as optional parameters. + +In addition to `bids[].params.video`, Aax adapter consumes parameters specified in the `mediaTypes.video`. + +#### Example of Instream Video Ad-unit +``` +var videoAdUnit = { + code: 'video1', + mediaTypes: { + video: { + context: "instream", + playerSize: [640, 480], + mimes: ['video/mp4'], + placement: 1 + } + }, + bids: [{ + bidder: 'aax', + params: { + cid: 'aax_test_customer', + crid: 'aax_crid', + } + }] +}; +``` + +#### Example of Native Ad-unit +``` +var adUnits = [{ + code: 'div-gpt-ad-6874091242345-0', + mediaTypes: { + native: { + image: { + required: true, + sizes: [300, 250], + wmin: 50, + }, + title: { + required: true, + len: 80 + } + } + }, + bids: [{ + bidder: 'aax', + params: { + cid: 'aax_test_customer', + crid: 'aax_crid' + } + }] +}]; +``` + +#### Example of Banner Ad-unit +``` +var adUnits = [{ + code: 'div-gpt-ad-6874091242345-0', + mediaTypes: { + banner: { + sizes: [ + [728, 90], + [300, 600], + [300, 250] + ], + } + }, + bids: [{ + bidder: 'aax', + params: { + cid: 'aax_test_customer', + crid: 'aax_crid' + } + }] +}]; +``` diff --git a/dev-docs/bidders/aceex.md b/dev-docs/bidders/aceex.md new file mode 100644 index 0000000000..e380d3aa54 --- /dev/null +++ b/dev-docs/bidders/aceex.md @@ -0,0 +1,27 @@ +--- +layout: bidder +title: Aceex +description: Prebid Aceex Bidder Adaptor +biddercode: aceex +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +userId: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: false +pbs: true +--- + +### Note: + +The Example Bidding adapter requires setup before beginning. Please contact us at tech@aceex.com + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `accountid` | required | Endpoint id | `'hash'` | `string` | diff --git a/dev-docs/bidders/acuityads.md b/dev-docs/bidders/acuityads.md index a6f10c6e20..95d4784821 100644 --- a/dev-docs/bidders/acuityads.md +++ b/dev-docs/bidders/acuityads.md @@ -10,7 +10,7 @@ schain_supported: true userId: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId media_types: banner, video, native safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: false pbs: true --- diff --git a/dev-docs/bidders/adagio.md b/dev-docs/bidders/adagio.md index d658da1cbe..220d544cf7 100644 --- a/dev-docs/bidders/adagio.md +++ b/dev-docs/bidders/adagio.md @@ -6,13 +6,14 @@ pbjs: true biddercode: adagio media_types: banner, native, video userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, pubProvidedId, sharedId, unifiedId -getFloor: true +floors_supported: true gdpr_supported: true usp_supported: true coppa_supported: true schain_supported: true gvl_id: 617 -prebid_member: true, +prebid_member: true +fpd_supported: false --- ### Note @@ -21,7 +22,7 @@ The Adagio bidder adaptor requires setup and approval from the Adagio team. Plea ### Bid Params -**Important**: Adagio needs to collect attention data about the ads displayed on a page and must listen to some specifics ad-server events. Please refer to the [Adagio user guide](https://adagio-team.atlassian.net/wiki/spaces/AH/pages/67272705/EN+Adagio+Prebid.js+installation+guide+for+publishers) for details. +**Important**: Adagio needs to collect attention data about the ads displayed on a page and must listen to some specifics ad-server events. Please refer to the [Adagio user guide](https://adagioio.notion.site/Adagio-Account-Setup-Guide-fbcd940649224cdfa10393d2f008792e) for details. {: .table .table-bordered .table-striped } @@ -35,7 +36,6 @@ The Adagio bidder adaptor requires setup and approval from the Adagio team. Plea | `environment`* | recommended | Environment where the page is displayed.
    - max length: 30
    - max distinctives values: 10 | `'desktop'` | `string` | | `category`* | recommended | Category of the content displayed in the page.
    - max length: 30
    - max distinctives values: 50 | `'sport'` | `string` | | `subcategory`* | optional | Subcategory of the content displayed in the page.
    - max length: 30
    - max distinctives values: 50 | `'handball'` | `string` | -| `postBid` | optional | Used in Post-Bid context only. | `true` | `boolean` | | `video` | optional | OpenRTB 2.5 video options object.
    All options will override ones defined in mediaTypes.video | `{skip: 1, playbackmethod: [6]}` | `object` | | `native` | optional | Partial OpenRTB Native 1.2 request object. Supported fields are:
    - context
    -plcmttype | `{context: 1, plcmttype: 2}` | `object` | @@ -47,3 +47,7 @@ The Adagio bidder adaptor requires setup and approval from the Adagio team. Plea | Name | description | |--------------|-------------------------------------| | `adagio_bvw` | Url to handle Measure beacon | + +### First Party Data + +Adagio does not support FPD for now. It will be added soon. diff --git a/dev-docs/bidders/adbite.md b/dev-docs/bidders/adbite.md index fde3a6e8af..07b2aa749f 100644 --- a/dev-docs/bidders/adbite.md +++ b/dev-docs/bidders/adbite.md @@ -3,7 +3,7 @@ layout: bidder title: Adbite description: Adbite LLC pbjs: true -pbs: true +pbs: false biddercode: adbite media_types: banner, native, video gdpr_supported: true diff --git a/dev-docs/bidders/adblender.md b/dev-docs/bidders/adblender.md index 94830f05fe..6f3edddf6a 100644 --- a/dev-docs/bidders/adblender.md +++ b/dev-docs/bidders/adblender.md @@ -13,6 +13,7 @@ usp_supported: true ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|--------|----------|-------------|---------|----------| -| `zone` | required | | | `string` | +| Name | Scope | Description | Example | Type | +|---------------|----------|------------------------------------------------------------------------------------------------------------------|----------------------------------------|----------| +| `zone` | required | The unique identifier of the ad placement. Could be obtained from the AdBlender UI or from your account manager. | "e5ff8e48-4bd0-4a2c-9236-55530ab8981d" | `string` | +| `kvTargeting` | optional | Key/Value - a pair of the unique values that will be used for the custom targeting option. | {key1: value2, key2: value2} | `object` | diff --git a/dev-docs/bidders/adbutler.md b/dev-docs/bidders/adbutler.md index 2eab4bbadd..478bcc4db1 100644 --- a/dev-docs/bidders/adbutler.md +++ b/dev-docs/bidders/adbutler.md @@ -4,7 +4,8 @@ title: AdButler description: Prebid AdButler Bidder Adaptor pbjs: true biddercode: adbutler -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/adf.md b/dev-docs/bidders/adf.md index 34f70931ed..4695771cf6 100644 --- a/dev-docs/bidders/adf.md +++ b/dev-docs/bidders/adf.md @@ -4,26 +4,32 @@ title: AdformOpenRTB description: Prebid Adform Bidder Adaptor biddercode: adf media_types: banner, native, video +coppa_supported: true gdpr_supported: true usp_supported: true prebid_member: true pbjs: true pbs: true -userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, sharedId, unifiedId +schain_supported: true +userIds: all gvl_id: 50 prevBiddercode: adformOpenRTB +floors_supported: true +multiformat_supported: will-bid-on-one --- ### Bid params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------------|----------|----------------------|--------------------|-----------| -| `mid` | required | | `12345` | `integer` | -| `adxDomain` | optional | The Adform domain | `'adx.adform.net'` | `string` | -| `priceType` | optional | Price type | `'gross'` | `string` | +| Name | Scope | Description | Example | Type | +|-------------|----------------------------|----------------------|--------------------|-----------| +| `mid` | required, if `inv` and `nmane` not set | Placement ID | `12345` | `integer` | +| `inv` | required, if `mid` not set | Inventory source ID | `1234` | `integer` | +| `mname` | required, if `mid` not set | Placement name | `"Leaderboard"` | `string` | +| `adxDomain` | optional, Prebid.js only | The Adform domain | `"adx.adform.net"` | `string` | +| `priceType` | optional | Price type | `"gross"` | `string` | -Note: prebid-server adapter supports only `mid` parameter - other params could be set by adjusting prebid-server openRTB request. +Note: Bid placement should be defined using the `mid` parameter or `inv` and `mname` parameters (dynamic master tag) but not both. ### OpenRTB request config @@ -38,7 +44,3 @@ pbjs.setConfig({ } }); ``` - -### Multi-format ads - -Adform bid adapter does not support multi-format ad unit setup. Please use [twin ad unit codes]({{site.baseurl}}/dev-docs/adunit-reference.html#twin-adunit-codes) to enable multi-format auctions. diff --git a/dev-docs/bidders/adfinity.md b/dev-docs/bidders/adfinity.md index 4d80018fb9..ce9b16a758 100644 --- a/dev-docs/bidders/adfinity.md +++ b/dev-docs/bidders/adfinity.md @@ -6,7 +6,8 @@ pbjs: true biddercode: adfinity media_types: banner, video, native gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/adform.md b/dev-docs/bidders/adform.md index 1f796f0876..3676871ca8 100644 --- a/dev-docs/bidders/adform.md +++ b/dev-docs/bidders/adform.md @@ -9,9 +9,10 @@ usp_supported: true prebid_member: true pbjs: true pbs: true -userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, sharedId, unifiedId +userIds: all gvl_id: 50 -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- **Adform bid adapter is deprecated since Prebid 5.0. Please refer to [AdformOpenRTB adapter](#adf) documentation to fetch bids from Adform demand sources.** diff --git a/dev-docs/bidders/adgeneration.md b/dev-docs/bidders/adgeneration.md index 812cfbecd7..b7493c7257 100644 --- a/dev-docs/bidders/adgeneration.md +++ b/dev-docs/bidders/adgeneration.md @@ -5,8 +5,8 @@ description: Prebid Ad Generation Bidder Adaptor pbjs: true pbs: true biddercode: adgeneration +userIds: novatiq, criteo, id5Id media_types: native -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/adglare.md b/dev-docs/bidders/adglare.md index b938a28ca3..7e8f6db2d7 100644 --- a/dev-docs/bidders/adglare.md +++ b/dev-docs/bidders/adglare.md @@ -5,7 +5,8 @@ description: Prebid Adapter for AdGlare Ad Server pbjs: true biddercode: adglare media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/adhash.md b/dev-docs/bidders/adhash.md index 191bbec27c..f341d3e6de 100644 --- a/dev-docs/bidders/adhash.md +++ b/dev-docs/bidders/adhash.md @@ -5,7 +5,7 @@ description: Prebid AdHash Bidder Adapter pbjs: true biddercode: adhash safeframes_ok: false -pbjs_version_notes: not in 5.x +gdpr_supported: true --- ### Note @@ -27,4 +27,4 @@ Please note that a number of AdHash functionalities are not supported in the Pre | Name | Scope | Description | Example | Type | |---------------|----------|--------------|------------------------------------------------|----------| | `publisherId` | required | Publisher ID | `'0x1234567890123456789012345678901234567890'` | `string` | -| `platformURL` | required | Platform URL | `'https://adhash.org/p/struma/'` | `string` | +| `platformURL` | required | Platform URL | `'https://adhash.org/p/example/'` | `string` | diff --git a/dev-docs/bidders/adhese.md b/dev-docs/bidders/adhese.md index 07e592417d..d0bcaea03c 100644 --- a/dev-docs/bidders/adhese.md +++ b/dev-docs/bidders/adhese.md @@ -10,7 +10,6 @@ gdpr_supported: true userIds: id5Id gvl_id: 553 pbs_app_supported: true -pbjs_version_notes: not in 5.x --- ### Registration diff --git a/dev-docs/bidders/adlive.md b/dev-docs/bidders/adlive.md deleted file mode 100644 index d67f6791b0..0000000000 --- a/dev-docs/bidders/adlive.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: bidder -title: Adlive -description: adlive bid adapter -pbjs: true -biddercode: adlive -pbjs_version_notes: not in 5.x ---- - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|------------+----------+-------------------------------------------+----------------------------------------------|------| -| `hashes` | required | Array of hashes, provided by adlive | ['1e100887dd614b0909bf6c49ba7f69fdd1360437'] | Array of strings | diff --git a/dev-docs/bidders/adlivetech.md b/dev-docs/bidders/adlivetech.md new file mode 100644 index 0000000000..74398ac2e0 --- /dev/null +++ b/dev-docs/bidders/adlivetech.md @@ -0,0 +1,70 @@ +--- +layout: bidder +title: Adlivetech +description: Prebid Adlivetech Bidder Adapter +pbjs: true +biddercode: adlivetech +aliasCode: grid +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +floors_supported: true +userIds: all +tcf2_supported: true +coppa_supported: true +fpd_supported: true +--- + +### Table of Contents + +- [Bid Params](#adlivetech-bid-params) +- [Bidder Config](#adlivetech-bidder-config) +- [First Party Data](#adlivetech-first-party) + +     + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| +| `uid` | required | Represents the Adlivetech bidder system Ad Slot ID associated with the respective div id from the site page. | `1` | `integer` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | +| `bidFloor` | optional | Floor of the impression opportunity. If present in the request overrides XML info. | `0.8` | `float` | + + + +### Bidder Config + +You can allow writing in localStorage `pbjs.setBidderConfig` for the bidder `adlivetech` +``` +pbjs.setBidderConfig({ + bidders: ["adlivetech"], + config: { + localStorageWriteAllowed: true + } +}) +``` +If it will be "true" this allow Adlivetech Bid Adapter to write userId in first party localStorage + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.ext.device`: Non standard arbitrary user device +- `ortb2.user.keywords`: Standard IAB OpenRTB 2.5 user.keywords field. It will be included in ext.keywords.user.ortb2 +- `ortb2.site.keywords`: Standard IAB OpenRTB 2.5 site.keywords field. It will be included in ext.keywords.site.ortb2 +- `ortb2.site.cat[]`: Standard IAB OpenRTB 2.5 site.cat field. It will be sent as part of site.cat array +- `ortb2.site.pagecat[]`: Standard IAB OpenRTB 2.5 site.pagecat field. It will be sent as part of site.cat array +- `ortb2.site.content.genre`: Standard IAB OpenRTB 2.5 site.content.genre field + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` +- `ortb2.imp[].instl` diff --git a/dev-docs/bidders/adman.md b/dev-docs/bidders/adman.md index 821ed67f9d..b4b6b41ec9 100644 --- a/dev-docs/bidders/adman.md +++ b/dev-docs/bidders/adman.md @@ -7,8 +7,8 @@ pbs: true biddercode: adman gdpr_supported: true usp_supported: true -media_types: banner, video -pbjs_version_notes: not in 5.x +media_types: banner, video, native +userIds: uid2, lotamePanoramaId, idx --- ### Note: diff --git a/dev-docs/bidders/admaru.md b/dev-docs/bidders/admaru.md new file mode 100644 index 0000000000..b86621a700 --- /dev/null +++ b/dev-docs/bidders/admaru.md @@ -0,0 +1,43 @@ +--- +layout: bidder +title: Admaru +description: Admaru Bidder Adapter +pbjs: true +biddercode: admaru +media_types: banner +gdpr_supported: false +schain_supported: false +usp_supported: false +--- + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `pub_id` | required | Publisher id | `'ap4m2b6m8'` | `string` | +| `adspace_id` | required | Adspace id | `'a3j5n6b1'` | `string` | + +### Test Parameters +``` +var adUnits = [ + { + code: 'test-div', + mediaTypes: { + banner: { + sizes: [[300, 250]], // a display size + } + }, + bids: [ + { + bidder: "admaru", + params: { + pub_id: '1234', // string - required + adspace_id: '1234' // string - required + } + } + ] + } +]; +``` \ No newline at end of file diff --git a/dev-docs/bidders/admedia.md b/dev-docs/bidders/admedia.md index 2253e4eed2..d9530b2d31 100644 --- a/dev-docs/bidders/admedia.md +++ b/dev-docs/bidders/admedia.md @@ -6,7 +6,8 @@ pbjs: true biddercode: admedia media_types: banner gdpr_supported: false -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/admixer.md b/dev-docs/bidders/admixer.md index d2fa0061e5..42beb6e5a2 100644 --- a/dev-docs/bidders/admixer.md +++ b/dev-docs/bidders/admixer.md @@ -5,16 +5,19 @@ description: Prebid AdMixer Bidder Adaptor pbjs: true pbs: true biddercode: admixer -media_types: video +media_types: banner, video, native gdpr_supported: true usp_supported: true schain_supported: true gvl_id: 511 +userIds: AdmixerID +prebid_member: true --- ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|--------|----------|-------------|---------|----------| -| `zone` | required | | | `string` | +| Name | Scope | Description | Example | Type | +|---------------|----------|----------------------------------------------------------------------------------------------------------------|----------------------------------------|----------| +| `zone` | required | The unique identifier of the ad placement. Could be obtained from the Admixer UI or from your account manager. | "e5ff8e48-4bd0-4a2c-9236-55530ab8981d" | `string` | +| `kvTargeting` | optional | Key/Value - a pair of the unique values that will be used for the custom targeting option. | {key1: value2, key2: value2} | `object` | diff --git a/dev-docs/bidders/adnuntius.md b/dev-docs/bidders/adnuntius.md index cdb2766ccd..50a308ff3c 100644 --- a/dev-docs/bidders/adnuntius.md +++ b/dev-docs/bidders/adnuntius.md @@ -3,9 +3,12 @@ layout: bidder title: Adnuntius description: Prebid Adnuntius Bidder Adaptor pbjs: true +pbs: true biddercode: adnuntius -media_types: banner +media_types: banner, video gdpr_supported: true +fpd_supported: true +gvl_id: 855 --- ### Bid Params @@ -53,23 +56,96 @@ Here's an example of sending targeting information about categories to adnuntius There's an option to send segment id in the bidder config that will be picked up and sent to the ad server. Below is an example on how to do this: ``` +pbjs.setBidderConfig({ + bidders: ['adnuntius', 'bidderB'], + config: { + ortb2: { + user: { + data: [{ + name: "adnuntius", + segment: [ + { id: "1" }, + { id: "2" } + ] + }] + } + } + } +}); +``` + +### Disable cookies for adnuntius + +You have the option to tell adnuntius not to set cookies in your browser. This does not mean that third party ads being served through the ad server will not set cookies. Just that Adnuintius will not set it for internal ads. + +``` + +pbjs.setBidderConfig({ + bidders: ['adnuntius'], + config: { + useCookie: false + } +}); +``` + +Use cookie will always be set to true by default. Changing it to false will disable cookies. + +### Prebid Server Test Request + +The following test parameters can be used to verify that Prebid Server is working properly with the server-side Adnuntius adapter. the `auId` below will not return a creative. Please substitute it with your own. - pbjs.setBidderConfig({ - bidders: ['adnuntius', 'bidderB'], - config: { - ortb2: { - user: { - data: [{ - name: "adnuntius", - segment: [ - { id: "1" }, - { id: "2" } - ] - }] - } - } - } - }); - -´´´ ``` +"imp": [{ + "id": "impression-id", + "banner": { + "format": [{ + "w": 980, + "h": 240 + }, { + "w": 980, + "h": 360 + }] + }, + "ext": { + "adnuntius": { + "auId": "abc123" + } + } +}] +``` + +### First Party Data + +publishers can use the `ortb2` configuration parameter to provide First Party Data. We accept all standard OpenRTB fields for both: + +- `ortb2.site` +- `ortb2.user` + +These fields are optional and only needed for user identification and contextual targeting. How to use it can be read here: [Prebid ortb2](https://docs.prebid.org/features/firstPartyData.html). Currently we only support this for our prebid server bidder, but will add it to the client bidder in the future. + +### Video requests +Currently we only support client requests and instream context. An example request would look like this: + +``` +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream' + } + }, + bids: [{ + bidder: 'adnuntius', + params: { + auId: '00000000001cd429', //put your placement id here + + video: { + skippable: true, + playback_method: ['auto_play_sound_off'] + } + } + }] +}; +``` + diff --git a/dev-docs/bidders/adot.md b/dev-docs/bidders/adot.md index a7aa51a606..4f280a5c5f 100644 --- a/dev-docs/bidders/adot.md +++ b/dev-docs/bidders/adot.md @@ -4,10 +4,13 @@ title: Adot description: Prebid Adot Bidder Adapter biddercode: adot media_types: banner, video, native +userIds: pubProvidedId gdpr_supported: true gvl_id: 272 pbjs: true pbs: true +floors_supported: true +schain_supported: true --- ### Prebid JS @@ -18,20 +21,14 @@ pbs: true | Name | Scope | Description | Example | Type | |---------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| | `placementId` | optional | The placement ID from Adot. | `'adot_placement_224521'` | `string` | -| `position` | optional | Specify the position of the ad as a relative measure of visibility or prominence. Allowed values: Unknown: `0` (default); Above the fold: `1` ; Below the fold: `3`. | `0` | `integer-` | -| `video` | required if the adUnit is a video | Object containing video targeting parameters. See [Video Object](#adot-video-object) for details. | `video: { mimes: ['video/mp4'] }` | `object` | +| `video` | optional | Object containing video targeting parameters. See [Video Object](#adot-video-object) for details. | | `object` | #### Video Object {: .table .table-bordered .table-striped } | Name | Scope | Description | Type | |-------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| -| `mimes` | required | Array of strings listing the content MIME types supported, e.g., `['video/mp4']`. | `Array` | -| `minduration` | optional | Integer that defines the minimum video ad duration in seconds. | `integer` | -| `maxduration` | optional | Integer that defines the maximum video ad duration in seconds. | `integer` | -| `protocols` | required | Array of supported video protocols, e.g., `[2, 3]` | `Array` | | `container` | optional | Selector used for finding the element in which the video player will be displayed, e.g., `#div-1`. The `ad unit code` will be used if no `container` is provided. | `string` | -| `instreamContext` | required if `video.context` is `instream` | String used to define the type of instream video. Allowed values: Pre-roll: `pre-roll`; Mid-roll: `mid-roll` ; Post-roll: `post-roll`. | `string` | #### Bid Config #### PublisherId @@ -79,6 +76,7 @@ pbjs.setBidderConfig({ |---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| | `placementId` | optional | An ID which identifies this placement of the impression. | `'adot_placement_224521'` | `string` | | `parallax` | optional (only for prebid-server) | Specify if the wanted advertising's creative is a parallax. | `true/false` | `boolean` | +| `publisherPath` | optional | Specific to each integration. Do not use until asked by someone from adot. | `/hubvisor` | `string` | #### Testing Bid Request diff --git a/dev-docs/bidders/adpartner.md b/dev-docs/bidders/adpartner.md index caddd1ad55..ead43860ca 100644 --- a/dev-docs/bidders/adpartner.md +++ b/dev-docs/bidders/adpartner.md @@ -5,12 +5,11 @@ description: Prebid AdPartner Bidder Adaptor pbjs: true biddercode: adpartner media_types: banner -pbjs_version_notes: not in 5.x --- ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|----------|----------|-------------|----------------------|-----------| -| `unitId` | required | Unit ID. | `5809` | `integer` | +| Name | Scope | Description | Example | Type | +|-------------|----------|-------------|----------------------|-----------| +| `partnerId` | required | Partner ID. | `5809` | `integer` | diff --git a/dev-docs/bidders/adplus.md b/dev-docs/bidders/adplus.md new file mode 100644 index 0000000000..ea31c7621f --- /dev/null +++ b/dev-docs/bidders/adplus.md @@ -0,0 +1,19 @@ +--- +layout: bidder +title: AdPlus +description: Prebid AdPlus Bidder Adapter +biddercode: adplus +media_types: banner +pbjs: true +--- +### Note: + +The AdPlus Bidding adapter requires setup before beginning. Please contact us at . + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------|-------------------------------------------|-----------| +| `adUnitId` | required | Ad Unit ID | `'-3'` | `string` | +| `inventoryId` | required | Inventory ID | `'-1'` | `string` | \ No newline at end of file diff --git a/dev-docs/bidders/adpone.md b/dev-docs/bidders/adpone.md index 608b228ff1..c2da708ebd 100644 --- a/dev-docs/bidders/adpone.md +++ b/dev-docs/bidders/adpone.md @@ -5,7 +5,7 @@ description: Prebid Adpone Bidder Adaptor pbjs: true pbs: true biddercode: adpone -bidder_supports_deals: false +deals_supported: false media_types: banner gvl_id: 799 --- diff --git a/dev-docs/bidders/adprime.md b/dev-docs/bidders/adprime.md index 11bd34ba16..4452ddfc97 100644 --- a/dev-docs/bidders/adprime.md +++ b/dev-docs/bidders/adprime.md @@ -5,11 +5,11 @@ description: Prebid Adprime Bidder Adapter biddercode: adprime gdpr_supported: true usp_supported: true -media_types: banner, video +media_types: banner, video, native +tcf2_supported: true pbjs: true pbs: true pbs_app_supported: true -pbjs_version_notes: not in 5.x --- ### Note: @@ -23,4 +23,5 @@ The Adprime Bidding adapter requires setup before beginning. Please contact us a |---------------|----------|-----------------------|-----------|-----------| | `placementId` | required | Adprime placement id | `'1234asdf'` | `string` | | `keywords` | optional | page context keywords | ['car','sport'] | `array` | +| `audiences` | optional | publisher audiences | ['aud1','aud2'] | `array` | diff --git a/dev-docs/bidders/adquery.md b/dev-docs/bidders/adquery.md new file mode 100644 index 0000000000..fd1419c80c --- /dev/null +++ b/dev-docs/bidders/adquery.md @@ -0,0 +1,20 @@ +--- +layout: bidder +title: Adquery +description: Prebid Adquery Bidder Adaptor +pbjs: true +biddercode: adquery +gdpr_supported: true +usp_supported: true +schain_supported: true +gvl_id: 902 +userIds: adQuery QiD +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------|-------------------------------------------|-----------| +| `placementId` | required | Placement ID | `6d93f2a0e5f0fe2cc3a6e9e3ade964b43b07f897`| `string` | +| `type` | required | Ad Type | `banner300x250` | `string` | diff --git a/dev-docs/bidders/adrelevantis.md b/dev-docs/bidders/adrelevantis.md index 97ceab7c8a..734f6462f4 100644 --- a/dev-docs/bidders/adrelevantis.md +++ b/dev-docs/bidders/adrelevantis.md @@ -4,6 +4,7 @@ title: Adrelevantis description: Prebid Adrelevantis (adrelevantis.xyz) Bidder Adaptor biddercode: adrelevantis media_types: banner, video, native +fpd_supported: true pbjs: true --- @@ -26,9 +27,13 @@ pbjs.setBidderConfig({ bidders: ['adrelevantis'], config: { ortb2: { - context: { + site: { keywords: keywords, - category: categories + ext: { + data: { + category: categories + } + } } } } diff --git a/dev-docs/bidders/adrino.md b/dev-docs/bidders/adrino.md new file mode 100644 index 0000000000..864b2507c9 --- /dev/null +++ b/dev-docs/bidders/adrino.md @@ -0,0 +1,56 @@ +--- +layout: bidder +title: Adrino +description: Prebid Adrino Bidder Adapter +pbjs: true +pbs: false +biddercode: adrino +media_types: no-display, native +gdpr_supported: true +gvl_id: 1072 +--- + +### Note + +The Adrino bidder adapter requires setup and approval from the Adrino team. Please reach out to [wydawcy@adrino.pl](mailto:wydawcy@adrino.pl) for more information. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|--------|----------|--------------------------------------|------------------|----------| +| `hash` | required | Identifier for specific ad placement | `'abcdef123456'` | `string` | + +### Native example + +``` +var adUnits = [ + code: '/12345678/prebid_native_example_1', + mediaTypes: { + native: { + image: { + required: true, + sizes: [[300, 210],[300,150],[140,100]] + }, + title: { + required: true + }, + sponsoredBy: { + required: false + }, + body: { + required: false + }, + icon: { + required: false + } + } + }, + bids: [{ + bidder: 'adrino', + params: { + hash: 'abcdef123456' + } + }] +]; +``` diff --git a/dev-docs/bidders/adriver.md b/dev-docs/bidders/adriver.md index 3461aceb2c..3d5907c9fb 100644 --- a/dev-docs/bidders/adriver.md +++ b/dev-docs/bidders/adriver.md @@ -4,9 +4,9 @@ title: adriver description: Adriver adapter biddercode: adriver pbjs: true -bidder_supports_deals: true -userIds: sharedId, id5Id, uid2Id -getFloor: true +deals_supported: true +userIds: sharedId, id5Id, uid2Id, adriverId +floors_supported: true --- diff --git a/dev-docs/bidders/adsolut.md b/dev-docs/bidders/adsolut.md index 95fc34dd89..96b36dd835 100644 --- a/dev-docs/bidders/adsolut.md +++ b/dev-docs/bidders/adsolut.md @@ -3,6 +3,9 @@ layout: bidder title: adsolut description: Prebid adsolut Bidder Adaptor pbjs: true +media_types: banner, native, video +gdpr_supported: true +usp_supported: true biddercode: adsolut aliasCode: adkernel --- diff --git a/dev-docs/bidders/adspend.md b/dev-docs/bidders/adspend.md index b238b57606..bc836ffd91 100644 --- a/dev-docs/bidders/adspend.md +++ b/dev-docs/bidders/adspend.md @@ -6,7 +6,8 @@ pbjs: true biddercode: adspend media_types: banner gdpr_supported: false -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/adsyield.md b/dev-docs/bidders/adsyield.md new file mode 100644 index 0000000000..f8e7b1b758 --- /dev/null +++ b/dev-docs/bidders/adsyield.md @@ -0,0 +1,18 @@ +--- +layout: bidder +title: AdsYield +description: Prebid AdsYield Bidder Adaptor +pbjs: true +biddercode: adsyield +aliasCode: admixer +media_types: video +gdpr_supported: true +usp_supported: true +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|------------------------------------------------------------------------------------------------------------------|----------------------------------------|----------| +| `zone` | required | The unique identifier of the ad placement. Could be obtained from the AdsYield UI or from your account manager. | "e5ff8e48-4bd0-4a2c-9236-55530ab8981d" | `string` | diff --git a/dev-docs/bidders/adtargetme.md b/dev-docs/bidders/adtargetme.md new file mode 100644 index 0000000000..3073dbd201 --- /dev/null +++ b/dev-docs/bidders/adtargetme.md @@ -0,0 +1,25 @@ +--- +layout: bidder +title: Adtargetme +description: Prebid Adtargetme Bidder Adapter +biddercode: adtargetme +gdpr_supported: false +usp_supported: false +coppa_supported: false +schain_supported: false +dchain_supported: false +media_types: banner +safeframes_ok: true +deals_supported: false +floors_supported: false +fpd_supported: true +pbjs: true +pbs: true +pbs_app_supported: true +prebid_member: false +multiformat_supported: will-bid-on-one +--- + +### Note: + +The Adtargetme Bidding adapter requires setup before beginning. Please contact us at info@adtarget.me diff --git a/dev-docs/bidders/aduptech.md b/dev-docs/bidders/aduptech.md index 2e1a092b21..9189dab0a3 100644 --- a/dev-docs/bidders/aduptech.md +++ b/dev-docs/bidders/aduptech.md @@ -4,6 +4,7 @@ title: AdUp Technology description: Prebid Bidder Adapter for AdUp Technology biddercode: aduptech gdpr_supported: true +floors_supported: true gvl_id: 647 media_types: banner, native pbjs: true diff --git a/dev-docs/bidders/advangelists.md b/dev-docs/bidders/advangelists.md index 0d5f47a56d..79fdaca310 100644 --- a/dev-docs/bidders/advangelists.md +++ b/dev-docs/bidders/advangelists.md @@ -5,7 +5,6 @@ description: Prebid Advangelists Bidder Adapter pbjs: true pbs: true biddercode: advangelists -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/advenue.md b/dev-docs/bidders/advenue.md index f2760d45b9..7e4559328c 100644 --- a/dev-docs/bidders/advenue.md +++ b/dev-docs/bidders/advenue.md @@ -4,7 +4,8 @@ title: Advenue description: Prebid Advenue Bidder Adaptor pbjs: true biddercode: advenue -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/advertly.md b/dev-docs/bidders/advertly.md index 2b3fc7d339..016a67b285 100644 --- a/dev-docs/bidders/advertly.md +++ b/dev-docs/bidders/advertly.md @@ -4,7 +4,8 @@ title: advertly description: Prebid ADVERTLY Bidder Adapter pbjs: true biddercode: advertly -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/adview.md b/dev-docs/bidders/adview.md new file mode 100644 index 0000000000..a69b21ce4b --- /dev/null +++ b/dev-docs/bidders/adview.md @@ -0,0 +1,34 @@ +--- +layout: bidder +title: AdView +description: Prebid AdView Bidder Adapter +biddercode: AdView +gdpr_supported: true +gvl_id: 1022 +usp_supported: true +coppa_supported: true +schain_supported: true +dchain_supported: false +userId: +media_types: banner, video, native +safeframes_ok: true +bidder_supports_deals: true +pbjs: false +pbs: true +pbs_app_supported: true +prebid_member: false +--- + +### Note: + +Currently adapter doesn’t support multi impression and can not perform impression splitting, so only the first impression will be delivered. + +The Example Bidding adapter requires setup before beginning. Please contact us at partner@adview.com + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|-----------|----------| +| `placementId` | required | Placement ID | `'posid00001'` | `string` | +| `accountId` | required | Account ID | `'accountid01'` | `string` | \ No newline at end of file diff --git a/dev-docs/bidders/adxcg.md b/dev-docs/bidders/adxcg.md index 9f85e7170e..f7803f0ac5 100644 --- a/dev-docs/bidders/adxcg.md +++ b/dev-docs/bidders/adxcg.md @@ -2,7 +2,7 @@ layout: bidder title: adxcg description: Prebid adxcg bidder adaptor -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/adyoulike.md b/dev-docs/bidders/adyoulike.md index cdfc18ccca..05b2f78297 100644 --- a/dev-docs/bidders/adyoulike.md +++ b/dev-docs/bidders/adyoulike.md @@ -6,19 +6,23 @@ pbjs: true pbs: true media_types: banner, video, native biddercode: adyoulike +userIds: criteo, sharedId gdpr_supported: true +gvl_id: 259 usp_supported: true +floors_supported: true +schain_supported: true --- ### Note: + The Adyoulike Header Bidding adaptor requires setup and approval from the Adyoulike team. Please reach out to your account manager or prebid@adyoulike.com for more information. ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |-------------|----------|----------------------------------|--------------------------------------|----------| | `placement` | required | The placement ID from Adyoulike. | `'194f787b85c829fb8822cdaf1ae64435'` | `string` | - Same 'placement' parameter can be used from either prebid JS or prebid server. diff --git a/dev-docs/bidders/afp.md b/dev-docs/bidders/afp.md new file mode 100644 index 0000000000..07e3d197ea --- /dev/null +++ b/dev-docs/bidders/afp.md @@ -0,0 +1,201 @@ +--- +layout: bidder +title: AFP +description: Prebid AFP Bidder Adapter +pbjs: true +media_types: banner, video +biddercode: afp +safeframes_ok: false +--- + +### Note + +You can use this adapter to get a bid from AFP. +Please reach out to your AFP account team before using this plugin to get placeId. +The code below returns a demo ad. + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------------|---------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| +| `placeId` | required | Place id. | '5af45ad34d506ee7acad0c26' | `string` | +| `placeType` | required | Place type. | 'In-image', 'In-image Max', 'In-content Banner', 'In-content Video', 'Out-content Video', 'In-content Stories', 'Action Scroller', 'Action Scroller Light', 'Just Banner' | `string` | +| `placeContainer` | required (if the frame is not safe) | The container of the place where the ad will be displayed. The css selector is specified as the value. | '#container' | `string` | +| `imageUrl` | required (for 'In-image', 'In-image Max' placeType) | URL of the image on which the banner will be displayed. | 'https://creative.astraone.io/files/default_image-1-600x400.jpg' | `string` | +| `imageWidth` | required (for 'In-image', 'In-image Max' placeType) | Image width. | 600 | `integer` | +| `imageHeight` | required (for 'In-image', 'In-image Max' placeType) | Image height. | 400 | `integer` | + + +### InImage Example page + + +```html + + + + + Prebid.js In-image Example + + + + +

    In-image

    +
    +
    + +
    + +
    + +

    Just Banner

    +
    +
    + +
    + + +``` +### InImage Example page with GPT + +```html + + + + + Prebid.js In-image Example + + + + + +

    In-image

    +
    +
    + +
    +
    + +
    +
    + + +``` diff --git a/dev-docs/bidders/aja.md b/dev-docs/bidders/aja.md index 334ece6150..11233433ec 100644 --- a/dev-docs/bidders/aja.md +++ b/dev-docs/bidders/aja.md @@ -2,23 +2,23 @@ layout: bidder title: AJA description: Prebid AJA Bidder Adaptor +userIds: criteo, unifiedId, imuid pbjs: true pbs: true biddercode: aja media_types: video, native -pbjs_version_notes: not in 5.x --- -### Note: +### Note The AJA Bidding adaptor requires setup and approval before beginning. Please reach out to for more details ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |-------|----------|---------------------|------------|----------| -| `asi` | required | ad spot hash code | `'123abc'` | `string` | +| `asi` | required | ad spot hash code | `'123abc'` | `string` | ### Configuration @@ -31,11 +31,11 @@ pbjs.setConfig({ userSync: { filterSettings: { iframe: { - bidders: '*', // '*' represents all bidders - filter: 'include' - } - } - } + bidders: "*", // '*' represents all bidders + filter: "include", + }, + }, + }, }); ``` @@ -45,8 +45,7 @@ For Prebid.js v1.14.0 and before: pbjs.setConfig({ userSync: { iframeEnabled: true, - enabledBidders: ['aja'] - } + enabledBidders: ["aja"], + }, }); ``` - diff --git a/dev-docs/bidders/algorix.md b/dev-docs/bidders/algorix.md index d6b6c0a363..1ac9335c56 100644 --- a/dev-docs/bidders/algorix.md +++ b/dev-docs/bidders/algorix.md @@ -5,17 +5,19 @@ description: Prebid AlgoriX Bidder Adapter biddercode: algorix gdpr_supported: false gvl_id: -usp_supported: false -coppa_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true media_types: banner, video, native pbjs: false pbs: true pbs_app_supported: true +prebid_member: true --- ### Note: -Algorix adapter requires setup and approval from the Algorix team, even for existing in-app developers and publishers. Please reach out to your account team or email to prebid@algorix.co for more information. +AlgoriX adapter requires setup and approval from the AlgoriX team, even for existing in-app developers and publishers. Please reach out to your account team or email to prebid@algorix.co for more information. ### Bid Params @@ -24,5 +26,11 @@ Algorix adapter requires setup and approval from the Algorix team, even for exis |---------------|----------|---------------|--------------------------------------|----------| | `sid` | required | Sid | `'30014'` | `string` | | `token` | required | Token | `'028bca2d3b5c4f0ba155fa34864b0c4d'` | `string` | +| `placementId` | optional | Placement Id | `'123456'` | `string` | +| `appId` | optional | App Id | `'asdasdasd'` | `string` | +| `region` | optional | Server Region | `'APAC' or 'USE'` | `string` | -Note: Prebid Server adapter only checks for and uses first imp bid params. All other imp bid params are ignored. +Note: +* Prebid Server adapter only checks for and uses first imp bid params. All other imp bid params are ignored. +* placementId and appId will be generated on AlgoriX Platform. +* region is optional param, which determine the AlgoriX server. APAC for SG endpoint, USE for US endpoint, Other for Global endpoint. diff --git a/dev-docs/bidders/alkimi.md b/dev-docs/bidders/alkimi.md new file mode 100644 index 0000000000..c3122166b0 --- /dev/null +++ b/dev-docs/bidders/alkimi.md @@ -0,0 +1,27 @@ +--- +layout: bidder +title: Alkimi +description: Prebid Alkimi Bidder Adapter +biddercode: alkimi +media_types: banner, video +pbjs: true +pbs: true +schain_supported: true +gdpr_supported: true +usp_supported: true +coppa_supported: true +userIds: all +floors_supported: true +multiformat_supported: will-bid-on-any +--- + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|-----------| +| `token` | required | The ID issued by Alkimi to the publisher | `'8a80d8e9-0cf9-4329-8486-6f5bbcd8a61a'` | `string` | +| `bidFloor` | required | Minimum bid for this impression expressed in CPM. | `0` | `float` | +| `pos` | optional | Specify the position of the ad as a relative measure of visibility or prominence. Allowed values: Above the fold: `1`; Below the fold: `3`; Middle of the fold: `7`; | `0` | `integer` | diff --git a/dev-docs/bidders/amx.md b/dev-docs/bidders/amx.md index bddf72a938..f03447d1fe 100644 --- a/dev-docs/bidders/amx.md +++ b/dev-docs/bidders/amx.md @@ -10,10 +10,11 @@ coppa_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId, amxId biddercode: amx safeframes_ok: true -media_types: banner, video +media_types: banner, video, native pbjs: true pbs: true pbs_app_supported: true +fpd_supported: true gvl_id: 737 --- @@ -22,8 +23,8 @@ gvl_id: 737 {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-------------|----------|-----------------------------------------------------------------|---------------------------------|----------| +| `tagId` | required | Tag ID | `'cHJlYmlkLm9yZw'` | `string` | | `testMode` | optional | Activate 100% fill ads | `true` | `boolean`| -| `tagId` | optional | Tag ID | `'cHJlYmlkLm9yZw'` | `string` | | `adUnitId` | optional | Ad Unit ID used in reporting. Will default to `bid.adUnitCode` | `'sticky_banner'` | `string` | ### Test Parameters @@ -37,4 +38,40 @@ To enable 100% fill test ads, you can use the following `params`: } ``` -Note that the `tagId` is case-sensitive. This will produce a bid at $10 with a test creative. +This will produce a bid at $10 with a test creative. + +Note that the `tagId` is case-sensitive. Do not use `cHJlYmlkLm9yZw` in production environments: this ID is for testing only. + +### First Party Data + +From Prebid.js >= 4.30, publishers can use the `ortb2` configuration parameter to provide First Party Data. We accept all standard OpenRTB fields for both: + +- `ortb2.site` +- `ortb2.user` + +Note that all fields are optional. For contextual data (e.g. categories), standard IAB taxonomies are supported. We do not support passing first party data via bid parameters. + +#### Example - Setting ortb2.site and ortb2.user fields + +```javascript +pbjs.setBidderConfig({ + bidders: ["amx"], + config: { + ortb2: { + site: { + keywords: "kw1,kw2", + cat: ["IAB2"], + sectioncat: ["IAB2-1"], + pagecat: ["IAB2-22"], + content: { + context: 5 + } + }, + user: { + yob: 1981, + keywords: "kw3", + } + } + } +}) +``` diff --git a/dev-docs/bidders/aniview.md b/dev-docs/bidders/aniview.md index 4ae7c6ce14..a51cc6f840 100644 --- a/dev-docs/bidders/aniview.md +++ b/dev-docs/bidders/aniview.md @@ -1,16 +1,19 @@ --- layout: bidder title: ANIVIEW -description: Prebid ANIVIEW Bidder Adaptor +description: Prebid ANIVIEW Bidder Adapter pbjs: true biddercode: aniview -media_types: video +media_types: banner, video gdpr_supported: true usp_supported: true +schain_supported: true +safeframes_ok: true +gvl_id: 780 --- ### Note: -For more information about [Aniview Ad Server](http://www.aniview.com/), please contact info@aniview.com. +For more information about [Aniview Ad Server](https://www.aniview.com/), please contact info@aniview.com. ### Bid Params @@ -19,3 +22,24 @@ For more information about [Aniview Ad Server](http://www.aniview.com/), please |------------------|----------|------------------|------------------------------|----------| | `AV_PUBLISHERID` | required | Publisher/Netid | `'55b88d4a181f465b3e8b4567'` | `string` | | `AV_CHANNELID` | required | Channel id | `'5a5f17a728a06102d14c2718'` | `string` | + +### Test Parameters +``` +videoAdUnit = [ +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'outstream' + }, + }, + bids: [{ + bidder: 'aniview', + params: { + AV_PUBLISHERID: '55b78633181f4603178b4568', + AV_CHANNELID: '5d19dfca4b6236688c0a2fc4' + } + }] +}]; +``` diff --git a/dev-docs/bidders/aol.md b/dev-docs/bidders/aol.md index a7b454b426..6e162546aa 100644 --- a/dev-docs/bidders/aol.md +++ b/dev-docs/bidders/aol.md @@ -7,9 +7,22 @@ biddercode: aol gdpr_supported: true usp_supported: true gvl_id: 25 -userIds: verizonMediaId +userIds: connectId --- +### IMPORTANT NOTICE! +**TL;DR** +1. The `aol` adapter is scheduled to be depreciated. +2. Our New `yahoossp` is available for early adoption. +3. Please contact your Account Manager/Executive for migration details. + +Dear Publishers & Partners, +As part of our platform consolidation process to simplify your integrations moving forward +We invite you to switch from the `oneVideo` Adapter to our NEW `yahoossp` bid adapter for both Display & Video inventory. +FYI - The oneVideo adapter is scheduled for depreciation in the upcoming months. + +Thanks in advance, +Yahoo SSP ### Note: This adapter allows use of both ONE by AOL: Display and ONE by AOL: Mobile platforms. In order to differentiate these sources of demand in your ad server and reporting, you may use the optional `onedisplay` and `onemobile` adapter aliases instead. diff --git a/dev-docs/bidders/apacdex.md b/dev-docs/bidders/apacdex.md index 3257909e1a..9a29acd80c 100644 --- a/dev-docs/bidders/apacdex.md +++ b/dev-docs/bidders/apacdex.md @@ -9,7 +9,9 @@ gdpr_supported: true schain_supported: true usp_supported: true userIds: all -getFloor: true +floors_supported: true +pbs: true +pbs_app_supported: true --- ### Table of Contents @@ -26,12 +28,14 @@ getFloor: true ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|--------------|----------|-------------------------------------------------------------------------------------|---------------------------------------------------|----------| -| `siteId` | required | Publisher site ID from Apacdex | `'apacdex1234'` | `string` | -| `floorPrice` | optional | CPM bidfloor in USD | `0.03` | `float` | -| `geo` | optional | GEO data of device. See [Geo Object](#apacdex-geo-object) for details. | `{"lat":17.98928,"lon":99.7741712,"accuracy":20}` | `object` | +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------------------------------------------------------------------------------|---------------------------------------------------|----------| +| `placementId`*| required | Placement ID provided by Apacdex | `'plc100000'` | `string` | +| `siteId`* | required | Publisher site ID from Apacdex | `'apacdex1234'` | `string` | +| `floorPrice` | optional | CPM bidfloor in USD | `0.03` | `float` | +| `geo` | optional | GEO data of device. See [Geo Object](#apacdex-geo-object) for details. | `{"lat":17.98928,"lon":99.7741712,"accuracy":20}` | `object` | +(*) Please do not use `placementId` and `siteId` at the same time.     @@ -59,9 +63,9 @@ Publishers declare video inventory by passing the following parameters via media |----------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------| | `context` | required | instream or outstream |`"outstream"` | `string` | | `playerSize`| required | width, height of the player in pixels | `[640,360]` - will be translated to w and h in bid request | `array` | -| `mimes` | required | List of content MIME types supported by the player (see openRTB v2.5 for options) | `["video/mp4"]`| `array`| -| `protocols` | required | Supported video bid response protocol values
    1: VAST 1.0
    2: VAST 2.0
    3: VAST 3.0
    4: VAST 1.0 Wrapper
    5: VAST 2.0 Wrapper
    6: VAST 3.0 Wrapper
    7: VAST 4.0
    8: VAST 4.0 Wrapper | `[2,3,5,6]` | `array`| -| `api` | required | Supported API framework values:
    1: VPAID 1.0
    2: VPAID 2.0
    3: MRAID-1
    4: ORMMA
    5: MRAID-2 | `[2]` | `array` | +| `mimes` | recommended | List of content MIME types supported by the player (see openRTB v2.5 for options) | `["video/mp4"]`| `array`| +| `protocols` | recommended | Supported video bid response protocol values
    1: VAST 1.0
    2: VAST 2.0
    3: VAST 3.0
    4: VAST 1.0 Wrapper
    5: VAST 2.0 Wrapper
    6: VAST 3.0 Wrapper
    7: VAST 4.0
    8: VAST 4.0 Wrapper | `[2,3,5,6]` | `array`| +| `api` | recommended | Supported API framework values:
    1: VPAID 1.0
    2: VPAID 2.0
    3: MRAID-1
    4: ORMMA
    5: MRAID-2 | `[2]` | `array` | | `maxduration` | recommended | Maximum video ad duration in seconds. | `30` | `integer` | | `minduration` | recommended | Minimum video ad duration in seconds | `6` | `integer` | | `playbackmethod` | recommended | Playback methods that may be in use. Only one method is typically used in practice. (see openRTB v2.5 section 5.10 for options)| `[2]`| `array` | @@ -170,4 +174,4 @@ var outstreamAdUnit = { }; ``` mediaTypes.video object reference to section 3.2.7 Object: Video in the OpenRTB 2.5 document -You must review all video parameters to ensure validity for your player and DSPs \ No newline at end of file +You must review all video parameters to ensure validity for your player and DSPs diff --git a/dev-docs/bidders/appnexus.md b/dev-docs/bidders/appnexus.md index c29e3e4f30..9872ea41f0 100644 --- a/dev-docs/bidders/appnexus.md +++ b/dev-docs/bidders/appnexus.md @@ -6,16 +6,21 @@ biddercode: appnexus media_types: banner, video, native gdpr_supported: true prebid_member: true -userIds: criteo, unifiedId, netId, identityLink, flocId, uid2 +userIds: criteo, flocId, identityLink, netId, pubProvidedId, uid2, unifiedId, schain_supported: true coppa_supported: true usp_supported: true -getFloor: true +floors_supported: true +fpd_supported: true pbjs: true pbs: true gvl_id: 32 --- +### Disclosure: + +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. + ### Table of Contents - [Bid Params](#appnexus-bid-params) @@ -23,7 +28,9 @@ gvl_id: 32 - [User Object](#appnexus-user-object) - [App Object](#appnexus-app-object) - [Custom Targeting keys](#custom-targeting-keys) +- [Auction Level Keywords](#appnexus-auction-keywords) - [Passing Keys Without Values](#appnexus-no-value) +- [First Party Data](#appnexus-fpd) - [User Sync in AMP](#appnexus-amp) - [Debug Auction](#appnexus-debug-auction) @@ -38,26 +45,26 @@ All AppNexus (Xandr) placements included in a single call to `requestBids` must {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| -| `placementId` | required | The placement ID from AppNexus. You may identify a placement using the `invCode` and `member` instead of a placement ID. The `placementID` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. Legacy code can retain the `string` value. **Prebid Server requires an integer value.** | `234234` | `integer` | -| `member` | optional | The member ID from AppNexus. Must be used with `invCode`. | `'12345'` | `string` | -| `invCode` | optional | The inventory code from AppNexus. Must be used with `member`. | `'abc123'` | `string` | -| `publisherId` | optional | The publisher ID from AppNexus. It is used by the AppNexus end point to identify the publisher when `placementId` is not provided and `invCode` goes wrong. The `publisherId` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. | `12345` | `integer` | -| `frameworks` | optional | Array of integers listing API frameworks for Banner supported by the publisher. | `integer` | -| `user` | optional | Object that specifies information about an external user. See [User Object](#appnexus-user-object) for details. | `user: { age: 25, gender: 0, dnt: true}` | `object` | -| `allowSmallerSizes` | optional | If `true`, ads smaller than the values in your ad unit's `sizes` array will be allowed to serve. Defaults to `false`. | `true` | `boolean` | -| `usePaymentRule` (PBJS) or `use_pmt_rule` (PBS) | optional | If `true`, Appnexus will return net price to Prebid.js after publisher payment rules have been applied. | `true` | `boolean` | -| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Mapped to [buy-side segment targeting](https://monetize.xandr.com/docs/segment-targeting) (login required). Values can be empty. See [Passing Keys Without Values](#appnexus-no-value) below for examples. Note that to use keyword with the Prebid Server adapter, that feature must be enabled for your account by an AppNexus account manager. | `keywords: { genre: ['rock', 'pop'] }` | `object` | -| `video` | optional | Object containing video targeting parameters. See [Video Object](#appnexus-video-object) for details. | `video: { playback_method: ['auto_play_sound_off'] }` | `object` | -| `app` | optional | Object containing mobile app parameters. See the [App Object](#appnexus-app-object) for details. | `app : { id: 'app-id'}` | `object` | -| `reserve` | optional | Sets a floor price for the bid that is returned. If floors have been configured in the AppNexus Console, those settings will override what is configured here. | `0.90` | `float` | -| `position` | optional | Identify the placement as above or below the fold. Allowed values: Unknown: `unknown`; Above the fold: `above`; Below the fold: `below` | `'above'` | `string` | -| `trafficSourceCode` | optional | Specifies the third-party source of this impression. | `'my_traffic_source'` | `string` | -| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | -| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | -| `pubClick` | optional | Specifies a publisher-supplied URL for third-party click tracking. This is just a placeholder into which the publisher can insert their own click tracker. This parameter should be used for an unencoded tracker. This parameter is expected to be the last parameter in the URL. Please note that the click tracker placed in this parameter will only fire if the creative winning the auction is using AppNexus click tracking properly. | `'http://click.adserver.com/'` | `string` | -| `extInvCode` | optional | Specifies predefined value passed on the query string that can be used in reporting. The value must be entered into the system before it is logged. | `'10039'` | `string` | -| `externalImpId` | optional | Specifies the unique identifier of an externally generated auction. | `'bacbab02626452b097f6030b3c89ac05'` | `string` | -| `generate_ad_pod_id`| optional | Signal to AppNexus to split impressions by ad pod and add unique ad pod id to each request. Specific to long form video endpoint only. Supported by Prebid Server, not Prebid JS. | `true` | `boolean` | +| `placement_id` (PBS) or `placementId` (PBJS) | required | The placement ID from AppNexus. You may identify a placement using the `invCode` and `member` instead of a placement ID. This parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. Legacy code can retain the `string` value. **Prebid Server requires an integer value.** | `234234` | `integer` | +| `member` | optional | The member ID from AppNexus. Must be used with `invCode`. | `'12345'` | `string` | +| `invCode` | optional | The inventory code from AppNexus. Must be used with `member`. | `'abc123'` | `string` | +| `publisherId` | optional | The publisher ID from AppNexus. It is used by the AppNexus end point to identify the publisher when placement id is not provided and `invCode` goes wrong. The `publisherId` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. | `12345` | `integer` | +| `frameworks` | optional | Array of integers listing API frameworks for Banner supported by the publisher. | `integer` | +| `user` | optional | Object that specifies information about an external user. See [User Object](#appnexus-user-object) for details. | `user: { age: 25, gender: 0, dnt: true}` | `object` | +| `allowSmallerSizes` | optional | If `true`, ads smaller than the values in your ad unit's `sizes` array will be allowed to serve. Defaults to `false`. | `true` | `boolean` | +| `usePaymentRule` (PBJS) or `use_pmt_rule` (PBS) | optional | If `true`, Appnexus will return net price to Prebid.js after publisher payment rules have been applied. | `true` | `boolean` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Mapped to [buy-side segment targeting](https://monetize.xandr.com/docs/segment-targeting) (login required). A maximum of 100 key/value pairs can be defined at the page level. Each tag can have up to 100 additional key/value pairs defined. Values can be empty. See [Passing Keys Without Values](#appnexus-no-value) below for examples. If you want to pass keywords for all adUnits, see [Auction Level Keywords](#appnexus-auction-keywords) for an example. Note that to use keyword with the Prebid Server adapter, that feature must be enabled for your account by an AppNexus account manager. | `keywords: { genre: ['rock', 'pop'] }` | `object` | +| `video` | optional | Object containing video targeting parameters. See [Video Object](#appnexus-video-object) for details. | `video: { playback_method: ['auto_play_sound_off'] }` | `object` | +| `app` | optional | Object containing mobile app parameters. See the [App Object](#appnexus-app-object) for details. | `app : { id: 'app-id'}` | `object` | +| `reserve` | optional | Sets a floor price for the bid that is returned. If floors have been configured in the AppNexus Console, those settings will override what is configured here unless 'Reserve Price Override' is checked. See [Xandr docs](https://docs.xandr.com/bundle/monetize_monetize-standard/page/topics/create-a-floor-rule.html) | `0.90` | `float` | +| `position` | optional | Identify the placement as above or below the fold. Allowed values: Unknown: `unknown`; Above the fold: `above`; Below the fold: `below` | `'above'` | `string` | +| `trafficSourceCode` | optional | Specifies the third-party source of this impression. | `'my_traffic_source'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `pubClick` | optional | Specifies a publisher-supplied URL for third-party click tracking. This is just a placeholder into which the publisher can insert their own click tracker. This parameter should be used for an unencoded tracker. This parameter is expected to be the last parameter in the URL. Please note that the click tracker placed in this parameter will only fire if the creative winning the auction is using AppNexus click tracking properly. | `'http://click.adserver.com/'` | `string` | +| `extInvCode` | optional | Specifies predefined value passed on the query string that can be used in reporting. The value must be entered into the system before it is logged. | `'10039'` | `string` | +| `externalImpId` | optional | Specifies the unique identifier of an externally generated auction. | `'bacbab02626452b097f6030b3c89ac05'` | `string` | +| `generate_ad_pod_id` | optional | Signal to AppNexus to split impressions by ad pod and add unique ad pod id to each request. Specific to long form video endpoint only. Supported by Prebid Server, not Prebid JS. | `true` | `boolean` |     @@ -135,6 +142,24 @@ pbjs.bidderSettings = { } ``` + + +#### Auction Level Keywords + +It's possible to pass a set of keywords for the whole request, rather than a particular adUnit. Though they would apply to all adUnits (which include the appnexus bidder) in an auction, these keywords can work together with the bidder level keywords (if for example you want to have specific targeting for a particular adUnit). + +Below is an example of how to define these auction level keywords for the appnexus bidder: +``` +pbjs.setConfig({ + appnexusAuctionKeywords: { + genre: ['classical', 'jazz'], + instrument: 'piano' + } +}); +``` + +Like in the bidder.params.keywords, the values here can be empty. Please see the section immediately below for more details. + #### Passing Keys Without Values @@ -160,6 +185,17 @@ keywords: { } ``` + + +#### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +At this time however, the `appnexus` bidder only reads the First Party Data when using the Prebid Server and Prebid Server Premium endpoints. The client-side version of the `appnexus` bidder does not use the values from the First Party Data fields. + +PBS/PSP supports all first party data fields: site, user, segments, and imp-level first party data. + + #### User Sync in AMP @@ -218,7 +254,7 @@ that would match with the test creative. }, "ext": { "appnexus": { - "placementId": 13144370 + "placement_id": 13144370 } } }] diff --git a/dev-docs/bidders/aseal.md b/dev-docs/bidders/aseal.md new file mode 100644 index 0000000000..604623a724 --- /dev/null +++ b/dev-docs/bidders/aseal.md @@ -0,0 +1,53 @@ +--- +layout: bidder +title: Aseal +description: Prebid Aseal Bidder Adapter +pbjs: true +biddercode: aseal +media_types: banner +--- + +### BidParams + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-----------------|----------|---------------------------------|------------------------------------------|--------------------| +| `placeUid` | required | The Place UID from Aotter | `'f4a74f73-9a74-4a87-91c9-545c6316c23d'` | `string` | + +# Configuration + +Following configuration is required: + +```js +pbjs.setConfig({ + aseal: { + clientId: "YOUR_CLIENT_ID" + } +}); +``` + +# Ad Unit Example + +```js +var adUnits = [ + { + code: "banner-div", + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [300, 600] + ] + } + }, + bids: [ + { + bidder: "aseal", + params: { + placeUid: "f4a74f73-9a74-4a87-91c9-545c6316c23d" + } + } + ] + } +]; +``` diff --git a/dev-docs/bidders/aso.md b/dev-docs/bidders/aso.md new file mode 100644 index 0000000000..8e4fae6934 --- /dev/null +++ b/dev-docs/bidders/aso.md @@ -0,0 +1,58 @@ +--- +layout: bidder +title: Adserver.Online +description: Prebid Adserver.Online Bidder Adapter +biddercode: aso +gdpr_supported: true +usp_supported: true +media_types: video +safeframes_ok: true +deals_supported: false +pbjs: true +pbs: false +floors_supported: true +--- +### Note: + +For more information about [Adserver.Online](https://adserver.online), please contact support@adsrv.org. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `zone` | required | Zone ID | `73815` | `integer` | + +### Test Parameters + +```js + var adUnit = { + code: 'unit1', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + bids: [ + { + bidder: 'aso', + params: { + zone: 73815, + } + } + ] +} +``` + +#### Video Caching + +Note that the Adserver.Online adapter expects a client-side Prebid Cache to be enabled for video bidding. + +```js +pbjs.setConfig({ + usePrebidCache: true, + cache: { + url: 'https://prebid.adnxs.com/pbc/v1/cache' + } +}); +``` diff --git a/dev-docs/bidders/atomx.md b/dev-docs/bidders/atomx.md index 378c2b37b0..ddca88bbbc 100644 --- a/dev-docs/bidders/atomx.md +++ b/dev-docs/bidders/atomx.md @@ -4,7 +4,8 @@ title: Atomx description: Prebid Atomx Bidder Adaptor pbjs: true biddercode: atomx -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/audiencerun.md b/dev-docs/bidders/audiencerun.md index b7d4a9fbcd..8f61791191 100644 --- a/dev-docs/bidders/audiencerun.md +++ b/dev-docs/bidders/audiencerun.md @@ -5,39 +5,45 @@ description: Prebid AudienceRun Bidder Adaptor pbjs: true biddercode: audiencerun media_types: banner +gvl_id: 944 gdpr_supported: true +usp_supported: true +schain_supported: true +safeframes_ok: false +prebid_member: false +userIds: all +floors_supported: true --- -### Disclosure - -This bidder sets `adId` on the bid response and hasn't responded to the Prebid.js team to confirm uniqueness -of this value. See [Issue 6381](https://github.com/prebid/Prebid.js/issues/6381). - ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-------------|---------|----------| -| `zoneId` | required | | | `string` | - -### Description - -Module that connects to AudienceRun demand sources. - -Use `audiencerun` as bidder. - -`zoneId` is required and must be 10 alphanumeric characters. - -### AdUnits configuration example -``` - var adUnits = [{ - code: 'test-div', - sizes: [[300, 600]], - bids: [{ - bidder: 'audiencerun', - params: { - zoneId: 'xtov2mgij0' - } - }] - }]; +| Name | Scope | Description | Example | Type | +| ---------- | -------- | --------------------------------------------------------------------------- | -------------- | -------- | +| `zoneId` | required | The zone id provided by AudienceRun | `'xtov2mgij0'` | `string` | +| `bidfloor` | optional | The bid floor for the zone id provided by AudienceRun in USD (default: 0.0) | `0.5` | `float` | + +### Registration + +The AudienceRun Header Bidding adaptor requires setup and approval from the AudienceRun team. Please reach out to our team on for more details. + +### Example + +Use `audiencerun` as bidder. Note that `zoneId` is required and must be 10 alphanumeric characters. + +```js +var adUnits = [ + { + code: "test-div", + sizes: [[300, 600]], + bids: [ + { + bidder: "audiencerun", + params: { + zoneId: "xtov2mgij0", + }, + }, + ], + }, +]; ``` diff --git a/dev-docs/bidders/automatad.md b/dev-docs/bidders/automatad.md index cd1c2045b4..3b16d99709 100644 --- a/dev-docs/bidders/automatad.md +++ b/dev-docs/bidders/automatad.md @@ -4,14 +4,26 @@ title: Automatad OpenRTB Bid Adapter description: Automatad OpenRTB Bid Adapter biddercode: automatad pbjs: true +pbs: true media_types: banner +fpd_supported: false --- -#### Bid Params +#### Prebid.js Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-----------|----------|---------------------------|------------|----------| | `siteId` | required | The site ID from automatad. | `"12adf45c"` | `string` | -| `placementId` | required | The placement ID from automatad. | `"a34gh6d"` | `string` | +| `placementId` | optional | The placement ID from automatad. | `"a34gh6d"` | `string` | + +### Prebid-Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------|---------|----------| +| `position` | optional | Position field from automatad | `22390678` | `string` | +| `placementId` | optional | The placement ID from automatad. | `"a34gh6d"` | `string` | + + diff --git a/dev-docs/bidders/avantisvideo.md b/dev-docs/bidders/avantisvideo.md index 2f1d2e72ee..bdc5ae4dd9 100644 --- a/dev-docs/bidders/avantisvideo.md +++ b/dev-docs/bidders/avantisvideo.md @@ -5,13 +5,15 @@ description: Avantis Video Bidder Adapter pbjs: true biddercode: avantisvideo aliasCode: aniview -media_types: video +media_types: banner, video gdpr_supported: true usp_supported: true +schain_supported: true +safeframes_ok: true --- ### Note: -For more information about [Avantis Video](https://www.avantisvideo.com/). +For more information about [Avantis Video](https://www.avantisvideo.com/), please contact contact@avantisvideo.com. ### Bid Params diff --git a/dev-docs/bidders/axonix.md b/dev-docs/bidders/axonix.md index 6a7ecae034..84ffe5dcd6 100644 --- a/dev-docs/bidders/axonix.md +++ b/dev-docs/bidders/axonix.md @@ -5,6 +5,8 @@ description: Axonix Prebid Adaptor biddercode: axonix media_types: banner, video pbjs: true +pbs: true +gvl_id: 678 --- ### Prebid Server Note: diff --git a/dev-docs/bidders/beachfront.md b/dev-docs/bidders/beachfront.md index 0a12f356e0..80e24b0f08 100644 --- a/dev-docs/bidders/beachfront.md +++ b/dev-docs/bidders/beachfront.md @@ -4,10 +4,11 @@ title: Beachfront description: Prebid Beachfront Bidder Adapter biddercode: beachfront media_types: video -getFloor: true +floors_supported: true +fpd_supported: true gdpr_supported: true usp_supported: true -userIds: unifiedId, identityLink, uid2 +userIds: unifiedId, identityLink, uid2, hadronId schain_supported: true prebid_member: true pbjs: true @@ -26,56 +27,85 @@ For further information, please contact adops@beachfront.com. ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |------------|----------|---------------------------------------------------------------------------------------------|------------------------------------------|----------| -| `appId` | required | Beachfront Exchange ID | `'11bc5dd5-7421-4dd8-c926-40fa653bec76'` | `string` | -| `bidfloor` | required | Bid floor | `0.01` | `float` | -| `video` | optional | Object with video parameters. See the [video section below](#beachfront-video) for details. | | `object` | -| `banner` | optional | Object with banner parameters. See the [banner section below](#beachfront-banner) for details. | | `object` | -| `player` | optional | Object with outstream player parameters. See the [player section below](#beachfront-player) for details. | | `object` | +| `appId` | required | Beachfront Exchange ID | `'11bc5dd5-7421-4dd8-c926-40fa653bec76'` | `string` | +| `bidfloor` | required | Bid floor | `0.01` | `float` | +| `video` | optional | Object with video parameters. See the [video section below](#beachfront-video) for details. | | `object` | +| `banner` | optional | Object with banner parameters. See the [banner section below](#beachfront-banner) for details. | | `object` | +| `player` | optional | Object with outstream player parameters. See the [player section below](#beachfront-player) for details. | | `object` | -### video params +#### video params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |------------------|----------|------------------------------------------------|-------------------------------------------|-----------------| -| `appId` | optional | Beachfront Exchange ID for video bids. | `'11bc5dd5-7421-4dd8-c926-40fa653bec76'` | `string` | -| `bidfloor` | optional | Bid floor for video bids. | `0.01` | `float` | -| `tagid` | optional | Tag ID | `'placement-name'` | `string` | -| `responseType` | optional | Video response type.
    `both`: VAST URL and VAST XML
    `nurl`: VAST URL only
    `adm`: VAST XML only | `'both'` | `string` | -| `mimes` | optional | Array of strings listing supported MIME types. | `["video/mp4", "application/javascript"]` | `Array` | +| `appId` | optional | Beachfront Exchange ID for video bids. | `'11bc5dd5-7421-4dd8-c926-40fa653bec76'` | `string` | +| `bidfloor` | optional | Bid floor for video bids. | `0.01` | `float` | +| `tagid` | optional | Tag ID | `'placement-name'` | `string` | +| `responseType` | optional | Video response type.
    `both`: VAST URL and VAST XML
    `nurl`: VAST URL only
    `adm`: VAST XML only | `'both'` | `string` | +| `mimes` | optional | Array of strings listing supported MIME types. | `["video/mp4", "application/javascript"]` | `Array` | | `playbackmethod` | optional | Playback method supported by the publisher.
    `1`: Auto-play sound on
    `2`: Auto-play sound off
    `3`: Click-to-play
    `4`: Mouse-over | `1` | `integer` | -| `maxduration` | optional | Maximum video ad duration in seconds. | `30` | `integer` | -| `placement` | optional | Placement type for the impression.
    `1`: In-Stream
    `2`: In-Banner
    `3`: In-Article
    `4`: In-Feed
    `5`: Interstitial/Slider/Floating | `1` | `integer` | -| `skip` | optional | Indicates if the player will allow the video to be skipped. | `1` | `integer` | -| `skipmin` | optional | Videos of total duration greater than this number of seconds can be skippable. | `15` | `integer` | -| `skipafter` | optional | Number of seconds a video must play before skipping is enabled. | `5` | `integer` | +| `maxduration` | optional | Maximum video ad duration in seconds. | `30` | `integer` | +| `placement` | optional | Placement type for the impression.
    `1`: In-Stream
    `2`: In-Banner
    `3`: In-Article
    `4`: In-Feed
    `5`: Interstitial/Slider/Floating | `1` | `integer` | +| `skip` | optional | Indicates if the player will allow the video to be skipped. | `1` | `integer` | +| `skipmin` | optional | Videos of total duration greater than this number of seconds can be skippable. | `15` | `integer` | +| `skipafter` | optional | Number of seconds a video must play before skipping is enabled. | `5` | `integer` | -### banner params +#### banner params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |------------|----------|-----------------------------------------|------------------------------------------|----------| -| `appId` | optional | Beachfront Exchange ID for banner bids. | `'3b16770b-17af-4d22-daff-9606bdf2c9c3'` | `string` | +| `appId` | optional | Beachfront Exchange ID for banner bids. | `'3b16770b-17af-4d22-daff-9606bdf2c9c3'` | `string` | | `bidfloor` | optional | Bid floor for banner bids. | `0.01` | `float` | -| `tagid` | optional | Tag ID | `'placement-name'` | `string` | +| `tagid` | optional | Tag ID | `'placement-name'` | `string` | -### player params +#### player params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | +| Name | Scope | Description | Example | Type | |------------|----------|-----------------------------------------|------------------------------------------|----------| | `progressColor` | optional | The color of the progress bar formatted as a CSS value. | `'#50A8FA'` | `string` | | `adPosterColor` | optional | The color of the ad poster formatted as a CSS value. | `'#FFFFFF'` | `string` | | `expandInView` | optional | Defines whether to expand the player when the ad slot is in view. Defaults to `false`. | `false` | `boolean` | | `collapseOnComplete` | optional | Defines whether to collapse the player when ad playback has completed. Defaults to `true`. | `true` | `boolean` | +### First Party Data + +Publishers should use the `ortb2` method of setting First Party Data. The following fields are supported: + +- ortb2.site.\* +- ortb2.app.\* +- ortb2.user.\* + +Example first party data that's available to all bidders and all adunits: + +``` +pbjs.setConfig({ + ortb2: { + site: { + keywords: "kw1,kw2", + content: { + title: "title1", + series: "series1" + } + }, + user: { + keywords: "a,b", + gender: "M", + yob: 1984 + } + } +}); +``` + ### Prebid Server As seen in the JSON response from \{your PBS server\}\/bidder\/params [(example)](https://prebid.adnxs.com/pbs/v1/bidders/params), the beachfront diff --git a/dev-docs/bidders/beop.md b/dev-docs/bidders/beop.md new file mode 100644 index 0000000000..f1728716d5 --- /dev/null +++ b/dev-docs/bidders/beop.md @@ -0,0 +1,15 @@ +--- +layout: bidder +title: BeOp +description: BeOp Bidder Adaptor +pbjs: true +biddercode: beop +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------|---------|----------| +| `accountId` or `networkId` | required | Your BeOp account ID | `'5a8af500c9e77c00017e4cad'` | `string` | +| `currency` | optional | Your currency | `'EUR'` (default) or `'USD'` | `string` | diff --git a/dev-docs/bidders/between.md b/dev-docs/bidders/between.md index 59eac200bd..b37304b1b5 100644 --- a/dev-docs/bidders/between.md +++ b/dev-docs/bidders/between.md @@ -8,9 +8,10 @@ biddercode: between schain_supported: true gdpr_supported: true pbs_app_supported: true -userIds: sharedId +userIds: all gvl_id: 724 usp_supported: true +safeframes_ok: false --- ### Prebid.js Bid Params @@ -19,8 +20,6 @@ usp_supported: true | Name | Scope | Description | Example | Type | |---------------|----------|-------------|---------|----------| | `s` | required | Section ID from Between SSP control panel | 999999 | `integer` | -| `w` | required | width of placement(Number) | 240 | -| `h` | required | height of placement(Number) | 400 | ### Prebid-Server Bid Params diff --git a/dev-docs/bidders/biddo.md b/dev-docs/bidders/biddo.md new file mode 100644 index 0000000000..bd6310f5a4 --- /dev/null +++ b/dev-docs/bidders/biddo.md @@ -0,0 +1,23 @@ +--- +layout: bidder +title: Biddo +description: Prebid Biddo Bidder Adapter +pbjs: true +biddercode: biddo +safeframes_ok: false +--- + +### Note + +Here is what you need for Prebid integration with Biddo: +1. Register with Biddo. +2. Once registered and approved, you will receive a Zone ID. +3. Use the Zone ID as parameters in params. + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|------------------------------------------------|----------| +| `zoneId` | required | Zone ID | `379783` | `number` | diff --git a/dev-docs/bidders/bidfluence.md b/dev-docs/bidders/bidfluence.md index 5f4a4e1de7..4b90d41086 100644 --- a/dev-docs/bidders/bidfluence.md +++ b/dev-docs/bidders/bidfluence.md @@ -5,7 +5,8 @@ description: Bidfluence Adaptor for Prebidjs pbjs: true biddercode: bidfluence gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/bidlab.md b/dev-docs/bidders/bidlab.md index 3607f72f38..0dbc539640 100644 --- a/dev-docs/bidders/bidlab.md +++ b/dev-docs/bidders/bidlab.md @@ -6,7 +6,8 @@ pbjs: true biddercode: bidlab gdpr_supported: true media_types: banner, video -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/bidmachine.md b/dev-docs/bidders/bidmachine.md index c314667874..82f1dd997e 100644 --- a/dev-docs/bidders/bidmachine.md +++ b/dev-docs/bidders/bidmachine.md @@ -11,7 +11,7 @@ schain_supported: true dchain_supported: false media_types: banner, video safeframes_ok: true -bidder_supports_deals: false +deals_supported: false pbjs: false pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/bidmyadz.md b/dev-docs/bidders/bidmyadz.md new file mode 100644 index 0000000000..52d3c1f66c --- /dev/null +++ b/dev-docs/bidders/bidmyadz.md @@ -0,0 +1,22 @@ +--- +layout: bidder +title: BidMyAdz +description: Prebid Bidmyadz Bidder Adapter +biddercode: bidmyadz +usp_supported: true +schain_supported: true +media_types: banner, video, native +gdpr_supported: true +pbjs: false +pbs: true +pbs_app_supported: true +pbjs_version_notes: not in 5.x +--- + +### Prebid Server Bid Params +Currently adapter doesn't support multiimpression, so only the first impression will be delivered + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|----------------------------------------------------------|------------|-----------| +| `placementId` | required | Placement Id will be generated on BidMyAdz Platform. | `'1234'` | `string` | diff --git a/dev-docs/bidders/bidphysics.md b/dev-docs/bidders/bidphysics.md index 1e322a3afe..d9dae7f143 100644 --- a/dev-docs/bidders/bidphysics.md +++ b/dev-docs/bidders/bidphysics.md @@ -5,7 +5,8 @@ description: Prebid BidPhysics Bidder Adaptor pbjs: true biddercode: bidphysics gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/big-richmedia.md b/dev-docs/bidders/big-richmedia.md new file mode 100644 index 0000000000..8c2d6917df --- /dev/null +++ b/dev-docs/bidders/big-richmedia.md @@ -0,0 +1,55 @@ +--- +layout: bidder +title: BigRichMedia +description: Prebid Big Richmedia Bidder Adapter +biddercode: big-richmedia +pbjs: true +media_types: banner, video +userIds: criteo, unifiedId, netId, identityLink, flocId, uid2 +schain_supported: true +coppa_supported: true +usp_supported: true +floors_supported: true +fpd_supported: true +gdpr_supported: true +gvl_id: 32 +--- + +#### Global Settings + +Set the publisherId for using bigRichemedia + +``` +pbjs.que.push(function() { + // use the bid server in Taiwan (country code: tw) + pbjs.setConfig({ + bigRichmedia: { + 'publisherId': 'A7FN99NZ98F5ZD4G' + } + }); +}); +``` + +#### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-----------|----------|---------------------------|------------|----------| +| `placementId` | required | The placement ID. You may identify a placement using the `invCode` and `member` instead of a placement ID. | `234234` | `integer` | +| `member` | optional | The member ID from AppNexus. Must be used with `invCode`. | `'12345'` | `string` | +| `invCode` | optional | The inventory code from AppNexus. Must be used with `member`. | `'abc123'` | `string` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. | `keywords: { genre: ['rock', 'pop'] }` | `object` | + +#### Video Object + +Those configuration parameters are read from mediaTypes.video + +{: .table .table-bordered .table-striped } +| Name | Description | Type | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `minduration` | Integer that defines the minimum video ad duration in seconds. | `integer` | +| `maxduration` | Integer that defines the maximum video ad duration in seconds. | `integer` | +|`context` | A string that indicates the type of video ad requested. Allowed values: `"pre_roll"`; `"mid_roll"`; `"post_roll"`; `"outstream"`. | `string` | +| `skippable` | Boolean which, if `true`, means the user can click a button to skip the video ad. Defaults to `false`. | `boolean` | +|`skipoffset`| Integer that defines the number of seconds until an ad can be skipped. Assumes `skippable` setting was set to `true`. | `integer` | +| `frameworks` | Array of integers listing API frameworks supported by the publisher. Allowed values: None: `0`; VPAID 1.0: `1`; VPAID 2.0: `2`; MRAID 1.0: `3`; MRAID 2.0: `4`; ORMMA: `5`; OMID 1.0 `6`. | `Array` | diff --git a/dev-docs/bidders/bizzclick.md b/dev-docs/bidders/bizzclick.md index dee853df60..694d56e3b0 100644 --- a/dev-docs/bidders/bizzclick.md +++ b/dev-docs/bidders/bizzclick.md @@ -9,14 +9,14 @@ coppa_supported: true schain_supported: true media_types: banner, video, native safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true -pbjs_version_notes: not in 5.x +pbs: true --- ### Note: -The Example Bidding adapter requires setup before beginning. Please contact us at support@bizzclick.com +The Example Bidding adapter requires setup before beginning. Please contact us at support@bizzclick.com .BizzClick will only respond to the first impression and that multiple ad formats of that single impression are not supported. ### Bid Params diff --git a/dev-docs/bidders/bliink.md b/dev-docs/bidders/bliink.md new file mode 100644 index 0000000000..7c1a86f932 --- /dev/null +++ b/dev-docs/bidders/bliink.md @@ -0,0 +1,22 @@ +--- +layout: bidder +title: BLIINK +description: Prebid BLIINK Bidder Adaptor +pbjs: true +pbs: true +media_types: video, banner +biddercode: bliink +gdpr_supported: true +usp_supported: false +--- + +### Note: +The BLIINK Header Bidding adaptor requires setup and approval from the BLIINK team. Please reach out to your account manager for more informations. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------------------|--------------------------------------|----------| +| `tagId` | required | The TagID from BLIINK. | `'32'` | `string` | +| `imageUrl` | optional | The image url on which the ad is displayed in case of in-image ad. | `'https://image.png'` | `string` | diff --git a/dev-docs/bidders/bmtm.md b/dev-docs/bidders/bmtm.md index 8c7f67c8d1..3d99a82779 100644 --- a/dev-docs/bidders/bmtm.md +++ b/dev-docs/bidders/bmtm.md @@ -4,10 +4,11 @@ title: Bright Mountain Media description: Prebid Bright Mountain Media Bidder Adapter biddercode: bmtm media_types: banner, video -getFloor: true +floors_supported: true schain_supported: true pbjs: true pbs: true +userIds: id5Id, sharedId --- ### Bid Params diff --git a/dev-docs/bidders/boldwin.md b/dev-docs/bidders/boldwin.md index 10e7ed89d5..084e923814 100644 --- a/dev-docs/bidders/boldwin.md +++ b/dev-docs/bidders/boldwin.md @@ -5,8 +5,7 @@ description: Prebid Boldwin Bidder Adapter pbjs: true biddercode: boldwin gdpr_supported: true -media_types: banner, video -pbjs_version_notes: not in 5.x +media_types: banner, video, native --- ### Note: @@ -18,4 +17,4 @@ The Boldwin Bidding adapter requires setup before beginning. Please contact us a {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|-----------------------|-----------|-----------| -| `placementId` | required | Adprime placement id | `'1234asdf'` | `'string'` | +| `placementId` | required | Boldwin placement id | `'1234asdf'` | `'string'` | diff --git a/dev-docs/bidders/brave.md b/dev-docs/bidders/brave.md new file mode 100644 index 0000000000..e26f0f7249 --- /dev/null +++ b/dev-docs/bidders/brave.md @@ -0,0 +1,26 @@ +--- +layout: bidder +title: Brave +description: Prebid Brave Bidder Adapter +biddercode: brave +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: true +pbs: false +--- + +### Note: + +The Brave Header Bidding adapter requires setup and approval from the Brave team. Please reach out to your account manager or support@thebrave.io for more information + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------------------------|-------------------------------------|-----------| +| `placementId` | required | Brave's platform placement id | `'to0QI2aPgkbBZq6vgf0oHitouZduz0qw'` | `string` | diff --git a/dev-docs/bidders/bucksense.md b/dev-docs/bidders/bucksense.md index e276f7724b..b3fc9dc686 100644 --- a/dev-docs/bidders/bucksense.md +++ b/dev-docs/bidders/bucksense.md @@ -4,6 +4,7 @@ title: Bucksense description: Prebid Bucksense Bidder Adapter pbjs: true biddercode: bucksense +gdpr_supported: true --- ### Bid params diff --git a/dev-docs/bidders/byplay.md b/dev-docs/bidders/byplay.md index 3247ebd3b8..0cd4a92035 100644 --- a/dev-docs/bidders/byplay.md +++ b/dev-docs/bidders/byplay.md @@ -5,7 +5,8 @@ description: Prebid ByPlay Bidder Adaptor pbjs: true biddercode: byplay media_types: video -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/c1x.md b/dev-docs/bidders/c1x.md index c24b70318b..af3a99716e 100644 --- a/dev-docs/bidders/c1x.md +++ b/dev-docs/bidders/c1x.md @@ -5,7 +5,8 @@ description: Prebid C1X Bidder Adaptor pbjs: true biddercode: c1x gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/catapultx.md b/dev-docs/bidders/catapultx.md new file mode 100644 index 0000000000..abb551bf81 --- /dev/null +++ b/dev-docs/bidders/catapultx.md @@ -0,0 +1,23 @@ +--- +layout: bidder +title: CatapultX +description: CatapultX Bidder Adaptor +pbjs: true +pbs: true +biddercode: catapultx +aliasCode : adkernel +media_types: banner, video +gdpr_supported: true +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.catapultx.com'` | `string` | +| `zoneId` | required | Zone Id | 76156 | `integer`| diff --git a/dev-docs/bidders/cedato.md b/dev-docs/bidders/cedato.md index fe25e346a0..2aa6857b46 100644 --- a/dev-docs/bidders/cedato.md +++ b/dev-docs/bidders/cedato.md @@ -9,7 +9,8 @@ usp_supported: true nav_section: reference pbjs: true biddercode: cedato -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid params diff --git a/dev-docs/bidders/clickforce.md b/dev-docs/bidders/clickforce.md index a617304ee7..2b961b28b7 100644 --- a/dev-docs/bidders/clickforce.md +++ b/dev-docs/bidders/clickforce.md @@ -5,7 +5,6 @@ description: Prebid Clickforce Bidder Adaptor pbjs: true biddercode: clickforce media_types: native -pbjs_version_notes: not in 5.x --- ### Bid Params (display ad) diff --git a/dev-docs/bidders/clicktripz.md b/dev-docs/bidders/clicktripz.md index dabc6ef6d0..a7a175df80 100644 --- a/dev-docs/bidders/clicktripz.md +++ b/dev-docs/bidders/clicktripz.md @@ -5,7 +5,8 @@ description: Prebid Clicktripz Bidder Adaptor pbjs: true biddercode: clicktripz media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/codefuel.md b/dev-docs/bidders/codefuel.md new file mode 100644 index 0000000000..f2b9b20833 --- /dev/null +++ b/dev-docs/bidders/codefuel.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: CodeFuel +description: CodeFuel Prebid Bidder Adapter +pbjs: true +pbs: true +media_types: banner +biddercode: CodeFuel +gdpr_supported: false +usp_supported: false +floors_supported: false +--- + +### Description + +Module that connects to Codefuel bidder to fetch bids. +Display format is supported but not native format. Using OpenRTB standard. + +### Bid Params +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------------------------------|------------------------------------------|----------| +| `placementId` | required | Placement-Id defined by the caller | `'0111f8ac-2d40-4613-8557-b47dbf622fff'` | `string` | + + +### Configuration + + +```javascript + pbjs.setConfig({ + codefuel: { + bidderUrl: 'https://prebidtest.zemanta.com/api/bidder/prebidtest/bid/' + } +}); +``` diff --git a/dev-docs/bidders/coinzilla.md b/dev-docs/bidders/coinzilla.md index 45bd80bc4c..7e77dee719 100644 --- a/dev-docs/bidders/coinzilla.md +++ b/dev-docs/bidders/coinzilla.md @@ -3,6 +3,7 @@ layout: bidder title: Coinzilla description: Prebid Coinzilla Bidder Adaptor pbjs: true +pbs: true biddercode: coinzilla --- diff --git a/dev-docs/bidders/collectcent.md b/dev-docs/bidders/collectcent.md index d48aefb665..78e42374aa 100644 --- a/dev-docs/bidders/collectcent.md +++ b/dev-docs/bidders/collectcent.md @@ -4,6 +4,7 @@ title: Collectcent description: Prebid Collectcent Bidder Adaptor pbjs: true biddercode: collectcent +enable_download: false pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/colombia.md b/dev-docs/bidders/colombia.md index 8500c375ee..10ea4fe7ea 100644 --- a/dev-docs/bidders/colombia.md +++ b/dev-docs/bidders/colombia.md @@ -4,7 +4,8 @@ title: COLOMBIA description: Prebid COLOMBIA Bidder Adaptor pbjs: true biddercode: colombia -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/colossus.md b/dev-docs/bidders/colossus.md index a01899d0af..968bf90204 100644 --- a/dev-docs/bidders/colossus.md +++ b/dev-docs/bidders/colossus.md @@ -6,18 +6,25 @@ biddercode: colossus usp_supported: true schain_supported: true media_types: banner, video, native -userIds: britepoolid, identityLink, unifiedId, id5Id +userIds: britepoolid, identityLink, unifiedId, id5Id, uid2 gdpr: true pbjs: false pbs: true pbs_app_supported: true --- +### Disclosure: + +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. + ### Prebid.Server Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------------|----------|----------------------------------------------------------|------------|-----------| -| `TagID` | required | Placement Id will be generated on Colossus SSP Platform. | `'0'` | `string` | +| `TagID` | optional | Placement Id will be generated on Colossus SSP Platform. | `'0'` | `string` | +| `groupId` | optional | Group Id will be generated on Colossus SSP Platform. | `'0'` | `string` | + +You only need to use one parameter: either TagID or groupId *For prebidJS parametres, look into colossusssp.md* diff --git a/dev-docs/bidders/colossusssp.md b/dev-docs/bidders/colossusssp.md index a571a4f42b..cb188c5d68 100644 --- a/dev-docs/bidders/colossusssp.md +++ b/dev-docs/bidders/colossusssp.md @@ -6,11 +6,10 @@ biddercode: colossusssp usp_supported: true schain_supported: true media_types: banner, video, native -userIds: britepoolid, identityLink, unifiedId, id5Id +userIds: britepoolid, identityLink, unifiedId, id5Id, uid2 gdpr: true pbjs: true pbs: false -pbjs_version_notes: not in 5.x --- ### Prebid.JS Bid Params @@ -18,7 +17,8 @@ pbjs_version_notes: not in 5.x {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------------|----------|----------------------------------------------------------|------------|-----------| -| `placement_id` | required | Placement Id will be generated on Colossus SSP Platform. | `0` | `integer` | +| `placement_id` | optional | Placement Id will be generated on Colossus SSP Platform. Use instead of group_id | `0` | `integer` | +| `group_id` | optional | Group Id will be generated on Colossus SSP Platform. Use instead of placement_id | `0` | `integer` | | `traffic` | optional | Type traffic | `'banner'` | `string` | *For colossus prebid server parametres, look into colossus.md* diff --git a/dev-docs/bidders/compass.md b/dev-docs/bidders/compass.md new file mode 100644 index 0000000000..ac2506bc9a --- /dev/null +++ b/dev-docs/bidders/compass.md @@ -0,0 +1,28 @@ +--- +layout: bidder +title: Compass +description: Prebid Compass Bidder Adapter +biddercode: compass +usp_supported: true +gdpr_supported: true +coppa_supported: true +schain_supported: true +floors_supported: true +media_types: banner, video, native +pbjs: true +pbs: true +pbs_app_supported: true +gvl_id: 883 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | + +### Note + +For the prebid server and prebid.js you only need to use one parameter: either placementId or endpointId diff --git a/dev-docs/bidders/connectad.md b/dev-docs/bidders/connectad.md index 2a8c0e1558..b5f67acab3 100644 --- a/dev-docs/bidders/connectad.md +++ b/dev-docs/bidders/connectad.md @@ -11,7 +11,7 @@ schain_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId prebid_member: true safeframes_ok: true -getFloor: true +floors_supported: true pbjs: true pbs: true gvl_id: 138 diff --git a/dev-docs/bidders/consumable.md b/dev-docs/bidders/consumable.md index 9f56640166..b0a30a0018 100644 --- a/dev-docs/bidders/consumable.md +++ b/dev-docs/bidders/consumable.md @@ -2,11 +2,15 @@ layout: bidder title: Consumable description: Prebid Consumable Bidder Adaptor +userIds: all +usp_supported: true pbjs: true pbs: true pbs_app_supported: true biddercode: consumable gdpr_supported: true +schain_supported: true +coppa_supported: true gvl_id: 591 --- diff --git a/dev-docs/bidders/contentexchange.md b/dev-docs/bidders/contentexchange.md new file mode 100644 index 0000000000..364ee93d6f --- /dev/null +++ b/dev-docs/bidders/contentexchange.md @@ -0,0 +1,21 @@ +--- +layout: bidder +title: ContentExchange +description: Prebid Contentexchange Bidder Adapter +biddercode: contentexchange +usp_supported: true +schain_supported: true +media_types: banner, video, native +gdpr_supported: true +pbjs: true +pbs: false +pbs_app_supported: false +--- + +### Prebid.JS Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|----------------------------------------------------------|------------|-----------| +| `placementId` | required | Placement Id will be generated on ContentExchange Platform. | `'1234'` | `string` | +| `adFormat` | required | `[banner, video, native]` | `'banner'` | `string` | diff --git a/dev-docs/bidders/converge.md b/dev-docs/bidders/converge.md index e2720237b0..d4a010aad0 100644 --- a/dev-docs/bidders/converge.md +++ b/dev-docs/bidders/converge.md @@ -1,21 +1,29 @@ --- layout: bidder -title: Converge -description: Prebid Converge Bidder Adaptor +title: Converge-Digital +description: Converge-Digital Bidder Adaptor pbjs: true +pbs: true biddercode: converge -media_types: banner, video +aliasCode : adkernel +media_types: banner, native, video gdpr_supported: true usp_supported: true -pbjs_version_notes: not in 5.x +coppa_supported: true +pbs_app_supported: true +gvl_id: 248 +schain_supported: true +userIds: all --- +### Note: + +The Converge-Digital Bidding adapter requires setup and approval before implementation. Please reach out to for more details. ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| -| `uid` | required | Represents the Converge bidder system Ad Slot ID associated with the respective div id from the site page. | `59` | `integer` | -| `priceType` | optional | Can take the values `gross` or `net`, default value is `net`. Net represents the header bid price with the Converge header bidder margin already extracted. Gross price does contain the Converge bidder margin within. | `'gross'` | `string` | -| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | ConvergeDigital RTB host | `'cpm.convergeselect.net'` | `string` | +| `zoneId` | required | Zone Id | `30164` | `integer` | diff --git a/dev-docs/bidders/conversant.md b/dev-docs/bidders/conversant.md index 6991323c74..4298219be0 100644 --- a/dev-docs/bidders/conversant.md +++ b/dev-docs/bidders/conversant.md @@ -7,8 +7,9 @@ pbs: true biddercode: conversant media_types: video gdpr_supported: true -userIds: criteo, id5Id, identityLink, liveIntentId, parrableId, pubCommonId, unifiedId +userIds: criteo, id5Id, identityLink, liveIntentId, parrableId, pubCommonId, unifiedId, publinkId prebid_member: true +schain_supported: true gvl_id: 24 --- @@ -20,7 +21,7 @@ gvl_id: 24 | Name | Scope | Description | Example | Type | |---------------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------|-------------------|------------------| -| `site_id` | required | The site ID from Conversant. | `'87293'` | `string` | +| `site_id` | optional | The site ID from Conversant. | `'87293'` | `string` | | `secure` | required (for secure pages) | If impression requires secure HTTPS URL creative assets and markup. 0 for non-secure, 1 for secure. Default is non-secure | `1` | `integer` | | `bidfloor` | optional | Bid floor | `0.50` | `float` | | `tag_id` | optional | Identifies specific ad placement. | `'cnvr-test-tag'` | `string` | @@ -74,3 +75,57 @@ The following values are defined in the [ORTB 2.5 spec](https://www.iab.com/wp-c + `8` : VAST 4.0 Wrapper + `9` : DAAST 1.0 + `10` : DAAST 1.0 Wrapper + +### First Party Data +Publishers should use the `ortb2` method of setting for setting First Party Data. +Example first party data configuration that is available to all adUnits +``` +pbjs.setConfig({ + debug: true, + cache: { + url: 'https://prebid.adnxs.com/pbc/v1/cache' + }, + ortb2: { + site: { + content: { + series: 'MySeries', + season: 'My Season', + episode: 3, + title: 'My Title' + } + } + } +}); +``` + +Example AdUnit specific data using the `ortb2Imp` object +``` + var videoAdUnit = { + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]] + } + }, + ortb2Imp: { + instl: 1, + ext: { + data: { + adUnitSpecificAttribute: "123" + } + } + }, + bids: [{ + bidder: 'conversant', + params: { + site_id: '108060', + mimes: ['video/mp4', 'video/webm'] + } + }] + } + + pbjs.que.push(function(){ + pbjs.addAdUnits(videoAdUnits); + } +``` + diff --git a/dev-docs/bidders/cosmos.md b/dev-docs/bidders/cosmos.md index d8d35a9b42..deb8130dbe 100644 --- a/dev-docs/bidders/cosmos.md +++ b/dev-docs/bidders/cosmos.md @@ -4,7 +4,8 @@ title: COSMOS description: Prebid COSMOS Bidder Adapter pbjs: true biddercode: cosmos -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Integration Note: diff --git a/dev-docs/bidders/cpmstar.md b/dev-docs/bidders/cpmstar.md index f01b0b56f7..3b97562e91 100644 --- a/dev-docs/bidders/cpmstar.md +++ b/dev-docs/bidders/cpmstar.md @@ -9,7 +9,6 @@ media_types: banner, video gdpr_supported: true usp_supported: true coppa_supported: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/criteo.md b/dev-docs/bidders/criteo.md index fe5d109427..1e9954ed64 100644 --- a/dev-docs/bidders/criteo.md +++ b/dev-docs/bidders/criteo.md @@ -10,17 +10,18 @@ gdpr_supported: true usp_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, pubProvidedId, sharedId, unifiedId prebid_member: true -getFloor: false* +floors_supported: false +fpd_supported: true +schain_supported: true gvl_id: 91 --- ### Notes -{: .alert.alert-warning :} -For Native Ads, in order to avoid further decoding issues of special characters, the assets need to be sent as placeholders. -That means, `sendId: true` becomes mandatory for all fields receiving URLs, notably: `icon`, `image`, `clickUrl`, `privacyLink`, `privacyIcon`. -*Criteo currently only supports getFloor if floors are in Euros and if the publisher is enabling the Criteo Publisher Tag external js call. +{: .alert.alert-warning :} +This bidder adapter automatically includes the Criteo User ID module and performs iFrame syncs. -See [Sending Asset Placeholders]({{site.baseurl}}/dev-docs/show-native-ads.html#sending-asset-placeholders). +{: .alert.alert-warning :} +Criteo currently only supports getFloor if floors are in USD and if the publisher is enabling the Criteo Publisher Tag external js call. The collected floors will only be used for logging purposes and won't bid taken into account when bidding. {: .alert.alert-warning :} Prebid-Server support is on alpha test and is currently a non-finished product. Activation requires setup and approval before beginning. Please reach out to your account manager or publishers@criteo.com for more details. @@ -39,6 +40,11 @@ of this value. See [Issue 6381](https://github.com/prebid/Prebid.js/issues/6381) | `networkId` | required | The network ID from Criteo. Please reach out your Criteo representative for more details. | `456456` | `integer` | | `nativeCallback` | optional | (Prebid.js only) Callback to perform render in native integrations. Please reach out your Criteo representative for more details. | `function(payload) { console.log(payload); }` | `function` | | `integrationMode` | optional | (Prebid.js only) Integration mode to use for ad render (none or 'AMP'). Please reach out your Criteo representative for more details. | `'AMP'` | `string` | +| `publisherSubId` | optional | Custom identifier for reporting. Please reach out your Criteo representative for more details. | `'adunit-1'` | `string` | + +### First Party Data + +Criteo supports both `ortb2` (`site` and `user`) and `ortb2Imp` methods to set [First Party Data](https://docs.prebid.org/features/firstPartyData.html). ### Video Object @@ -47,7 +53,7 @@ of this value. See [Issue 6381](https://github.com/prebid/Prebid.js/issues/6381) |-------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------| | `minduration` | optional | Minimum ad duration in seconds | `5` | `integer` | | `startdelay` | optional | Duration offset (in second) from the start of the content for showing the video ad before the start of the Video. Pre-roll: `0` (default); Mid-roll: `>0`; Default mid-roll: `-1`; Post-roll: `-2`; | `5` | `integer` | -| `playbackmethod` | required | Defines how is initiated the video inventory. Page Load with Sound On: `1`; Page Load with Sound Off: `2`; Click with Sound On: `3`; Mouse-Over with Sound On: `4`; Entering Viewport with Sound On: `5`; Entering Viewport with Sound Off by Default: `6`; | `1` | `integer` | +| `playbackmethod` | required | Defines how the video inventory is initiated. Page Load with Sound On: `1`; Page Load with Sound Off: `2`; Click with Sound On: `3`; Mouse-Over with Sound On: `4`; Entering Viewport with Sound On: `5`; Entering Viewport with Sound Off by Default: `6`; | `[4, 5]` | `Array` | | `placement` | required | Video placement type. In-Stream: `1`; In-Banner: `2`; In-Article: `3`: In-Feed: `4`; Interstitial: `5`; | `1` | `integer` | | `skip` | required | Ability from the video player for the user to skip the video. Not skippable: `0`; Skippable: `1`; | `1` | `integer` | @@ -78,7 +84,7 @@ var adUnits = [ playerSize: [640,480], protocols: [2, 3], skip: 0, - playbackmethod: 1, + playbackmethod: [1], placement: 1 } }, @@ -90,3 +96,9 @@ var adUnits = [ }] }]; ``` + +### Additional Config (Optional) + +Criteo Bid Adapter supports the collection of the user's hashed email, if available. + +Please consider passing it to the adapter, following [these guidelines](https://publisherdocs.criteotilt.com/prebid/#hashed-emails). \ No newline at end of file diff --git a/dev-docs/bidders/cwire.md b/dev-docs/bidders/cwire.md new file mode 100644 index 0000000000..8c45b82d18 --- /dev/null +++ b/dev-docs/bidders/cwire.md @@ -0,0 +1,24 @@ +--- +layout: bidder +title: C-WIRE +description: C-WIRE Prebid Bidder Adapter +pbjs: true +biddercode: cwire +gdpr_supported: false +usp_supported: false +schain_supported: false +userIds: flocId, uid2Id +enable_download: true +media_types: banner, video +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `pageId` | required | C-WIRE page id | `2453` | `integer` | +| `placementId` | required | C-WIRE placement id | `113244` | `integer` | +| `cwcreative` | required | C-WIRE creative id to force | `42` | `integer` | +| `refgroups` | required | C-WIRE group name to force | `'test-user'` | `string` | +| `cwapikey` | required | C-WIRE API key for integration testing | `'xxx-yyy-some-uuid'` | `string` | diff --git a/dev-docs/bidders/dailyhunt.md b/dev-docs/bidders/dailyhunt.md index cbb7440034..8054d482d2 100644 --- a/dev-docs/bidders/dailyhunt.md +++ b/dev-docs/bidders/dailyhunt.md @@ -6,7 +6,8 @@ pbjs: true biddercode: dailyhunt media_types: display, native, video gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/decenterads.md b/dev-docs/bidders/decenterads.md index 1e496566f2..206d453ca3 100644 --- a/dev-docs/bidders/decenterads.md +++ b/dev-docs/bidders/decenterads.md @@ -8,7 +8,8 @@ biddercode: decenterads media_types: banner, video, native gdpr_supported: true pbs_app_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/deepintent.md b/dev-docs/bidders/deepintent.md index 4c7ce15dcf..762de6591f 100644 --- a/dev-docs/bidders/deepintent.md +++ b/dev-docs/bidders/deepintent.md @@ -5,7 +5,7 @@ description: Prebid Deepintent Bidder Adaptor pbjs: true pbs: true biddercode: deepintent -media_types: banner +media_types: banner, video gdpr_supported: true usp_supported: true gvl_id: 541 @@ -75,4 +75,58 @@ var adUnits = [ } ]; ``` +### video parameters +Deepintent supports video as of Prebid v1.16.0 +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | +| :----------------------| :------- | :---------------------------------------------------------- | :------ | +| `video.mimes` | required | Video MIME types | `['video/mp4','video/x-flv']` | +| `video.skippable` | optional | If 'true', user can skip ad | `true` | +| `video.minduration` | optional | Minimum ad duration in seconds | `5` | +| `video.maxduration` | optional | Maximum ad duration in seconds | `30` | +| `video.startdelay` | optional | Start delay in seconds for pre-roll, mid-roll, or post-roll ad placements | `5` | +| `video.playbackmethod` | optional | Defines whether inventory is user-initiated or autoplay sound on/off
    Values:
    `1`: Auto-play, sound on
    `2`: Auto-play, sound off
    `3`: Click-to-play
    `4`: mouse-over | `1` | +| `video.api` | optional | API frameworks supported
    Values:
    `1`: VPAID 1.0
    `2`: VPAID 2.0
    `3`: MRAID-1
    `4`: ORMMA
    `5`: MRAID-2 | `[1, 2]` | +| `video.protocols` | optional | Supported video bid response protocols
    Values
    `1`: VAST 1.0
    `2`: VAST 2.0
    `3`: VAST 3.0
    `4`: VAST 1.0 Wrapper
    `5`: VAST 2.0 Wrapper
    `6`: VAST 3.0 Wrapper | `[5, 6]` | +| `video.battr` | optional | Blocked creative attributes, See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.3 for values | `[3, 9]` | +| `video.linearity` | optional | Indicates if the impression is linear or nonlinear
    Values:
    `1`: Linear/In-Stream
    `2`: Non-Linear/Overlay. | `1` | +| `video.placement` | optional | Video placement type. See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.9 for Values | `1` | +| `video.minbitrate` | optional | Minumim bit rate in Kbps. | 50 | +| `video.maxbitrate` | optional | Maximum bit rate in Kbps. | 70 | + +### AdUnit Format for Video +```javascript +var videoAdUnits = [ +{ + code: 'test-div-video', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream' + } + }, + bids: [{ + bidder: 'deepintent', + params: { + publisherId: '32572', // required + adSlot: '38519891@300x250' // required + video: { + mimes: ['video/mp4','video/x-flv'], // required + skip: 1, // optional + minduration: 5, // optional + maxduration: 30, // optional + startdelay: 5, // optional + playbackmethod: [1,3], // optional + api: [ 1, 2 ], // optional + protocols: [ 2, 3 ], // optional + battr: [ 13, 14 ], // optional + linearity: 1, // optional + placement: 2, // optional + minbitrate: 10, // optional + maxbitrate: 10 // optional + } + } + }] +}] +``` diff --git a/dev-docs/bidders/deltaprojects.md b/dev-docs/bidders/deltaprojects.md new file mode 100644 index 0000000000..cafcc93ef8 --- /dev/null +++ b/dev-docs/bidders/deltaprojects.md @@ -0,0 +1,54 @@ +--- +layout: bidder +title: Delta Projects +description: Prebid Delta Projects Bidder Adapter +biddercode: deltaprojects +gdpr_supported: true +gvl_id: 209 +media_types: banner +safeframes_ok: false +floors_supported: true +pbjs: true +--- + +### Note +Contact publishers@deltaprojects.com to get a publisher id and to agree on a currency. Delta Projects +will always bid and log values in the agreed upon currency, utilizing the currency module if necessary and available. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|--------------------------------------------------------------------------|-----------------|----------| +| `publisherId` | required | Publisher ID from Delta Projects. Contact publishers@deltaprojects.com | `'4'` | `string` | +| `currency` | optional | The bid currency agreed with Delta Projects. | `'SEK'` | `string` | +| `siteId` | optional | Site ID from Delta Projects. | `'example.com'` | `string` | +| `tagId` | optional | Identifier for specific ad placement or ad tag. | `'1234'` | `string` | +| `test` | optional | Indicate test model. Don't set anything if it is not in test mode. | `'true'` | `string` | + +### Example +#### Banner +``` +var adUnits = [ + { + code: 'adunit-code', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + bids: [ + { + bidder: 'deltaprojects', + params: { + publisherId: '4', // publisherId from Delta Projects. + currency: 'SEK', // the currency agreed with Delta Projects. + siteId: 'example.com', // siteId from Delta Projects. + tagId: 'tagId123', // id for ad placement or ad tag. + test: 'true', // disable test mode by remove this parameter. + } + } + ] + } +]; +``` diff --git a/dev-docs/denakop.md b/dev-docs/bidders/denakop.md similarity index 90% rename from dev-docs/denakop.md rename to dev-docs/bidders/denakop.md index 2d984f8474..0b390e05e4 100644 --- a/dev-docs/denakop.md +++ b/dev-docs/bidders/denakop.md @@ -1,6 +1,6 @@ --- layout: bidder -title: denakop +title: Denakop description: Denakop Bidder Adaptor pbjs: true pbs: true @@ -16,7 +16,7 @@ aliasCode : adkernel ### Note: -The Denakop bidding adapter requires setup and approval before implementation. Please reach out to for more details. +The Denakop bidding adapter requires setup and approval before implementation. Please reach out to for more details. ### Bid Params diff --git a/dev-docs/bidders/dgads.md b/dev-docs/bidders/dgads.md index 73bd6f02ca..4575da5bc6 100644 --- a/dev-docs/bidders/dgads.md +++ b/dev-docs/bidders/dgads.md @@ -5,7 +5,8 @@ description: Prebid dgads Bidder Adapter pbjs: true biddercode: dgads media_types: native -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/dianomi.md b/dev-docs/bidders/dianomi.md new file mode 100644 index 0000000000..66ef7ddf74 --- /dev/null +++ b/dev-docs/bidders/dianomi.md @@ -0,0 +1,95 @@ +--- +layout: bidder +title: Dianomi +description: Prebid Dianomi Bidder Adaptor +biddercode: dianomi +media_types: banner, native +coppa_supported: false +gdpr_supported: true +usp_supported: true +prebid_member: true +pbjs: true +pbs: false +schain_supported: true +userIds: all +gvl_id: 885 +floors_supported: true +fpd_supported: true +multiformat_supported: will-bid-on-one +--- + +### Note +- Supports `display` and `banner` formats. +- Uses `OpenRTB` standard. + +### Registration + +The Dianomi Adapter requires setup before beginning. Please contact us at eng@dianomi.com. + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------------------------|----------------------|--------------------|-----------| +| `smartadId` | required | Placement ID | `12345` | `integer` | +| `endpoint` | optional | for testing only | `www-prebid.dianomi.com` | `string` | + + +Note: smartadId is a pre agreed ID between the publisher and Dianomi. + +#### Native example + +```js +var adUnits = [ + code: 'your-native-container-id', + mediaTypes: { + native: { + image: { + required: false, + sizes: [100, 50] + }, + title: { + required: false, + len: 140 + }, + sponsoredBy: { + required: false + }, + clickUrl: { + required: false + }, + body: { + required: false + }, + icon: { + required: false, + sizes: [50, 50] + } + } + }, + bids: [{ + bidder: 'dianomi', + params: { + smartadId: 9607 + } + }] +]; +``` + +#### Banner example +```js +var adUnits = [ + code: 'your-banner-container-id', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + bids: [{ + bidder: 'dianomi', + params: { + smartadId: 9607 + } + }] +]; +``` \ No newline at end of file diff --git a/dev-docs/bidders/didnavideo.md b/dev-docs/bidders/didnavideo.md new file mode 100644 index 0000000000..c73e778d06 --- /dev/null +++ b/dev-docs/bidders/didnavideo.md @@ -0,0 +1,45 @@ +--- +layout: bidder +title: diDNA Video +description: Prebid diDNA Video Bidder Adapter +pbjs: true +biddercode: didnavideo +aliasCode: aniview +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +safeframes_ok: true +--- + +### Note: +For more information about [diDNA](http://didna.io/). + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `AV_PUBLISHERID` | required | Publisher/Netid | `'55b88d4a181f465b3e8b4567'` | `string` | +| `AV_CHANNELID` | required | Channel id | `'5a5f17a728a06102d14c2718'` | `string` | + +### Test Parameters +``` +videoAdUnit = [ +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'outstream' + }, + }, + bids: [{ + bidder: 'didnavideo', + params: { + AV_PUBLISHERID: '55b78633181f4603178b4568', + AV_CHANNELID: '5d19dfca4b6236688c0a2fc4' + } + }] +}]; +``` diff --git a/dev-docs/bidders/displayio.md b/dev-docs/bidders/displayio.md new file mode 100644 index 0000000000..d7bbe95424 --- /dev/null +++ b/dev-docs/bidders/displayio.md @@ -0,0 +1,37 @@ +--- +layout: bidder +title: Displayio +description: Prebid Displayio Bidder Adapter +biddercode: displayio +media_types: banner, video +gdpr_supported: true +usp_supported: true +safeframes_ok: true +pbjs: true +pbs: false +prebid_member: false +gvl_id: none +--- + +### Note: + +Before configuring the display.io adapter you must reach out your account manager from display.io team (or send a request to contact@display.io) for approval and setup steps. + +### Bid Params + +{: .table .table-bordered .table-striped } + +| Name | Scope | Type | Description | Example | +|----------------| ----- | ---- |----------------------------------------|-------------------------------| +| `siteId` | required | Number | SiteId and PlacementID are your inventory IDs on the display.io platform (please ask your Account Manager for your site and placement IDs). | 7753 | +| `placementId` | required | Number | SiteId and PlacementID are your inventory IDs on the display.io platform (please ask your Account Manager for your site and placement IDs). | 5375 | +| `adsSrvDomain` | required | String | | "appsrv.display.io" | +| `cdnDomain` | required | String | | "cdn.display.io" | +| `pageCategory` | optional | String | Comma-separated list of IAB content categories that describe the current page or view of the site, list of available values. | "pageCategory1, pageCategory2" | +| `keywords` | optional | String | Comma-separated list of keywords describing the content. | "keyword1, keyword2, keyword3" | +| `custom` | optional | Object | User-defined targeting key-value pairs. custom applies to a specific unit. | `{headerTextColor: "red", fixedHeaderSelector: '.site-header'}` | +| `custom.headerText`| optional | String | Ad container header text. By default, text is "Scroll to continue with content". Limited to 50 characters. | "Our awesome advertisement"| +| `custom.headerTextColor`| optional | String | Ad container header text color, "white" by default | "#2196f3"| +| `custom.headerBackgroundColor`| optional | String | Ad container header background color, "black" by default | "#fff" | +| `custom.adContainerBackgroundColor`| optional | String | Ad container body background color, "transparent" by default | "#000"| +| `custom.fixedHeaderSelector`| optional | String | In case your webpage has a fixed header – the header Id attribute or header class attribute should be defined as a value for parameter fixedHeaderSelector. | ".site-header"| diff --git a/dev-docs/bidders/districtm.md b/dev-docs/bidders/districtm.md index aa75acb5f7..17e35d4242 100644 --- a/dev-docs/bidders/districtm.md +++ b/dev-docs/bidders/districtm.md @@ -10,6 +10,7 @@ aliasCode : appnexus sidebarType: 1 isBidder: true gvl_id: 144 +pbjs_version_notes: not supported in 7.0+ --- ### Bid Params diff --git a/dev-docs/bidders/districtmdmx.md b/dev-docs/bidders/districtmdmx.md index 6af35635eb..7eb0b76894 100644 --- a/dev-docs/bidders/districtmdmx.md +++ b/dev-docs/bidders/districtmdmx.md @@ -6,10 +6,11 @@ pbjs: true biddercode: districtmDMX gdpr_supported: true schain_supported: true -getFloor: true +floors_supported: true usp_supported: true coppa_supported: true userIds: britepoolId, criteo, id5Id, identityLink, intentiq, liveIntentId, netId, parrableId, pubCommonId, unifiedId +pbjs_version_notes: not supported in 7.0+ --- @@ -33,4 +34,3 @@ userIds: britepoolId, criteo, id5Id, identityLink, intentiq, liveIntentId, netId | `floor` | optional | Bid floor price | `"1.00"` | `string` | | `revShare` | optional | Publisher Revenue Share | `"0.85"` | `string` | | `currency` | optional | Currency code | `"usd"` | `string` | - diff --git a/dev-docs/bidders/distroscale.md b/dev-docs/bidders/distroscale.md new file mode 100644 index 0000000000..9ae2f745c9 --- /dev/null +++ b/dev-docs/bidders/distroscale.md @@ -0,0 +1,50 @@ +--- +layout: bidder +title: DistroScale +description: Prebid DistroScale Bidder Adaptor +biddercode: distroscale +media_types: banner +pbjs: true +pbs: false +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +fpd_supported: true +userIds: all +floors_supported: true +safeframes_ok: false +prebid_member: true +gvl_id: 754 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------------|-----------------|----------| +| `pubid` | required | Publisher ID | `'12345'` | `string` | +| `zoneid` | optional | Zone ID | `'67890'` | `string` | + + +### Prebid Test Request + +``` +var adUnits = [{ + code: 'banner-1', + mediaTypes: { + banner: { + sizes: [[300, 250]], + } + }, + bids: [{ + bidder: 'distroscale', + params: { + pubid: '12345' // required, must be a string + ,zoneid: '67890' // optional, must be a string + } + }] +}]; +``` + +These test parameters can be used to verify that the DistroScale adapter is working properly. This example includes a DistroScale test publisher ID, an optional zone ID and sizes that would match with the test creative. diff --git a/dev-docs/bidders/djax.md b/dev-docs/bidders/djax.md index 6c9c8200ed..477d34f1ec 100644 --- a/dev-docs/bidders/djax.md +++ b/dev-docs/bidders/djax.md @@ -4,7 +4,8 @@ title: DJAX description: Prebid djax Bidder Adapter pbjs: true biddercode: djax -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/dmx.md b/dev-docs/bidders/dmx.md index 7c34908359..9b6e2968d9 100644 --- a/dev-docs/bidders/dmx.md +++ b/dev-docs/bidders/dmx.md @@ -6,6 +6,7 @@ media_types: banner, video biddercode: dmx gvl_id: 144 gdpr_supported: true +pbjs_version_notes: not supported in 7.0+ --- ### Bid Params diff --git a/dev-docs/bidders/doceree.md b/dev-docs/bidders/doceree.md index 92075772c6..f40812868c 100644 --- a/dev-docs/bidders/doceree.md +++ b/dev-docs/bidders/doceree.md @@ -5,6 +5,8 @@ description: Prebid DivReach Bidder Adapter pbjs: true biddercode: doceree media_types: banner +tcf2_supported: true +gdpr_supported: true --- ### Bid Params @@ -14,3 +16,5 @@ media_types: banner |-------------------|----------|----------------|---------------------------|----------| | `placementId` | required | Placement Id | `'DOC_7jm9j5eqkl0xvc5w'` | `string` | | `publisherUrl` | optional | Current url | `https://doceree.com` | `string` | +| `gdpr` | optional | Flag to check if gdpr applies | `1` | `string` | +| `gdprConsent` | optional | URL-safe base64-encoded Transparency & Consent string | `CPQfU1jPQfU1jG0AAAENAwCAAAAAAAAAAAAAAAAAAAAA.IGLtV_T9fb2vj-_Z99_tkeYwf95y3p-wzhheMs-8NyZeH_B4Wv2MyvBX4JiQKGRgksjLBAQdtHGlcTQgBwIlViTLMYk2MjzNKJrJEilsbO2dYGD9Pn8HT3ZCY70-vv__7v3ff_3g` | `string` | diff --git a/dev-docs/bidders/duration.md b/dev-docs/bidders/duration.md new file mode 100644 index 0000000000..2c2e61cb9a --- /dev/null +++ b/dev-docs/bidders/duration.md @@ -0,0 +1,86 @@ +--- +layout: bidder +title: Duration Media +description: Prebid Duration Media Bidder Adapter +biddercode: duration +aliasCode: nobid +pbjs: true +pbs: true +media_types: banner, video +gdpr_supported: true +gvl_id: 816 +usp_supported: true +schain_supported: true +coppa_supported: true +userId: criteo, unifiedId, id5Id +safeframes_ok: true +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------|---------|----------| +| `siteId` | required | siteId is provided by your Duration Media account manager(s) | | `integer` | +| `placementId` | optional | placementId is provided by your Duration Media account manager(s). This parameter allows to report on a specific ad unit | | `integer` | +| `video`| optional | Object containing video targeting parameters. Note that this parameter is not used in Prebid Server. See [Video Object](#duration-video-object) for details. | `video: { playback_method: ['auto_play_sound_off'] }` | `object`| + + +### Note +If you are using Google Ad Manager (GAM), it is highly recommended to make sure the “Serve in Safeframe” box in creative settings is unchecked. +If you absolutely want to run Duration Media in a Saferame creative, please contact your Duration Media repsentative to coordinate this setup. + + +# Test Parameters +``` + var adUnits = [ + { + code: 'test-div1', + mediaTypes: { + banner: { + sizes: [[300, 250]], // a display size + } + }, + bids: [ + { + bidder: "duration", + params: { + siteId: 2, + placementId: 3 + } + } + ] + },{ + code: 'test-div2', + mediaTypes: { + banner: { + sizes: [[320, 50]], // a mobile size + } + }, + bids: [ + { + bidder: "duration", + params: { + siteId: 2 + } + } + ] + } + ]; +``` + + + +#### Video Object + +{: .table .table-bordered .table-striped } +| Name | Description | Type | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `skippable` | Boolean which, if `true`, means the user can click a button to skip the video ad. Defaults to `false`. | `boolean` | +| `playback_method` | Array of strings listing playback methods supported by the publisher. Allowed values: `"auto_play_sound_on"`; `"auto_play_sound_off"`; `"click_to_play"`; `"mouseover"`; `"auto_play_sound_unknown"`; `"viewport_sound_on"`, `"viewport_sound_off"`. | `Array` | +| `position` | Array of strings listing video player position supported by the publisher. Allowed values: `"na"`, `"atf"`, `"btf"`, `"head"`, `"foot"`, `"sidebar"`, `"full"`. | `Array` | +| `mimes` | Array of strings listing the content MIME types supported, e.g., `["video/x-flv", "video/x-ms-wmv"]`. | `Array` | +| `minduration` | Integer that defines the minimum video ad duration in seconds. | `integer` | +| `maxduration` | Integer that defines the maximum video ad duration in seconds. | `integer` | +| `frameworks` | Array of integers listing API frameworks supported by the publisher. Allowed values: None: `0`; VPAID 1.0: `1`; VPAID 2.0: `2`; MRAID 1.0: `3`; ORMMA: `4`; MRAID 2.0: `5`. | `Array` | + diff --git a/dev-docs/bidders/e_volution.md b/dev-docs/bidders/e_volution.md index 867093350f..0a0da06563 100644 --- a/dev-docs/bidders/e_volution.md +++ b/dev-docs/bidders/e_volution.md @@ -11,7 +11,8 @@ pbs: true pbs_app_supported: true usp_supported: true schain_supported: true -pbjs_version_notes: not in 5.x +pbjs_version_notes: in 6.8+ +userIds: id5Id --- ### Note: diff --git a/dev-docs/bidders/ebdr.md b/dev-docs/bidders/ebdr.md index 2218f1ca60..56036ed355 100644 --- a/dev-docs/bidders/ebdr.md +++ b/dev-docs/bidders/ebdr.md @@ -5,7 +5,6 @@ description: Prebid EngageBDR Bidder Adaptor biddercode: ebdr pbjs: true media_types: video -pbjs_version_notes: not in 5.x --- ### Bid params diff --git a/dev-docs/bidders/edgequeryx.md b/dev-docs/bidders/edgequeryx.md index 5731ce33d1..11451f6332 100644 --- a/dev-docs/bidders/edgequeryx.md +++ b/dev-docs/bidders/edgequeryx.md @@ -8,7 +8,8 @@ media_types: display gdpr_supported: true schain_supported: true usp_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/emoteev.md b/dev-docs/bidders/emoteev.md index 553a9b236c..d9731d89ba 100644 --- a/dev-docs/bidders/emoteev.md +++ b/dev-docs/bidders/emoteev.md @@ -6,7 +6,8 @@ pbjs: true biddercode: emoteev gdpr_supported: true userIds: pubCommonId -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/emx_digital.md b/dev-docs/bidders/emx_digital.md index f87facc38e..00acc8c306 100644 --- a/dev-docs/bidders/emx_digital.md +++ b/dev-docs/bidders/emx_digital.md @@ -10,6 +10,7 @@ gdpr_supported: true gvl_id: 183 usp_supported: true schain_supported: true +userIds: identityLink, uid2 --- ### Registration diff --git a/dev-docs/bidders/engageya.md b/dev-docs/bidders/engageya.md index 1e8066d8c4..a085c9bd45 100644 --- a/dev-docs/bidders/engageya.md +++ b/dev-docs/bidders/engageya.md @@ -6,7 +6,6 @@ media_type: banner, native biddercode: engageya pbjs: true gdpr_supported: true -pbjs_version_notes: not in 5.x --- ### Bid params diff --git a/dev-docs/bidders/envivo.md b/dev-docs/bidders/envivo.md index b5e2771e3f..b19dd59148 100644 --- a/dev-docs/bidders/envivo.md +++ b/dev-docs/bidders/envivo.md @@ -4,7 +4,8 @@ title: envivo description: Prebid envivo Bidder Adapter pbjs: true biddercode: envivo -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/epom.md b/dev-docs/bidders/epom.md index 228670bceb..d1d5897a28 100644 --- a/dev-docs/bidders/epom.md +++ b/dev-docs/bidders/epom.md @@ -10,7 +10,7 @@ coppa_supported: true schain_supported: false media_types: banner, video, native safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: false pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/ergadx.md b/dev-docs/bidders/ergadx.md new file mode 100644 index 0000000000..2aedf405a1 --- /dev/null +++ b/dev-docs/bidders/ergadx.md @@ -0,0 +1,27 @@ +--- +layout: bidder +title: eRGADX +description: eRGADX Bidder Adaptor +pbjs: true +pbs: true +biddercode: ergadx +aliasCode : adkernel +media_types: banner, native, video +gdpr_supported: true +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +--- + +### Note: + +The eRGADX bidding adapter requires setup and approval before implementation. Please reach out to for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.ergadx.com'` | `string` | +| `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/etarget.md b/dev-docs/bidders/etarget.md index 251697a776..d68eeb522f 100644 --- a/dev-docs/bidders/etarget.md +++ b/dev-docs/bidders/etarget.md @@ -2,18 +2,81 @@ layout: bidder title: Etarget description: Prebid Etarget Bidder Adaptor -pbjs: true biddercode: etarget media_types: banner, video gdpr_supported: true +usp_supported: true +pbjs: true +fpd_supported: true +gvl_id: 29 --- - ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | | :--- | :---- | :---------- | :------ | -| `refid` | required | | `12345` | +| `refid` | required | Placement ID | `12345` | | `country` | required | Country domain | `1` | +| `options` | optional | Additional data | `{site:'example.com'}` | + +#### First Party Data + +In release 5.0 and later, publishers should use the `ortb2` method of setting First Party Data. The following fields are supported: +- ortb2.site.ext.data.* +- ortb2.site.keywords +- ortb2.site.content.data[] +- ortb2.user.ext.data.* +- ortb2.user.data[] + +The ETARGET exchange supports the IAB standard Audience Taxonomy v1.1 and Content Taxonomy v2.2. + +Example first party data that's available to all bidders and all adunits: +``` +pbjs.setConfig({ + ortb2: { + site: { + keywords: "kw1,kw2", + ext: { + data: { + prodtype: ["tech","mobile"] + } + } + }, + user: { + ext: { + data: { + ucat:["new"] + } + } + } + } +}; +``` + +Example of first party data available only to the ETARGET bidder. Applies across all ad units. +``` +pbjs.setBidderConfig({ + bidders: ["etarget"], + config: { + ortb2: { + site: { + keywords: "kw1,kw2", + ext: { + data: { + prodtype: ["tech","mobile"] + } + } + }, + user: { + ext: { + data: { + ucat:["new"] + } + } + } + } + } +}; +``` diff --git a/dev-docs/bidders/feedad.md b/dev-docs/bidders/feedad.md index 14bb43c6a8..bfcf75ec66 100644 --- a/dev-docs/bidders/feedad.md +++ b/dev-docs/bidders/feedad.md @@ -16,3 +16,4 @@ gvl_id: 781 |---------------|----------|----------------------------------------------------------|----------------------------------------------------------|----------| | `clientToken` | required | Your FeedAd client token. Check your FeedAd admin panel. | `'EiRjZDFiYzI2ZC03OTA2LTQyOTEtOGFmMC0xYzMyZmMwNTFkMDU='` | `string` | | `placementId` | required | A FeedAd placement ID of your choice | `'prebid-test'` | `string` | +| `decoration` | optional | A decoration to apply to the ad slot. See our [documentation](https://docs.feedad.com/web/feed_ad/#decorations) | `'sticky bottom height=200px'` | `string` | diff --git a/dev-docs/bidders/felixads.md b/dev-docs/bidders/felixads.md new file mode 100644 index 0000000000..9bc6ed33c7 --- /dev/null +++ b/dev-docs/bidders/felixads.md @@ -0,0 +1,28 @@ +--- +layout: bidder +title: felixads +description: Prebid felixads Bidder Adaptor +pbjs: true +pbs: false +biddercode: felixads +aliascode: adkernel +media_types: banner, native, video +gdpr_supported: true +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +userIds: all +--- + +### Note: + +The felixads Bidding adaptor requires setup and approval before beginning. Please reach out to for more details + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | felixads's RTB host | `'cpm.felixads.com'` | `string` | +| `zoneId` | required | RTB zone id | `'30164'` | `integer` | diff --git a/dev-docs/bidders/fidelity.md b/dev-docs/bidders/fidelity.md index 2ccca5fb16..f18a36bf0b 100644 --- a/dev-docs/bidders/fidelity.md +++ b/dev-docs/bidders/fidelity.md @@ -9,7 +9,8 @@ media_types: banner gdpr_supported: true usp_supported: true gvl_id: 408 -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/finative.md b/dev-docs/bidders/finative.md new file mode 100644 index 0000000000..9dff5844c5 --- /dev/null +++ b/dev-docs/bidders/finative.md @@ -0,0 +1,17 @@ +--- +layout: bidder +title: Finative +description: Prebid Finative Bidder Adaptor +pbjs: true +biddercode: finative +media_types: native +gdpr_supported: true +--- + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------|--------------------|-----------| +| `adUnitId` | required | ID of the Ad Unit | `8ao` | `string` | +| `url` | optional | URL from the Page | `example.tld` | `string` | diff --git a/dev-docs/bidders/fluct.md b/dev-docs/bidders/fluct.md index 9360ed72d2..5403970b0d 100644 --- a/dev-docs/bidders/fluct.md +++ b/dev-docs/bidders/fluct.md @@ -9,7 +9,6 @@ coppa_supported: false usp_supported: false schain_supported: true pbjs: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/futureads.md b/dev-docs/bidders/futureads.md new file mode 100644 index 0000000000..016a8fa997 --- /dev/null +++ b/dev-docs/bidders/futureads.md @@ -0,0 +1,24 @@ +--- +layout: bidder +title: FutureAds +description: Prebid FutureAds Bidder Adaptor +pbjs: true +pbs: true +biddercode: futureads +aliasCode: admixer +media_types: banner, video, native +gdpr_supported: true +usp_supported: true +schain_supported: true +gvl_id: 511 +userIds: AdmixerID +prebid_member: true +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|----------------------------------------------------------------------------------------------------------------|----------------------------------------|----------| +| `zone` | required | The unique identifier of the ad placement. Could be obtained from the FutureAds UI or from your account manager. | "e5ff8e48-4bd0-4a2c-9236-55530ab8981d" | `string` | +| `kvTargeting` | optional | Key/Value - a pair of the unique values that will be used for the custom targeting option. | {key1: value2, key2: value2} | `object` | diff --git a/dev-docs/bidders/gamma.md b/dev-docs/bidders/gamma.md index c514b25192..3935c66e0e 100644 --- a/dev-docs/bidders/gamma.md +++ b/dev-docs/bidders/gamma.md @@ -6,7 +6,6 @@ pbjs: true pbs: true biddercode: gamma media_types: video -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/getintent.md b/dev-docs/bidders/getintent.md index 6e0f519249..671ec6fe1f 100644 --- a/dev-docs/bidders/getintent.md +++ b/dev-docs/bidders/getintent.md @@ -4,8 +4,8 @@ title: GetIntent description: Prebid GetIntent Bidder Adaptor pbjs: true biddercode: getintent -media_types: video -pbjs_version_notes: not in 5.x +media_types: video, banner +floors_supported: true --- @@ -24,6 +24,22 @@ pbjs_version_notes: not in 5.x #### video +Adapter supports the following mediaTypes.video parameters: + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|--------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|------------------| +| `protocols` | optional | The list of the restricted VAST protocol versions. Possible values: `1` – VAST 1.0, `2` – VAST 2.0, `3` – VAST 3.0, `4` – VAST 1.0 Wrapper, `5` – VAST 2.0 Wrapper, `6` – VAST 3.0 Wrapper. | `[4,5,6]` | `Array` | +| `mimes` | optional | Array of Mime Type strings. | `['application/javascript']` | `Array` | +| `minduration`| optional | Minimal video duration. | `30` | `integer` | +| `maxduration`| optional | Maximal video duration. | `30` | `integer` | +| `minbitrate` | optional | Minimal Video bitrate. | `256` | `integer` | +| `maxbitrate` | optional | Maximal Video bitrate. | `512` | `integer` | +| `api` | optional | API of the inventory. Possible values: `1` - VPAID 1.0, `2` - VPAID 2.0, `3` - MRAID-1, `4` - ORMMA, `5` - MRAID-2. | `[3,4]` | `Array` | +| `skip` | optional | Skippability of the inventory. Possible values (case insensitive): `1` - skippable inventory is allowed, `0` - skippable inventory is not allowed. | `0` | `integer` | + +List of custom parameters available at bidder params level + {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|------------------| diff --git a/dev-docs/bidders/glimpse.md b/dev-docs/bidders/glimpse.md index a505282776..ae5a245ee7 100644 --- a/dev-docs/bidders/glimpse.md +++ b/dev-docs/bidders/glimpse.md @@ -1,95 +1,126 @@ --- layout: bidder title: Glimpse Protocol -description: Glimpse Protocol Bidder Adapter +description: Glimpse Protocol Bid Adapter biddercode: glimpse pbjs: true gdpr_supported: true +usp_supported: true +deals_supported: true media_types: banner +gvl_id: 1012 --- ## Overview ``` -Module Name: Glimpse Protocol Adaptor +Module Name: Glimpse Protocol Bid Adapter Module Type: Bidder Adapter -Maintainer: tim@glimpseprotocol.io +Maintainer: support@glimpseportal.io ``` ## Description -This module connects publishers to Glimpse Protocol's demand sources via Prebid.js. Our -innovative marketplace protects consumer privacy while allowing precise targeting. It is -compliant with GDPR, DPA and CCPA. +Glimpse protects consumer privacy while allowing precise targeting. This module connects publishers +to Glimpse Protocol's demand sources via Prebid.js. -This module was built and tested against prebid 3.21.0 and so compatibility against -version 2 and earlier is unknown. +## Supported Media Types -## Media Types +{: .table .table-bordered .table-striped } +| Type | Sizes | +| -------- | ----------------------------------------- | +| `Banner` | 300x250, 300x600, 320x50, 728x90, 970x250 | -| Type | Support | -| -------- | ------------------------------------------------------------------ | -| `Banner` | Fully supported for 320x50, 300x250, 300x600, 728x90, and 970x250. | +## Setup -## Bid Parameters +### Prerequisites -The only parameter is `placementId` and it is required. +Before you start, you will need to build a `prebid.js` file with the Glimpse module included, and include both `gpt.js` and `prebid.js` in the `head` of each page with supply. An example of a typical pair of script tags might be: -### Banner +```html + -| Name | Scope | Description | Example | Type | -| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ | -| `placementId` | Required | An identifier associated unique to a publisher and ad unit. Values can be obtained through our publisher portal. | 'glimpse-demo-300x250' | String | - -## Setup Guide - -Follow these steps to configure and add the glimpse module to your Prebid.js integration. + +``` -### 0. Preconditions +## Configuration -- A built prebid module with the glimpse adaptor included -- You've included the built prebid adaptor and GPT script in your websites html code -- You've setup GAM mappings +### Bid Requests -### 1. Create an account and setup your domain via the Publisher Portal +Our adapter expects the following values in the `params` block of each bid request: -Coming soon. +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | Example | +| ----- | -------- | ------ | --------------------------------------------------------------------------------------------------- | ---------------------- | +| `pid` | Required | string | A unique identifier representing an ad unit. It is provided by Glimpse when registering an ad unit. | 'glimpse-placement-id' | -### 2. Enable Glimpse as a bidder on your ad units +#### Example ```javascript -const adUnits = { - code: 'your-ad-unit-div-id', - mediaTypes: { - banner: { - sizes: [[300, 250]], +const units = [ + { + code: "ad-unit-0", + mediaTypes: { + banner: { sizes: [[300, 250]] }, }, - }, - bids: [ - { - bidder: 'glimpse', - params: { - placementId: 'placementId-from-publisher-portal', + bids: [ + { + bidder: "glimpse", + params: { + pid: "glimpse-placement-id", + }, }, - }, - ... - ], - ... -} + ], + }, +] ``` -## FAQs +### First Party Data -### Can I test my setup without a Publisher Portal Account? +Our adapter works with first party data providers as described [here](https://docs.prebid.org/features/firstPartyData.html). In this example we add Permutive data to our bidder request using [setBidderConfig](https://docs.prebid.org/features/firstPartyData.html#supplying-bidder-specific-data). -Yep. Use a demo placementId: +#### Example -- glimpse-demo-320x50 -- glimpse-demo-300x250 -- glimpse-demo-300x600 -- glimpse-demo-728x90 -- glimpse-demo-970x250 +```javascript +pbjs.que.push(() => { + pbjs.setBidderConfig({ + bidders: ["glimpse"], + config: { + ortb2: { + site: { + keywords: "business,finance,crypto", + ext: { + data: { + permutive: { + pvc: JSON.parse(localStorage.getItem("permutive-pvc")) ?? {}, + }, + }, + }, + }, + user: { + ext: { + data: { + permutive: { + keywords: JSON.parse(localStorage.getItem("_psegs")) ?? [], + enrichers: + JSON.parse( + localStorage.getItem("permutive-data-enrichers") + ) ?? {}, + }, + }, + }, + }, + }, + }, + }) +}) +``` + +## FAQs -### How do I get more help? +### Can you provide additional support? -Reach out to us at [hello@glimpseprotocol.io](mailto:hello@glimpseprotocol.io) +Of course! You can check the Glimpse Prebid Adapter documentation [here](https://docs.glimpseportal.io/en/latest/) or reach out to us at [support@glimpseportal.io](mailto:support@glimpseportal.io). diff --git a/dev-docs/bidders/gmossp.md b/dev-docs/bidders/gmossp.md index 98b20a2ee2..06d4f21a3c 100644 --- a/dev-docs/bidders/gmossp.md +++ b/dev-docs/bidders/gmossp.md @@ -4,6 +4,7 @@ title: GMOSSP description: Prebid GMOSSP Bidder Adaptor pbjs: true biddercode: gmossp +userIds: imuid, sharedId, identityLink media_types: banner --- diff --git a/dev-docs/bidders/gnet.md b/dev-docs/bidders/gnet.md index 8cd6b3af53..70af8f195d 100644 --- a/dev-docs/bidders/gnet.md +++ b/dev-docs/bidders/gnet.md @@ -1,10 +1,9 @@ --- layout: bidder -title: gnet +title: Gnet description: Prebid Gnet Bidder Adaptor pbjs: true biddercode: gnet -pbjs_version_notes: not in 5.x --- ### Bid Params @@ -12,6 +11,6 @@ pbjs_version_notes: not in 5.x {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|--------------------------------------------|-------------------------------------|----------| -| `websiteId` | required | The Gnet website ID | `'4'` | `string` | -| `externalId` | required | The Gnet external ID | `'4d52cccf30309282256012cf30309282'` | `string` | +| `websiteId` | required | The Gnet website ID | `'1'` | `string` | +| `adunitId` | required | The Gnet adunit ID | `'1'` | `string` | diff --git a/dev-docs/bidders/go2net.md b/dev-docs/bidders/go2net.md index 7210f822de..f1ce1099d6 100644 --- a/dev-docs/bidders/go2net.md +++ b/dev-docs/bidders/go2net.md @@ -11,6 +11,7 @@ media_types: video ### bid params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|--------|----------|-------------|---------|----------| -| `zone` | required | | | `string` | +| Name | Scope | Description | Example | Type | +|---------------|----------|----------------------------------------------------------------------------------------------------------------|----------------------------------------|----------| +| `zone` | required | The unique identifier of the ad placement. Could be obtained from the Go2Net UI or from your account manager. | "e5ff8e48-4bd0-4a2c-9236-55530ab8981d" | `string` | +| `kvTargeting` | optional | Key/Value - a pair of the unique values that will be used for the custom targeting option. | {key1: value2, key2: value2} | `object` | diff --git a/dev-docs/bidders/goldbach.md b/dev-docs/bidders/goldbach.md new file mode 100644 index 0000000000..6f9b4f7fc5 --- /dev/null +++ b/dev-docs/bidders/goldbach.md @@ -0,0 +1,199 @@ +--- +layout: bidder +title: Goldbach +description: Prebid Goldbach Bidder Adaptor +biddercode: goldbach +media_types: banner, video, native +gdpr_supported: true +prebid_member: true +userIds: criteo, unifiedId, netId, identityLink, flocId, uid2 +schain_supported: true +coppa_supported: true +usp_supported: true +getFloor: true +pbjs: true +pbs: true +--- + +### Table of Contents + +- [Bid Params](#godlbach-bid-params) +- [Video Object](#godlbach-video-object) +- [User Object](#godlbach-user-object) +- [App Object](#godlbach-app-object) +- [Custom Targeting keys](#custom-targeting-keys) +- [Passing Keys Without Values](#godlbach-no-value) +- [User Sync in AMP](#godlbach-amp) +- [Debug Auction](#godlbach-debug-auction) + + + +{: .alert.alert-danger :} +All Goldbach (Xandr) placements included in a single call to `requestBids` must belong to the same parent Publisher. If placements from two different publishers are included in the call, the Goldbach bidder will not return any demand for those placements.
    +*Note: This requirement does not apply to adapters that are [aliasing](/dev-docs/publisher-api-reference/aliasBidder.html) the Goldbach adapter.* + +#### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| +| `placementId` | required | The placement ID from Goldbach. You may identify a placement using the `invCode` and `member` instead of a placement ID. The `placementID` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. Legacy code can retain the `string` value. **Prebid Server requires an integer value.** | `234234` | `integer` | +| `member` | optional | The member ID from Goldbach. Must be used with `invCode`. | `'12345'` | `string` | +| `invCode` | optional | The inventory code from Goldbach. Must be used with `member`. | `'abc123'` | `string` | +| `publisherId` | optional | The publisher ID from Goldbach. It is used by the Goldbach end point to identify the publisher when `placementId` is not provided and `invCode` goes wrong. The `publisherId` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. | `12345` | `integer` | +| `frameworks` | optional | Array of integers listing API frameworks for Banner supported by the publisher. | `integer` | +| `user` | optional | Object that specifies information about an external user. See [User Object](#godlbach-user-object) for details. | `user: { age: 25, gender: 0, dnt: true}` | `object` | +| `allowSmallerSizes` | optional | If `true`, ads smaller than the values in your ad unit's `sizes` array will be allowed to serve. Defaults to `false`. | `true` | `boolean` | +| `usePaymentRule` (PBJS) or `use_pmt_rule` (PBS) | optional | If `true`, Xandr will return net price to Prebid.js after publisher payment rules have been applied. | `true` | `boolean` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Mapped to [buy-side segment targeting](https://monetize.xandr.com/docs/segment-targeting) (login required). Values can be empty. See [Passing Keys Without Values](#godlbach-no-value) below for examples. Note that to use keyword with the Prebid Server adapter, that feature must be enabled for your account by an Goldbach account manager. | `keywords: { genre: ['rock', 'pop'] }` | `object` | +| `video` | optional | Object containing video targeting parameters. See [Video Object](#godlbach-video-object) for details. | `video: { playback_method: ['auto_play_sound_off'] }` | `object` | +| `app` | optional | Object containing mobile app parameters. See the [App Object](#godlbach-app-object) for details. | `app : { id: 'app-id'}` | `object` | +| `reserve` | optional | Sets a floor price for the bid that is returned. If floors have been configured in the Goldbach Console, those settings will override what is configured here unless 'Reserve Price Override' is checked. See [Xandr docs](https://docs.xandr.com/bundle/monetize_monetize-standard/page/topics/create-a-floor-rule.html) | `0.90` | `float` | +| `position` | optional | Identify the placement as above or below the fold. Allowed values: Unknown: `unknown`; Above the fold: `above`; Below the fold: `below` | `'above'` | `string` | +| `trafficSourceCode` | optional | Specifies the third-party source of this impression. | `'my_traffic_source'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `pubClick` | optional | Specifies a publisher-supplied URL for third-party click tracking. This is just a placeholder into which the publisher can insert their own click tracker. This parameter should be used for an unencoded tracker. This parameter is expected to be the last parameter in the URL. Please note that the click tracker placed in this parameter will only fire if the creative winning the auction is using Goldbach click tracking properly. | `'http://click.adserver.com/'` | `string` | +| `extInvCode` | optional | Specifies predefined value passed on the query string that can be used in reporting. The value must be entered into the system before it is logged. | `'10039'` | `string` | +| `externalImpId` | optional | Specifies the unique identifier of an externally generated auction. | `'bacbab02626452b097f6030b3c89ac05'` | `string` | +| `generate_ad_pod_id`| optional | Signal to Goldbach to split impressions by ad pod and add unique ad pod id to each request. Specific to long form video endpoint only. Supported by Prebid Server, not Prebid JS. | `true` | `boolean` | + +     + +#### Video Object + +{: .table .table-bordered .table-striped } +| Name | Description | Type | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `minduration` | Integer that defines the minimum video ad duration in seconds. | `integer` | +| `maxduration` | Integer that defines the maximum video ad duration in seconds. | `integer` | +|`context` | A string that indicates the type of video ad requested. Allowed values: `"pre_roll"`; `"mid_roll"`; `"post_roll"`; `"outstream"`. | `string` | +| `skippable` | Boolean which, if `true`, means the user can click a button to skip the video ad. Defaults to `false`. | `boolean` | +|`skipoffset`| Integer that defines the number of seconds until an ad can be skipped. Assumes `skippable` setting was set to `true`. | `integer` | +| `playback_method` | A string that sets the playback method supported by the publisher. Allowed values: `"auto_play_sound_on"`; `"auto_play_sound_off"`; `"click_to_play"`; `"mouse_over"`; `"auto_play_sound_unknown"`. | `string` | +| `frameworks` | Array of integers listing API frameworks supported by the publisher. Allowed values: None: `0`; VPAID 1.0: `1`; VPAID 2.0: `2`; MRAID 1.0: `3`; MRAID 2.0: `4`; ORMMA: `5`; OMID 1.0 `6`. | `Array` | + + + + +#### User Object + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|------------------| +| `age` | The age of the user. | `35` | `integer` | +| `externalUid` | Specifies a string that corresponds to an external user ID for this user. | `'1234567890abcdefg'` | `string` | +| `segments` | Specifies the segments to which the user belongs. | `[1, 2]` | `Array` | +| `gender` | Specifies the gender of the user. Allowed values: Unknown: `0`; Male: `1`; Female: `2` | `1` | `integer` | +| `dnt` | Do not track flag. Indicates if tracking cookies should be disabled for this auction | `true` | `boolean` | +| `language` | Two-letter ANSI code for this user's language. | `EN` | `string` | + + + + +#### App Object + +Goldbach supports using prebid within a mobile app's webview. If you are interested in using an SDK, please see [Prebid Mobile]({{site.baseurl}}/prebid-mobile/prebid-mobile.html) instead. + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|------------------| +| `id` | The App ID. | `'B1O2W3M4AN.com.prebid.webview'` | `string` | +| `device_id` | Object that contains the advertising identifiers of the user (`idfa`, `aaid`, `md5udid`, `sha1udid`, or `windowsadid`). | `{ aaid: "38400000-8cf0-11bd-b23e-10b96e40000d" }` | `object` | +| `geo` | Object that contains the latitude (`lat`) and longitude (`lng`) of the user. | `{ lat: 40.0964439, lng: -75.3009142 }` | `object` | + + + +#### Custom Targeting keys + +Goldbach returns custom keys that can be sent to the adserver through bidderSettings: buyerMemberId, dealPriority, and dealCode. The following snippet demonstrates how to add these custom keys as key-value pairs. + +``` +pbjs.bidderSettings = { + godlbach: { + adserverTargeting: [ + { + key: "apn_buyer_memberid", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.buyerMemberId; + } + }, + { + key: "apn_prio", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.dealPriority; + } + }, { + key: "apn_dealcode", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.dealCode; + } + } + ] + } +} +``` + + + +#### Passing Keys Without Values + +It's possible to use the `keywords` parameter to define keys that do not have any associated values. Keys with empty values can be created in Prebid.js and can also be sent through Prebid Server to Goldbach. The following are examples of sending keys with empty values: + + +``` +keywords: { + myKeyword: '', + myOtherKeyword: [''] +} +``` + +The preceding example passes the key `myKeyword` with an empty value. The key `myOtherKeyword` contains an empty value array. + +You can define keys with values and without values in the same `keywords` definition. In this next example, we've defined the key `color` with an array of values: `red`, `blue`, and `green`. We've followed that with the key `otherKeyword` with an empty value array. + +``` +keywords: { + color: ['red', 'blue', 'green'], + otherKeyword: [''] +} +``` + + + +#### User Sync in AMP + +If you are syncing user id's with Prebid Server and are using Goldbach's managed service, see [AMP Implementation Guide cookie-sync instructions](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for details. + + + +#### Mobile App Display Manager Version + +The Goldbach endpoint expects `imp.displaymanagerver` to be populated for mobile app sources +requests, however not all SDKs will populate this field. If the `imp.displaymanagerver` field +is not supplied for an `imp`, but `request.app.ext.prebid.source` +and `request.app.ext.prebid.version` are supplied, the adapter will fill in a value for +`diplaymanagerver`. It will concatenate the two `app` fields as `-` fo fill in +the empty `displaymanagerver` before sending the request to Goldbach. + +#### Debug Auction + +{: .alert.alert-danger :} +Enabling the Goldbach Debug Auction feature should only be done for diagnosing the Goldbach auction. Do not enable this feature in a production setting where it may impact users. + +To understand what is happening behind the scenes during an auction, you can enable a debug auction by adding an `apn_prebid_debug` cookie with a JSON string. For example: + +{% highlight js %} +{ "enabled": true, "dongle": "QWERTY", "debug_timeout": 1000, "member_id": 958 } +{% endhighlight %} + +To view the results of the debug auction, add the `pbjs_debug=true` query string parameter and open your browser's developer console. + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|-----------------------------------------------------------------|-----------------------|------------------| +| `enabled` | Toggle the debug auction to occur | `true` | `boolean` | +| `dongle` | Your account's unique debug password. | `QWERTY` | `string` | +| `member_id` | The ID of the member running the debug auction | `958` | `integer` | +| `debug_timeout` | The timeout for the debug auction results to be returned | `3000` | `integer` | + diff --git a/dev-docs/bidders/gothamads.md b/dev-docs/bidders/gothamads.md index e3fabc29e7..d41aa86cbd 100644 --- a/dev-docs/bidders/gothamads.md +++ b/dev-docs/bidders/gothamads.md @@ -10,7 +10,7 @@ ccpa_supported: true schain_supported: true media_types: banner, video, native safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true --- diff --git a/dev-docs/bidders/grid.md b/dev-docs/bidders/grid.md index c6a619cc28..acaee18643 100644 --- a/dev-docs/bidders/grid.md +++ b/dev-docs/bidders/grid.md @@ -6,15 +6,24 @@ pbjs: true pbs: true biddercode: grid media_types: banner, video +multiformat_supported: will-bid-on-any gdpr_supported: true usp_supported: true schain_supported: true -getFloor: true +floors_supported: true userIds: all tcf2_supported: true coppa_supported: true +fpd_supported: true --- +### Table of Contents + +- [Bid Params](#grid-bid-params) +- [Bidder Config](#grid-bidder-config) +- [First Party Data](#grid-first-party) + + ### Bid Params @@ -24,3 +33,62 @@ coppa_supported: true | `uid` | required | Represents the MediaGrid bidder system Ad Slot ID associated with the respective div id from the site page. | `1` | `integer` | | `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | | `bidFloor` | optional | Floor of the impression opportunity. If present in the request overrides XML info. | `0.8` | `float` | + +Parameter `keywords` must have following format: +``` +{ + "site":{ + "publisher1":[ + { + "name":"SomeKeywordsBlockName", + "segment1Name":[ + "segment2Value" + ], + "segment2Name":[ + "segment2Value1", + "segment2Value2", + ... + ], + ... + } + ], + ... + } +} +``` + + + +### Bidder Config + +You can allow writing in localStorage `pbjs.setBidderConfig` for the bidder `grid` +``` +pbjs.setBidderConfig({ + bidders: ["grid"], + config: { + localStorageWriteAllowed: true + } +}) +``` +If it will be "true" this allow TheMediaGrid Bid Adapter to write userId in first party localStorage + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.ext.device`: Non standard arbitrary user device +- `ortb2.user.keywords`: Standard IAB OpenRTB 2.5 user.keywords field. It will be included in ext.keywords.user.ortb2 +- `ortb2.site.keywords`: Standard IAB OpenRTB 2.5 site.keywords field. It will be included in ext.keywords.site.ortb2 +- `ortb2.site.cat[]`: Standard IAB OpenRTB 2.5 site.cat field. It will be sent as part of site.cat array +- `ortb2.site.pagecat[]`: Standard IAB OpenRTB 2.5 site.pagecat field. It will be sent as part of site.cat array +- `ortb2.site.content.genre`: Standard IAB OpenRTB 2.5 site.content.genre field + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` +- `ortb2.imp[].instl` diff --git a/dev-docs/bidders/gridNM.md b/dev-docs/bidders/gridNM.md index 3524b8df87..ba1c7c1d2f 100644 --- a/dev-docs/bidders/gridNM.md +++ b/dev-docs/bidders/gridNM.md @@ -7,6 +7,7 @@ biddercode: gridNM media_types: video gdpr_supported: true usp_supported: true +fpd_supported: true --- @@ -34,3 +35,9 @@ usp_supported: true | `video.startdelay` | optional | Indicates the start delay in seconds | `0` | `int` | | `video.placement` | optional | Placement type for the impression. | `1` | `int` | | `video.playbackmethod` | optional | Playback methods that may be in use | `[1]` | `integer array` | + +### First Party Data + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` diff --git a/dev-docs/bidders/groupm.md b/dev-docs/bidders/groupm.md new file mode 100644 index 0000000000..166b07d703 --- /dev/null +++ b/dev-docs/bidders/groupm.md @@ -0,0 +1,93 @@ +--- +layout: bidder +title: GroupM +description: Prebid GroupM Bidder Adaptor +biddercode: groupm +aliasCode: pubmatic +media_types: banner, video, native +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +floors_supported: true +userIds: all +prebid_member: true +safeframes_ok: true +pbjs: true +pbs: true +pbs_app_supported: true +fpd_supported: true +gvl_id: 98 +pbjs_version_notes: not supported in 6.24+ +--- + +{: .alert.alert-warning :} +This bidder is not available in PBJS 6.24 and later. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------------|------------------------------|----------| +| `publisherId` | required | Publisher ID | `'32572'` | `string` | +| `adSlot` | optional | Ad Slot Name (see below)| `'38519891'` | `string` | +| `pmzoneid` | optional | Zone ID | `'zone1,zone2'` | `string` | +| `lat` | optional | Latitude | `'40.712775'` | `string` | +| `lon` | optional | Longitude | `'-74.005973'` | `string` | +| `yob` | optional | Year of Birth | `'1982'` | `string` | +| `gender` | optional | Gender | `'M'` | `string` | +| `kadpageurl` | optional | Overrides Page URL | `'http://www.yahoo.com/'`| `string` | +| `kadfloor` | optional | Bid Floor | `'1.75'` | `string` | +| `currency` | optional | Bid currency | `'AUD'` (Value configured only in the 1st adunit will be passed on.
    Values if present in subsequent adunits, will be ignored.) | `string` | +| `dctr` | optional | Deal Custom Targeting
    (Value configured only in the 1st adunit will be passed on.
    Values if present in subsequent adunits, will be ignored.) | `'key1=123\|key2=345'` | `string` | +| `bcat` | optional | Blocked IAB Categories
    (Values from all slots will be combined and only unique values will be passed. An array of strings only. Each category should be a string of a length of more than 3 characters.) | `[ 'IAB1-5', 'IAB1-6', 'IAB1-7' ]` | `array of strings` | +| `deals` | optional | PMP deals
    (Values from each slot will be passed per slot. An array of strings only. Each deal-id should be a string of a length of more than 3 characters.) | `[ 'deal-id-5', 'deal-id-6', 'deal-id-7' ]` | `array of strings` | +| `outstreamAU` | optional | Oustream AdUnit described in Blue BillyWig UI. This field is mandatory if mimeType is described as video and context is outstream (i.e., for outstream videos) | `'renderer_test_groupm'` | `string` | + +GroupM is an aliased bidder of PubMatic + +### Prebid Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------------|------------------------------|----------| +| `publisherId` | required | Publisher ID | `"32572"` | `string` | +| `adSlot` | optional | Ad Slot Name | `"38519891"` | `string` | +| `pmzoneid` | optional | Comma separated zone id. Used im deal targeting & site section targeting. e.g drama,sport| `"zone1,zone2"` | `string` | +| `dctr` | optional | Deal Custom Targeting, pipe separated key-value pairs| `"key1=123\|key2=345"` | `string` | +| `wrapper` | optional | Specifies GroupM openwrap configuration for a publisher | `"wrapper": { "profile": 123, "version": 1}` | `object` | +| `keywords` | optional | A set of key-value pairs; A key can have one or more values associated with it. They are used in buy-side segment targeting.| `"keywords": { "genre": ["rock", "pop"] }` | `object` | + + + +### Prebid Server Test Request + +The following test parameters can be used to verify that Prebid Server is working properly with the +GroupM adapter. This example includes an `imp` object with an GroupM test publisher ID, ad slot, +and sizes that would match with the test creative. + +``` +"imp":[ + { + "id":“"some-impression-id”, + "banner":{ + "format":[ + { + "w":300, + "h":250 + }, + { + "w":300, + "h":600 + } + ] + }, + "ext":{ + "groupm":{ + "publisherId":“156276”, + "adSlot":"groupm_test" + } + } + } + ] +``` diff --git a/dev-docs/bidders/growads.md b/dev-docs/bidders/growads.md new file mode 100644 index 0000000000..8f7c295ad4 --- /dev/null +++ b/dev-docs/bidders/growads.md @@ -0,0 +1,18 @@ +--- +layout: bidder +title: GrowAdvertising +description: Prebid GrowAdvertising Bidder Adapter +pbjs: true +biddercode: growads +media_types: banner, native +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------|--------------------|----------| +| `zoneId` | required | ZoneId ID | `'unique-zone-id'` | `string` | +| `domain` | optional | Domain | `'example.org'` | `string` | +| `minCPM` | optional | Minimum CPM | `1.5` | `float` | +| `maxCPM` | optional | Maximum CPM | `10.8` | `float` | diff --git a/dev-docs/bidders/gumgum.md b/dev-docs/bidders/gumgum.md index 34ed13433e..43e6c3e114 100644 --- a/dev-docs/bidders/gumgum.md +++ b/dev-docs/bidders/gumgum.md @@ -8,8 +8,8 @@ pbs_app_supported: true biddercode: gumgum media_types: banner, video schain_supported: true -getFloor: true -userIds: unifiedId +floors_supported: true +userIds: unifiedId, identityLink gdpr_supported: true usp_supported: true --- @@ -33,6 +33,7 @@ Client side and server side parameters differ slightly. For Server side (Prebid | `zone` | required for all bid requests tracking a single domain or site | Tracking ID | `'ggumtest'` | `string` | | `pubId` | required for all bid requests tracking multiple domains or sites | Publisher ID | `123` | `integer` | | `irisid` | optional | Iris.tv ID | `'iris_6f9285823a4'` | `string` | +| `slot` | optional | Placement ID | `40` | `number` | ### Client Side Bid Params @@ -42,6 +43,7 @@ Client side and server side parameters differ slightly. For Server side (Prebid | `zone` | required for all bid requests tracking a single domain or site | Tracking ID | `'ggumtest'` | `string` | | `pubId` | required for all bid requests tracking multiple domains or sites | Publisher ID | `123` | `integer` | | `slot` | required for slot placement only | Slot ID | `9` | `integer` | +| `product` | required for new supported products like 'skin' | Product Type | `skin` | `string` | | `iriscat` | optional | Iris.tv segments | `'segment1,segment2'` | `string` | | `irisid` | optional | Iris.tv ID | `'123'` | `string` | | `bidfloor` | optional | CPM bidfloor in USD | `0.03` | `float` | @@ -94,6 +96,17 @@ To enable ad requests for in-screen, either `zone` or `pubId` must be present in } } +#### Skin +Skin ad requests require the `product` parameter with the value of `skin` in the params object: + + { + bidder: 'gumgum', + params: { + zone: 'zone_id', // provided by GumGum + product: 'skin' + } + } + #### Slot Slot ad requests require the `slot` parameter in the params object: diff --git a/dev-docs/bidders/haxmedia.md b/dev-docs/bidders/haxmedia.md index 6931acb025..096d358667 100644 --- a/dev-docs/bidders/haxmedia.md +++ b/dev-docs/bidders/haxmedia.md @@ -9,7 +9,8 @@ media_types: banner, video, native gdpr: true pbjs: true pbs: false -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Prebid.JS Bid Params diff --git a/dev-docs/bidders/hpmdnetwork.md b/dev-docs/bidders/hpmdnetwork.md index 026647b478..b1557dc4fc 100644 --- a/dev-docs/bidders/hpmdnetwork.md +++ b/dev-docs/bidders/hpmdnetwork.md @@ -5,7 +5,8 @@ description: Prebid HPMD Network Bidder Adaptor pbjs: true biddercode: hpmdnetwork media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- Note: diff --git a/dev-docs/bidders/huaweiads.md b/dev-docs/bidders/huaweiads.md new file mode 100644 index 0000000000..25e7955014 --- /dev/null +++ b/dev-docs/bidders/huaweiads.md @@ -0,0 +1,36 @@ +--- +layout: bidder +title: HuaweiAds +description: Prebid HuaweiAds Bidder Adapter +biddercode: huaweiads +gvl_id: 856 +media_types: banner, video, native +gdpr_supported: true +coppa_supported: true +safeframes_ok: false +deals_supported: true +pbjs: false +pbs: true +pbs_app_supported: true +prebid_member: false +--- + +### Note: + +The Example Bidding adapter requires setup before beginning. Please contact us at hwads@huawei.com. +1. The following parameters need to be registered on the HuaweiAds platform, and at the same time, the permission to access the server interface needs to be opened on the HuaweiAds platform. +2. You can find ( publisherid, signkey, keyid ) on the platform after registration. +3. You need to create your advertising creative on the platform and get the corresponding ( slotid, adtype ). +4. We need OAID, GAID, IMEI (One must not be empty, you can collect OAID first, or use GAID) in our request, so when using prebidmobile, please add something like "TargetingParams.addUserData("oaid", "oaid-test") TargetingParams.addUserData("gaid", "gaid-test") TargetingParams.addUserData("imei", "imei-test")". +5. You can also send the clientTime to the HuaweiAds Adx server, like "TargetingParams.addUserData("clientTime", "2018-11-02 16:34:07.981+0800")". if not, it will use the prebid server time and zone. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|-----------|----------| +| `publisherid` | required | Publisher Id | `'2001000399'` | `string` | +| `signkey` | required | Sign Key | `'5d********82c38594f8b2bdfd9f********a398dca734932898e3********8d'` | `string` | +| `keyid` | required | Key Id | `'2'` | `string` | +| `slotid` | required | Slot Id | `'u42ohmaufh'` | `string` | +| `adtype` | required | Ad Type | `'native'` | `string` | diff --git a/dev-docs/bidders/idx.md b/dev-docs/bidders/idx.md new file mode 100644 index 0000000000..9d65996106 --- /dev/null +++ b/dev-docs/bidders/idx.md @@ -0,0 +1,25 @@ +--- +layout: bidder +title: IDX bidder adapter +description: Prebid IDX Bidder Adapter +biddercode: idx +gdpr_supported: false +usp_supported: false +coppa_supported: false +schain_supported: false +dchain_supported: false +media_types: banner +safeframes_ok: true +deals_supported: false +floors_supported: false +fpd_supported: false +pbjs: false +pbs: false +prebid_member: false +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| diff --git a/dev-docs/bidders/imonomy.md b/dev-docs/bidders/imonomy.md index 134cc2b5c2..d9fcb504b6 100644 --- a/dev-docs/bidders/imonomy.md +++ b/dev-docs/bidders/imonomy.md @@ -4,7 +4,8 @@ title: Imonomy description: Prebid Imonomy Bidder Adaptor pbjs: true biddercode: imonomy -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/impactify.md b/dev-docs/bidders/impactify.md index 5bb97133a9..20c55f326b 100644 --- a/dev-docs/bidders/impactify.md +++ b/dev-docs/bidders/impactify.md @@ -3,7 +3,7 @@ layout: bidder title: Impactify description: Prebid Impactify Bidder Adapter pbjs: true -pbs: false +pbs: true biddercode: impactify gdpr_supported: true tcf2_supported: true @@ -11,8 +11,8 @@ usp_supported: true schain_supported: true coppa_supported: true media_types: video +userIds: criteo, id5Id, pubCommonId, unifiedId, uid2, netId gvl_id: 606 -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/improvedigital.md b/dev-docs/bidders/improvedigital.md old mode 100644 new mode 100755 index c2257fcf6b..b77db46be5 --- a/dev-docs/bidders/improvedigital.md +++ b/dev-docs/bidders/improvedigital.md @@ -5,15 +5,18 @@ description: Prebid Improve Digital Bidder Adaptor biddercode: improvedigital pbjs: true pbs: true +coppa_supported: true gdpr_supported: true -userIds: criteo, id5Id usp_supported: true +userIds: all media_types: banner, native, video schain_supported: true gvl_id: 253 pbs_app_supported: true --- +     + ### Bid params {: .table .table-bordered .table-striped } @@ -21,9 +24,10 @@ pbs_app_supported: true |----------------|----------|----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|-----------| | `placementId` | required | The placement ID from Improve Digital. | `1234567` | `integer` | | `keyValues` | optional | Contains one or more key-value pairings for key-value targeting | `{ testKey1: ['testValueA'], testKey2: ['testValueB', 'testValueC'] }` | `object` | -| `size` | optional | Single size filter. Where a placement supports multiple sizes, this forces the response to feature only one of the multiple sizes. This parameter is ignored when `usePrebidSizes` is enabled (see the [Sizes](#improvedigital-sizes) section below). | `{ w:300, h:250 }` | `object` | | `bidFloor` | optional | Bid floor price | `0.01` | `float` | | `bidFloorCur` | optional | Bid floor price currency. Supported values: USD (default), EUR, GBP, AUD, DKK, SEK, CZK, CHF, NOK | `'USD'` | `string` | +| `extend` | optional | See the [Extend mode section](#improvedigital-extend) | `true` | `boolean` | +| `rendererConfig` | optional | Configuration object for JS renderer of the RAZR creatives. Provided by Improve Digital. | `{ key1: value1 }` | `object` | | `video` | optional | Object with video parameters. See the [Video params](#improvedigital-video) section below for details. | | `object` | @@ -39,25 +43,47 @@ pbs_app_supported: true ### Configuration -#### Single-Request + -By default, the adapter sends one request for each ad unit to Improve Digital's ad server. For example, if there are 4 Prebid ad units defined on the page, you'll see 4 calls out to ad.360yield.com/hb. +#### Sizes -The Improve Digital adapter supports `Single Request` mode, where all ad unit requests are made in a single call to ad.360yield.com/hb. To turn this feature on, call `setConfig`: +By default, the adapter doesn't send Prebid ad unit sizes to Improve Digital's ad server and the sizes defined for each placement in the Polaris platform will be used. If the ad server should only respond with creative sizes as defined in Prebid ad unit configuration, turn on `usePrebidSizes` adapter parameter like this: ``` pbjs.setConfig({ - improvedigital: {singleRequest: true} + improvedigital: { usePrebidSizes: true } }); ``` - + -#### Sizes +#### Renderer Config + +Global configuration for the special creative format renderer. Please use [rendererConfig bid param](#improvedigital-params) for ad slot specific configuration. + +``` +pbjs.setConfig({ + improvedigital: { + rendererConfig: { + // Global config object provided by Improve Digital + } + } +}); +``` + + + +#### Extend Mode + +Improve Digital Extend mode provides publishers with access to additional demand from other SSPs. Before enabling please contact our team for more information. +The Extend mode can be enabled: +* per ad unit via the `extend` [bid param](#improvedigital-params) +* for all ad units via `setConfig()`: -By default, the adapter doesn't send Prebid ad unit sizes to Improve Digital's ad server and the sizes defined for each placement in the Polaris platform will be used. If the ad server should only respond with creative sizes as defined in Prebid ad unit configuration, turn on `usePrebidSizes` adapter parameter like this: ``` pbjs.setConfig({ - improvedigital: {usePrebidSizes: true} + improvedigital: { + extend: true + } }); ``` diff --git a/dev-docs/bidders/incrementx.md b/dev-docs/bidders/incrementx.md new file mode 100644 index 0000000000..3168d8d494 --- /dev/null +++ b/dev-docs/bidders/incrementx.md @@ -0,0 +1,21 @@ +--- +layout: bidder +title: IncrementX +description: Prebid IncrementX Bidder Adaptor +pbjs: true +biddercode: incrx +media_types: banner +gdpr_supported: true +multiformat_supported: will-bid-on-one +--- + +### Note: + +The IncrementX adapter currently doesn't support multiple sizes per ad placement and will favour the first one if multiple sizes exists. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|--------------------------|-----------------|----------| +| placementId | required | incrementx placement id | `'PNX-HB-123'` | `string` | diff --git a/dev-docs/bidders/infytv.md b/dev-docs/bidders/infytv.md new file mode 100644 index 0000000000..96b2fb41cf --- /dev/null +++ b/dev-docs/bidders/infytv.md @@ -0,0 +1,26 @@ +--- +layout: bidder +title: InfyTV +description: Prebid InfyTV Bidder Adapter +pbjs: true +biddercode: infytv +gdpr_supported: true +media_types: video +coppa_supported: true +pbs: true +pbs_app_supported: true +usp_supported: true +schain_supported: true +--- + +### Note: + +The Example Bidding adapter requires setup before beginning. Please contact us at adops@infy.tv + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|-----------|----------| +| `publisherId` | required | Publisher ID | `'11111'` | `string` | +| `placementId` | optional | Placement ID | `'11111'` | `string` | diff --git a/dev-docs/bidders/inmar.md b/dev-docs/bidders/inmar.md index 23f028e296..ff988e3a6d 100644 --- a/dev-docs/bidders/inmar.md +++ b/dev-docs/bidders/inmar.md @@ -2,13 +2,12 @@ layout: bidder title: Inmar description: Prebid Inmar Bidder Adapter - biddercode: inmar usp_supported: true userIds: identityLink, liveIntentId, unifiedId, pubCommonId, pubProvidedId, sharedId media_types: banner, video safeframes_ok: false -bidder_supports_deals: true +deals_supported: true pbjs: true --- ### Note: diff --git a/dev-docs/bidders/inmobi.md b/dev-docs/bidders/inmobi.md index aa87c6cb33..bafea45f6d 100644 --- a/dev-docs/bidders/inmobi.md +++ b/dev-docs/bidders/inmobi.md @@ -7,7 +7,8 @@ gdpr_supported: true usp_supported: false gvl_id: 333 coppa_supported: true -media_types: banner, video +schain_supported: true +media_types: banner, video, native pbs: true pbs_app_supported: true --- @@ -17,6 +18,12 @@ pbs_app_supported: true The InMobi Prebid adapter requires a setup to create placement IDs. Please contact your InMobi partner manager for setup assistance. For queries, write to us at prebid-support@inmobi.com +### User Sync Disclosure: + +InMobi has partnered with a third party, ID5, to use their ID as our primary user identifier for mobile web supply. We will also rely on ID5 IDs to handle compliance flows related to Data Subject Right requests in our systems. Hence, we require the publisher to use ID5’s sync URL for user syncing and passing the corresponding ID5 ID to InMobi in the bid request. For this purpose, we provide ID5’s sync URL in our Prebid adapter for User ID sync. Note that, InMobi has a direct contract with ID5 for consuming ID5 ID and the user sync via Prebid does not require the publisher to get into a contractual relationship with ID5. + +To opt out of InMobi ads on mobile web inventory or for any other requests, the user needs to visit the Opt-out page on InMobi website (https://www.inmobi.com/page/opt-out/). For opting out of ID5 ID entirely, the user needs to visit ID5’s opt out page: https://id5.io/platform-privacy-policy/. + ### Bid Params {: .table .table-bordered .table-striped } diff --git a/dev-docs/bidders/innity.md b/dev-docs/bidders/innity.md index f5dc7b7d0e..228490a590 100644 --- a/dev-docs/bidders/innity.md +++ b/dev-docs/bidders/innity.md @@ -4,7 +4,6 @@ title: Innity description: Prebid Innity Bidder Adapter pbjs: true biddercode: innity -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/insticator.md b/dev-docs/bidders/insticator.md new file mode 100644 index 0000000000..06568fb78c --- /dev/null +++ b/dev-docs/bidders/insticator.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: Insticator +description: Prebid Insticator Bidder Adapter +biddercode: insticator +gdpr_supported: true +usp_supported: true +schain_supported: true +media_types: banner, video +multiformat_supported: will-bid-on-any +pbjs: true +gvl_id: 910 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------|----------------------|----------| +| `adUnitId` | Required | The ad unit ID provided by Insticator | `'test'` | `string` | +| `yob` | optional | Year of Birth | `'1982'` | `string` | +| `gender` | optional | Gender | `'M'` | `string` | +| `instl` | optional | 1 = the ad is interstitial or full screen, 0 = not interstitial. | `1` | `number` | +| `pos` | optional | ad position as per IAB standards | `1` | `number` | + +### video parameters + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | +|------------------------|----------|-------------------------------------------------------------|---------| +| `video.mimes` | required | Video MIME types | `['video/mp4','video/x-flv']` | +| `video.w` | recommended | Width of the video player in device independent pixels (DIPS). | `300` | +| `video.h` | recommended | Height of the video player in device independent pixels (DIPS). | `250` | +| `video.placement` | recommended | Video placement type | `2` | + \ No newline at end of file diff --git a/dev-docs/bidders/integr8.md b/dev-docs/bidders/integr8.md new file mode 100644 index 0000000000..27662ef942 --- /dev/null +++ b/dev-docs/bidders/integr8.md @@ -0,0 +1,17 @@ +--- +layout: bidder +title: Integr8 +description: Prebid Integr8 Bidder Adapter +pbjs: true +biddercode: integr8 +media_types: banner, video +--- + + +### Bid Params + +| Name | Scope |Description | Example | Type | +|---------------|----------|------------------------------------------------------------------------|--------------------|-----------| +| `propertyId` | required |Property id | `"12345"` | `string` | +| `placementId` | required |Placement id | `"54321"` | `string` | +| `data` | optional |Catalog data (contents) and/or inventory data (custom key/value pairs) | `{catalogs: [{ catalogId: "699229", items: ["193", "4", "1"] }], inventory: { category: ["tech"], query: ["iphone 12"] }}` | `object` | diff --git a/dev-docs/bidders/interactiveOffers.md b/dev-docs/bidders/interactiveOffers.md index f95591a67f..daadab5e9d 100644 --- a/dev-docs/bidders/interactiveOffers.md +++ b/dev-docs/bidders/interactiveOffers.md @@ -10,14 +10,14 @@ media_types: banner --- ### Note: -Module that connects to interactiveOffers demand sources. Param pubid is required. +Module that connects to interactiveOffers demand sources. Param partnerId is required. ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|-------------|---------|----------| -| `pubid` | required | Publisher id | 35 | `integer` | +| `partnerId` | required | Partner id | 'abc123' | `string` | Example: @@ -25,7 +25,7 @@ Example: { bidder: "interactiveOffers", params: { - pubid: 35 + partnerId: "abc123" } } ``` diff --git a/dev-docs/bidders/invibes.md b/dev-docs/bidders/invibes.md index 993d1a3c81..2ab1046385 100644 --- a/dev-docs/bidders/invibes.md +++ b/dev-docs/bidders/invibes.md @@ -10,12 +10,20 @@ userIds: pubCommonId, pubProvidedId, uid2, zeotapIdPlus, id5id pbs: true --- +### Disclosure +The bidder will use the Local Storage if allowed by the publisher and user gives consent on page with the following purposes: + - set an internal Invibes ID + - get the internal Invibes ID if it was set priorly for the user + +The bidder will NOT set any cookies. The bidder will also try to read from Cookies if publisher gibes the internal ID if this wasn't found in LocalStorage. + ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-----------------|----------|--------------------------------------|-------------------------------------------------|----------| | `placementId` | required | The Invibes placement ID | `'1234567'` | `string` | -| `domainId` | optional | Id of domain (only prebid server) | `1001` | `integer`| +| `domainId` | optional | Id of domain | `1001` | `integer`| +| `customEndpoint`| optional | Custom test domain | `https://bid.videostep.com/Bid/VideoAdContent` | `integer`| | `debug` | optional | Debug paramentes (only prebid server)| `{ "testBvid": "1234", "testLog": true }` | `object` | diff --git a/dev-docs/bidders/iprom.md b/dev-docs/bidders/iprom.md index 5c123a13db..f9d05f25cc 100644 --- a/dev-docs/bidders/iprom.md +++ b/dev-docs/bidders/iprom.md @@ -5,7 +5,8 @@ description: iPROM Prebid Adaptor biddercode: iprom media_types: banner pbjs: true -pbjs_version_notes: not in 5.x +enable_download: true +pbjs_version_notes: not in 5.x, in 6.2+ --- ### Prebid Server Note: diff --git a/dev-docs/bidders/iqm.md b/dev-docs/bidders/iqm.md index a9c01669a9..a3251a5a72 100644 --- a/dev-docs/bidders/iqm.md +++ b/dev-docs/bidders/iqm.md @@ -6,14 +6,78 @@ pbjs: true biddercode: iqm --- - -### Bid Params +# Parameters {: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | +| :------------ | :------- | :------------------------ | :------------------- | +| `publisherId` | required | The Publisher ID from iQM | "df5fd732-c5f3-11e7-abc4-cec278b6b50a" | +| `geo.country` | required | The publisher country| "USA" | +| `placementId` | required | The Placement ID from iQM | 23451 | +| `bidfloor` | optional | Bid Floor | 0.50 | + +# Description + +Module that connects to iQM demand sources + +# Test Parameters +``` +var adUnits = [{ + code: 'div-gpt-ad-1460505748561-0', + mediaTypes: { + banner: { + sizes: [[300,250]] + } + }, + + bids: [{ + bidder: 'iqm', + params: { + geo:{ + country:'USA' + }, + + publisherId: 'df5fd732-c5f3-11e7-abc4-cec278b6b50a', + placementId: 23451, + bidfloor: 0.50 + } + }] + + }] + +``` + +# adUnit Video + +``` + var videoAdUnit = { + code: 'video1', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream' + } + }, + bids: [{ + bidder: 'iqm', + params: { + // placementId: iosDevice ? 13239390 : 13232361, // Add your own placement id here. Note, skippable video is not supported on iOS + publisherId: 'df5fd732-c5f3-11e7-abc4-cec278b6b50a', + placementId: 23451, + geo:{ + country:'USA' + }, + + bidfloor: 0.05, + video: { + placement :2, + mimes: ['video/mp4'], + protocols: [2,5], + skipppable: true, + playback_method: ['auto_play_sound_off'] + } + } + }] + }; -| Name | Scope | Description | Example | Type | -|---------------|----------|----------------------------|------------------------------------------|-----------| -| `publisherId` | required | The Publisher ID from iQM. | `'df5fd732-c5f3-11e7-abc4-cec278b6b50a'` | `string` | -| `tagId` | required | The Tag ID from iQM. | `'1c5c9ec2-c5f4-11e7-abc4-cec278b6b50a'` | `string` | -| `placementId` | required | The Placement ID from iQM. | `'50cc36fe-c5f4-11e7-abc4-cec278b6b50a'` | `string` | -| `bidfloor` | required | Bid floor | `0.50` | `integer` | +``` diff --git a/dev-docs/bidders/iqzone.md b/dev-docs/bidders/iqzone.md new file mode 100644 index 0000000000..c8d6d07c4d --- /dev/null +++ b/dev-docs/bidders/iqzone.md @@ -0,0 +1,25 @@ +--- +layout: bidder +title: IQzone +description: Prebid IQzone Bidder Adapter +biddercode: iqzone +usp_supported: true +gdpr_supported: true +schain_supported: true +media_types: banner, video, native +pbjs: true +pbs: true +pbs_app_supported: true +--- + +### Prebid.js Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | + +### Note + +For the prebid server and prebid.js you only need to use one parameter: either placementId or endpointId diff --git a/dev-docs/bidders/ironsource.md b/dev-docs/bidders/ironsource.md index f8d1ee0ebc..a4ee00012e 100644 --- a/dev-docs/bidders/ironsource.md +++ b/dev-docs/bidders/ironsource.md @@ -8,7 +8,8 @@ media_types: no-display, video schain_supported: true gdpr_supported: true usp_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note diff --git a/dev-docs/bidders/ix.md b/dev-docs/bidders/ix.md index 8dd0d38e33..0e7a94ccf2 100644 --- a/dev-docs/bidders/ix.md +++ b/dev-docs/bidders/ix.md @@ -5,14 +5,15 @@ description: Prebid Index Exchange Bidder Adapter biddercode: ix pbjs: true pbs: true -userIds: identityLink, netId, fabrickId, zeotapIdPlus, uid2 +userIds: identityLink, netId, fabrickId, zeotapIdPlus, uid2, unifiedId, id5Id, lotamePanoramaId, publinkId, hadronId, pubcid pbs_app_supported: true schain_supported: true coppa_supported: true gdpr_supported: true -getFloor: true +floors_supported: true usp_supported: true -media_types: banner, video +media_types: banner, video, native +fpd_supported: true gvl_id: 10 prebid_member: yes --- @@ -27,37 +28,16 @@ Maintainer: prebid.support@indexexchange.com ## Description -Publishers may access Index Exchange's (IX) network of demand -sources through our Prebid.js and Prebid Server adapters. Both of these modules are GDPR and CCPA compliant. +Publishers may access Index Exchange's (IX) network of demand sources through our Prebid.js and Prebid Server adapters. Both of these modules are GDPR and CCPA compliant. ### IX Prebid.js Adapter -Our Prebid.js adapter is compatible with both the older ad unit format where the `sizes` and -`mediaType` properties are placed at the top-level of the ad unit, and the newer -format where this information is encapsulated within the `mediaTypes` object. We -recommend that you use the newer format when possible as it will be better able -to accommodate new feature additions. +This module connects publishers to Index Exchange's (IX) network of demand sources through Prebid.js. This module is GDPR and CCPA compliant. -If a mix of properties from both formats is present within an ad unit, the -newer format's properties will take precedence. +It is compatible with the new Prebid.js 5.0 ad unit format where banner and video properties, including the size parameter, are stored in the `adUnits[].mediaTypes` object. IX still supports both size as an optional parameter and the Missing Sizes feature, but we recommend upgrading to the Prebid.js 5.0 format. -Here are examples of both formats. +For more information about how the `adUnits[].mediaTypes` object is formatted in Prebid.js 5.0, refer to the following example. -##### Older Format -```javascript -var adUnits = [{ - // ... - - sizes: [ - [300, 250], - [300, 600] - ] - - // ... -}]; -``` - -##### Newer Format ```javascript var adUnits = [{ // ... @@ -70,60 +50,69 @@ var adUnits = [{ }, video: { context: 'instream', - playerSize: [ - [1280, 720] - ] + playerSize: [300, 250] } }, // ... }]; ``` - ### Supported Media Types (Prebid.js) {: .table .table-bordered .table-striped } -| Type | Support | -| ------ | ------- | -| `Banner` | Fully supported for all IX approved sizes | -| `Video` | Fully supported for all IX approved sizes | -| `Native` | Not supported | +| Type | Support | +|---|---| +| `banner` | Fully supported for all IX approved sizes | +| `video` | Fully supported for all IX approved sizes | +| `native` | Supported | ### Supported Media Types (Prebid Server) {: .table .table-bordered .table-striped } | Type | Support | -| ------ | ------- | -| `Banner` | Fully supported | -| `Video` | Fully supported, including ad pods for OTT | -| `Native` | Not supported | +|------|-------| +| `banner` | Fully supported | +| `video` | Fully supported, including ad pods for OTT | +| `native` | Supported | + +# Ad Unit or Bidder Parameters + +These params can be specified in the ad unit level, which will be the preferred way going forward with PBJS 5.0 + +Each of the IX-specific parameters provided under the object are detailed here. -## Bid Parameters +The following parameters are specified in the ad unit `adUnits[].mediaTypes`. This includes each of the IX-specific parameters provided under `adUnits[].bids[].params`. -Each of the IX-specific parameters provided under the `adUnits[].bids[].params` -object are detailed here. +In Prebid.js versions 5.0 and above, mediaType and sizes are not required to be defined at the ad unit level. ### Banner {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `siteId` | Required | An IX-specific identifier that is associated with a specific size on this ad unit. This is similar to a placement ID or an ad unit ID that some other modules have. | `'3723'` | `string` | -| `size` | Required for client-side serving | The single size associated with the site ID. It should be one of the sizes listed in the ad unit under `adUnits[].sizes` or `adUnits[].mediaTypes.banner.sizes`. Note that the 'ix' Prebid Server bid adapter ignores this parameter. | `[300, 250]` | `Array` | -| `id` | Optional | An alphanumerical value used to identify the `slot_id` in reporting | `id: 'billboardHomepage'`, `id: 'billboardArticle'` | `string` | +| Key | Scope | Type | Description | +|---|---|---|---| +| `siteId` | Required | String | An IX-specific identifier that is associated with this ad unit. It will be associated to the single size, if the size provided. This is similar to a placement ID or an ad unit ID that some other modules have. For example, `'3723'`, `'6482'`, `'3639'`| +| `sizes` | Optional | Number[Number[]] | The size/sizes associated with the site ID, as listed in the ad unit under `adUnits[].mediaTypes.banner.sizes`. For example, `[300, 250], [300, 600], [728, 90]`| ### Video {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `siteId` | Required | An IX-specific identifier that is associated with a specific size on this ad unit. This is similar to a placement ID or an ad unit ID that some other modules have. | `'3723'` | `string` | -| `size` | Required | The single size associated with the site ID. It should be one of the sizes listed in the ad unit under `adUnits[].sizes` or `adUnits[].mediaTypes.video.playerSize`. | `[300, 600]` | `Array` | -| `video` | Required | The video object will serve as the properties of the video ad. You can create any field under the video object that is mentioned in the `OpenRTB Spec v2.5`. Some fields like `mimes`, `protocols`, `minduration`, `maxduration` are required. Properties not defined at this level, will be pulled from the Adunit level. | `video: { startdelay: 0 }` | `object` | -| `video.mimes` | Required | Array list of content MIME types supported. | `['video/mp4', 'video/x-flv']` | `Array` | -| `video.minduration` | Required | Minimum video ad duration in seconds. | `0` | `integer` | -| `video.maxduration` | Required | Maximum video ad duration in seconds. | `300` | `integer` | -| `video.protocol` / `video.protocols` | Required | Either a single protocol provided as an integer, or protocols provided as a list of integers. `2` - VAST 2.0, `3` - VAST 3.0, `5` - VAST 2.0 Wrapper, `6` - VAST 3.0 Wrapper | `[2,3,5,6]` | `integer` / `Array` | -| `id` | Optional | An alphanumerical value used to identify the `slot_id` in reporting | `id: 'inStreamCTP'`, `id: 'inStreamAutoPlay'` | `string` | +| Key | Scope | Type | Description | +|---|---|---|---| +| `siteId` | Required | String | An IX-specific identifier that is associated with this ad unit. It will be associated to the single size, if the size is provided. This is similar to a placement ID or an ad unit ID that some other modules have. For example, `'3723'`, `'6482'`, `'3639'`| +| `size` | Optional | Number[] | The single size that is associated with the site ID, as listed in the ad unit under `adUnits[].sizes` or `adUnits[].mediaTypes.video.playerSize`. For example, [300, 250], [300, 600].

    This parameter is optional in Prebid.js versions 5.0 and above. Versions prior to 5.0 will still require a size parameter.| +| `video` | Optional | Hash | The video object will serve as the properties of the video ad. You can create any field under the video object that is mentioned in the `OpenRTB Spec v2.5`. Some fields like `mimes, protocols, minduration, maxduration` are required. Properties not defined at this level, will be pulled from the Adunit level.| +| `video.w` | Required | Integer | The width of the video player in pixels that will be passed to demand partners.
    *If you are using Index’s outstream player and have placed the video object at the `bidder` level, this is a required field. You must define the size of the video player using the `video.w` and `video.h` parameters, with a minimum video player size of 300 x 250.| +| `video.h` | Required | Integer | The height of the video player in pixels that will be passed to demand partners.
    *If you are using Index’s outstream player and have placed the video object at the `bidder` level, this is a required field. You must define the size of the video player using the `video.w` and `video.h` parameters, with a minimum video player size of 300 x 250.| +| `video.playerSize` | Optional* | Integer | The video player size that will be passed to demand partners.
    *If you are using Index’s outstream player and have placed the video object at the `adUnit` level, this is a required field. You must define the size of the video player using this parameter, with a minimum `video` player size of 300 x 250. | +| `video.mimes` | Required | String[] | If you are using Index’s outstream video player and want to learn more about what is supported, see [List of supported OpenRTB bid request fields for Sellers.](https://kb.indexexchange.com/publishers/openrtb_integration/list_of_supported_openrtb_bid_request_fields_for_sellers.htm#Video) | +| `video.minduration` | Required | Integer | Minimum video ad duration in seconds.| +| `video.maxduration` | Required | Integer | Maximum video ad duration in seconds.| +| `video.protocol` / `video.protocols` | Required | Integer / Integer[] | Either a single protocol provided as an integer, or protocols provided as a list of integers. `2` - VAST 2.0, `3` - VAST 3.0, `5` - VAST 2.0 Wrapper, `6` - VAST 3.0 Wrapper| +| `video.playerConfig` | Optional | Hash | The Index specific outstream player configurations. +| `video.playerConfig.floatOnScroll` | Optional | Boolean | A boolean specifying whether you want to use the player’s floating capabilities, where:
    - `true`: Use the Index player’s float capabilities.
    **Note**: If you set `floatOnScroll` to `true`, Index updates the `placement` value to `5`.
    **Note:** We do not recommend using the player's default float capabilities if you have more than one outstream ad unit per page.
    - `false`: Do not use the Index player's float capabilities (default). | +| `video.playerConfig.floatSize` | Optional | Integer[] | The height and width of the floating player in pixels. If you do not specify a float size, the player adjusts to the aspect ratio of the player size that is defined when it is not floating. Index recommends that you review and test the float size to your user experience preference.| + +### Native +Index supports the native assets that Prebid.js recognizes. For the list of native assets, see [Prebid.js Native Implementation Guide on the Prebid site.](https://docs.prebid.org/prebid/native-implementation.html#3-prebidjs-native-adunit-overview) ## Setup Guide @@ -132,7 +121,7 @@ integration. The examples in this guide assume the following starting configuration (you may remove banner or video, if either does not apply). -In regards to video, `context` can either be `'instream'` or `'outstream'`. Note that `outstream` requires additional configuration on the adUnit. +In regards to video, `context` can either be `'instream'` or `'outstream'`. ```javascript var adUnits = [{ @@ -152,9 +141,7 @@ var adUnits = [{ mediaTypes: { video: { context: 'instream', - playerSize: [ - [1280, 720] - ] + playerSize: [1280, 720] } }, bids: [] @@ -170,13 +157,12 @@ bid objects under `adUnits[].bids`: { bidder: 'ix', params: { - siteId: '123456', - size: [300, 250] + siteId: '123456' } } ``` -Set `params.siteId` and `params.size` in each bid object to the values provided +Set `params.siteId` in the bid object to the values provided by your IX representative. **Examples** @@ -196,14 +182,12 @@ var adUnits = [{ bids: [{ bidder: 'ix', params: { - siteId: '123456', - size: [300, 250] + siteId: '123456' } }, { bidder: 'ix', params: { - siteId: '123456', - size: [300, 600] + siteId: '123456' } }] }]; @@ -211,28 +195,32 @@ var adUnits = [{ **Video (Instream):** ```javascript var adUnits = [{ - code: 'video-request-a', + code: 'video-div-a', mediaTypes: { video: { + // Preferred location for openrtb v2.5 compatible video obj context: 'instream', - playerSize: [ - [1280, 720] - ] + playerSize: [300, 250], + api: [2], + protocols: [2, 3, 5, 6], + minduration: 5, + maxduration: 30, + mimes: ['video/mp4', 'application/javascript'], + placement: 3 } }, bids: [{ bidder: 'ix', params: { - siteId: '123456', - size: [1280, 720], + siteId: '12345' + } + }, { + bidder: 'ix', + params: { + siteId: '12345', video: { - mimes: [ - 'video/mp4', - 'video/webm' - ], - minduration: 0, - maxduration: 60, - protocols: [6] + // openrtb v2.5 compatible video obj + // If required, use this to override mediaTypes.video.XX properties } } }] @@ -242,45 +230,52 @@ Please note that you can re-use the existing `siteId` within the same flex position. **Video (Outstream):** -Note that currently, outstream video rendering must be configured by the publisher. In the adUnit, a `renderer` object must be defined, which includes a `url` pointing to the video rendering script, and a `render` function for creating the video player. See http://prebid.org/dev-docs/show-outstream-video-ads.html for more information. +Publishers have two options to receive outstream video demand from Index: +* Using Index’s outstream video player +* In an outstream video configuration set up by the publisher. For more information, see [Prebid’s documentation on how to show video ads.](https://docs.prebid.org/dev-docs/show-outstream-video-ads.html) + +**Index’s outstream video player** +Publishers who are using Index as a bidding adapter in Prebid.js can show outstream video ads on their site from us by using Index’s outstream video player. This allows a video ad to display inside of a video player and can be placed anywhere on a publisher’s site, such as in-article, in-feed, and more. + +Define a new `video` object for our outstream video player at either the adUnit level or the `bidder` level. If you are setting it at the bidder level, define the size of the video player using the parameters `video.h` and `video.w`. If you are setting it at the `adUnit` level, define the size using `video.playerSize`.
    **Note:** The bidder level video configurations override the adunit level configurations. The `playerConfig` is only a bidder level configuration. + +For more information on how to structure the `video` object, refer to the following code example: + ```javascript var adUnits = [{ - code: 'video-div-a', + code: 'div-gpt-ad-1571167646410-1', mediaTypes: { video: { + playerSize: [640, 360], context: 'outstream', - playerSize: [[640, 360]] - } - }, - renderer: { - url: 'https://test.com/my-video-player.js', - render: function (bid) { - ... + api: [2], + protocols: [2, 3, 5, 6], + minduration: 5, + maxduration: 30, + mimes: ['video/mp4', 'application/javascript'], + placement: 5 } }, bids: [{ bidder: 'ix', params: { - siteId: '123456', - size: [640, 360], + siteId: '715964' video: { - mimes: [ - 'video/mp4', - 'video/webm' - ], - minduration: 0, - maxduration: 60, - protocols: [6] + playerConfig: { + floatOnScroll: true, + floatSize: [300,250] + } } } }] }]; ``` +Please note that your use of the outstream video player will be governed by and subject to the terms and conditions of i) any master services or license agreement entered into by you and Index Exchange; ii) the information provided on our knowledge base linked [here](https://kb.indexexchange.com/publishers/prebid_integration/outstream_video_prebidjs.htm) and [here](https://kb.indexexchange.com/publishers/guidelines/standard_contractual_clauses.htm), and iii) our [Privacy Policy](https://www.indexexchange.com/privacy/). Your use of Index’s outstream video player constitutes your acknowledgement and acceptance of the foregoing. #### Video Caching -Note that the IX adapter expects a client-side Prebid Cache to be enabled for video bidding. +Note that the IX adapter expects a client-side Prebid Cache to be enabled for instream video bidding. ``` pbjs.setConfig({ @@ -291,8 +286,53 @@ pbjs.setConfig({ }); ``` +#### Native +We support the three native template rendering options that are provided in the [Setting up Prebid Native in Google Ad Manager](https://docs.prebid.org/adops/gam-native.html). The following code is an example of a Prebid native set up using Google Ad Manager, but the concept and implementation should be similar for other ad servers. + +``` +pbjs.addAdUnits({ + code: slot.code, + mediaTypes: { + native: { + image: { + required: true, + sizes: [150, 50] + }, + title: { + required: true, + len: 80 + }, + sponsoredBy: { + required: true + }, + clickUrl: { + required: true + }, + privacyLink: { + required: false + }, + body: { + required: true + len: 90 + }, + icon: { + required: true, + sizes: [50, 50] + } + } + }, + bids: [{ + bidder: 'ix', + params: { + siteId: '715966' + } + }] +}); +``` + #### User Sync Add the following code to enable user sync. IX strongly recommends enabling user syncing through iFrames. This functionality improves DSP user match rates and increases the IX bid rate and bid price. Be sure to call `pbjs.setConfig()` only once. +**Note**: While we recommend iframe-based user syncing, we also support image-based user syncing. If both are enabled, we will default to using iframe, because it allows us more flexibility to optimize the frequency, timing, and coverage for syncing. ``` pbjs.setConfig({ @@ -312,21 +352,21 @@ pbjs.setConfig({ By default, the IX bidding adapter bids on all banner sizes available in the ad unit when configured to at least one banner size. If you want the IX bidding adapter to only bid on the banner size it’s configured to, switch off this feature using `detectMissingSizes`. ``` pbjs.setConfig({ - ix: { - detectMissingSizes: false - } - }); + ix: { + detectMissingSizes: false + } +}); ``` OR ``` pbjs.setBidderConfig({ - bidders: ["ix"], - config: { - ix: { - detectMissingSizes: false - } - } - }); + bidders: ["ix"], + config: { + ix: { + detectMissingSizes: false + } + } +}); ``` ### 2. Include `ixBidAdapter` in your build process @@ -357,6 +397,35 @@ gulp build --modules=bidderModules.json ## Setting First Party Data (FPD) +As a part of 4.30, IX will start to pick up FPD in the global FPD module, as well as continue to pick up IX bidder-specific FPD. Previous versions of IX Bid Adapter will only support the IX bidder-specific FPD. + +### Global FPD + +As of Prebid.js 4.30, use the more generic `ortb2` interface, which can be used for more than just First Party Data. + +The First Party Data feature allows publishers to specify key/value data in one place where each compatible bid adapter can read it. + +To supply global data, use the [`setConfig()`](/dev-docs/publisher-api-reference/setConfig.html) function as illustrated below: + +``` +pbjs.setConfig({ + ortb2: { + site: { + ... + }, + user: { + ... + } + } +}); +``` + +Use the [`setBidderConfig()`](/dev-docs/publisher-api-reference/setBidderConfig.html) function to supply bidder-specific data. + +For more information about the standard or more detailed examples, refer to [First Party Data Feature](/features/firstPartyData.html). + +### IX bidder-specific FPD + FPD allows you to specify key-value pairs that are passed as part of the query string to IX for use in Private Marketplace Deals which rely on query string targeting for activation. For example, if a user is viewing a @@ -384,6 +453,9 @@ pbjs.setConfig({ The values can be updated at any time by calling `pbjs.setConfig` again. The changes will be reflected in any proceeding bid requests. +{: .alert.alert-warning :} +Continue to use IX bidder-specific First Party Data for IX deals. Global First Party Data is not yet supported in IX deals. Consult your IX representative with any questions. + ## Setting a Server Side Timeout Setting a server-side timeout allows you to control the max length of time taken to connect to the server. The default value when unspecified is 50ms. @@ -447,25 +519,16 @@ to `'ix'` across all ad units that bids are being requested for does not exceed ### Time-To-Live (TTL) -Banner bids from IX have a TTL of 300 seconds while video bids have a TTL of 1 hour, after which time they become invalid. - -If an invalid bid wins, and its associated ad is rendered, it will not count -towards total impressions on IX's side. +Banner bids from Index have a TTL of 600 seconds while video bids have a TTL of 3 hours, after which time they become invalid.
    +**Note:** Index supports the `bid.exp` attribute in the bid response which allows our adapter to specify the maximum number of seconds allowed between the auction and billing notice. In the absence of the `bid.exp` attribute, the TTL provided above applies. ## FAQs -### Why do I have to input size in `adUnits[].bids[].params` for IX when the size is already in the ad unit? - -There are two important reasons why we require it: - -1. An IX site ID maps to a single size, whereas an ad unit can have multiple -sizes. To ensure that the right site ID is mapped to the correct size in the ad -unit we require the size to be explicitly stated. +#### Why do I have to input size in `adUnits[].bids[].params` for IX when the size is already in the ad unit? -2. An ad unit may have sizes that IX does not support. By explicitly stating the -size, you can choose not to have IX bid on certain sizes that are invalid. +If you are using Prebid.js version 5.0 and above, the `size` parameter is not a required field. Only the `siteID` is required, and it is stored with the sizes in the ad unit. -### How can I view the bid request sent to IX by Prebid.js? +#### How can I view the bid request sent to IX by Prebid.js? In your browser of choice, create a new tab and open the developer tools. In developer tools, select the network tab. Then, navigate to a page where IX is diff --git a/dev-docs/bidders/navelix.md b/dev-docs/bidders/janet.md similarity index 79% rename from dev-docs/bidders/navelix.md rename to dev-docs/bidders/janet.md index cc6ad3fb6c..dace78c2c8 100644 --- a/dev-docs/bidders/navelix.md +++ b/dev-docs/bidders/janet.md @@ -1,8 +1,8 @@ --- layout: bidder -title: Navelix -description: Prebid Navelix Bidder Adapter -biddercode: navelix +title: JANet +description: Prebid JANet Bidder Adapter +biddercode: janet aliasCode: adtelligent media_types: video,banner gdpr_supported: true @@ -13,7 +13,7 @@ usp_supported: true safeframes_ok: true prebid_member: true pbjs: true -pbs: false +pbs: true --- ### Bid params @@ -21,15 +21,12 @@ pbs: false {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-------|----------|---------------------------------|----------|-----------| -| `aid` | required | The source ID from navelix. | `529814` | `integer` | +| `aid` | required | The source ID from janet. | `529814` | `integer` | ### Description -Get access to multiple demand partners across Navelix AdExchange and maximize your yield with Navelix header bidding adapter. - -Navelix header bidding adapter connects with Navelix demand sources in order to fetch bids. +JANet header bidding adapter connects with JANet demand sources in order to fetch bids. This adapter provides a solution for accessing Video demand and display demand. -Navelix now supports adpod. ### Test Parameters ``` @@ -45,7 +42,7 @@ Navelix now supports adpod. } }, bids: [{ - bidder: 'navelix', + bidder: 'janet', params: { aid: 472386 } @@ -62,7 +59,7 @@ Navelix now supports adpod. } }, bids: [{ - bidder: 'navelix', + bidder: 'janet', params: { aid: 472386 } @@ -80,7 +77,7 @@ Navelix now supports adpod. } }, bids: [{ - bidder: 'navelix', + bidder: 'janet', params: { aid: 472386 } @@ -96,7 +93,7 @@ Navelix now supports adpod. } } bids: [{ - bidder: 'navelix', + bidder: 'janet', params: { aid: 529814 } @@ -113,7 +110,7 @@ It is possible to configure requests to be split into chunks so as to have fewer ``` pbjs.setBidderConfig({ config: { - navelix: { + janet: { chunkSize: 1 // makes 1 http request per 1 adunit configured } } diff --git a/dev-docs/bidders/jcm.md b/dev-docs/bidders/jcm.md index 266c16c3b4..bb54e79087 100644 --- a/dev-docs/bidders/jcm.md +++ b/dev-docs/bidders/jcm.md @@ -4,7 +4,8 @@ title: J Carter Marketing description: Prebid J Carter Marketing Bidder Adaptor pbjs: true biddercode: jcm -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/jixie.md b/dev-docs/bidders/jixie.md index b9241665de..4839bc6b4b 100644 --- a/dev-docs/bidders/jixie.md +++ b/dev-docs/bidders/jixie.md @@ -5,8 +5,9 @@ description: Prebid Jixie Bidder Adaptor pbjs: true pbs: true biddercode: jixie -bidder_supports_deals: false +deals_supported: false media_types: banner, video +userIds: uid2, unifiedId gdpr_supported: false --- diff --git a/dev-docs/bidders/justpremium.md b/dev-docs/bidders/justpremium.md index 20732ff502..f5eebddc3c 100644 --- a/dev-docs/bidders/justpremium.md +++ b/dev-docs/bidders/justpremium.md @@ -6,6 +6,7 @@ pbjs: true biddercode: justpremium gdpr_supported: true usp_supported: true +schain_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId --- diff --git a/dev-docs/bidders/kargo.md b/dev-docs/bidders/kargo.md index 926a62f1a1..d759460b4d 100644 --- a/dev-docs/bidders/kargo.md +++ b/dev-docs/bidders/kargo.md @@ -4,12 +4,16 @@ title: Kargo description: Prebid Kargo Bidder Adaptor pbjs: true biddercode: kargo +media_types: banner, video gdpr_supported: true userIds: unifiedId usp_supported: true gvl_id: 972 --- +### Disclosure: +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. + ### Note: Kargo is an invitation-only marketplace. Please reach out to your Kargo account manager to get setup. Also, you *must* test on a mobile device, or emulate a mobile device by manipulating the user agent string sent to the server. diff --git a/dev-docs/bidders/kobler.md b/dev-docs/bidders/kobler.md index a93b1032b3..ed1b8c3215 100644 --- a/dev-docs/bidders/kobler.md +++ b/dev-docs/bidders/kobler.md @@ -5,8 +5,8 @@ description: Kobler Bidder Adapter biddercode: kobler pbjs: true media_types: banner -getFloor: true -bidder_supports_deals: true +floors_supported: true +deals_supported: true --- ### Note: @@ -17,14 +17,15 @@ Please reach out to for more information. ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|--------------------| -| `placementId` | required | The identifier of the placement, it has to be issued by Kobler. | `'xjer0ch8'` | `string` | -| `zip` | optional | Zip code of the user or the medium. When multiple ad units are submitted together, it is enough to set this parameter on the first one. | `'102 22'` | `string` | -| `test` | optional | Whether the request is for testing only. When multiple ad units are submitted together, it is enough to set this parameter on the first one. Defaults to false. | `true` | `boolean` | -| `floorPrice` | optional | Floor price in CPM and in USD. Can be used as an alternative to the [Floors module](https://docs.prebid.org/dev-docs/modules/floors.html), which is also supported by this adapter. Defaults to 0. | `5.0` | `float` | -| `position` | optional | The position of the ad unit. Can be used to differentiate between ad units if the same placement ID is used across multiple ad units. Defaults to 0. | `1` | `string` | -| `dealIds` | optional | Array of deal IDs. | `['abc328745', 'mxw243253']` | `array of strings` | +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|--------------------| +| `test` | optional | Whether the request is for testing only. When multiple ad units are submitted together, it is enough to set this parameter on the first one. Enables providing a custom URL through config.pageUrl. Defaults to false. | `true` | `boolean` | +| `floorPrice` | optional | Floor price in CPM and in USD. Can be used as an alternative to the [Floors module](https://docs.prebid.org/dev-docs/modules/floors.html), which is also supported by this adapter. Defaults to 0. | `5.0` | `float` | +| `dealIds` | optional | Array of deal IDs. | `['abc328745', 'mxw243253']` | `array of strings` | + +### Implicit parameters + +Kobler identifies the placement using the combination of the page URL and the allowed sizes. As a result, it's important that the correct sizes are provided in `banner.sizes` in order for Kobler to correctly identify the placement. The main, desired format should be the first element of this array. ### Example ```javascript @@ -36,17 +37,18 @@ Please reach out to for more information. } }, bids: [{ - bidder: 'kobler', - params: { - placementId: 'k5H7et3R0' - } + bidder: 'kobler' }] }]; ``` In order to see a sample bid from Kobler (without a proper setup), you have to also do the following: -- Change the [`refererInfo` function](https://github.com/prebid/Prebid.js/blob/master/src/refererDetection.js) to return `'https://www.tv2.no/a/11734615'` as a [`referer`](https://github.com/prebid/Prebid.js/blob/caead3ccccc448e4cd09d074fd9f8833f56fe9b3/src/refererDetection.js#L169). This is necessary because Kobler only bids on recognized articles. +- Change the [`refererInfo` function](https://github.com/prebid/Prebid.js/blob/master/src/refererDetection.js) to return `'https://www.tv2.no/a/11734615'` as a `page`. This is necessary because Kobler only bids on recognized articles. - Change the adapter's [`BIDDER_ENDPOINT`](https://github.com/prebid/Prebid.js/blob/master/modules/koblerBidAdapter.js#L8) to `'https://bid-service.dev.essrtb.com/bid/prebid_rtb_call'`. This endpoint belongs to the development server that is set up to always return a bid for the correct `placementId` and page URL combination. + +- Set the `test` parameter to `true`. +- Set `config.pageUrl` to `'https://www.tv2.no/mening-og-analyse/14555348/'`. This is necessary because Kobler only bids on recognized articles. Kobler runs its own test campaign to make sure there is always a bid for this specific page URL. + ### Example With Optional Parameters ```javascript @@ -60,11 +62,8 @@ In order to see a sample bid from Kobler (without a proper setup), you have to a bids: [{ bidder: 'kobler', params: { - placementId: 'k5H7et3R0', - zip: '102 22', test: true, floorPrice: 5.0, - position: 1, dealIds: ['abc328745', 'mxw243253'] } }] diff --git a/dev-docs/bidders/komoona.md b/dev-docs/bidders/komoona.md index 14a371176e..bf5d0c0331 100644 --- a/dev-docs/bidders/komoona.md +++ b/dev-docs/bidders/komoona.md @@ -4,7 +4,8 @@ title: Komoona description: Prebid Komoona Bidder Adaptor pbjs: true biddercode: komoona -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/krushmedia.md b/dev-docs/bidders/krushmedia.md index a6b4ce8012..90b4734ed9 100644 --- a/dev-docs/bidders/krushmedia.md +++ b/dev-docs/bidders/krushmedia.md @@ -9,7 +9,6 @@ media_types: banner, video, native gdpr: true pbjs: true pbs: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/kubient.md b/dev-docs/bidders/kubient.md index 4161e77ef1..83badb939f 100644 --- a/dev-docs/bidders/kubient.md +++ b/dev-docs/bidders/kubient.md @@ -6,17 +6,69 @@ pbjs: true pbs: true schain_supported: true biddercode: kubient -media_types: banner +media_types: banner, video gdpr_supported: true usp_supported: true +coppa_supported: true +tcf2_supported: true gvl_id: 794 -pbjs_version_notes: not in 5.x --- ### Note: The Kubient Bidder Adapter requires setup and approval before beginning. Please reach out to for more details. +Banner Settings: + +var adUnits = [ + { + code: 'banner-ad-unit', + mediaTypes: { + banner: { + sizes: [[300, 100]] + } + }, + bids: [{ + bidder: 'kubient', + params: { + zoneid: "5fbb948f1e22b", + } + }] + } +]; + +Video Settings: + +var adUnits = [ + { + code: 'video-ad-unit', + mediaTypes: { + video: { + playerSize: [300, 250], // required + context: 'instream', // required + mimes: ['video/mp4','video/x-flv'], // required + protocols: [ 2, 3 ], // required, set at least 1 value in array + placement: 1, // optional, defaults to 2 when context = outstream + api: [ 1, 2 ], // optional + skip: 0, // optional + minduration: 5, // optional + maxduration: 30, // optional + playbackmethod: [1,3], // optional + battr: [ 13, 14 ], // optional + linearity: 1, // optional + minbitrate: 10, // optional + maxbitrate: 10 // optional + } + }, + bids: [{ + bidder: 'kubient', + params: { + zoneid: "60ad1c0b35864", + } + }] + } +]; + ### Bid Params {: .table .table-bordered .table-striped } diff --git a/dev-docs/bidders/kueez.md b/dev-docs/bidders/kueez.md new file mode 100644 index 0000000000..4402017dc6 --- /dev/null +++ b/dev-docs/bidders/kueez.md @@ -0,0 +1,82 @@ +--- +layout: bidder +title: Kueez +description: Prebid Kueez Bidder Adapter +multiformat_supported: will-bid-on-any +pbjs: true +biddercode: kueez +media_types: banner, video +schain_supported: true +gdpr_supported: true +usp_supported: true +floors_supported: true +userIds: all +fpd_supported: true +--- + +### Note + +The Kueez adapter requires setup and approval. Please reach out to prebid@kueez.com. + +### Bid Parameters + +#### Banner, Video + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | Example +| ---- | ----- | ---- | ----------- | ------- +| `org` | required | String | the organization Id provided by your Kueez representative | "test-org-id" +| `floorPrice` | optional | Number | Minimum price in USD. Misuse of this parameter can impact revenue | 1.5 +| `placementId` | optional | String | A unique placement identifier | "12345678" +| `testMode` | optional | Boolean | This activates the test mode | false + +## Example + ```javascript +var adUnits = [{ + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [728, 90] + ] + } + }, + bids: [{ + bidder: 'kueez', + params: { + org: 'test-org-id', // Required + floorPrice: 1.2, // Optional + placementId: '12345678', // Optional + testMode: true // Optional + } + }] + }, + { + code: 'dfp-video-div', + sizes: [ + [640, 480] + ], + mediaTypes: { + video: { + playerSize: [ + [640, 480] + ], + context: 'instream' + } + }, + bids: [{ + bidder: 'kueez', + params: { + org: 'test-org-id', // Required + floorPrice: 1.50, // Optional + placementId: '12345678', // Optional + testMode: true // Optional + } + }] + } +]; +``` + +### Configuration +Kueez recommends setting UserSync by iframe for monetization. diff --git a/dev-docs/bidders/lasso.md b/dev-docs/bidders/lasso.md new file mode 100644 index 0000000000..f119cfe927 --- /dev/null +++ b/dev-docs/bidders/lasso.md @@ -0,0 +1,28 @@ +--- +layout: bidder +title: Lasso +description: Prebid Lasso Bidder Adaptor +biddercode: lasso +pbjs: true +pbs: false +media_types: banner +gdpr_supported: false +gvl_id: none +coppa_supported: true +usp_supported: true +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +multiformat_supported: will-not-bid +--- + +### Note: +The Lasso Bidding adapter requires setup before beginning. Please contact us at headerbidding@lassomarketing.io + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------------------|--------------------------------------|----------| +| `adUnitId` | required | Unique adUnitId from Lasso | `'12345'` | `string` | diff --git a/dev-docs/bidders/lemma.md b/dev-docs/bidders/lemma.md index 68c76068a7..fd3d712113 100644 --- a/dev-docs/bidders/lemma.md +++ b/dev-docs/bidders/lemma.md @@ -4,7 +4,8 @@ title: LEMMA description: Prebid Lemma Bidder Adapter pbjs: true biddercode: lemma -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Integration Note: diff --git a/dev-docs/bidders/lifestreet.md b/dev-docs/bidders/lifestreet.md index 049e1acad3..dc867e2600 100644 --- a/dev-docs/bidders/lifestreet.md +++ b/dev-docs/bidders/lifestreet.md @@ -9,7 +9,8 @@ media_types: video gdpr_supported: true usp_supported: true gvl_id: 67 -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/limelightDigital.md b/dev-docs/bidders/limelightDigital.md new file mode 100644 index 0000000000..9714e224f2 --- /dev/null +++ b/dev-docs/bidders/limelightDigital.md @@ -0,0 +1,18 @@ +--- +layout: bidder +title: Limelight Digital +description: Prebid Limelight Digital Bidder Adaptor +pbjs: true +biddercode: limelightDigital +media_types: video +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example |type| +| :----------- | :--------- | :------------ | :----------------- |:---| +| `host` | required | Ad network's RTB host | `'exchange.ortb.net'` | `string` | +| `adUnitId` | required | Ad Unit Id will be generated on Limelight Digital Platform. | 0 | `integer` | +| `adUnitType` | required | Type of Ad Unit (`'video'`, `'banner'`) | `'banner'` | `string` | +| `publisherId` | optional | Publisher ID | `'12345'` | `string` | diff --git a/dev-docs/bidders/lkqd.md b/dev-docs/bidders/lkqd.md index e2a48b1fb0..ecc917df44 100644 --- a/dev-docs/bidders/lkqd.md +++ b/dev-docs/bidders/lkqd.md @@ -3,8 +3,11 @@ layout: bidder title: LKQD description: Prebid LKQD Bidder Adaptor pbjs: true -biddercode: lkqd -pbjs_version_notes: not in 5.x +biddercode: lkqd +media_types: video +gdpr_supported: true +schain_supported: true +pbjs_version_notes: not ported to 5.x --- ### Note: @@ -15,5 +18,29 @@ For more information about [LKQD Ad Serving and Management](https://www.nexstard {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |------------------|----------|------------------|----------------|------| -| `placementId` | required | | `'263'` | `string` | | `siteId` | required | | `'662921'` | `string` | +| `placementId` | required | | `'263'` | `string` | + + +### Ad Unit Setup for Instream Video +```javascript +var adUnits = [ +{ + code: 'video1', // ad slot HTML element ID + mediaTypes: { + video: { // We recommend setting the following video params + // in Ad Unit rather than bidder params as per Prebid 4.0 recommendation. + playerSize: [640, 480], // required + context: 'instream' // required + } + }, + bids: [{ + bidder: 'lkqd', + params: { + siteId: '662921', // required + placementId: '263' // required + } + }], + ... +} +``` diff --git a/dev-docs/bidders/logan.md b/dev-docs/bidders/logan.md index d50f36fabe..01fb0f3af2 100644 --- a/dev-docs/bidders/logan.md +++ b/dev-docs/bidders/logan.md @@ -8,7 +8,6 @@ schain_supported: true media_types: banner, video, native gdpr: true pbjs: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/logicad.md b/dev-docs/bidders/logicad.md index 038c9a7eac..f0c28c3825 100644 --- a/dev-docs/bidders/logicad.md +++ b/dev-docs/bidders/logicad.md @@ -6,12 +6,11 @@ pbjs: true pbs: true pbs_app_supported: true biddercode: logicad -bidder_supports_deals: false +deals_supported: false media_types: banner, native userIds: all gdpr_supported: false prebid_member: false -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/loglylift.md b/dev-docs/bidders/loglylift.md new file mode 100644 index 0000000000..af9630ba63 --- /dev/null +++ b/dev-docs/bidders/loglylift.md @@ -0,0 +1,27 @@ +--- +layout: bidder +title: LOGLY lift +description: Prebid LOGLY lift Bidder Adaptor +biddercode: loglylift +gdpr_supported: false +usp_supported: false +coppa_supported: false +schain_supported: false +dchain_supported: false +media_types: banner, native +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +pbjs: true +pbs: false +prebid_member: false +--- + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|--------|----------|----------------------------------------------------------|----------|-----------| +| `adspotId` | required | adspot id managed by LOGLY lift | `4302078` | `integer` | diff --git a/dev-docs/bidders/loopme.md b/dev-docs/bidders/loopme.md index cd2bc82b47..bc261b6922 100644 --- a/dev-docs/bidders/loopme.md +++ b/dev-docs/bidders/loopme.md @@ -6,7 +6,8 @@ pbjs: true biddercode: loopme gdpr_supported: true media_types: banner, video -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid params diff --git a/dev-docs/bidders/lunamedia.md b/dev-docs/bidders/lunamedia.md index 80d72de5f8..00f9dc31c3 100644 --- a/dev-docs/bidders/lunamedia.md +++ b/dev-docs/bidders/lunamedia.md @@ -5,7 +5,8 @@ description: Prebid Luna Media Bidder Adapter pbjs: true pbs: true biddercode: lunamedia -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/lunamediahb.md b/dev-docs/bidders/lunamediahb.md index a54bc09d8c..4fd4d09d09 100644 --- a/dev-docs/bidders/lunamediahb.md +++ b/dev-docs/bidders/lunamediahb.md @@ -5,8 +5,9 @@ description: Prebid Lunamedia Bidder Adapter biddercode: lunamediahb usp_supported: true schain_supported: true +gdpr_supported: true +coppa_supported: true media_types: banner, video, native -gdpr: true pbjs: true pbs: false --- diff --git a/dev-docs/bidders/luponmedia.md b/dev-docs/bidders/luponmedia.md index 7c7b46b1b5..598bc5d82e 100644 --- a/dev-docs/bidders/luponmedia.md +++ b/dev-docs/bidders/luponmedia.md @@ -9,7 +9,7 @@ usp_supported: true coppa_supported: true schain_supported: true userIds: digitrust, identityLink, liveIntentId, pubCommonId -pbjs_version_notes: not in 5.x +pbjs_version_notes: not in 5.x, in 6.2+ --- ### Note: diff --git a/dev-docs/bidders/madvertise.md b/dev-docs/bidders/madvertise.md index 815e312bd2..3f58b6578b 100644 --- a/dev-docs/bidders/madvertise.md +++ b/dev-docs/bidders/madvertise.md @@ -10,7 +10,6 @@ media_types: banner, video safeframes_ok: true pbs: true pbs_app_supported: true -pbjs_version_notes: not in 5.x --- ### Prebid.js Bid Params @@ -18,7 +17,8 @@ pbjs_version_notes: not in 5.x {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |--------------|----------|---------------------------------------------------------------------------------------------------------|-----------------------------------------|-----------| -| `s` | required | Zone code. This parameter should be the unique Publisher ID of your mobile application or website. | `'/4543756/prebidadaptor/madvertiseHB'` | `string` | +| `zoneId` | required Prebid version 5.x+| Zone code. This parameter should be the unique Publisher ID of your mobile application or website. | `/1111111/banner` | `string` | +| `s` | required in-scope only for 4.x | Zone code. This parameter should be the unique Publisher ID of your mobile application or website. Replace by zoneId starting 5.x | `/1111111/banner` | `string` | | `lat` | optional | Latitude | `48.866667` | `float` | | `long` | optional | Longitude | `2.333333` | `float` | | `age` | optional | Age | `19` | `integer` | @@ -32,7 +32,7 @@ pbjs_version_notes: not in 5.x { bidder: 'madvertise', params: { - s: "/4543756/prebidadaptor/madvertiseHB", + zoneId: "/4543756/prebidadaptor/madvertiseHB", tgt:'aa=a;bb=b' } } @@ -79,3 +79,4 @@ pbjs_version_notes: not in 5.x "tmax": 1000 } ``` + diff --git a/dev-docs/bidders/mantis.md b/dev-docs/bidders/mantis.md index 5e663ba17f..ba004f27b6 100644 --- a/dev-docs/bidders/mantis.md +++ b/dev-docs/bidders/mantis.md @@ -7,7 +7,6 @@ biddercode: mantis media_types: native, video usp_supported: true gdpr_supported: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/marsmedia.md b/dev-docs/bidders/marsmedia.md index a38b704088..8281cb732f 100644 --- a/dev-docs/bidders/marsmedia.md +++ b/dev-docs/bidders/marsmedia.md @@ -7,7 +7,7 @@ pbs: true biddercode: marsmedia media_types: video, banner gdpr_supported: true -getFloor: true +floors_supported: true schain_supported: true usp_supported: true coppa_supported: true diff --git a/dev-docs/bidders/mathildeads.md b/dev-docs/bidders/mathildeads.md new file mode 100644 index 0000000000..c7dbe99b03 --- /dev/null +++ b/dev-docs/bidders/mathildeads.md @@ -0,0 +1,20 @@ +--- +layout: bidder +title: MathildeAds +description: Prebid MathildeAds Bidder Adapter +biddercode: mathildeads +usp_supported: true +schain_supported: true +media_types: banner, video, native +gdpr_supported: true +pbjs: true +pbs: false +pbs_app_supported: false +--- + +### Prebid.JS Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|----------------------------------------------------------|------------|-----------| +| `placementId` | required | Placement Id will be generated on MathildeAds Platform. | `'1234'` | `string` | diff --git a/dev-docs/bidders/meazy.md b/dev-docs/bidders/meazy.md index 5a22b93b07..380816144d 100644 --- a/dev-docs/bidders/meazy.md +++ b/dev-docs/bidders/meazy.md @@ -4,7 +4,8 @@ title: Meazy description: Prebid Meazy Bidder Adaptor pbjs: true biddercode: meazy -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid params diff --git a/dev-docs/bidders/mediafuse.md b/dev-docs/bidders/mediafuse.md index bea840ecbb..188298e188 100644 --- a/dev-docs/bidders/mediafuse.md +++ b/dev-docs/bidders/mediafuse.md @@ -2,69 +2,155 @@ layout: bidder title: MediaFuse description: Prebid MediaFuse Bidder Adapter +biddercode: mediafuse +media_types: video,banner +gdpr_supported: true +schain_supported: true +coppa_supported: true +usp_supported: true +safeframes_ok: true +prebid_member: true pbjs: true pbs: true -biddercode: mediafuse -aliasCode: adtelligent -media_types: banner, video --- -### Bid params +#### Prebid Server Test Request -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------|----------|---------------------------------|----------|-----------| -| `aid` | required | The traffic source ID | `529814` | `integer` | +The following test parameters can be used to verify that Prebid Server is working properly with the server-side Mediafuse adapter. This example includes an Mediafuse test placement ID and sizes that would match with the test creative. - -### Test Parameters ``` - var adUnits = [ - - // Video instream adUnit - { - code: 'div-test-div', - sizes: [[640, 480]], - mediaTypes: { - video: { - context: 'instream' - } - }, - bids: [{ - bidder: 'mediafuse', - params: { - aid: 331133 - } - }] +var adUnits = [ + // Banner adUnit + { + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } }, - - // Video outstream adUnit - { - code: 'outstream-test-div', - sizes: [[640, 480]], - mediaTypes: { - video: { - context: 'outstream' + bids: [{ + bidder: 'mediafuse', + params: { + placementId: 13144370 + } + }] + }, + // Native adUnit + { + code: 'native-div', + sizes: [[1, 1]], + mediaTypes: { + native: { + title: { + required: true + }, + body: { + required: true + }, + image: { + required: true + }, + sponsoredBy: { + required: true + }, + icon: { + required: false } + } + }, + bids: [{ + bidder: 'mediafuse', + params: { + placementId: 13232354, + allowSmallerSizes: true + } + }] + }, + // Video instream adUnit + { + code: 'video-instream', + sizes: [[640, 480]], + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'instream' }, - bids: [{ - bidder: 'mediafuse', - params: { - aid: 331133 - } - }] }, - - // Banner adUnit - { - code: 'div-test-div', - sizes: [[300, 250]], - bids: [{ - bidder: 'mediafuse', - params: { - aid: 529814 + bids: [{ + bidder: 'mediafuse', + params: { + placementId: 13232361, + video: { + skippable: true, + playback_methods: ['auto_play_sound_off'] } - }] - } - ]; -``` + } + }] + }, + // Video outstream adUnit + { + code: 'video-outstream', + sizes: [[300, 250]], + mediaTypes: { + video: { + playerSize: [[300, 250]], + context: 'outstream', + // Certain ORTB 2.5 video values can be read from the mediatypes object; below are examples of supported params. + // To note - mediafuse supports additional values for our system that are not part of the ORTB spec. If you want + // to use these values, they will have to be declared in the bids[].params.video object instead using the mediafuse syntax. + // Between the corresponding values of the mediaTypes.video and params.video objects, the properties in params.video will + // take precedence if declared; eg in the example below, the `skippable: true` setting will be used instead of the `skip: 0`. + minduration: 1, + maxduration: 60, + skip: 0, // 1 - true, 0 - false + skipafter: 5, + playbackmethod: [2], // note - we only support options 1-4 at this time + api: [1,2,3] // note - option 6 is not supported at this time + } + }, + bids: [ + { + bidder: 'mediafuse', + params: { + placementId: 13232385, + video: { + skippable: true, + playback_method: 'auto_play_sound_off' + } + } + } + ] + }, + // Banner adUnit in a App Webview + // Only use this for situations where prebid.js is in a webview of an App + // See Prebid Mobile for displaying ads via an SDK + { + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + } + bids: [{ + bidder: 'mediafuse', + params: { + placementId: 13144370, + app: { + id: "B1O2W3M4AN.com.prebid.webview", + geo: { + lat: 40.0964439, + lng: -75.3009142 + }, + device_id: { + idfa: "4D12078D-3246-4DA4-AD5E-7610481E7AE", // Apple advertising identifier + aaid: "38400000-8cf0-11bd-b23e-10b96e40000d", // Android advertising identifier + md5udid: "5756ae9022b2ea1e47d84fead75220c8", // MD5 hash of the ANDROID_ID + sha1udid: "4DFAA92388699AC6539885AEF1719293879985BF", // SHA1 hash of the ANDROID_ID + windowsadid: "750c6be243f1c4b5c9912b95a5742fc5" // Windows advertising identifier + } + } + } + }] + } +]; +``` \ No newline at end of file diff --git a/dev-docs/bidders/mediafuseLift.md b/dev-docs/bidders/mediafuseLift.md deleted file mode 100644 index fd95ca0f39..0000000000 --- a/dev-docs/bidders/mediafuseLift.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: bidder -title: MediaFuse Lift -description: Prebid MediaFuse Lift Bidder Adaptor -top_nav_section: dev_docs -nav_section: reference -pbjs: true -biddercode: mediafuseLift -aliasCode : orbitsoft ---- - - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|----------------|----------|----------------------------------------------------------------------|-------------------------------------|-----------| -| `placementId` | required | The placement ID (site channel ID) | `142` | `integer` | -| `requestUrl` | required | Url to perform search request | `'http://adserver.com/ads/show/hb'` | `string` | -| `style` | optional | Creative styles. Actual only for text ads | | `string` | -| `customParams` | optional | Permits passing any publisher key-value pairing into the bid request | `{"macro_name": "macro_value" }` | `object` | - diff --git a/dev-docs/bidders/mediago.md b/dev-docs/bidders/mediago.md index 42d5b3a484..670231f398 100644 --- a/dev-docs/bidders/mediago.md +++ b/dev-docs/bidders/mediago.md @@ -5,7 +5,8 @@ description: MediaGo Prebid Bidder Adapter biddercode: mediago media_types: banner pbjs: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/mediakeys.md b/dev-docs/bidders/mediakeys.md new file mode 100644 index 0000000000..c15e5ff62d --- /dev/null +++ b/dev-docs/bidders/mediakeys.md @@ -0,0 +1,428 @@ +--- +layout: bidder +title: Mediakeys +description: Mediakeys Prebid Bidder Adapter +biddercode: mediakeys +media_types: banner, video, native +gvl_id: 498 +pbjs: true +floors_supported: true +gdpr_supported: true +schain_supported: true +coppa_supported: true +usp_supported: true +safeframes_ok: true +userIds: all +fpd_supported: true +--- + + +### Table of Contents + +- [Table of Contents](#table-of-contents) +- [Important Notice](#important-notice) +- [Bid Params](#bid-params) + - [First Party Data](#first-party-data) + - [Required and Recommended Modules](#required-and-recommended-modules) +- [MediaType Banner](#mediatype-banner) +- [MediaType Video](#mediatype-video) + - [Instream video](#instream-video) + - [Outstream video](#outstream-video) +- [MediaType Native](#mediatype-native) + + + +### Important Notice + +The Mediakeys Bidding adapter requires setup before beginning and will respond with bids for whitelisted domains only. + +Please contact us at prebidjs@mediakeys.com. + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|---------------------|------------------------------|-----------|-----------| +| `context` | required for native | Native context | `1` | `integer` | +| `plcmttype` | required for native | Native placement type | `2` | `integer` | + + + +#### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.site.*`: Standard IAB OpenRTB 2.5 site fields +- `ortb2.site.content.data[]`: Standard IAB segment taxonomy site data +- `ortb2.site.ext.data.*`: Non standard arbitrary site data +- `ortb2.user.*`: Standard IAB OpenRTB 2.5 user fields +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.ext.data.*`: Non standard arbitrary user data + +Please note that field `ortb2.app.*`, in a webview context, is **not supported**. + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` + +Example first party data that's available to all bidders and all adunits: + +```javascript +pbjs.setConfig({ + ortb2: { + site: { + // standard IAB OpenRTB 2.5 site fields are passed in `ortb2.site.*` + name: "example", + cat: ["IAB2"], + domain: "page.example.com", + + // standard IAB segment taxonomy site data is passed in `ortb2.site.content.data[]` + content: { + userrating: "4", + data: [{ name: "www.sitedataprovider1.com" }] + }, + + // any non standard arbitrary site data is passed in `ortb2.site.ext.data.*` + ext: { data: { arbitrarySiteKey: "arbitrary" } } + }, + user: { + // standard IAB OpenRTB 2.5 user fields are passed in `ortb2.user.*` + keywords: "a,b", + geo: { country: "FRA", lat: 48.9, lon: 2.2 }, + + // standard IAB segment taxonomy user data are passed in `ortb2.user.data[]` + data: [{ name: "www.userdataprovider1.com" }], + + // any non standard arbitrary user data is passed in `ortb2.user.ext.data.*` + ext: { data: { arbitraryUserKey: "arbitrary" } } + } + } +}); +``` + +Example of first party data available only to the Mediakeys bidder and applies across all ad units: + +```javascript +pbjs.setBidderConfig({ + bidders: ['mediakeys'], + config: { + ortb2: { + site: { + ext: { + data: { + pageType: "article", + category: "tools" + } + } + }, + user: { + ext: { + data: { + registered: true, + interests: ["cars"] + } + } + } + } + } +}); +``` + +Example of an adunit-specific with first party data: + +```javascript +var adUnit = { + // applies to all bidders + ortb2Imp: { + instl:1 + }, + bids: [{ + bidder: 'mediakeys', + params: {}, + // applies to mediakeys bidder only + ortb2Imp: { + ext: { + data: { + pbadslot: "homepage-top-rect", + adUnitSpecificAttribute: "123" + } + } + } + }] +}; +``` + + + +#### Required and Recommended Modules + +Mediakeys fully supports the following [Prebid.js Modules](https://docs.prebid.org/dev-docs/modules/): + +{: .table .table-bordered .table-striped } +| Module | Scope | +|-------------------------------------------------------------------------------------------------------|-----------------------------| +| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagement.html) | Required in Europe | +| [Consent Management - US Privacy](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | Required in US - California | +| [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html) | Required for all traffic | +| [Instream Tracking](https://docs.prebid.org/dev-docs/modules/instreamTracking.html) | Required for Instream Video | +| [First Party Data Enrichment](https://docs.prebid.org/dev-docs/modules/enrichmentFpdModule.html) | Recommended for all traffic | + +Publishers must utilize the required modules in described scope to be able to receive bid responses. + +Before using [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html) Module, please confirm with the Mediakeys team +the proper `asi` and `sid` field values that you should pass. + + + +### MediaType Banner + +The Mediakeys adapter accepts any valid [OpenRTB Spec 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) property. + +Example Ad Unit: + +```javascript +const adUnits = [{ + code: 'banner-1', + mediaTypes: { + banner: { + sizes: [[300, 250],[300, 600]], + } + }, + bids: [{ + bidder: 'mediakeys', + params: {} // no params required. + }] +}]; +``` + + + +### MediaType Video + +The Mediakeys adapter accepts any valid [OpenRTB Spec 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) video property. + +Properties can be defined at the adUnit `mediaTypes.video` or `bid[].params` level. + +Please refer to the following table to find acceptable values for mediakeys bidder: + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|-------------|-----------------------------------------------------------------|------------|--------| +| context | required | instream or outstream |"outstream" | string | +| playerSize (*) | required | width, height of the player in pixels | [640,360]
    translated to w and h in bid request | array<integers> | +| mimes | recommended | Content MIME types supported | ["video/x-ms-wmv", "video/mp4"]
    default: ["video/mp4"]| array<string>| +| protocols | recommended | Array of supported video protocols:
    2: VAST 2.0
    3: VAST 3.0 | [2,3]
    default: [3] | array<integers>| +| maxduration | recommended | Maximum video ad duration in seconds. | 30
    default: not set | integer | +| skip | recommended | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. | 1
    default: 0 | integer | + +(*) Mediakeys bidder will adapt the bid response to send the video format closest to the `playerSize` (from an aspect ratio point of view). To maximize the responses, please consider requesting formats like: + +- small video: `360x268` (minimal bandwidth, low quality) +- medium video: `640x360` (low bandwidth, medium quality) +- standard video: `640×480` (medium bandwidth, good quality) +- full wide video: `854×480` (high bandwidth, superior quality) +- HD video: `1280x720` (maximum bandwidth, best quality) + + + +#### Instream video + +For [Instream Video](https://docs.prebid.org/prebid-video/video-getting-started.html#instream), you have to enable the [Instream Tracking Module](https://docs.prebid.org/dev-docs/modules/instreamTracking.html) to have Prebid emit the `onBidWon` required event. + +Required Prebid configuration: + +a. Enable the instream tracking module and whitelist mediakeys Vast server url. + +```javascript +pbjs.que.push(function () { + pbjs.setConfig({ + instreamTracking: { + // enable the `bidWon` event required by mediakeys + enabled: true, + // enable mediakeys vast server to have Prebid emit the `bidWon` event + urlPattern: /mediakeys\.io/ + } + }); +}); +``` + +b. Do not mark the bid as "used" as it could prevent emitting the `bidWon` event. + +```javascript +pbjs.que.push(function () { + pbjs.addAdUnits(adUnits); + pbjs.requestBids({ + timeout: 1000, + bidsBackHandler: function (bids) { + const highestCpmBids = pbjs.getHighestCpmBids('video1'); + + if (highestCpmBids.length > 0) { + // !! DO NOT use this !! + // pbjs.markWinningBidAsUsed({ + // adUnitCode: adUnits[0].code + // }); + invokeVideoPlayer(highestCpmBids[0].vastUrl); + } + } + }); +}); +``` + +Example Ad Unit: + +```javascript +const adUnits = [{ + code: 'video1', + mediaTypes: { + video: { + context: 'instream', + playerSize: [854, 480], + // additional OpenRTB video params + // placement: 2, + // ... + mimes: ['video/mp4'], + protocols: [2, 3], + skip: 1 + } + }, + bids: [{ + bidder: 'mediakeys', + params: { + video: { + // additional OpenRTB video params + // will be merged with params defined at mediaTypes level + api: [1] + } + } + }] +}]; +``` + + + +#### Outstream video + +Required Prebid configuration: + +You must set up your preferred outstream renderer in the ad unit and use the following example code to fetch the +`vast xml` document from mediakeys ad-server. + +Example Ad Unit: + +```javascript +const adUnits = [{ + code: 'video1', + mediaTypes: { + video: { + context: 'outstream', + playerSize: [1280, 720], + // additional OpenRTB video params + // placement: 2, + // ... + mimes: ['video/mp4'], + protocols: [2, 3], + skip: 0 + } + }, + // this renderer is required for outstream video mediatype + renderer: { + url: 'https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js', + // the render method must fetch the vast xml document before displaying video + render: function (bid) { + var adResponse = fetch(bid.vastUrl).then(resp => resp.text()).then(text => ({ + ad: { + video: { + content: text, + player_height: bid.playerHeight, + player_width: bid.playerWidth + } + } + })) + + adResponse.then((content) => { + bid.renderer.push(() => { + ANOutstreamVideo.renderAd({ + targetId: bid.adUnitCode, + adResponse: content + }); + }); + }) + } + }, + bids: [{ + bidder: 'mediakeys', + params: { + placementId: 13232385, + video: { + // additional OpenRTB video params + // will be merged with params defined at mediaTypes level + api: [1] + } + } + }] +}]; +``` + + + +### MediaType Native + +The Mediakeys adapter accepts any valid [OpenRTB Native Ads Specification](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) native property. + +Please refer to [Prebid native ad unit documentation](https://docs.prebid.org/prebid/native-implementation.html#3-prebidjs-native-adunit-overview), and the following table to see required and recommended parameters. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|--------------------|----------------------------------------------------------|---------|-----------| +| context | required | The context in which the ad appears | `1` | integer | +| plcmttype | recommended | The design/format/layout of the ad unit being offered | `1` | integer | + +Required Prebid configuration: + +Refer to [Prebid documentation](https://docs.prebid.org/prebid/native-implementation.html#4-implementing-the-native-template) +to use your preferred method for native ad template rendering. + +Example Ad Unit: + +This example uses the [external javascript file rendering method](https://docs.prebid.org/prebid/native-implementation.html#43-implementing-the-custom-renderer-scenario). + +```javascript +const adUnits = [{ + code: 'native-1', + sizes: [360, 360], + mediaTypes: { + native: { + rendererUrl: 'https://example.com/nativeRender.js', + body: { + required: true + }, + title: { + required: true, + len: 120 + }, + sponsoredBy: { + required: true + }, + icon: { + required: true, + sizes: [180, 180] + }, + image: { + required: true, + sizes: [300, 250] + } + } + }, + bids: [{ + bidder: 'mediakeys', + native: { + context: 1, + plcmttype: 1, + } + }] +}]; +``` diff --git a/dev-docs/bidders/medianet.md b/dev-docs/bidders/medianet.md index 73de20eb45..5795543ede 100644 --- a/dev-docs/bidders/medianet.md +++ b/dev-docs/bidders/medianet.md @@ -11,7 +11,8 @@ prebid_member: true pbjs: true gvl_id: 142 schain_supported: true -getFloor: true +floors_supported: true +pbs: true --- ### Bid Params diff --git a/dev-docs/bidders/mediasniper.md b/dev-docs/bidders/mediasniper.md new file mode 100644 index 0000000000..613989688d --- /dev/null +++ b/dev-docs/bidders/mediasniper.md @@ -0,0 +1,21 @@ +--- +layout: bidder +title: Mediasniper +description: Mediasniper Prebid Bidder Adapter +biddercode: mediasniper +media_types: banner +pbjs: true +floors_supported: true +safeframes_ok: true +--- +### Note: + +The Mediasniper Bidding adapter requires setup before beginning. Please contact us at oleg@rtbtech.org + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `placementId` | required | Placement id | `'11111'` | `string` | +| `siteid` | optional | Site id | `'11111'` | `string` | diff --git a/dev-docs/bidders/mediasquare.md b/dev-docs/bidders/mediasquare.md index 4777ebf6ec..02ebc4d0af 100644 --- a/dev-docs/bidders/mediasquare.md +++ b/dev-docs/bidders/mediasquare.md @@ -9,6 +9,7 @@ usp_supported: true schain_supported: true userIds: id5Id media_types: banner, video, native +floors_supported: true glv_id: 791 --- diff --git a/dev-docs/bidders/mgid.md b/dev-docs/bidders/mgid.md index 8365380c02..f363ab5d96 100644 --- a/dev-docs/bidders/mgid.md +++ b/dev-docs/bidders/mgid.md @@ -8,7 +8,6 @@ biddercode: mgid media_types: banner,native gdpr_supported: true gvl_id: 358 -pbjs_version_notes: not in 5.x --- ### Table of Contents diff --git a/dev-docs/bidders/microad.md b/dev-docs/bidders/microad.md index 0e133ab94a..09f710565b 100644 --- a/dev-docs/bidders/microad.md +++ b/dev-docs/bidders/microad.md @@ -5,7 +5,6 @@ description: Prebid MicroAd SSP Bidder Adaptor pbjs: true biddercode: microad media_types: banner -pbjs_version_notes: not in 5.x --- Note: diff --git a/dev-docs/bidders/minutemedia.md b/dev-docs/bidders/minutemedia.md new file mode 100644 index 0000000000..5636f4f49a --- /dev/null +++ b/dev-docs/bidders/minutemedia.md @@ -0,0 +1,83 @@ +--- +layout: bidder +title: MinuteMedia +description: Prebid MinuteMedia Bidder Adapter +pbjs: true +biddercode: minutemedia +media_types: banner, video +multiformat_supported: will-bid-on-any +schain_supported: true +gdpr_supported: true +usp_supported: true +floors_supported: true +userIds: all +fpd_supported: true +gvl_id: 918 +--- + +### Note + +The MinuteMedia adapter requires setup and approval. Please reach out to hb@minutemedia.com to setup an MinuteMedia account. + +### Bid Parameters + +#### Banner ,Video + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | Example +| ---- | ----- | ---- | ----------- | ------- +| `org` | required | String | MinuteMedia publisher Id provided by your MinuteMedia representative | "56f91cd4d3e3660002000033" +| `floorPrice` | optional | Number | Minimum price in USD.

    **WARNING:**
    Misuse of this parameter can impact revenue | 2.00 +| `placementId` | optional | String | A unique placement identifier | "12345678" +| `testMode` | optional | Boolean | This activates the test mode | false + +## Example +```javascript +var adUnits = [{ + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [728, 90] + ] + } + }, + bids: [{ + bidder: 'minutemedia', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 0.05, // Optional + placementId: '12345678', // Optional + testMode: false // Optional + } + }] + }, + { + code: 'dfp-video-div', + sizes: [ + [640, 480] + ], + mediaTypes: { + video: { + playerSize: [ + [640, 480] + ], + context: 'instream' + } + }, + bids: [{ + bidder: 'minutemedia', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 5.00, // Optional + placementId: '12345678', // Optional + testMode: false // Optional + } + }] + } +]; +``` + +### Configuration +MinuteMedia recommends setting UserSync by iframe for monetization. diff --git a/dev-docs/bidders/missena.md b/dev-docs/bidders/missena.md index 4b2c853b0c..895cfe8c43 100644 --- a/dev-docs/bidders/missena.md +++ b/dev-docs/bidders/missena.md @@ -6,7 +6,7 @@ biddercode: missena gvl_id: 867 pbjs: true safeframes_ok: false -pbjs_version_notes: not in 5.x +pbjs_version_notes: not in 5.x, in 6.2+ --- ### Note diff --git a/dev-docs/bidders/mobfox.md b/dev-docs/bidders/mobfox.md index 9bcd5f61d1..46c5ee5ca3 100644 --- a/dev-docs/bidders/mobfox.md +++ b/dev-docs/bidders/mobfox.md @@ -5,7 +5,8 @@ description: Prebid MobFox Bidder Adaptor pbjs: true biddercode: mobfox media_types: video -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/mobfoxpb.md b/dev-docs/bidders/mobfoxpb.md index eec2b0d860..84b35c2c25 100644 --- a/dev-docs/bidders/mobfoxpb.md +++ b/dev-docs/bidders/mobfoxpb.md @@ -11,7 +11,7 @@ pbjs: true pbs: true pbs_app_supported: true gvl_id: 311 -pbjs_version_notes: not in 5.x +enable_download: true --- ### Prebid.JS Bid Params diff --git a/dev-docs/bidders/mobsmart.md b/dev-docs/bidders/mobsmart.md index 59a5b165ab..19f2b516c7 100644 --- a/dev-docs/bidders/mobsmart.md +++ b/dev-docs/bidders/mobsmart.md @@ -6,7 +6,8 @@ pbjs: true biddercode: mobsmart media_types: banner userIds: pubCommonId -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/motionspots.md b/dev-docs/bidders/motionspots.md new file mode 100644 index 0000000000..e08e862e65 --- /dev/null +++ b/dev-docs/bidders/motionspots.md @@ -0,0 +1,30 @@ +--- +layout: bidder +title: Motionspots +description: Motionspots Bidder Adaptor +pbjs: true +pbs: true +biddercode: motionspots +aliasCode : adkernel +media_types: banner, native, video +gdpr_supported: true +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +userIds: all +floors_supported: true +fpd_supported: true +--- + +### Note: + +The Motionspots bidding adapter requires setup and approval before implementation. Please reach out to for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.motionspots.com'` | `string` | +| `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/mytarget.md b/dev-docs/bidders/mytarget.md index cf96c21dff..d53cbca13a 100644 --- a/dev-docs/bidders/mytarget.md +++ b/dev-docs/bidders/mytarget.md @@ -4,7 +4,6 @@ title: myTarget description: Prebid myTarget Bidder Adapter pbjs: true biddercode: mytarget -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/nafdigital.md b/dev-docs/bidders/nafdigital.md index a21d4173c6..5ea7fb30d5 100644 --- a/dev-docs/bidders/nafdigital.md +++ b/dev-docs/bidders/nafdigital.md @@ -6,7 +6,8 @@ top_nav_section: dev_docs nav_section: reference pbjs: true biddercode: nafdigital -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/nanointeractive.md b/dev-docs/bidders/nanointeractive.md index 43fed8d69f..0154d901e0 100644 --- a/dev-docs/bidders/nanointeractive.md +++ b/dev-docs/bidders/nanointeractive.md @@ -8,7 +8,8 @@ biddercode: nanointeractive media_types: banner gdpr_supported: true gvl_id: 72 -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Requirements: diff --git a/dev-docs/bidders/nasmediaAdmixer.md b/dev-docs/bidders/nasmediaAdmixer.md index a8a676e2c6..a9910a1a0a 100644 --- a/dev-docs/bidders/nasmediaAdmixer.md +++ b/dev-docs/bidders/nasmediaAdmixer.md @@ -4,7 +4,8 @@ title: Nasmedia Admixer description: Prebid Nasmedia Admixer Bidder Adapter pbjs: true biddercode: nasmediaAdmixer -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/nativo.md b/dev-docs/bidders/nativo.md index 67d7921d18..9c72c55f07 100644 --- a/dev-docs/bidders/nativo.md +++ b/dev-docs/bidders/nativo.md @@ -18,5 +18,5 @@ The Nativo Bidder adapter requires setup before beginning. Please contact us at {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|---------------------------------------------------------------------------------|--------------|-----------| -| `placementId` | required | Publication placement ID value from the Nativo Platform | `13144370` | `integer` | +| `placementId` | optional | Publication placement ID value from the Nativo Platform | `13144370` | `integer` | | `url` | optional | Publication url value associated with placement ID value in the Nativo Platform | `https://test-sites.internal.nativo.net/testing/prebid_adpater.html` | `string` | diff --git a/dev-docs/bidders/newborntownWeb.md b/dev-docs/bidders/newborntownWeb.md index 6dee12c74d..f95a9b1968 100644 --- a/dev-docs/bidders/newborntownWeb.md +++ b/dev-docs/bidders/newborntownWeb.md @@ -4,7 +4,8 @@ title: newborntownWeb description: Prebid newborntownWeb Bidder Adaptor pbjs: true biddercode: newborntownWeb -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/newspassid.md b/dev-docs/bidders/newspassid.md new file mode 100644 index 0000000000..6fa709e5ba --- /dev/null +++ b/dev-docs/bidders/newspassid.md @@ -0,0 +1,76 @@ +--- +Module Name: NewspassId Bidder Adapter +Module Type: Bidder Adapter +Maintainer: techsupport@newspassid.com +layout: bidder +title: Newspass ID +description: LMC Newspass ID Prebid JS Bidder Adapter +biddercode: newspassid +gdpr_supported: false +gvl_id: none +usp_supported: true +coppa_supported: false +schain_supported: true +dchain_supported: false +userIds: criteo, id5Id, tdid, identityLink, liveIntentId, parrableId, pubCommonId, lotamePanoramaId, sharedId, fabrickId +media_types: banner +safeframes_ok: true +deals_supported: true +floors_supported: false +fpd_supported: false +pbjs: true +pbs: false +prebid_member: false +multiformat_supported: will-bid-on-any +--- + +### Description + +LMC Newspass ID Prebid JS Bidder Adapter that connects to the NewspassId demand source(s). + +The Newspass bid adapter supports Banner mediaTypes ONLY. +This is intended for USA audiences only, and does not support GDPR + + +### Bid Params + +{: .table .table-bordered .table-striped } + +| Name | Scope | Description | Example | Type | +|-----------|----------|---------------------------|------------|----------| +| `siteId` | required | The site ID. | `"NPID0000001"` | `string` | +| `publisherId` | required | The publisher ID. | `"4204204201"` | `string` | +| `placementId` | required | The placement ID. | `"0420420421"` | `string` | +| `customData` | optional | publisher key-values used for targeting | `[{"settings":{},"targeting":{"key1": "value1", "key2": "value2"}}], ` | `array` | + +### Test Parameters + + +A test ad unit that will consistently return test creatives: + +``` + +//Banner adUnit + +adUnits = [{ + code: 'id-of-your-banner-div', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + }, + bids: [{ + bidder: 'newspassid', + params: { + publisherId: 'NEWSPASS0001', /* an ID to identify the publisher account - required */ + siteId: '4204204201', /* An ID used to identify a site within a publisher account - required */ + placementId: '8000000015', /* an ID used to identify the piece of inventory - required - for appnexus test use 13144370. */ + customData: [{"settings": {}, "targeting": {"key": "value", "key2": ["value1", "value2"]}}],/* optional array with 'targeting' placeholder for passing publisher specific key-values for targeting. */ + } + }] + }]; +``` + +### Note: + +Please contact us at techsupport@newspassid.com for any assistance testing your implementation before going live into production. diff --git a/dev-docs/bidders/nextMillennium.md b/dev-docs/bidders/nextMillennium.md index 926bcd6eeb..5aa72fdf2e 100644 --- a/dev-docs/bidders/nextMillennium.md +++ b/dev-docs/bidders/nextMillennium.md @@ -1,16 +1,31 @@ --- layout: bidder title: NextMillennium -description: NextMillennium bid adapter +gdpr_supported: true +usp_supported: true +coppa_supported: false +schain_supported: false +dchain_supported: false +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +pbs_app_supported: false pbjs: true +pbs: true biddercode: nextMillennium media_types: banner -pbjs_version_notes: not in 5.x +description: NextMillennium bid adapter --- ### bid params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|----------------+----------+------------------------------------------+-----------|---------| +| Name | Scope | Description | Example | Type | +|----------------+-------+-----------------------------------+-----------+---------| | `placement_id` | required | Placement ID, provided by nextMillennium | `'12345'` | String | +| `group_id` | optional | Group ID, provided by nextMillennium | `'12345'` | String | + +Required one of the two parameters placement_id or group_id. + +Further information for the auction on NextMillennium side is generated automatically. diff --git a/dev-docs/bidders/nextroll.md b/dev-docs/bidders/nextroll.md index accca4ab35..c99e92a4b3 100644 --- a/dev-docs/bidders/nextroll.md +++ b/dev-docs/bidders/nextroll.md @@ -8,7 +8,6 @@ media_types: display, native gdpr_supported: false usp_supported: true prebid_member: true -pbjs_version_notes: not in 5.x --- ### Bid Params @@ -19,7 +18,7 @@ pbjs_version_notes: not in 5.x | `sellerId` | required | The seller ID from NextRoll.Please reach out your NextRoll representative for more details. | `'541459'` | `string` | | `publisherId` | optional | The publisher ID from NextRoll.Please reach out your NextRoll representative for more details. | `'956812'` | `string` | | `zoneId` | optional | Descriptive or unique identifier for the ad position | `'main-banner-505/600x160'` | `string` | -| `bidfloor` | optional | Per ad-unit bid floor | `2.3` | `number` | +| `bidfloor` | optional | Per ad-unit bid floor, used if the floor module is not available | `2.3` | `number` | #### Example of Banner Ad-unit ``` @@ -29,6 +28,17 @@ var adUnits = [ mediaTypes: { banner: {sizes: [[300, 250], [160, 600]]} }, + // If floors module is enabled + floors: { + currency: "USD", + schema: { + delimiter: "|", + fields: ["mediaType", "size"] + }, + values: { + "*|*": 2.0 + } + }, bids: [{ bidder: 'nextroll', params: { diff --git a/dev-docs/bidders/nexx360.md b/dev-docs/bidders/nexx360.md new file mode 100644 index 0000000000..6d9abd6391 --- /dev/null +++ b/dev-docs/bidders/nexx360.md @@ -0,0 +1,68 @@ +--- +layout: bidder +title: Nexx360 +description: Prebid Nexx360 Bidder Adapter +pbjs: true +biddercode: nexx360 +gdpr_supported: true +usp_supported: true +schain_supported: true +userIds: id5Id +media_types: banner, video +glv_id: 965 +pbs: false + +--- + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|--------------------------------------|-----------| +| `account` | required | Nexx360 account ID | `'1067'` | `string` | +| `tagId` | required | Nexx360 tag ID | `'luvxjvgn'` | `string` | +| `bidfloor` | optional | Bidfloor applied to auction (default: 0) | `0.8` | `float` | +| `bidfloorCurrency` | optional | Bidfloor currency (default: `'USD'`) - Can be `'USD'` or `'EUR'` | `'USD'` | `string` | +| `keywords` | optional | Keywords used for targeting | `{ 'interest': ['cars', 'sports']}` | `object` | + +### Test Parameters + +``` +var adUnits = [ + // Banner adUnit + { + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + }, + bids: [{ + bidder: 'nexx360', + params: { + account: '1067', + tagId: 'luvxjvgn' + } + }] + }, + // Video adUnit + { + code: 'video1', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream' + } + }, + bids: [{ + bidder: 'nexx360', + params: { + account: '1067', + tagId: 'luvxjvgn' + } + }] + }; + +]; +``` diff --git a/dev-docs/bidders/oftmedia.md b/dev-docs/bidders/oftmedia.md index dcb7302602..4af214c00f 100644 --- a/dev-docs/bidders/oftmedia.md +++ b/dev-docs/bidders/oftmedia.md @@ -8,8 +8,14 @@ aliasCode : appnexus gdpr_supported: true coppa_supported: true usp_supported: true -pbs: true +pbs: false schain_supported: true +media_types: banner, video, native +prebid_member: true +userIds: criteo, flocId, identityLink, netId, pubProvidedId, uid2, unifiedId, +floors_supported: true +fpd_supported: true +gvl_id: 32 --- ### Bid Params diff --git a/dev-docs/bidders/oftmediahb.md b/dev-docs/bidders/oftmediahb.md deleted file mode 100644 index 6c90055382..0000000000 --- a/dev-docs/bidders/oftmediahb.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: bidder -title: 152MediaHB -description: Prebid 152MediaHB Bidder Adaptor -pbjs: true -media_types: video -gdpr_supported: true -biddercode: oftmediahb -aliasCode : adkernel ---- - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|----------|----------|-----------------------|---------------------------|----------| -| `host` | required | Ad network's RTB host | `'cpm.152media.com'` | `string` | -| `zoneId` | required | RTB zone id | `'30164'` | `string` | - -oftmediahb is an aliased bidder for AdKernel diff --git a/dev-docs/bidders/ogury.md b/dev-docs/bidders/ogury.md index 213001ce90..a1ae8c5f42 100644 --- a/dev-docs/bidders/ogury.md +++ b/dev-docs/bidders/ogury.md @@ -8,10 +8,11 @@ gvl_id: 31 usp_supported: false coppa_supported: false schain_supported: false +floors_supported: true dchain_supported: false media_types: banner safeframes_ok: false -bidder_supports_deals: false +deals_supported: false pbjs: true pbs: false prebid_member: false diff --git a/dev-docs/bidders/oneVideo.md b/dev-docs/bidders/oneVideo.md deleted file mode 100644 index d77c059d67..0000000000 --- a/dev-docs/bidders/oneVideo.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: bidder -title: OneVideo -description: Prebid One Video Bidder Adaptor -pbjs: true -biddercode: oneVideo -media_types: video -gdpr_supported: true -usp_supported: true ---- - -### Note: - -One Video adapter only supports video ads. - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------|----------|--------------|----------|----------| -| `pubId` | required | Publisher ID | `'brxd'` | `string` | diff --git a/dev-docs/bidders/onedisplay.md b/dev-docs/bidders/onedisplay.md index d7d4002b83..e0749df141 100644 --- a/dev-docs/bidders/onedisplay.md +++ b/dev-docs/bidders/onedisplay.md @@ -6,7 +6,19 @@ pbjs: true biddercode: onedisplay aliasCode : aol --- +### IMPORTANT NOTICE! +**TL;DR** +1. The `onedisplay` adapter is scheduled to be depreciated. +2. Our New `yahoossp` is available for early adoption. +3. Please contact your Account Manager/Executive for migration details. +Dear Publishers & Partners, +As part of our platform consolidation process to simplify your integrations moving forward +We invite you to switch from the `onedisplay` Adapter to our NEW `yahoossp` bid adapter for both Display & Video inventory. +FYI - The oneVideo adapter is scheduled for depreciation in the upcoming months. + +Thanks in advance, +Yahoo SSP ### Bid Params diff --git a/dev-docs/bidders/onemobile.md b/dev-docs/bidders/onemobile.md index c830acf841..aabc65de76 100644 --- a/dev-docs/bidders/onemobile.md +++ b/dev-docs/bidders/onemobile.md @@ -7,7 +7,19 @@ biddercode: onemobile aliasCode : aol --- +### IMPORTANT NOTICE! +**TL;DR** +1. The `onemobile` adapter is scheduled to be depreciated. +2. Our New `yahoossp` is available for early adoption. +3. Please contact your Account Manager/Executive for migration details. +Dear Publishers & Partners, +As part of our platform consolidation process to simplify your integrations moving forward +We invite you to switch from the `onemobile` Adapter to our NEW `yahoossp` bid adapter for both Display & Video inventory. +FYI - The oneVideo adapter is scheduled for depreciation in the upcoming months. + +Thanks in advance, +Yahoo SSP ### Bid Params diff --git a/dev-docs/bidders/onetag.md b/dev-docs/bidders/onetag.md index 861137a841..a0ed2656dc 100644 --- a/dev-docs/bidders/onetag.md +++ b/dev-docs/bidders/onetag.md @@ -10,6 +10,8 @@ gdpr_supported: true gvl_id: 241 usp_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +schain_supported: true +getFloor: true --- diff --git a/dev-docs/bidders/open8.md b/dev-docs/bidders/open8.md index 0f930563dc..fd97dc9a0e 100644 --- a/dev-docs/bidders/open8.md +++ b/dev-docs/bidders/open8.md @@ -5,7 +5,8 @@ description: Prebid OPEN8 Bidder Adaptor pbjs: true biddercode: open8 media_types: video, banner -pbjs_version_notes: not in 5.x +enable_download: true +pbjs_version_notes: added version 6.16 --- ### Bid Params diff --git a/dev-docs/bidders/openweb.md b/dev-docs/bidders/openweb.md new file mode 100644 index 0000000000..162df57a03 --- /dev/null +++ b/dev-docs/bidders/openweb.md @@ -0,0 +1,64 @@ +--- +layout: bidder +title: OpenWeb +description: Prebid OpenWeb Bidder Adapter +biddercode: openweb +media_types: banner +gdpr_supported: true +userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +schain_supported: true +coppa_supported: true +usp_supported: true +safeframes_ok: true +prebid_member: true +pbjs: true +pbs: true +gvl_id: 280 +--- + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------|----------|---------------------------------|----------|-----------| +| `aid` | required | The source ID from OpenWeb. | `650342` | `integer` | + +### Description +OpenWeb.com official prebid adapter. Available in both client and server side versions. +OpenWeb header bidding adapter provides solution for accessing banner demand. + +### Test Parameters +``` +var adUnits = [ + // Banner adUnit + { + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + code: 'div-test-div', + bids: [{ + bidder: 'openweb', + params: { + aid: 650342 + } + }] + }, + // Prebid server + { + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + code: 'div-test-div', + bids: [{ + bidder: 'openweb', + params: { + aid: 650346 + } + }] + } +]; +``` diff --git a/dev-docs/bidders/openwebvideo.md b/dev-docs/bidders/openwebvideo.md new file mode 100644 index 0000000000..bc6a663c50 --- /dev/null +++ b/dev-docs/bidders/openwebvideo.md @@ -0,0 +1,45 @@ +--- +layout: bidder +title: OpenWeb Video +description: Prebid OpenWeb Video Bidder Adapter +pbjs: true +biddercode: openwebvideo +aliasCode: aniview +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +safeframes_ok: true +--- + +### Note: +For more information about [OpenWeb](https://www.openweb.com/). + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `AV_PUBLISHERID` | required | Publisher/Netid | `'55b88d4a181f465b3e8b4567'` | `string` | +| `AV_CHANNELID` | required | Channel id | `'5a5f17a728a06102d14c2718'` | `string` | + +### Test Parameters +``` +videoAdUnit = [ +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'outstream' + }, + }, + bids: [{ + bidder: 'openwebvideo', + params: { + AV_PUBLISHERID: '55b78633181f4603178b4568', + AV_CHANNELID: '5d19dfca4b6236688c0a2fc4' + } + }] +}]; +``` diff --git a/dev-docs/bidders/openx.md b/dev-docs/bidders/openx.md index e3c6a103b9..71b7cc65e9 100644 --- a/dev-docs/bidders/openx.md +++ b/dev-docs/bidders/openx.md @@ -10,16 +10,24 @@ schain_supported: true gdpr_supported: true usp_supported: true coppa_supported: true -getFloor: true -userIds: britepoolId, criteo, fabrickId, haloId, id5Id, identityLink, idxId, intentIqId, liveIntentId, lotamePanoramaId, merkleId, netId, parrableId, pubCommonId, quantcastId, sharedId, tapadId, unifiedId, verizonMediaId, zeotapIdPlus +floors_supported: true +userIds: admixerId, adtelligentId, amxId, britepoolId, criteo, dapId, deepintentId, dmdId, fabrickId, flocId, hadronId, id5Id, identityLink, idxId, imuId, intentIqId, kinessoId, liveIntentId, lotamePanoramaId, merkleId, mwOpenLinkId, naveggId, netId, novatiq, parrableId, pubCommonId, publinkId, quantcastId, sharedId, tapadId, uid2, unifiedId, verizonMediaId, zeotapIdPlus prebid_member: true +fpd_supported: true gvl_id: 69 +fpd_supported: true --- ### Registration If you have any questions regarding set up, please reach out to your account manager or support@openx.com. +Please note that OpenX is transitioning its serving architecture and currently has 2 bid adapters as of Prebid 7. The legacy adapter is named openxBidAdapter. +The newer of the two is openxOrtbBidAdapter. Publishers are welcome to test with openxOrtbBidAdapter and give feedback. +After the transition openxOrtbBidAdapter will replace openxBidAdapter. + +IMPORTANT: only include either openxBidAdapter or openxOrtbBidAdapter in your build. + ### Bid Parameters #### Banner @@ -33,6 +41,40 @@ If you have any questions regarding set up, please reach out to your account man | `doNotTrack` | optional | Prevents advertiser from using data for this user.

    **WARNING:**
    Impacts all bids in the request. May impact revenue. | true | Boolean | | `coppa` | optional | Enables Child's Online Privacy Protection Act (COPPA) regulations. **WARNING:**
    Impacts all bids in the request. May impact revenue. | true | Boolean | +### AdUnit Format for Banner +```javascript +var adUnits = [ + { + code: 'test-div', + sizes: [[728, 90]], // a display size + mediaTypes: {'banner': {}}, + bids: [ + { + bidder: 'openx', + params: { + unit: '539439964', + delDomain: 'se-demo-d.openx.net', + customParams: { + key1: 'v1', + key2: ['v2', 'v3'] + }, + } + }, { + bidder: 'openx', + params: { + unit: '539439964', + platform: 'a3aece0c-9e80-4316-8deb-faf804779bd1', + customParams: { + key1: 'v1', + key2: ['v2', 'v3'] + }, + } + } + ] + } +]; +``` + #### Video {: .table .table-bordered .table-striped } @@ -40,7 +82,63 @@ If you have any questions regarding set up, please reach out to your account man | ---- | ----- | ----------- | ------- | ---- | | `unit` | required | OpenX ad unit ID provided by your OpenX representative. | "1611023122" | String | | `delDomain` or `platform` | required | OpenX delivery domain or platform id provided by your OpenX representative. Both may be present. `platform` is preferred | "PUBLISHER-d.openx.net" or "555not5a-real-plat-form-id0123456789" | String | -| `openrtb` | optional | An OpenRtb Impression with Video subtype properties | `{ imp: [{ video: {mimes: ['video/x-ms-wmv, video/mp4']} }] }` | Object | + +#### mediaTypes.video + +The following video parameters are supported here so publishers may fully declare their video inventory: + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------| +| context | required | instream or outstream |"outstream" | string | +| playerSize| required | width, height of the player in pixels | [640,360] - will be translated to w and h in bid request | array | +| mimes | required | List of content MIME types supported by the player (see openRTB v2.5 for options) | ["video/mp4"]| array| +| protocols | recommended | Supported video bid response protocol values
    1: VAST 1.0
    2: VAST 2.0
    3: VAST 3.0
    4: VAST 1.0 Wrapper
    5: VAST 2.0 Wrapper
    6: VAST 3.0 Wrapper
    7: VAST 4.0
    8: VAST 4.0 Wrapper | [2,3,5,6] | array| +| api | recommended | Supported API framework values:
    1: VPAID 1.0
    2: VPAID 2.0
    3: MRAID-1
    4: ORMMA
    5: MRAID-2 | [2] | array | +| linearity | recommended | OpenRTB2 linearity. 1: linear (in-stream ad), 2: non-linear (overlay ad) | 1 | integer | +| maxduration | recommended | Maximum video ad duration in seconds. | 30 | integer | +| minduration | recommended | Minimum video ad duration in seconds | 6 | integer | +| playbackmethod | recommended | Playback methods that may be in use. Only one method is typically used in practice. (see openRTB v2.5 section 5.10 for options)| [2]| array | +| minbitrate | optional | Minimum bit rate in Kbps. | 300 | integer | +| maxbitrate | optional | Maximum bit rate in Kbps. | 9600 | integer | +| battr | optional | Blocked creative attributes | [13,14] | array| +| startdelay | recommended | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.
    >0: Mid-Roll (value indicates start delay in second)
    0: Pre-Roll
    -1: Generic Mid-Roll
    -2: Generic Post-Roll | 0 | integer | +| placement | recommended | Placement type for the impression. (see openRTB v2.5 section 5.9 for options) | 1 | integer | +| | | | | | + + +### AdUnit Format for Video +```javascript +var videoAdUnits = [ +{ + code: 'test-div-video', + mediaTypes: { + video: { + playerSize: [640, 480], // required + context: 'instream', + mimes: ['video/mp4','video/x-flv'], // required + minduration: 5, // optional + maxduration: 30, // optional + startdelay: 5, // optional + playbackmethod: [1,3], // optional + api: [ 1, 2 ], // optional + protocols: [ 2, 3 ], // optional + battr: [ 13, 14 ], // optional + linearity: 1, // optional + placement: 2, // optional + minbitrate: 10, // optional + maxbitrate: 10 // optional + } + }, + bids: [{ + bidder: 'openx', + params: { + unit: '1611023124', + delDomain: 'PUBLISHER-d.openx.net' + } + }] +}] +``` ## Example @@ -94,6 +192,42 @@ var adUnits = [ ]; ``` +#### First Party Data +OpenX supports FPD configured under `ortb2.user`and `ortb2.site.content` as described [here]((/features/firstPartyData.html)). +Ad unit specific FPD is not supported, and segment taxonomies (`segtax`) are simply passed through. If you have any +questions, please reach out to us at prebid@openx.com + +Example: +``` +pbjs.setConfig({ + ... + ortb2: { + site: { + content: { + data: [{ + name: "www.dataprovider1.com", + ext: { segtax: 4 }, + segment: [ + { id: "687" }, + { id: "123" } + ] + }] + }, + }, + user: { + data: [{ + name: "dataprovider.com", + ext: { segtax: 4 }, + segment: [ + { id: "1" } + ] + }], + } + } + ... +}); +``` + ### Configuration Add the following code to enable user syncing. By default, Prebid.js version 0.34.0+ turns off user syncing through iframes. OpenX strongly recommends enabling user syncing through iframes. This functionality improves DSP user match rates and increases the diff --git a/dev-docs/bidders/operaads.md b/dev-docs/bidders/operaads.md new file mode 100644 index 0000000000..49393966e3 --- /dev/null +++ b/dev-docs/bidders/operaads.md @@ -0,0 +1,31 @@ +--- +layout: bidder +title: OperaAds +description: Prebid OperaAds Bidder Adapter +biddercode: operaads +gdpr_supported: false +gvl_id: none +usp_supported: false +coppa_supported: true +schain_supported: true +dchain_supported: false +media_types: banner, video, native +safeframes_ok: false +deals_supported: false +pbjs: true +pbs: true +prebid_member: false +--- + +### Registration + +If you have any questions regarding set up, please reach out to your account manager or adtech-prebid-group@opera.com. + +### Bid Parameters + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|------------------------|------------------|----------| +| `placementId`| required | Placement Id | `s12345678` | `string` | +| `endpointId`| required | Endpoint ID | `ep1234566` | `string` | +| `publisherId`| required | Publisher ID | `pub123456` | `string` | diff --git a/dev-docs/bidders/optout.md b/dev-docs/bidders/optout.md new file mode 100644 index 0000000000..dc558f411a --- /dev/null +++ b/dev-docs/bidders/optout.md @@ -0,0 +1,18 @@ +--- +layout: bidder +title: Opt Out Advertising +description: Prebid Opt Out Advertising Bidder Adaptor +pbjs: true +pbs: true +biddercode: optout +gdpr_supported: true +gvl_id: 227 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------|----------------|-----------| +| `publisher` | required | Opt Out publisher ID | `8` | `string` | +| `adslot` | required | Opt Out Adslot | `prebid_demo` | `string` | diff --git a/dev-docs/bidders/otm.md b/dev-docs/bidders/otm.md index eb664b5f80..e900908c94 100644 --- a/dev-docs/bidders/otm.md +++ b/dev-docs/bidders/otm.md @@ -4,7 +4,8 @@ title: OTM description: OTM Bidder Adapter pbjs: true biddercode: otm -pbjs_version_notes: not in 5.x +floors_supported: true +media_types: banner --- ### Bid Params @@ -14,3 +15,4 @@ pbjs_version_notes: not in 5.x |---------------|----------|----------------------------------------|-------------|----------| | `tid` | required | A tag id | `'99'` | `string` | | `bidfloor` | optional | Floor price | `20` | `integer`| +| `domain` | optional | Custom domain | `domain.tld`| `string` | diff --git a/dev-docs/bidders/ottadvisors.md b/dev-docs/bidders/ottadvisors.md new file mode 100644 index 0000000000..3c359f610d --- /dev/null +++ b/dev-docs/bidders/ottadvisors.md @@ -0,0 +1,45 @@ +--- +layout: bidder +title: ottadvisors Video +description: Prebid Video Bidder Adapter +pbjs: true +biddercode: ottadvisors +aliasCode: aniview +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +safeframes_ok: true +--- + +### Note: +For more information about [ottadvisors](http://ottadvisors.com/). + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `AV_PUBLISHERID` | required | Publisher/Netid | `'55b88d4a181f465b3e8b4567'` | `string` | +| `AV_CHANNELID` | required | Channel id | `'5a5f17a728a06102d14c2718'` | `string` | + +### Test Parameters +``` +videoAdUnit = [ +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'outstream' + }, + }, + bids: [{ + bidder: 'ottadvisors', + params: { + AV_PUBLISHERID: '55b78633181f4603178b4568', + AV_CHANNELID: '5d19dfca4b6236688c0a2fc4' + } + }] +}]; +``` diff --git a/dev-docs/bidders/outbrain.md b/dev-docs/bidders/outbrain.md index 573cf5b87f..5e828d5028 100644 --- a/dev-docs/bidders/outbrain.md +++ b/dev-docs/bidders/outbrain.md @@ -13,7 +13,10 @@ pbjs: true pbs: true pbs_app_supported: true prebid_member: true +userIds: id5Id, identityLink pbjs_version_notes: v4.35 and later +floors_supported: true +multiformat_supported: will-bid-on-one --- ### Registration @@ -60,7 +63,7 @@ adapters: | `publisher.domain` | optional | The publisher domain | `'publisher.com'` | `string` | | `tagid` | optional | Identifier for specific ad placement or ad tag | `'tag-id'` | `string` | | `bcat` | optional | Blocked advertiser categories using the IAB content categories | `['IAB1-1']` | `string array` | -| `badv` | optional | Block list of advertisers by their domains | `['example.com]'` | `string array` | +| `badv` | optional | Block list of advertisers by their domains | `['example.com']` | `string array` | #### Native example diff --git a/dev-docs/bidders/outbrain_old.md b/dev-docs/bidders/outbrain_old.md index 5bf0794eb3..e0529b8eee 100644 --- a/dev-docs/bidders/outbrain_old.md +++ b/dev-docs/bidders/outbrain_old.md @@ -61,7 +61,7 @@ adapters: | `publisher.domain` | optional | The publisher domain | `'publisher.com'` | `string` | | `tagid` | optional | Identifier for specific ad placement or ad tag | `'tag-id'` | `string` | | `bcat` | optional | Blocked advertiser categories using the IAB content categories | `['IAB1-1']` | `string array` | -| `badv` | optional | Block list of advertisers by their domains | `['example.com]'` | `string array` | +| `badv` | optional | Block list of advertisers by their domains | `['example.com']` | `string array` | #### Native example diff --git a/dev-docs/bidders/outcon.md b/dev-docs/bidders/outcon.md index 243c7cb12d..7e97d1596b 100644 --- a/dev-docs/bidders/outcon.md +++ b/dev-docs/bidders/outcon.md @@ -4,7 +4,8 @@ title: Outcon description: Prebid Outcon Bidder Adaptor pbjs: true biddercode: outcon -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/ozone.md b/dev-docs/bidders/ozone.md index 8b59183e35..ac046ca072 100644 --- a/dev-docs/bidders/ozone.md +++ b/dev-docs/bidders/ozone.md @@ -8,7 +8,12 @@ media_types: banner gdpr_supported: true userIds: criteo, id5Id, tdid, identityLink, liveIntentId, parrableId, pubCommonId, lotamePanoramaId, sharedId, fabrickId gvl_id: 524 -bidder_supports_deals: true +deals_supported: true +schain_supported: true +coppa_supported: true +usp_supported: true +floors_supported: true +prebid_member: true --- diff --git a/dev-docs/bidders/pangle.md b/dev-docs/bidders/pangle.md index b7168ad589..6d4da22aea 100644 --- a/dev-docs/bidders/pangle.md +++ b/dev-docs/bidders/pangle.md @@ -8,7 +8,7 @@ coppa_supported: true schain_supported: false media_types: banner, video, native safeframes_ok: false -bidder_supports_deals: false +deals_supported: false pbjs: false pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/performax.md b/dev-docs/bidders/performax.md index 0fc5bea4f5..dafc5f2da3 100644 --- a/dev-docs/bidders/performax.md +++ b/dev-docs/bidders/performax.md @@ -5,7 +5,8 @@ description: Prebid Performax Bidder Adaptor pbjs: true biddercode: performax media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/appaloosa.md b/dev-docs/bidders/pgam.md similarity index 64% rename from dev-docs/bidders/appaloosa.md rename to dev-docs/bidders/pgam.md index 442af1934e..43a64290fc 100644 --- a/dev-docs/bidders/appaloosa.md +++ b/dev-docs/bidders/pgam.md @@ -1,9 +1,8 @@ --- layout: bidder -title: Appaloosa -description: Prebid Appaloosa Bidder Adapter -biddercode: appaloosa -aliasCode: adtelligent +title: PGAM +description: Prebid PGAM Bidder Adapter +biddercode: pgam media_types: video,banner gdpr_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId @@ -13,7 +12,7 @@ usp_supported: true safeframes_ok: true prebid_member: true pbjs: true -pbs: false +pbs: true --- ### Bid params @@ -21,15 +20,12 @@ pbs: false {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-------|----------|---------------------------------|----------|-----------| -| `aid` | required | The source ID from Appaloosa. | `529814` | `integer` | +| `aid` | required | The source ID from PGAM. | `529814` | `integer` | ### Description -Get access to multiple demand partners across Appaloosa AdExchange and maximize your yield with Appaloosa header bidding adapter. - -Appaloosa header bidding adapter connects with Appaloosa demand sources in order to fetch bids. +PGAM header bidding adapter connects with PGAM demand sources in order to fetch bids. This adapter provides a solution for accessing Video demand and display demand. -Appaloosa now supports adpod. ### Test Parameters ``` @@ -45,7 +41,7 @@ Appaloosa now supports adpod. } }, bids: [{ - bidder: 'appaloosa', + bidder: 'pgam', params: { aid: 472386 } @@ -62,7 +58,7 @@ Appaloosa now supports adpod. } }, bids: [{ - bidder: 'appaloosa', + bidder: 'pgam', params: { aid: 472386 } @@ -80,7 +76,7 @@ Appaloosa now supports adpod. } }, bids: [{ - bidder: 'appaloosa', + bidder: 'pgam', params: { aid: 472386 } @@ -96,7 +92,7 @@ Appaloosa now supports adpod. } } bids: [{ - bidder: 'appaloosa', + bidder: 'pgam', params: { aid: 529814 } @@ -104,20 +100,3 @@ Appaloosa now supports adpod. } ]; ``` - -### Additional Configuration - -It is possible to configure requests to be split into chunks so as to have fewer bid requests in a single http request -(default value is 10). - -``` - pbjs.setBidderConfig({ - config: { - appaloosa: { - chunkSize: 1 // makes 1 http request per 1 adunit configured - } - } - }); -``` - -Appaloosa is an aliased bidder for Adtelligent diff --git a/dev-docs/bidders/pilotx.md b/dev-docs/bidders/pilotx.md new file mode 100644 index 0000000000..999d0fdf08 --- /dev/null +++ b/dev-docs/bidders/pilotx.md @@ -0,0 +1,15 @@ +--- +layout: bidder +title: PilotX +description: Pilotx Prebid Adapter +biddercode: pilotx +media_types: banner, video +pbjs: true +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------|---------|----------| +| `placementId` | required | id to represent placement for pilotx | `'234234'` | `string` | diff --git a/dev-docs/bidders/pixfuture.md b/dev-docs/bidders/pixfuture.md new file mode 100644 index 0000000000..c718b385dc --- /dev/null +++ b/dev-docs/bidders/pixfuture.md @@ -0,0 +1,19 @@ +--- +layout: bidder +title: PixFuture +description: Prebid PixFuture Bidder Adapter +biddercode: pixfuture +media_types: banner +gdpr_supported: true +prebid_member: false +coppa_supported: true +usp_supported: true +userIds: flocId, criteoId, unifiedId, id5Id, sharedId, identityLink, liveIntentId, fabrickId +pbs: false +pbjs: true +--- +#### Bid Params + +| Name | Scope | Description | Example | Type | +|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| +| `pix_id` | required | The pix_id is an ID from PixFuture. The `pix_id` parameter should be a `string` | `"Abc123"` | `string` | diff --git a/dev-docs/bidders/piximedia.md b/dev-docs/bidders/piximedia.md index 6c72ed7d85..cc5072f0cd 100644 --- a/dev-docs/bidders/piximedia.md +++ b/dev-docs/bidders/piximedia.md @@ -5,7 +5,8 @@ description: Piximedia Bidder Adaptor pbjs: true biddercode: piximedia media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/platformio.md b/dev-docs/bidders/platformio.md index f8953d0039..3c1b68fcc5 100644 --- a/dev-docs/bidders/platformio.md +++ b/dev-docs/bidders/platformio.md @@ -6,7 +6,8 @@ pbjs: true biddercode: platformio media_types: native, video gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Disclosure diff --git a/dev-docs/bidders/playwire.md b/dev-docs/bidders/playwire.md new file mode 100644 index 0000000000..e1983cbc86 --- /dev/null +++ b/dev-docs/bidders/playwire.md @@ -0,0 +1,71 @@ +--- +layout: bidder +title: Playwire +description: Prebid Playwire Bidder Adapter +pbjs: true +biddercode: playwire +aliasCode: grid +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +floors_supported: true +userIds: all +tcf2_supported: true +coppa_supported: true +fpd_supported: true +prebid_member: true +--- + +### Table of Contents + +- [Bid Params](#playwire-bid-params) +- [Bidder Config](#playwire-bidder-config) +- [First Party Data](#playwire-first-party) + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| +| `uid` | required | Represents the Playwire bidder system Ad Slot ID associated with the respective div id from the site page. | `1` | `integer` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | +| `bidFloor` | optional | Floor of the impression opportunity. If present in the request overrides XML info. | `0.8` | `float` | + + + +### Bidder Config + +You can allow writing in localStorage `pbjs.setBidderConfig` for the bidder `playwire` +``` +pbjs.setBidderConfig({ + bidders: ["playwire"], + config: { + localStorageWriteAllowed: true + } +}) +``` +If it will be "true" this allow Playwire Bid Adapter to write userId in first party localStorage + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.ext.device`: Non standard arbitrary user device +- `ortb2.user.keywords`: Standard IAB OpenRTB 2.5 user.keywords field. It will be included in ext.keywords.user.ortb2 +- `ortb2.site.keywords`: Standard IAB OpenRTB 2.5 site.keywords field. It will be included in ext.keywords.site.ortb2 +- `ortb2.site.cat[]`: Standard IAB OpenRTB 2.5 site.cat field. It will be sent as part of site.cat array +- `ortb2.site.pagecat[]`: Standard IAB OpenRTB 2.5 site.pagecat field. It will be sent as part of site.cat array +- `ortb2.site.content.genre`: Standard IAB OpenRTB 2.5 site.content.genre field + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` +- `ortb2.imp[].instl` diff --git a/dev-docs/bidders/prebidServer.md b/dev-docs/bidders/prebidServer.md deleted file mode 100644 index f599598761..0000000000 --- a/dev-docs/bidders/prebidServer.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: bidder -title: Prebid Server -description: Prebid Server S2S Adaptor -biddercode: prebidServer -pbjs: true -media_types: banner, video -gdpr_supported: true ---- - -### Overview - -The Prebid Server Adapter is a meta-adapter. It's not an actual bidder, but -rather a way to get a batch of bids from other bidders with one request. -A request for the set of auctions is sent to Prebid Server, which performs -all the auctions server side (S2S), responding in time for Prebid.js to -send the results to the ad server. This lightens the performance load on the user's device. - -### Bid Params - -Bid params are sourced from the adapter configurations set for client side. These do not need to change for Prebid Server. - -{: .alert.alert-warning :} -**Errors in bidder parameters will cause Prebid Server to reject the -entire request.** The Prebid Server philosophy is to avoid silent failures -- -we assume you will test changes, and that it will be easier to notice a -4xx error coming from the server than a silent failure where it skips just -the bad parameter. - -### Configuration -To enable prebid server, set the following configuration. - -``` -pbjs.setConfig({ - s2sConfig: { - accountId : '12345', - bidders : ['appnexus','pubmatic', 'rubicon'], - defaultVendor: 'appnexus', - timeout: 300 - } -}); -``` - -To use multiple prebid servers, just define `s2sConfig` as an array. -The same bidder cannot be set in both configs. For example: - -``` -pbjs.setConfig({ - s2sConfig: [ - { - accountId: '12345', - bidders: ['appnexus','rubicon'], - defaultVendor: 'appnexus', - timeout: 300, - }, - { - accountId: '678910', - bidders: ['pubmatic'], - defaultVendor: 'rubicon', - timeout: 300, - }, - ], -}); -``` -Configuration options - -{: .table .table-bordered .table-striped } -| Field | Type | Required? | Description | -|--------------+---------------+-----------+--------------------------------------------------------------------------| -| `accountId` | String | yes | Prebid Server account ID. | -| `bidders` | Array[String] | yes | List of bidder codes; must have been enabled during Prebid.js build. | -| `defaultVendor` | String | no | Automatically includes all following options in the config with vendor's default values. Individual properties can be overridden by including them in the config along with this setting. | -| `enabled` | Boolean | no | Enables S2S; default: `false` (`true` when defaultVendor is set). | -| `endpoint` | String | no | Set the endpoint. For example: `https://prebid.adnxs.com/pbs/v1/openrtb2/auction` | -| `timeout` | Number | no | Bidder timeout, in milliseconds; default: `1000`. | -| `syncEndpoint` | String | no | Configures the user-sync endpoint. Highly recommended. | -| `adapter` | String | no | Adapter code; default: `"prebidServer"`. | -| `secure` | Integer | no | Override Prebid Server's determination of whether the request needs secure assets. Set to `1` to force secure assets on the response, or `0` for non-secure assets. | -| `adapterOptions` | Object | no | Arguments will be added to resulting OpenRTB payload to Prebid Server. | -| `extPrebid` | Object | no | Arguments will be added to resulting OpenRTB payload to Prebid Server. | - -### Examples - -**Video (Outstream):** -Note that currently, outstream video rendering must be configured by the publisher. In the adUnit, a `renderer` object must be defined, which includes a `url` pointing to the video rendering script, and a `render` function for creating the video player. See https://prebid.org/dev-docs/show-outstream-video-ads.html for more information. - -```javascript -var adUnits = [{ - code: 'div-gpt-ad-1460505748561-0', - mediaTypes: { - video: { - playerSize: [640, 480], - context: 'outstream', - mimes: ['video/mp4'], - protocols: [1, 2, 3, 4, 5, 6, 7, 8], - playbackmethod: [2], - skip: 1 - } - }, - bids: [ - { - bidder: 'appnexus', - params: { - placementId: 13232392 - }, - - } - ], - renderer: { - url: 'https://cdn.adnxs.com/renderer/video/ANOutstreamVideo.js', - render: function (bid) { - adResponse = { - ad: { - video: { - content: bid.vastXml, - player_height: bid.playerHeight, - player_width: bid.playerWidth - } - } - } - // push to render queue because ANOutstreamVideo may not be loaded yet. - bid.renderer.push(() => { - ANOutstreamVideo.renderAd({ - targetId: bid.adUnitCode, // target div id to render video. - adResponse: adResponse - }); - }); - } - } -}]; -``` diff --git a/dev-docs/bidders/prisma.md b/dev-docs/bidders/prisma.md new file mode 100644 index 0000000000..259bb792cd --- /dev/null +++ b/dev-docs/bidders/prisma.md @@ -0,0 +1,65 @@ +--- +layout: bidder +title: Prisma +description: Prebid Prisma Bidder Adapter +pbjs: true +biddercode: prisma +gdpr_supported: true +usp_supported: true +schain_supported: true +userIds: id5Id +media_types: banner, video +glv_id: 965 +pbs: false + +--- + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|--------------------------------------|-----------| +| `account` | required | Prisma account ID | `'1067'` | `string` | +| `tagId` | required | Prisma tag ID | `'luvxjvgn'` | `string` | + +### Test Parameters + +``` +var adUnits = [ + // Banner adUnit + { + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + }, + bids: [{ + bidder: 'prisma', + params: { + account: '1067', + tagId: 'luvxjvgn' + } + }] + }, + // Video adUnit + { + code: 'video1', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream' + } + }, + bids: [{ + bidder: 'prisma', + params: { + account: '1067', + tagId: 'luvxjvgn' + } + }] + }; + +]; +``` diff --git a/dev-docs/bidders/project-limelight.md b/dev-docs/bidders/projectLimelight.md similarity index 51% rename from dev-docs/bidders/project-limelight.md rename to dev-docs/bidders/projectLimelight.md index 16b56e3aed..2efcfe9ebd 100644 --- a/dev-docs/bidders/project-limelight.md +++ b/dev-docs/bidders/projectLimelight.md @@ -5,6 +5,9 @@ description: Prebid Project Limelight Bidder Adaptor pbjs: true biddercode: project-limelight aliasCode: projectLimeLight +media_types: video +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params @@ -12,6 +15,6 @@ aliasCode: projectLimeLight {: .table .table-bordered .table-striped } | Name | Scope | Description | Example |type| | :----------- | :--------- | :------------ | :----------------- |:---| -| `host` | required | Ad network's RTB host | `'ads.project-limelight.com'` | `string` | -| `adUnitId` | required | Ad Unit Id will be generated on Project Limelight Platform. | 0 |integer| -| `adUnitType` | required | Type of Ad Unit ('video', 'banner') | 'banner' |string| +| `host` | required | Ad network's RTB host | `'exchange.ortb.net'` | `string` | +| `adUnitId` | required | Ad Unit Id will be generated on Limelight Digital Platform. | 0 |integer| +| `adUnitType` | required | Type of Ad Unit (`'video'`, `'banner'`) | `'banner'` |string| diff --git a/dev-docs/bidders/proxistore.md b/dev-docs/bidders/proxistore.md index 6e884a2cd8..172c18cc8b 100644 --- a/dev-docs/bidders/proxistore.md +++ b/dev-docs/bidders/proxistore.md @@ -5,7 +5,6 @@ description: Prebid Proxistore Bidder Adapter pbjs: true biddercode: proxistore gdpr_supported: true -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/pubgenius.md b/dev-docs/bidders/pubgenius.md index 23cb4e5fab..3085968a32 100644 --- a/dev-docs/bidders/pubgenius.md +++ b/dev-docs/bidders/pubgenius.md @@ -5,7 +5,7 @@ description: Prebid pubGENIUS Bidder Adaptor pbjs: true biddercode: pubgenius media_types: banner -getFloor: true +floors_supported: true gdpr_supported: true usp_supported: true schain_supported: true diff --git a/dev-docs/bidders/pubmatic.md b/dev-docs/bidders/pubmatic.md index 0265738a9f..796a0e9524 100644 --- a/dev-docs/bidders/pubmatic.md +++ b/dev-docs/bidders/pubmatic.md @@ -8,22 +8,19 @@ gdpr_supported: true usp_supported: true coppa_supported: true schain_supported: true -getFloor: true +floors_supported: true userIds: all prebid_member: true safeframes_ok: true pbjs: true pbs: true pbs_app_supported: true +fpd_supported: true +ortb_blocking_supported: true gvl_id: 76 +multiformat_supported: will-bid-on-one --- -### Prebid Server Note: -Before configuring the PubMatic adapter as S2S, you must reach out to the PubMatic team for approval and setup steps. - -### Prebid 1.0 Upgrade Note: -If you upgrading from a Prebid version prior to 1.0, please reach out to your PubMatic Customer Success Manager prior to your upgrade. Publisher accounts need new settings to function correctly with the PubMatic Prebid 1.0 adapter and your Customer Success Manager will ensure your account is setup correctly. - ### Bid Params {: .table .table-bordered .table-striped } @@ -40,6 +37,7 @@ If you upgrading from a Prebid version prior to 1.0, please reach out to your Pu | `kadfloor` | optional | Bid Floor | `'1.75'` | `string` | | `currency` | optional | Bid currency | `'AUD'` (Value configured only in the 1st adunit will be passed on.
    Values if present in subsequent adunits, will be ignored.) | `string` | | `dctr` | optional | Deal Custom Targeting
    (Value configured only in the 1st adunit will be passed on.
    Values if present in subsequent adunits, will be ignored.) | `'key1=123|key2=345'` | `string` | +| `acat` | optional | Allowed categories
    (List of allowed categories for a given auction to be sent in either using ortb2 config (request.ext.prebid.bidderparams.pubmatic.acat) or using slot level params. If categories sent using both then priority will be given to ortb2 over slot level params.) | `[ 'IAB1-5', 'IAB1-6', 'IAB1-7' ]` | `array of strings` | | `bcat` | optional | Blocked IAB Categories
    (Values from all slots will be combined and only unique values will be passed. An array of strings only. Each category should be a string of a length of more than 3 characters.) | `[ 'IAB1-5', 'IAB1-6', 'IAB1-7' ]` | `array of strings` | | `deals` | optional | PMP deals
    (Values from each slot will be passed per slot. An array of strings only. Each deal-id should be a string of a length of more than 3 characters.) | `[ 'deal-id-5', 'deal-id-6', 'deal-id-7' ]` | `array of strings` | | `outstreamAU` | optional | Oustream AdUnit described in Blue BillyWig UI. This field is mandatory if mimeType is described as video and context is outstream (i.e., for outstream videos) | `'renderer_test_pubmatic'` | `string` | @@ -48,8 +46,6 @@ If you upgrading from a Prebid version prior to 1.0, please reach out to your Pu PubMatic recommends the UserSync configuration below. Without it, the PubMatic adapter will not able to perform user syncs, which lowers match rate and reduces monetization. -For Prebid.js v1.15.0 and later: - ```javascript pbjs.setConfig({ userSync: { @@ -63,16 +59,6 @@ pbjs.setConfig({ }); ``` -For Prebid.js v1.14.0 and before: - -```javascript -pbjs.setConfig({ - userSync: { - iframeEnabled: true, - enabledBidders: ['pubmatic'] - }}); -``` - Note: Combine the above the configuration with any other UserSync configuration. Multiple setConfig() calls overwrite each other and only last call for a given attribute will take effect. ### adSlot Specification and Multi-Size Ad Units @@ -85,23 +71,7 @@ The adSlot parameter supports two different formats: | Without Size | `'38519891'` | | With Size | `'38519891@300x205'` | -Support and behavior differs by Prebid.js version - -Prebid.js v2.13.0 and later: - -adSlot parameter is now optional. To omit the adSlot parameter, your publisher account must have default site and tag enabled. Consult your account manager to find out if default site and tag is enabled on your account. If used, both formats are supported. Without Size is the recommended option. If you are using Prebid Server, Prebid Server v0.69.0 or higher (Go version) or v1.18.0 or higher (Java version) is required to use Without Size. If you are using a managed service provider for Prebid Server, consult the provider to find out which version of Prebid Server they are using. All options will send the ad request with all sizes specified in the Prebid ad unit configuration. - -Prebid.js v2.9.0 to v2.12.0: - -Both formats are supported. Without Size is the recommended option. If you are using Prebid Server, Prebid Server v0.69.0 or higher (Go version) or v1.18.0 or higher (Java version) is required to use Without Size. If you are using a managed service provider for Prebid Server, consult the provider to find out which version of Prebid Server they are using. Both formats will send the ad request with all sizes specified in the Prebid ad unit configuration. - -Prebid.js v1.18.0 to v2.8.0: - -Both formats are supported. Without Size is the recommended option. If you are using Prebid Server, Prebid Server v0.69.0 or higher (Go version) or v1.18.0 or higher (Java version) is required to use Without Size. If you are using a managed service provider for Prebid Server, consult the provider to find out which version of Prebid Server they are using. Without Size will send the ad request with all sizes specified in the Prebid ad unit configuration. With Size will only request the specified size. Mutli-sized ad units are not supported when using Prebid Server. - -Prebid.js v1.17.0 and earlier: - -Only With Size is supported. To support multi-size ad units, list the PubMatic bidder entry multiple times, once for each size. Mutli-sized ad units are not supported when using Prebid Server. +adSlot parameter is optional. To omit the adSlot parameter, your publisher account must have default site and tag enabled. Consult your account manager to find out if default site and tag is enabled on your account. If used, both formats are supported. Without Size is the recommended option. Both options will send the ad request with all sizes specified in the Prebid ad unit configuration. ### video parameters The PubMatic adapter supports video as of Prebid v1.16.0 @@ -191,7 +161,6 @@ var adUnits = [ }]; ``` - ### Configuration for video For Video ads, prebid cache needs to be enabled for PubMatic adapter. ``` @@ -233,4 +202,12 @@ and sizes that would match with the test creative. } ] ``` + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). The following fields are supported: +- `ortb2.site.*` +- `ortb2.user.*` + +AdUnit-specific data is supported using `AdUnit.ortb2Imp.ext.*` diff --git a/dev-docs/bidders/pubnx.md b/dev-docs/bidders/pubnx.md deleted file mode 100644 index 9fb104d64a..0000000000 --- a/dev-docs/bidders/pubnx.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: bidder -title: PubNX -description: Prebid PubNX Bidder Adaptor -pbjs: true -biddercode: pubnx ---- - - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -| :--- | :---- | :---------- | :------ | :---- | -| `siteId` | required | The site ID from PubNX. | `12345` | Integer | -| `zoneIds` | optional | An array of integer zone IDs from PubNX. | `[12345, 4567]` | Array of integers | -| `networkId` | required | The network ID from PubNX. | `9969` | Integer | diff --git a/dev-docs/bidders/pubx.md b/dev-docs/bidders/pubx.md index 3fc59db779..e734c91ed6 100644 --- a/dev-docs/bidders/pubx.md +++ b/dev-docs/bidders/pubx.md @@ -9,7 +9,6 @@ coppa_supported: false usp_supported: false schain_supported: true pbjs: true -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/pulsepoint.md b/dev-docs/bidders/pulsepoint.md index c394d717f7..f55a15086d 100644 --- a/dev-docs/bidders/pulsepoint.md +++ b/dev-docs/bidders/pulsepoint.md @@ -7,7 +7,7 @@ gdpr_supported: true usp_supported: true schain_supported: true media_types: banner, video, native -userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, parrableId, pubCommonId, unifiedId +userIds: all pbjs: true pbs: true gvl_id: 81 diff --git a/dev-docs/bidders/pwbid.md b/dev-docs/bidders/pwbid.md index 48c08c33b4..26715707a2 100644 --- a/dev-docs/bidders/pwbid.md +++ b/dev-docs/bidders/pwbid.md @@ -12,7 +12,7 @@ schain_supported: true prebid_member: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, pubProvidedId, sharedId, unifiedId tcf1_supported: true -getFloor: false +floors_supported: false gvl_id: 842 --- diff --git a/dev-docs/bidders/quantumdex.md b/dev-docs/bidders/quantumdex.md index 1119a035c4..7391497300 100644 --- a/dev-docs/bidders/quantumdex.md +++ b/dev-docs/bidders/quantumdex.md @@ -10,8 +10,10 @@ gdpr_supported: true schain_supported: true usp_supported: true userIds: all -getFloor: true +floors_supported: true +pbs: true +pbs_app_supported: true --- # Description -Quantumdex is an aliased bidder of Apacdex bid adapter. Please refer to [Apacdex documentation](https://docs.prebid.org/dev-docs/bidders/apacdex) for bid parameters and implementation guide. \ No newline at end of file +Quantumdex is an aliased bidder of Apacdex bid adapter. Please refer to [Apacdex documentation](https://docs.prebid.org/dev-docs/bidders/apacdex) for bid parameters and implementation guide. diff --git a/dev-docs/bidders/rads.md b/dev-docs/bidders/rads.md index 0fd2dfe505..ba3baa6f51 100644 --- a/dev-docs/bidders/rads.md +++ b/dev-docs/bidders/rads.md @@ -7,6 +7,7 @@ biddercode: rads media_types: banner, video gdpr_supported: true gvl_id: 602 +userIds: uid2, netId --- diff --git a/dev-docs/bidders/ras.md b/dev-docs/bidders/ras.md new file mode 100644 index 0000000000..79a193bc44 --- /dev/null +++ b/dev-docs/bidders/ras.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: RingierAxelSpringer +description: Prebid RingierAxelSpringer Bidder Adapter +biddercode: ras +media_types: banner +pbjs: true +gvl_id: 1021 +gdpr_supported: true +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +--- + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `network` | required | Specific identifier provided by RAS | `'4178463'` | `string` | +| `site` | required | Specific identifier name (case-insensitive) that is associated with this ad unit and provided by RAS | `'example_com'` | `string` | +| `area` | required | Ad unit category name; only case-insensitive alphanumeric with underscores and hyphens are allowed | `'sport'` | `string` | +| `slot` | required | Ad unit placement name (case-insensitive) provided by RAS | `'slot'` | `string` | +| `pageContext` | optional | Web page context data | `{}` | `object` | +| `pageContext.dr` | optional | Document referrer URL address | `'https://example.com/'` | `string` | +| `pageContext.du` | optional | Document URL address | `'https://example.com/sport/football/article.html?id=932016a5-02fc-4d5c-b643-fafc2f270f06'` | `string` | +| `pageContext.dv` | optional | Document virtual address as slash-separated path that may consist of any number of parts (case-insensitive alphanumeric with underscores and hyphens); first part should be the same as `site` value and second as `area` value; next parts may reflect website navigation | `'example_com/sport/football'` | `string` | +| `pageContext.keyWords ` | optional | List of keywords associated with this ad unit; only case-insensitive alphanumeric with underscores and hyphens are allowed | `['euro', 'lewandowski']` | `string[]` | +| `pageContext.keyValues` | optional | Key-values associated with this ad unit (case-insensitive); following characters are not allowed in the values: `" ' = ! + # * ~ ; ^ ( ) < > ] [ & @` | `{}` | `object` | +| `pageContext.keyValues.ci` | optional | Content unique identifier | `'932016a5-02fc-4d5c-b643-fafc2f270f06'` | `object` | +| `pageContext.keyValues.adunit ` | optional | Ad unit name | `'example_com/sport'` | `string` | + diff --git a/dev-docs/bidders/readpeak.md b/dev-docs/bidders/readpeak.md index b882b6dc96..b4b53b8a89 100644 --- a/dev-docs/bidders/readpeak.md +++ b/dev-docs/bidders/readpeak.md @@ -4,7 +4,7 @@ title: Readpeak description: Readpeak Bidder Adaptor pbjs: true biddercode: readpeak -media_types: native +media_types: native, banner gdpr_supported: true tcf2_supported: true gvl_id: 290 diff --git a/dev-docs/bidders/reklamstore.md b/dev-docs/bidders/reklamstore.md index 8c9a025355..10d1b5909e 100644 --- a/dev-docs/bidders/reklamstore.md +++ b/dev-docs/bidders/reklamstore.md @@ -6,7 +6,8 @@ biddercode: reklamstore pbjs: true gdpr_supported: true media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/relaido.md b/dev-docs/bidders/relaido.md index 451554d9d4..6055ab0630 100644 --- a/dev-docs/bidders/relaido.md +++ b/dev-docs/bidders/relaido.md @@ -3,6 +3,7 @@ layout: bidder title: Relaido description: Prebid Relaido Bidder Adapter biddercode: relaido +userIds: imuid pbjs: true media_types: banner, video --- @@ -13,3 +14,4 @@ media_types: banner, video | Name | Scope | Description | Example | Type | |---------------|----------|-----------------------|-----------|-----------| | `placementId` | required | Relaido placement id | `1234567` | `string` | +| `video.playerSize` | optional | Video Player Size
    This field is mandatory if mediaTypes.video.playerSize is undefined. | `[1, 1]` or `[300, 250] over` | `array of number` | diff --git a/dev-docs/bidders/reload.md b/dev-docs/bidders/reload.md index 675b068536..6a6abca44e 100644 --- a/dev-docs/bidders/reload.md +++ b/dev-docs/bidders/reload.md @@ -4,7 +4,8 @@ title: Reload description: Reload Prebid Adaptor pbjs: true biddercode: reload -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/resultsmedia.md b/dev-docs/bidders/resultsmedia.md index d1a68d29ec..1bc0d46203 100644 --- a/dev-docs/bidders/resultsmedia.md +++ b/dev-docs/bidders/resultsmedia.md @@ -7,7 +7,8 @@ biddercode: resultsmedia media_types: video, banner gdpr_supported: true schain_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/revcontent.md b/dev-docs/bidders/revcontent.md index 81a4e331ea..3ba3d9869d 100644 --- a/dev-docs/bidders/revcontent.md +++ b/dev-docs/bidders/revcontent.md @@ -10,7 +10,6 @@ usp_supported: false pbjs: true pbs: true gvl_id: 203 -pbjs_version_notes: not in 5.x --- ### Note diff --git a/dev-docs/bidders/richaudience.md b/dev-docs/bidders/richaudience.md index 727a910907..eca8e93b0f 100644 --- a/dev-docs/bidders/richaudience.md +++ b/dev-docs/bidders/richaudience.md @@ -6,8 +6,13 @@ biddercode: richaudience userIds: criteo, id5Id, identityLink, liveIntentId, pubCommonId, unifiedId media_types: banner, video gdpr_supported: true -pbjs: true gvl_id: 108 +safeframes_ok: false +prebid_member: true +pbjs: true +pbs: true +schain_supported: true +floors_supported: true --- ### Bid Params diff --git a/dev-docs/bidders/rise.md b/dev-docs/bidders/rise.md index 42c67e4c5a..b2c330cff1 100644 --- a/dev-docs/bidders/rise.md +++ b/dev-docs/bidders/rise.md @@ -1,14 +1,17 @@ --- layout: bidder title: Rise -description: Prebid Bidder Adaptor +description: Prebid Rise Bidder Adapter +multiformat_supported: will-bid-on-any pbjs: true biddercode: rise -media_types: no-display, video +media_types: banner, video schain_supported: true gdpr_supported: true usp_supported: true -pbjs_version_notes: not in 5.x +floors_supported: true +userIds: all +gvl_id: 1043 --- ### Note @@ -17,53 +20,67 @@ The Rise adapter requires setup and approval. Please reach out to prebid-rise-en ### Bid Parameters -#### Video +#### Banner, Video {: .table .table-bordered .table-striped } | Name | Scope | Type | Description | Example | ---- | ----- | ---- | ----------- | ------- | `org` | required | String | Rise publisher Id provided by your Rise representative | "56f91cd4d3e3660002000033" | `floorPrice` | optional | Number | Minimum price in USD.

    **WARNING:**
    Misuse of this parameter can impact revenue | 2.00 -| `ifa` | optional | String | The ID for advertisers (also referred to as "IDFA") | "XXX-XXX" +| `placementId` | optional | String | A unique placement identifier | "12345678" | `testMode` | optional | Boolean | This activates the test mode | false ## Example ```javascript -var adUnits = [ - { +var adUnits = [{ + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [728, 90] + ] + } + }, + bids: [{ + bidder: 'rise', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 0.05, // Optional + placementId: '12345678', // Optional + testMode: false // Optional + } + }] + }, + { code: 'dfp-video-div', - sizes: [[640, 480]], + sizes: [ + [640, 480] + ], mediaTypes: { - video: { - playerSize: [[640, 480]], - context: 'instream' - } + video: { + playerSize: [ + [640, 480] + ], + context: 'instream' + } }, bids: [{ - bidder: 'rise', - params: { - org: '56f91cd4d3e3660002000033', // Required - floorPrice: 5.00, // Optional - ifa: 'XXX-XXX', // Optional - testMode: false // Optional - } + bidder: 'rise', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 5.00, // Optional + placementId: '12345678', // Optional + testMode: false // Optional + } }] - } - ]; + } +]; ``` ### Configuration Rise recommends setting UserSync by iframe for monetization. -For Prebid.js v1.15.0 and later: - -pbjs.setConfig({ - userSync: { - filterSettings: { - iframe: { - bidders: '*', // '*' represents all bidders - filter: 'include' - } - } - } -}); +### Versions +Prebid versions 5.0-5.3 are not supported +Banner >= 6.14.0 diff --git a/dev-docs/bidders/roundel.md b/dev-docs/bidders/roundel.md index 61fa4d03b5..fed8e9a1f5 100644 --- a/dev-docs/bidders/roundel.md +++ b/dev-docs/bidders/roundel.md @@ -22,4 +22,4 @@ Roundel is an aliased bidder for Index Exchange and must be configured alongside ## Bid Params Bidder params for roundel follow the same structure as the Index Exchange bidder. Please reference configuration examples [here](/dev-docs/bidders/ix). - \ No newline at end of file + diff --git a/dev-docs/bidders/converge_digital.md b/dev-docs/bidders/rtbanalytica.md similarity index 60% rename from dev-docs/bidders/converge_digital.md rename to dev-docs/bidders/rtbanalytica.md index fa17272a25..3718ed244b 100644 --- a/dev-docs/bidders/converge_digital.md +++ b/dev-docs/bidders/rtbanalytica.md @@ -1,28 +1,27 @@ --- layout: bidder -title: Converge-Digital -description: Converge-Digital Bidder Adaptor +title: RtbAnalytica +description: RtbAnalytica Bidder Adaptor pbjs: true pbs: true -biddercode: converge_digital +biddercode: rtbanalytica aliasCode : adkernel media_types: banner, native, video gdpr_supported: true usp_supported: true coppa_supported: true pbs_app_supported: true -gvl_id: 248 schain_supported: true --- ### Note: -The Converge-Digital Bidding adapter requires setup and approval before implementation. Please reach out to for more details. +The RtbAnalytica bidding adapter requires setup and approval before implementation. Please reach out to for more details. ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------|----------|-----------------------|---------------------------|----------| -| `host` | required | ConvergeDigital RTB host | `'cpm.convergeselect.net'` | `string` | +| `host` | required | RtbAnalytica RTB host | `'cpm.rtbanalytica.com'` | `string` | | `zoneId` | required | Zone Id | `30164` | `integer` | diff --git a/dev-docs/bidders/rtbdemand.md b/dev-docs/bidders/rtbdemand.md index 0407f9d60a..77859838e8 100644 --- a/dev-docs/bidders/rtbdemand.md +++ b/dev-docs/bidders/rtbdemand.md @@ -6,7 +6,8 @@ top_nav_section: dev_docs nav_section: reference pbjs: true biddercode: rtbdemand -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/rtbhouse.md b/dev-docs/bidders/rtbhouse.md index c4cc98247c..a2a39bfd43 100644 --- a/dev-docs/bidders/rtbhouse.md +++ b/dev-docs/bidders/rtbhouse.md @@ -6,10 +6,12 @@ gdpr_supported: true pbjs: true pbs: true biddercode: rtbhouse +prebid_member: true +floors_supported: true safeframes_ok: true media_types: banner, native schain_supported: true -userIds: id5Id, identityLink +userIds: id5Id, identityLink, pubProvidedId pbs_app_supported: true --- @@ -22,3 +24,11 @@ pbs_app_supported: true | `publisherId` | required | Unique publisher ID | `'ABCDEF'` | `string` | | `region` | required | Assigned region | `'prebid-eu'` | `string` | | `bidfloor` | optional | Minimal CPM value | `0.01` | `float` | +| `channel` | optional | Inventory channel identifier, limited to 50 characters | `Partner 1 - News` | `string` | + + +### Please note: + +* Since 4.43 the bidfloor param will be ignored if a value is specified via floor module. + +* The channel param is available starting from Prebid 6.6.0. Please reach your RTBHouse representative for details on how to enable and use the channel param. diff --git a/dev-docs/bidders/rtbsape.md b/dev-docs/bidders/rtbsape.md index 5a2966a6d1..de4dcbe73a 100644 --- a/dev-docs/bidders/rtbsape.md +++ b/dev-docs/bidders/rtbsape.md @@ -5,7 +5,6 @@ description: Prebid RtbSape Bidder Adaptor pbjs: true biddercode: rtbsape media_types: banner, video -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/rtbsolutions.md b/dev-docs/bidders/rtbsolutions.md index 53fa8379f5..994d9693fc 100644 --- a/dev-docs/bidders/rtbsolutions.md +++ b/dev-docs/bidders/rtbsolutions.md @@ -5,7 +5,8 @@ description: Prebid RTB Solutions Bidder Adaptor pbjs: true biddercode: rtbsolutions media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/rubicon.md b/dev-docs/bidders/rubicon.md index 706627241f..c988a014fe 100644 --- a/dev-docs/bidders/rubicon.md +++ b/dev-docs/bidders/rubicon.md @@ -7,17 +7,23 @@ gdpr_supported: true usp_supported: true coppa_supported: true schain_supported: true -getFloor: true -media_types: video +floors_supported: true +media_types: banner, video userIds: all prebid_member: true safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true pbs_app_supported: true +fpd_supported: true +ortb_blocking_supported: partial gvl_id: 52 +multiformat_supported: will-bid-on-one --- +### Disclosure: + +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. ### Registration @@ -42,32 +48,16 @@ For both Prebid.js and Prebid Server, the Rubicon Project adapter requires setup #### First Party Data -Rubicon Project requires that first party data be split into two categories: "inventory" and "visitor". - -For Prebid.js 4.29 and before, use the bidder specific AdUnit parameters noted above: -``` -var adUnit = { - ... - bids: [{ - bidder: 'rubicon', - params: { - accountId: 7780, // replace account/site/zone params - siteId: 87184, - zoneId: 413290, - inventory: { - prodtype: ["tech","mobile"] - }, - visitor: { - ucat:["new"] - } - } - }] -}; -``` +In release 4.30 and later, publishers should use the `ortb2` method of setting First Party Data. The following fields are supported: +- ortb2.site.ext.data.* +- ortb2.site.keywords +- ortb2.site.content.data[] +- ortb2.user.ext.data.* +- ortb2.user.data[] -In release 4.30 and later, we recommend using the ortb2 method of setting First Party Data. This can be done in two ways: global (cross-bidder) or bidder-specific. For Inventory, you will need to use site.ext.data, and For Visitor, you will need to use the user.ext.data. For More information about Audience Segments in Magnite: https://resources.rubiconproject.com/resource/publisher-resources/segment-management-user-guide/ +With regards to Contextual and Audience segments, the Magnite exchange supports the IAB standard taxonomies. See [the segment management user guide](https://resources.rubiconproject.com/resource/publisher-resources/segment-management-user-guide/) for more information. -Example first party data available to all bidders and all adunits: +Example first party data that's available to all bidders and all adunits: ``` pbjs.setConfig({ ortb2: { @@ -116,6 +106,45 @@ pbjs.setBidderConfig({ }; ``` +For Prebid.js 4.29 and before, use the bidder specific AdUnit parameters noted above: +``` +var adUnit = { + ... + bids: [{ + bidder: 'rubicon', + params: { + accountId: 7780, // replace account/site/zone params + siteId: 87184, + zoneId: 413290, + inventory: { + prodtype: ["tech","mobile"] + }, + visitor: { + ucat:["new"] + } + } + }] +}; +``` + +#### ORTB Blocking + +Rubicon supports passing up to 50 domains in `badv` for anything hitting Prebid Server, which includes these scenarios: + +1. client-side video +2. s2sConfig +3. App +4. AMP + +For example: +``` +pbjs.setConfig({ + ortb2: { + badv: ["domain1.com", "domain2.com"] + } +)}; +``` + #### mediaTypes.video The following video parameters are supported here so publishers may fully declare their video inventory: @@ -128,6 +157,7 @@ The following video parameters are supported here so publishers may fully declar | mimes | required | List of content MIME types supported by the player (see openRTB v2.5 for options) | ["video/mp4"]| array| | protocols | required | Supported video bid response protocol values
    1: VAST 1.0
    2: VAST 2.0
    3: VAST 3.0
    4: VAST 1.0 Wrapper
    5: VAST 2.0 Wrapper
    6: VAST 3.0 Wrapper
    7: VAST 4.0
    8: VAST 4.0 Wrapper | [2,3,5,6] | array| | api | required | Supported API framework values:
    1: VPAID 1.0
    2: VPAID 2.0
    3: MRAID-1
    4: ORMMA
    5: MRAID-2 | [2] | array | +| linearity | required | OpenRTB2 linearity. 1: linear (in-stream ad), 2: non-linear (overlay ad) | 1 | integer | | maxduration | recommended | Maximum video ad duration in seconds. | 30 | integer | | minduration | recommended | Minimum video ad duration in seconds | 6 | integer | | playbackmethod | recommended | Playback methods that may be in use. Only one method is typically used in practice. (see openRTB v2.5 section 5.10 for options)| [2]| array | @@ -214,6 +244,12 @@ pbjs.setConfig({ * The Rubicon Project adapter does not make concurrent banner and video requests. Instead, the adapter will send a video request if bids[].params.video is supplied, else a banner request will be made. +### Setting up the Prebid Server Adapter + +If you're a Prebid Server host company looking to enable the Rubicon server-side adapter, you'll need to contact globalsupport@magnite.com. They will provide: +- a Magnite DV+ XAPI login and password that you'll place in the PBS config +- a partner code you can use for cookie-syncing with Magnite's service + ### Configuration #### Single-Request diff --git a/dev-docs/bidders/sa_lunamedia.md b/dev-docs/bidders/sa_lunamedia.md new file mode 100644 index 0000000000..94e4f19b5e --- /dev/null +++ b/dev-docs/bidders/sa_lunamedia.md @@ -0,0 +1,23 @@ +--- +layout: bidder +title: SA Lunamedia +description: SA Lunamedia Bidder Adapter +biddercode: sa_lunamedia +usp_supported: true +schain_supported: true +media_types: banner, video, native +gdpr_supported: true +pbjs: false +pbs: true +pbs_app_supported: true +gvl_id: 998 +enable_download: false +--- + +### Prebid Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|----------------------------------------------------------|------------|-----------| +| `key` | required | Placement integration key | `'1234'` | `string` | +| `type` | optional | Supported values are `publisher` and `network`. | `'publisher'` | `string` | diff --git a/dev-docs/bidders/saambaa.md b/dev-docs/bidders/saambaa.md index 1d2415374b..ca38b82722 100644 --- a/dev-docs/bidders/saambaa.md +++ b/dev-docs/bidders/saambaa.md @@ -4,7 +4,6 @@ title: Saambaa description: Prebid Saambaa Bidder Adapter pbjs: true biddercode: saambaa -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/seedingAlliance.md b/dev-docs/bidders/seedingAlliance.md index bba20fe71b..0683e3a3d8 100644 --- a/dev-docs/bidders/seedingAlliance.md +++ b/dev-docs/bidders/seedingAlliance.md @@ -6,7 +6,6 @@ pbjs: true biddercode: seedingAlliance media_types: native gdpr_supported: true -pbjs_version_notes: not in 5.x --- ### Bid params diff --git a/dev-docs/bidders/seedtag.md b/dev-docs/bidders/seedtag.md index eccd2a0bef..8a285c3e6d 100644 --- a/dev-docs/bidders/seedtag.md +++ b/dev-docs/bidders/seedtag.md @@ -3,6 +3,9 @@ layout: bidder title: seedtag description: Prebid Seedtag Bidder Adapter pbjs: true +gdpr_supported: true +usp_supported: true +gvl_id: 157 media_types: banner, video biddercode: seedtag --- @@ -19,7 +22,7 @@ The publisher id 0000-0000-01 returns demo responses. | Name | Scope | Description | Example | Type | |-------------------|---------------------|--------------------------------------------------------------------------------|-----------------------|----------| | `publisherId` | required | The publisher id. | 0000-0000-01 | `string` | -| `adunitId` | required | The adunit id. | 00000 | `string` | +| `adUnitId` | required | The adunit id. | 00000 | `string` | | `placement` | required | Adunit placement, posibles values: banner, video, inImage, inScreen, inArticle | banner | `string` | | `adPosition` | optional | 0 - Below the Fold, 1 - Above the Fold | 0 | `number` | | `video` | optional for video | Video targeting parameters. See the video section below. | {} | `object` | diff --git a/dev-docs/bidders/segmento.md b/dev-docs/bidders/segmento.md index 3358f04be9..b6ed585a0d 100644 --- a/dev-docs/bidders/segmento.md +++ b/dev-docs/bidders/segmento.md @@ -5,7 +5,8 @@ description: Prebid Segmento Bidder Adaptor pbjs: true biddercode: segmento media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/sekindoUM.md b/dev-docs/bidders/sekindoUM.md index cf55667388..a51d4d63e4 100644 --- a/dev-docs/bidders/sekindoUM.md +++ b/dev-docs/bidders/sekindoUM.md @@ -6,7 +6,8 @@ pbjs: true biddercode: sekindoUM media_types: video gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/selectmedia.md b/dev-docs/bidders/selectmedia.md index 9b582590ed..96b284d697 100644 --- a/dev-docs/bidders/selectmedia.md +++ b/dev-docs/bidders/selectmedia.md @@ -6,6 +6,7 @@ pbjs: true biddercode: selectmedia aliasCode: adtelligent media_types: banner, video +gvl_id: 775 --- ### Bid params diff --git a/dev-docs/bidders/selectmediavideo.md b/dev-docs/bidders/selectmediavideo.md index 5018b660b5..b83990023e 100644 --- a/dev-docs/bidders/selectmediavideo.md +++ b/dev-docs/bidders/selectmediavideo.md @@ -1,17 +1,19 @@ --- layout: bidder title: SelectMedia Video -description: SelectMedia Video Bidder Adapter +description: Prebid SelectMedia Video Bidder Adapter pbjs: true biddercode: selectmediavideo aliasCode: aniview -media_types: video +media_types: banner, video gdpr_supported: true usp_supported: true +schain_supported: true +safeframes_ok: true --- ### Note: -For more information about [SelectMedia](http://www.selectmedia.asia/). +For more information about [SelectMedia](https://www.selectmedia.asia/), please contact info@selectmedia.asia. ### Bid Params diff --git a/dev-docs/bidders/sharethrough.md b/dev-docs/bidders/sharethrough.md index f3f12448a7..5b9517b3a1 100644 --- a/dev-docs/bidders/sharethrough.md +++ b/dev-docs/bidders/sharethrough.md @@ -5,14 +5,20 @@ biddercode: sharethrough description: Prebid Sharethrough Adaptor gdpr_supported: true coppa_supported: true -media_types: native +floors_supported: true +media_types: banner, video +safeframes_ok: true schain_supported: true -userIds: pubCommonId, unifiedId, identityLink, id5Id, sharedId, liveIntentId +userIds: all usp_supported: true pbjs: true pbs: true --- +### Disclosure: + +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. + ### Note: The Sharethrough bidder adapter requires additional setup and approval from the Sharethrough Integrations team. Please reach out to your account manager for more information to start using it. @@ -20,10 +26,7 @@ The Sharethrough bidder adapter requires additional setup and approval from the {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | -|-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|----------------------| -| `bidfloor` | optional | The floor price, or minimum amount, a publisher will accept for an impression, given in CPM in USD. | `1.00` | `float` | -| `iframe` | optional | If `true`, the ad will render in an iframe. Defaults to `false`. | `true` | `boolean` | -| `iframeSize`| optional | `[width, height]` If provided, use this size for the iframe size. Only applicable if `iframe` is `true`. If omitted, the largest size from the ad unit sizes array will be used. | `[300, 250]` | `[integer, integer]` | -| `bcat` | optional | Array of blocked IAB Categories | `['IAB1-2', 'IAB1-3']` | `string[]` | -| `badv` | optional | Array of blocked Advertisers by their domains | `['ford.com', 'pepsi.com']` | `string[]` | -| `pkey` | required | The placement key | `'DfFKxpkRGPMS7A9f71CquBgZ'` | `string` | +|-------------|----------|-----------------------------------------------|------------------------------|----------------------| +| `pkey` | required | The placement key | `'DfFKxpkRGPMS7A9f71CquBgZ'` | `string` | +| `bcat` | optional | Array of blocked IAB Categories | `['IAB1-2', 'IAB1-3']` | `string[]` | +| `badv` | optional | Array of blocked Advertisers by their domains | `['ford.com', 'pepsi.com']` | `string[]` | diff --git a/dev-docs/bidders/shinez.md b/dev-docs/bidders/shinez.md index b9bd8c8235..422ae2b0ea 100644 --- a/dev-docs/bidders/shinez.md +++ b/dev-docs/bidders/shinez.md @@ -1,42 +1,82 @@ ---- -layout: bidder -title: Shinez -description: Prebid Shinez Bidder Adapter -biddercode: shinez -media_types: banner -pbjs: true -pbjs_version_notes: not in 5.x ---- - -### Registration - -The Shinez adapter requires setup and approval from the Shinez team. Please reach out to tech-team@shinez.io for more information. - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|------------|----------|----------------------|------------|----------| -| `placementId` | required | A Shinez-specific identifier that is associated with a specific domain provided by your Shinez representative. | `'00654321'` | `string` | -| `unit` | optional | An alphanumerical value used to identify the slot_id in reporting. | `'__header-bid-1'` | `string` | - -### Examples - -#### Example Banner Ad Unit - -```javascript -var adUnit = { - code: "test-div", - mediaTypes: { - banner: { - sizes: [[300, 250]] - } - }, - bids: [{ - bidder: "shinez", - params: { - placementId: "00654321" - } - }] -}; -``` +--- +layout: bidder +title: Shinez +description: Prebid Shinez Bidder Adapter +multiformat_supported: will-bid-on-any +pbjs: true +biddercode: shinez +media_types: banner, video +schain_supported: true +usp_supported: true +floors_supported: true +userIds: all +fpd_supported: true +safeframes_ok: false +--- + +### Note + +The Shinez adapter requires setup and approval. Please reach out to tech-team@shinez.io to setup an Shinez account. + +### Bid Parameters + +#### Banner, Video + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | Example +| ---- | ----- | ---- | ----------- | ------- +| `org` | required | String | Shinez publisher Id provided by your Shinez representative | "56f91cd4d3e3660002000033" +| `floorPrice` | optional | Number | Minimum price in USD. | 2.00 +| `placementId` | optional | String | A unique placement identifier | "12345678" +| `testMode` | optional | Boolean | This activates the test mode | false + +## Example +```javascript +var adUnits = [{ + code: 'banner-div', + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [728, 90] + ] + } + }, + bids: [{ + bidder: 'shinez', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 0.05, // Optional + placementId: '12345678', // Optional + testMode: true // Optional + } + }] + }, + { + code: 'dfp-video-div', + sizes: [ + [640, 480] + ], + mediaTypes: { + video: { + playerSize: [ + [640, 480] + ], + context: 'instream' + } + }, + bids: [{ + bidder: 'shinez', + params: { + org: '56f91cd4d3e3660002000033', // Required + floorPrice: 5.00, // Optional + placementId: '12345678', // Optional + testMode: true // Optional + } + }] + } +]; +``` + +### Configuration +Shinez recommends setting UserSync by iframe for monetization. \ No newline at end of file diff --git a/dev-docs/bidders/slimcut.md b/dev-docs/bidders/slimcut.md index c308a7322a..7292cbc707 100644 --- a/dev-docs/bidders/slimcut.md +++ b/dev-docs/bidders/slimcut.md @@ -1,12 +1,12 @@ --- layout: bidder title: Slimcut -description: SlimCut Bidder Adaptor +description: SlimCut Bidder Adapter pbjs: true biddercode: slimcut media_types: video, banner gdpr_supported: true -pbjs_version_notes: not in 5.x +gvl_id: 102 --- ### Overview diff --git a/dev-docs/bidders/smaato.md b/dev-docs/bidders/smaato.md index 9db736519e..c058c1e91a 100644 --- a/dev-docs/bidders/smaato.md +++ b/dev-docs/bidders/smaato.md @@ -4,26 +4,42 @@ title: Smaato description: Prebid Smaato Bidder Adaptor biddercode: smaato gdpr_supported: true +gvl_id: 82 usp_supported: true coppa_supported: true media_types: banner, video -userIds: criteo, pubCommonId, unifiedId +userId: criteo, pubCommonId, unifiedId pbjs: true pbs: true pbs_app_supported: true prebid_member: true +floors_supported: true +fpd_supported: true +schain_supported: true --- ### Table of Contents +- [Registration](#smaato-registration) +- [Note](#smaato-note) - [Bid Params](#smaato-bid-params) - [App Object](#smaato-app-object) +- [Example Ad Units](#smaato-example-ad-units) - [First Party Data](#smaato-first-party) +- [Test Parameters](#smaato-test-parameters) + +     ### Registration The Smaato adapter requires setup and approval from the Smaato team, even for existing Smaato publishers. Please reach out to your account team or prebid@smaato.com for more information. + + +### Note + +The Smaato adapter will convert bidfloors to 'USD' currency as needed. + ### Bid Params @@ -32,7 +48,8 @@ The Smaato adapter requires setup and approval from the Smaato team, even for ex | Name | Scope | Description | Example | Type | |------------|----------|----------------------|------------|----------| | `publisherId` | required | Your Smaato publisher id | `'1100012345'` | `string` | -| `adspaceId` | required | Your Smaato adspace id | `'11002234'` | `string` | +| `adspaceId` | required | Your Smaato adspace id. Required for non adpod requests | `'11002234'` | `string` | +| `adbreakId` | required | Your Smaato adbreak id. Required for adpod (long-form video) requests | `'41002234'` | `string` | | `app` | optional | Object containing mobile app parameters. See the [App Object](#smaato-app-object) for details.| `app : { ifa: '56700000-9cf0-22bd-b23e-46b96e40003a'}` | `object` | @@ -47,12 +64,15 @@ Smaato supports using prebid within a mobile app's webview. | `ifa` | String that contains the advertising identifier of the user (e.g. idfa or aaid). | `'56700000-9cf0-22bd-b23e-46b96e40003a'` | `string` | | `geo` | Object that contains the latitude (`lat`) and longitude (`lon`) of the user. | `{ lat: 33.3, lon: -88.8 }` | `object` | + -### Example Banner Ad Unit +### Example Ad Units + +#### Example Banner Ad Unit ```javascript var adUnit = { - "code": "header-bid-tag-1", + "code": "banner unit", "mediaTypes": { "banner": { "sizes": [320, 50] @@ -68,7 +88,7 @@ var adUnit = { } ``` -### Example Video Ad Unit +#### Example Video Ad Unit ```javascript var adUnit = { @@ -98,26 +118,73 @@ var adUnit = { }] }; ``` +#### Example AdPod (long-form) Video Ad Unit + +```javascript +var adUnit = { + "code": "adpod unit", + "mediaTypes": { + "video": { + "context": "adpod", + "playerSize": [640, 480], + "adPodDurationSec": 300, + "durationRangeSec": [15, 30], + "requireExactDuration": false, + "mimes": ["video/mp4"], + "startdelay": 0, + "linearity": 1, + "protocols": [7], + "skip": 1, + "skipmin": 5, + "api": [7], + } + }, + "bids": [{ + "bidder": "smaato", + "params": { + "publisherId": "1100042525", + "adbreakId": "400000000" + } + }] +}; +``` + ### First Party Data +Publishers should use the `ortb2` method of setting First Party Data. The following fields are supported: +- ortb2.site.keywords +- ortb2.site.content +- ortb2.user.keywords +- ortb2.user.yob +- ortb2.user.gender +- ortb2.user.ext.eids + +The IAB standard taxonomies are not supported. -The Smaato adapter supports passing through first party data configured in your prebid integration. +Example first party data that's available to all bidders and all adunits: ```javascript pbjs.setConfig({ - fpd: { - context: { - keywords: "power tools" - }, + ortb2: { + site: { + keywords: "kw1,kw2", + content: { + title: "title1", + series: "series1" + } + }, user: { - keywords: "a,b", - gender: "M", + keywords: "a,b", + gender: "M", yob: 1984 } + } }); ``` + + ### Test Parameters Following example includes sample `imp` object with publisherId and adSlot which can be used to test Smaato Adapter diff --git a/dev-docs/bidders/smartadserver.md b/dev-docs/bidders/smartadserver.md index 0c5d7a3b13..1af90bdb5e 100644 --- a/dev-docs/bidders/smartadserver.md +++ b/dev-docs/bidders/smartadserver.md @@ -3,13 +3,14 @@ layout: bidder title: Smart AdServer description: Prebid Smart AdServer Bidder Adaptor biddercode: smartadserver -media_types: display, video +media_types: display, video, native gdpr_supported: true schain_supported: true usp_supported: true -userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +userIds: all pbjs: true pbs: true +floors_supported: true --- ### Registration @@ -46,6 +47,24 @@ The Smart AdServer bidder adaptor requires setup and approval from the Smart AdS | `protocol` | optional | Maximum open RTB video protocol supported | `8` (VAST 4.0 wrapper) | `integer` | | `startDelay` | optional | Allowed values: 1 (generic pre-roll, default), 2 (generic mid-roll), 3 (generic post-roll) | `1` | `integer` | +### Supported Media Types (Prebid.js) + +{: .table .table-bordered .table-striped } +| Type | Support | +|---|---| +| `banner` | Supported | +| `video` | Supported | +| `native` | Not currently supported | + +### Supported Media Types (Prebid Server) + +{: .table .table-bordered .table-striped } +| Type | Support | +|------|-------| +| `banner` | Supported | +| `video` | Supported | +| `native` | Supported | + ### Examples Without site/page/format : diff --git a/dev-docs/bidders/smarthub.md b/dev-docs/bidders/smarthub.md new file mode 100644 index 0000000000..fa3774828f --- /dev/null +++ b/dev-docs/bidders/smarthub.md @@ -0,0 +1,34 @@ +--- +layout: bidder +title: SmartHub +description: SmartHub Bidder Adapter +biddercode: smarthub +usp_supported: true +schain_supported: true +media_types: banner, video, native +gdpr_supported: true +pbjs: true +pbs: true +pbs_app_supported: true +--- + +### Prebid.js Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------|-------------------------------------|-----------| +| `partnerName` | required | Unique partner name | `'partnertest'` | `string` | +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | +| `iabCat` | optional | Array of IAB content categories that describe the content producer | `['IAB1-1', 'IAB3-1', 'IAB4-3']` | `Array(String)` | +| `minBidfloor` | optional | Minimal CPM value | `0.03` | `float` | +| `pos` | optional | The position of the placement on the page, see Open RTB spec v2.5. | `4` | `number` | + +### Prebid Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------|--------------------------------------|----------| +| `partnerName` | required | Unique partner name | `'partnertest'` | `string` | +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | diff --git a/dev-docs/bidders/smartico.md b/dev-docs/bidders/smartico.md index 937f5ecc08..f05859f3b3 100644 --- a/dev-docs/bidders/smartico.md +++ b/dev-docs/bidders/smartico.md @@ -5,7 +5,6 @@ description: Prebid Smartico Bidder Adaptor pbjs: true biddercode: smartico media_types: banner -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/smartrtb.md b/dev-docs/bidders/smartrtb.md index df674f69d8..f2f55a61d6 100644 --- a/dev-docs/bidders/smartrtb.md +++ b/dev-docs/bidders/smartrtb.md @@ -9,6 +9,8 @@ userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrable pbjs: true pbs: true pbs_app_supported: true +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Registration diff --git a/dev-docs/bidders/smartx.md b/dev-docs/bidders/smartx.md index afb5d1dbf5..e65dabd5e1 100644 --- a/dev-docs/bidders/smartx.md +++ b/dev-docs/bidders/smartx.md @@ -11,6 +11,8 @@ schain_supported: false usp_supported: true safeframes_ok: false pbjs: true +pbjs_version_notes: avoid 4.31-4.39 +floors_supported: true --- ### Registration @@ -27,7 +29,6 @@ Please reach out to your smartclip business contact for any questions and assist | `bidfloor` | required | Value of Bidfloor. | `0.3` | `float` | | `bidfloorcur` | required | Used Currency. (e.g. EUR, USD etc.) | `'EUR'` | `string` | | `context` | optional | Token that describes which context to play: 'instream' or 'outstream' | `'outstream'` | `string` | -| `outstream_function` | optional | Custom function to be used as a renderer. | `function(bid){console.log(bid);}` | `function` | | `outstream_options` | required | Object to set options on the smartx renderer. (Only required when setting mediaType.video.context = 'outstream') | `{}` | `object` | | `secure` | optional | Boolean identifying whether the requests should be https or not (used to override the protocol if the page isn't secure). | `true`| `boolean` | | `mimes` | optional | List of MIME types to allow in ad. | `['application/javascript', 'video/mp4', 'video/webm']` | `array` | @@ -43,10 +44,11 @@ Please reach out to your smartclip business contact for any questions and assist | Name | Scope | Description | Example | Type | | --------------- | -------- | -------------------------------------------------------------------------------------------- | ---------------- | ----------- | | `slot` | required | ID of element that video ad should be rendered into. | `'adSlot1'` | `string` | -| `minAdWidth` | optional | Minimum amount of space the player needs to expand. | `290` | `integer` | -| `maxAdWidth` | optional | Maximum size of the player. | `900` | `integer` | -| `title` | optional | Makes a defined advertising text appear in the below right corner. `[remainingTime]` can be used to display the remaining time of the advertisement. | `'Advertisement [remainingTime]s'` | `string` | -| `skipOffset` | optional | Define whenever the advertisement can be skipped. 0 = never | `0` | `integer` | -| `startOpen` | optional | Define whether the player should be initialized open or open when it is within view. | `false` | `bool` | -| `endingScreen` | optional | Define whether the player should stay open after advertising or not. | `true` | `bool` | -| `desiredBitrate`| optional | Define the desired bitrate of the mediafile. | `800` | `integer` | +| `minAdWidth` | optional | If the visible area is narrower than this size, no ad will be requested. The value is given in pixels. Default is `280`. | `290` | `integer` | +| `maxAdWidth` | optional | The player will fill the whole width of the element it gets, to have it narrower a different maximum width can be defined in pixels. Default is `800`. | `900` | `integer` | +| `title` | optional | The player can show a freely definable text, a macro `[remainingTime]` in this string will be replaced with the remaining play time of the ad in seconds. | `'Advertisement [remainingTime]s'` | `string` | +| `skipOffset` | optional | In order to enable skipping from the start set the delay to `0`, to show the skip button after 5 seconds set it to `5`. Setting a general skipOffset is discouraged. Note that linear creatives carrying a skipsoffet attribute will override the general player setting. By default the player does not set a general skipoffset, so a skip button will only be shown, if an ad has a specific skipoffset attached. | `0` | `integer` | +| `startOpen` | optional | Per default the player will start fully expanded, if a valid ad can be played. Setting this option to `false` will trigger an expand animation instead once the player comes into view. Default is `true`. | `'false'` | `string` | +| `endingScreen` | optional | By default the player will not close, but show the ending screen when an advertisement is complete (last frame of the ad and a replay button, if an advertisment comes with an endcard that will be shown). If set to `false` the player will collapse. Some VPAID creatives can cause issues with ending screen or replay behaviour. Default is `true`. | `'true'` | `string` | +| `desiredBitrate`| optional | You can specify a target bitrate for the creative, higher values will increase video quality but will cost bandwidth. Value is given in kpbs. Default is `700`. | `800` | `integer` | +| `visibilityThreshold`| optional | Defines the percentage of the player which has to be in the visible area to play and pause the advertisment. The default is `50`. | `50` | `integer` | diff --git a/dev-docs/bidders/smartyads.md b/dev-docs/bidders/smartyads.md index 3b0738bee3..671cf75ef0 100644 --- a/dev-docs/bidders/smartyads.md +++ b/dev-docs/bidders/smartyads.md @@ -9,7 +9,7 @@ coppa_supported: true schain_supported: true media_types: banner, video, native safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true --- diff --git a/dev-docs/bidders/smilewanted.md b/dev-docs/bidders/smilewanted.md index b38af9159c..aae2f17d16 100644 --- a/dev-docs/bidders/smilewanted.md +++ b/dev-docs/bidders/smilewanted.md @@ -4,6 +4,7 @@ title: Smile Wanted description: SmileWanted Bidder Adapter media_types: banner, video pbjs: true +pbs: true biddercode: smilewanted gdpr_supported: true usp_supported: true @@ -19,16 +20,16 @@ To use us as a bidder you must have an account and an active "zoneId" on our Smi {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------|----------|-----------------------|----------|-----------| -| `zoneId` | required | The placement zone ID | `test.com_header_bidding_display_atf` | `string` | +| `zoneId` | required | The placement zone ID | `'test.com_header_bidding_display_atf'` | `string` | ### Testing -You can add `#sw_test_campaign` at the end of any url, this will have the effect of responding with a Smile Wanted creative, with a high CPM which allows to win every auctions and see if the ad displays correctly. -(Please note that impressions and revenues of this test ad this will not be recorded and not be paid) +You can add `#sw_test_campaign` to the end of any URL. This will have the effect of responding with a Smile Wanted creative with a high CPM, which means you'll win every auction so you can see if the ad displays correctly. +(Please note that impressions and revenues of this test ad will *not* be recorded and *not* be paid.) ### User Sync -Add the following code to enable user sync. Smile Wanted strongly recommends enabling user syncing through iFrames. This functionality improves partners user match rates and increases the Smile Wanted bid rate and bid price. Be sure to call `pbjs.setConfig()` only once. +Add the following code to enable user sync. Smile Wanted strongly recommends enabling user syncing through iFrames. This functionality improves partners' user match rates and increases the Smile Wanted bid rate and bid price. Be sure to call `pbjs.setConfig()` only once. ``` pbjs.setConfig({ diff --git a/dev-docs/bidders/smms.md b/dev-docs/bidders/smms.md index f52ac751fb..821bffed34 100644 --- a/dev-docs/bidders/smms.md +++ b/dev-docs/bidders/smms.md @@ -5,7 +5,8 @@ description: Prebid SMMS Bidder Adaptor pbjs: true biddercode: smms media_types: banner, native -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/somo.md b/dev-docs/bidders/somo.md index 44724eb0a0..bd903ebbfc 100644 --- a/dev-docs/bidders/somo.md +++ b/dev-docs/bidders/somo.md @@ -5,7 +5,8 @@ description: Somo Audience Bidder Adapter pbjs: true biddercode: somo prevBiddercode: somoAudience -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Disclosure diff --git a/dev-docs/bidders/somoaudience.md b/dev-docs/bidders/somoaudience.md index 2b56243146..6bf9e30ace 100644 --- a/dev-docs/bidders/somoaudience.md +++ b/dev-docs/bidders/somoaudience.md @@ -4,8 +4,9 @@ title: Somo Audience description: Somo Audience Bidder Adapter biddercode: somoaudience media_types: banner, native, video -pbs: true -pbjs_version_notes: not in 5.x +pbs: false +enable_download: false +pbs_version_notes: they've pulled their PBS adapter --- diff --git a/dev-docs/bidders/andbeyond.md b/dev-docs/bidders/sonic_twist.md similarity index 71% rename from dev-docs/bidders/andbeyond.md rename to dev-docs/bidders/sonic_twist.md index 66964793fc..966fc2a4ed 100644 --- a/dev-docs/bidders/andbeyond.md +++ b/dev-docs/bidders/sonic_twist.md @@ -1,10 +1,10 @@ --- layout: bidder -title: Andbeyond Media -description: Andbeyond Media +title: Sonic Twist Media +description: Sonic Twist Media pbjs: true pbs: true -biddercode: andbeyond +biddercode: sonic_twist media_types: banner, native, video gdpr_supported: true usp_supported: true @@ -14,7 +14,7 @@ aliasCode : adkernel ### Note: -The andbeyond Bidding adaptor requires setup and approval before beginning. Please reach out to for more details +The Sonic Twist Media Bidding adaptor requires setup and approval before beginning. Please reach out to for more details ### Bid Params diff --git a/dev-docs/bidders/sortable.md b/dev-docs/bidders/sortable.md deleted file mode 100644 index 8a6487498e..0000000000 --- a/dev-docs/bidders/sortable.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -layout: bidder -title: Sortable -description: Prebid Sortable Bidder Adaptor -biddercode: sortable -pbjs: true -media_types: banner, native, video -gdpr_supported: true -usp_supported: true -schain_supported: true -prebid_member: true -gvl_id: 145 -pbjs_version_notes: not in 5.x ---- - -**Table of Contents** - -- [Bid params](#sortable-bid-params) -- [Banner Ads](#sortable-banner) -- [Configuration](#sortable-configuration) - - - -### Bid params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | -|------+-------+-------------+---------| -| `tagId` | required | The tag ID from Sortable. | `"test-pb-leaderboard"` | -| `siteId` | optional | Override the global Sortable site ID, [see here](#sortable-configuration). Please reach out to your Sortable Account Manager for more details. | `"example.com"` | -| `floor` | optional | The minumum CPM (in USD) requred to participate | `0.25` | -| `keywords` | optional | Publisher-defined key-value string pairs | `{ "key1": "val1", "key2": "val2" }` | - - - -### Banner Ads - -Sortable supports the banner features described in: - -- [The `adUnit` banner documentation](/dev-docs/adunit-reference.html#adUnit-banner-example) -- [Getting Started for Developers](/dev-docs/getting-started.html) - - - - -### Configuration - -The Sortable site ID should be set globally in order to improve user sync. How to do so: - -``` javascript -pbjs.setConfig({ - sortable: { - siteId: "example.com" - } -}); -``` - -The Sortable adapter has the ability to initiate user-sync requests that will improve DSP user ID match rate, -with the aim of generating higher bid prices. By default, Sortable sync requests are off. Setting the Sortable site ID globally as described above is required for user-sync requests. - -``` javascript -pbjs.setConfig({ - userSync: { - enabledBidders: ['sortable'], - iframeEnabled: true - }}); -``` - -Note: these configs should be combined with any other UserSync config calls, as subsequent calls to setConfig for the same attribute overwrite each other. diff --git a/dev-docs/bidders/sovrn.md b/dev-docs/bidders/sovrn.md index 3905d8c32e..3ae110acce 100644 --- a/dev-docs/bidders/sovrn.md +++ b/dev-docs/bidders/sovrn.md @@ -11,7 +11,8 @@ userIds: all prebid_member: true schain_supported: true gvl_id: 13 -getFloor: true +floors_supported: true +media_types: banner, video --- ### Bid Params @@ -21,3 +22,160 @@ getFloor: true |------------|----------|----------------------|------------|----------| | `tagid` | required | The sovrn Ad Tag ID | `'315045'` | `string` | | `bidfloor` | optional | Bid floor in dollars | `'0.04'` | `string` | + +Bid Params for video ads. These params should be added to `mediatype.video`. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------|-----------------| +| `mimes` | required | Content MIME types supported | `['video/mp4']` | `string array` | +| `minduration` | required | Minimum video ad duration in seconds | `5` | `integer` | +| `maxduration` | required | Maximum video ad duration in seconds | `10` | `integer` | +| `protocols` | required | The array of supported video protocols | `[1, 2]` | `integer array` | +| `w` | recommended | Width of the video player in device independent pixels (DIPS) | `5` | `integer` | +| `h` | recommended | Height of the video player in device independent pixels (DIPS) | `5` | `integer` | +| `startdelay` | recommended | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements | `5` | `integer` | +| `placement` | recommended | Placement type for the impression. Refer to List 5.9 | `5` | `integer` | +| `linearity` | recommended | Indicates if the impression must be linear, nonlinear, etc. Allowed by default | `0` | `integer` | +| `skip` | optional | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes | `0` | `integer` | +| `skipmin` | optional | Only if the ad is skippable. Videos of total duration greater than this number of seconds can be skippable | `5` | `integer` | +| `skipafter` | optional | Only if the ad is skippable. Number of seconds a video must play before skipping is enabled | `5` | `integer` | +| `sequence` | optional | For multiple ad in the same bid request. This value allow will for the coordinated delivery of multiple ad | `5` | `integer` | +| `battr` | optional | Blocked creative attributes | `[1]` | `integer array` | +| `maxextended` | optional | Max extended ad duration beyond the maxduration if extension is allowed. Blank or 0 - blocked. -1 - allowed without time limit | `5` | `integer` | +| `minbitrate` | optional | Minimum bit rate in Kbps | `5` | `integer` | +| `maxbitrate` | optional | Maximum bit rate in Kbps | `5` | `integer` | +| `boxingallowed` | optional | Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes | `5` | `integer` | +| `playbackmethod` | optional | Playback methods that may be in use. See [Video Playback Methods](#video-playback-methods) | `[1]` | `integer array` | +| `playbackend` | optional | The event that causes playback to end. Refer to Playback Cessation Modes | `5` | `integer` | +| `delivery` | optional | Supported delivery methods (1 = streaming, 2 = progressive, 3 = download). If none specified, assume all are supported. | `[1, 2]` | `integer array` | +| `pos` | recommended | Ad position on screen. Refer to [Ad Position](#ad-position) | `5` | `integer` | +| `api` | recommended | List of supported API frameworks for this impression. Refer to [API Frameworks](api-frameworks) | `[1, 2, 3]` | `integer array` | + + +### Note + +[Protocols list](https://docs.prebid.org/dev-docs/bidders/conversant.html#protocols) + +#### MIME types: + +##### With VPAID2: + +video/mp4, +video/3gpp, +application/javascript + +##### Without VPAID2: + +video/mp4, +video/3gpp + +#### Video Playback Methods: + +{: .table .table-bordered .table-striped } +| Value | Description | +|-------|----------------------------------------------------------| +| `1` | Initiates on Page Load with Sound On | +| `2` | Initiates on Page Load with Sound Off by Default | +| `3` | Initiates on Click with Sound On | +| `4` | Initiates on Mouse-Over with Sound On | +| `5` | Initiates on Entering Viewport with Sound On | +| `6` | Initiates on Entering Viewport with Sound Off by Default | + +#### Playback Cessation Modes: + +{: .table .table-bordered .table-striped } +| Value | Description | +|-------|-----------------------------------------------------------------------------------------------------------| +| `1` | On Video Completion or when Terminated by User | +| `2` | On Leaving Viewport or when Terminated by User | +| `3` | On Leaving Viewport Continues as a Floating/Slider Unit until Video Completion or when Terminated by User | + +#### Ad Position: + +{: .table .table-bordered .table-striped } +| Value | Description | +|-------|----------------| +| `0` | Unknown | +| `1` | Above the Fold | +| `2` | DEPRECATED | +| `3` | Below the Fold | +| `4` | Header | +| `5` | Footer | +| `6` | Sidebar | +| `7` | Full Screen | + +#### API Frameworks: + +{: .table .table-bordered .table-striped } +| Value | Description | +|-------|-------------| +| `1` | VPAID 1.0 | +| `2` | VPAID 2.0 | +| `3` | MRAID-1 | +| `4` | ORMMA | +| `5` | MRAID-2 | +| `6` | MRAID-3 | + +Source: [OpenRTB scpecification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) + +### Example + +#### Video instream adUnit + +``` + var instreamAdUnit = { + code: 'instream-div', + sizes: [[640, 480]], + mediaTypes: { + video: { + mimes: ['video/mp4'], + minduration: 4, + maxduration: 6, + context: 'instream' + } + }, + bids: [{ + bidder: 'sovrn', + params: { + tagid: '315045' + } + }] + } +``` +#### Video outstream adUnit + +``` + var outstreamAdUnit = { + code: 'outstream-div', + sizes: [[640, 480]], + mediaTypes: { + video: { + mimes: ['video/mp4'], + minduration: 4, + maxduration: 6, + context: 'outstream' + } + }, + bids: [{ + bidder: 'sovrn', + params: { + tagid: '315045' + } + }] + }, +``` +#### Banner adUnit + +``` + var bannerAdUnit = { + code: 'banner-div', + sizes: [[300, 250]], + bids: [{ + bidder: 'sovrn', + params: { + tagid: '315045' + } + }] + } +``` diff --git a/dev-docs/bidders/spotx.md b/dev-docs/bidders/spotx.md index 9a63dfb00d..a958f6ca76 100644 --- a/dev-docs/bidders/spotx.md +++ b/dev-docs/bidders/spotx.md @@ -5,20 +5,19 @@ description: Prebid SpotX Bidder Adaptor biddercode: spotx media_types: no-display, video gdpr_supported: true -userIds: id5Id, pubCommonId, unifiedId +userIds: id5Id, sharedId, unifiedId prebid_member: true schain_supported: true usp_supported: true safeframes_ok: false pbjs: true gvl_id: 165 -pbjs_version_notes: avoid 4.31-4.35 +floors_supported: true --- -### Note: +### Registration -There was an issue in the SpotX adapter in PBJS 4.31 that assumed all publishers had already set the [`ignoreVideoCacheKey`](/dev-docs/publisher-api-reference.html#setConfig-vast-cache). -Publishers using SpotX that haven't yet updated their ad server line items and turned on the ignoreVideoCacheKey option should avoid Prebid.js 4.31 - 4.35. +The SpotX adapter requires setup and approval from your Magnite account manager. Please reach out to them for more information. ### Bid Params @@ -32,7 +31,7 @@ Publishers using SpotX that haven't yet updated their ad server line items and t | `secure` | optional | Boolean identifying whether the requests should be https or not (used to override the protocol if the page isn't secure). | `true` | `boolean` | | `mimes` | optional | List of MIME types to allow in ad. | `['application/javascript', 'video/mp4', 'video/webm']` | `array` | | `ad_volume` | optional | Value between 0 and 1 to denote the volume the ad should start at | `0.7` | `float` | -| `price_floor` | optional | Set the current channel price floor in real time. | `10` | `integer` | +| `price_floor` | optional | Set the current channel price floor in real time. | `10` | `float` | | `hide_skin` | optional | Set to true to hide the SpotX skin | | `boolean` | | `custom` | optional | An object containing key-value pairs for reporting. See SpotX documentation [here](https://developer.spotxchange.com/content/local/docs/sdkDocs/DirectSdk/dsdk-custom-configs.md#custom-key-value-pair-reporting) | | `object` | | `min_duration` | optional | Minimum video ad duration in seconds | | `integer` | diff --git a/dev-docs/bidders/sspBC.md b/dev-docs/bidders/sspBC.md index 41a319747a..e51b83063b 100644 --- a/dev-docs/bidders/sspBC.md +++ b/dev-docs/bidders/sspBC.md @@ -4,8 +4,8 @@ title: sspBC description: Prebid sspBC Bidder Adaptor pbjs: true biddercode: sspBC -media_types: banner -getFloor: true +media_types: banner, video, native +floors_supported: true gdpr_supported: true gvl_id: 676 --- diff --git a/dev-docs/bidders/onefiftytwomedia.md b/dev-docs/bidders/streamkey.md similarity index 65% rename from dev-docs/bidders/onefiftytwomedia.md rename to dev-docs/bidders/streamkey.md index d7b157bcdb..9cd2cffbc5 100644 --- a/dev-docs/bidders/onefiftytwomedia.md +++ b/dev-docs/bidders/streamkey.md @@ -1,11 +1,12 @@ --- layout: bidder -title: 152 Media 3.0 -description: Prebid 152 Media RTB Bidder Adapter +title: Streamkey +description: Prebid Streamkey.tv Bidder Adapter pbjs: true -biddercode: onefiftytwomedia +pbs: true +biddercode: streamkey aliasCode: adtelligent -media_types: banner, video +media_types: video --- ### Bid params @@ -13,7 +14,7 @@ media_types: banner, video {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |-------|----------|---------------------------------|----------|-----------| -| `aid` | required | The source ID | `350975` | `integer` | +| `aid` | required | The traffic source ID | `232131` | `integer` | ### Test Parameters @@ -30,7 +31,7 @@ media_types: banner, video } }, bids: [{ - bidder: 'onefiftytwomedia', + bidder: 'streamkey', params: { aid: 331133 } @@ -47,23 +48,11 @@ media_types: banner, video } }, bids: [{ - bidder: 'onefiftytwomedia', + bidder: 'streamkey', params: { aid: 331133 } }] }, - - // Banner adUnit - { - code: 'div-test-div', - sizes: [[300, 250]], - bids: [{ - bidder: 'onefiftytwomedia', - params: { - aid: 350975 - } - }] - } ]; ``` diff --git a/dev-docs/bidders/stroeerCore.md b/dev-docs/bidders/stroeerCore.md index 9c0bae38c6..8fd6d99d27 100644 --- a/dev-docs/bidders/stroeerCore.md +++ b/dev-docs/bidders/stroeerCore.md @@ -4,16 +4,21 @@ title: StroeerCore description: Stroeer Bidder Adapter biddercode: stroeerCore media_types: banner -gdpr_supported: false +gdpr_supported: true schain_supported: false coppa_supported: false usp_supported: false safeframes_ok: true prebid_member: false pbjs: true -pbs: false +pbs: true gvl_id: 136 -bidder_supports_deals: true +pbs_app_supported: true +deals_supported: true +userIds: criteo, id5Id, netId, pubCommonId, sharedId +multiformat_supported: will-bid-on-one +floors_supported: false +fpd_supported: false --- ### Bid Params diff --git a/dev-docs/bidders/stv.md b/dev-docs/bidders/stv.md index d55a9f68a2..9cde162f24 100644 --- a/dev-docs/bidders/stv.md +++ b/dev-docs/bidders/stv.md @@ -6,7 +6,8 @@ pbjs: true biddercode: stv media_types: banner,video gdpr_supported: false -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/synacormedia.md b/dev-docs/bidders/synacormedia.md index a33aec42f1..2304d2e029 100644 --- a/dev-docs/bidders/synacormedia.md +++ b/dev-docs/bidders/synacormedia.md @@ -6,7 +6,7 @@ pbjs: true pbs: true biddercode: synacormedia media_types: banner, video -userIds: identityLink, verizonMediaId, pubCommonId, nextrollId +userIds: identityLink, verizonMediaId, pubCommonId gdpr_supported: false schain_supported: true usp_supported: true diff --git a/dev-docs/bidders/taboola.md b/dev-docs/bidders/taboola.md new file mode 100644 index 0000000000..97c3d6ebe3 --- /dev/null +++ b/dev-docs/bidders/taboola.md @@ -0,0 +1,59 @@ +--- +layout: bidder +title: Taboola +description: Prebid Taboola Bidder Adapter +pbjs: true +biddercode: taboola +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: false +media_types: banner +gvl_id: 42 +prebid_member: true +floors_supported: true +safeframes_ok: true +--- + +### Note +- Supports `display` format. +- Uses `OpenRTB` standard. + +### Registration + +The Taboola Adapter requires setup before beginning. Please contact us at prebid@taboola.com. + +### Bid Params + +{: .table .table-bordered .table-striped } + +| Name | Scope | Description | Example | Type | +|----------------|----------|---------------------------------------------------------|----------------------------|--------------| +| `tagId` | required | Tag ID / Placement Name
    | `'Below The Article'` | `String` | +| `publisherId` | required | Numeric Publisher ID
    (as provided by Taboola) | `'1234567'` | `String` | +| `bcat` | optional | List of blocked advertiser categories (IAB) | `['IAB1-1']` | `Array` | +| `badv` | optional | Blocked Advertiser Domains | `'example.com'` | `String Url` | +| `bidfloor` | optional | CPM bid floor | `0.25` | `Float` | + + +### Example Ad Unit +```javascript + var adUnits = [{ + code: 'your-unit-container-id', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + }, + bids: [{ + bidder: 'taboola', + params: { + tagId: 'Placement Name', + publisherId: 'your-publisher-id', + bidfloor: 0.25, // Optional - default is null + bcat: ['IAB1-1'], // Optional - default is [] + badv: ['example.com'] // Optional - default is [] + } + }] +}]; +``` diff --git a/dev-docs/bidders/talkads.md b/dev-docs/bidders/talkads.md new file mode 100644 index 0000000000..eed57d1a16 --- /dev/null +++ b/dev-docs/bidders/talkads.md @@ -0,0 +1,74 @@ +--- +layout: bidder +title: Talkads +description: Talkads Prebid Bidder Adapter +biddercode: talkads +gdpr_supported: true +gvl_id: 1074 +usp_supported: false +coppa_supported: false +media_types: banner, native +safeframes_ok: false +pbjs: true +pbs: false +prebid_member: false +pbjs_version_notes: v4.35 and later +--- + +### Registration + +The Talkads Adapter requires setup before beginning. Please contact us at www.natexo.com and register to the publisher side. + +### Configuration + +#### Prebid.js + +The TalkAds adapter does not work without setting the correct tag ID and bidder URL. +These parameters are totally specific to each Publisher, you will receive them when contacting us. + +### Bid Params + +{: .table .table-bordered .table-striped } + +| Name | Scope | Description | Example | Type | +|--------------|----------|----------------------------------------------------------------|---------------------------------------------------------|----------------| +| `tag_id` | required | The publisher tag id given by the Natexo team | `99` | `number` | +| `bidder_url` | required | The publisher bidder url given by the Natexo team | `'https://test.natexo-programmatic.com/tad/tag/prebid'` | `string` | + +#### Native example + +``` +var adUnits = [ + code: '/19968336/prebid_native_example_1', + mediaTypes: { + native: { + } + }, + bids: [{ + bidder: 'talkads', + params: { + tag_id: 0, + bidder_url: 'https://d.natexo-programmatic.com/tad/tag/testbid', + }, + }] +]; +``` + +#### Banner example +``` +var adUnits = [ + code: '/19968336/prebid_display_example_1', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + bids: [{ + bidder: 'talkads', + params: { + tag_id: 0, + bidder_url: 'https://d.natexo-programmatic.com/tad/tag/testbid', + }, + }] +]; +``` diff --git a/dev-docs/bidders/taphype.md b/dev-docs/bidders/taphype.md index df27868761..d95fe94236 100644 --- a/dev-docs/bidders/taphype.md +++ b/dev-docs/bidders/taphype.md @@ -4,7 +4,8 @@ title: TapHype description: Prebid TapHype Bidder Adaptor pbjs: true biddercode: taphype -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/tappx.md b/dev-docs/bidders/tappx.md index 256d676a88..0797111f67 100644 --- a/dev-docs/bidders/tappx.md +++ b/dev-docs/bidders/tappx.md @@ -1,6 +1,6 @@ --- layout: bidder -title: :tappx +title: tappx pbs: true pbjs: true media_types: banner, video @@ -18,18 +18,22 @@ userIds: all Please contact tappx@tappx.com to get set up. -**Note:** The Tappx prebid bidder only supports in app traffic at the moment - ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |------------|----------|------------------------|---------|----------| -| host | required | Tappx host | 'host1' | string | | tappxkey | required | An ID which identifies the adunit | 'key1' | string | | endpoint | required | Endpoint provided to publisher | 'endpoint1' | string | +| host | required(pbjs) optional(pbserver) | Tappx host | 'host1' | string | | bidfloor | optional | Minimum bid for this impression expressed in CPM (USD) | 1.2 | number | +| mktag | optional | An ID which identifies a group of adunits | 'key1' | string | +| bcid | optional | Block list of CID | ["1234"] | array of strings | +| bcrid | optional | Block list of CRID | ["1234"] | array of strings | ### Test Parameters Use the official test parameter specified in the oRTB standard (https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#object_request) + +### Other notes +- Parameters host is required in prebidjs and the old versions of prebid server. In case of doubt, always add the parameter. diff --git a/dev-docs/bidders/targetvideo.md b/dev-docs/bidders/targetvideo.md new file mode 100644 index 0000000000..34ed9148c9 --- /dev/null +++ b/dev-docs/bidders/targetvideo.md @@ -0,0 +1,17 @@ +--- +layout: bidder +title: TargetVideo +description: Prebid TargetVideo Bidder Adaptor +biddercode: targetVideo +media_types: banner +gdpr_supported: true +schain_supported: true +pbjs: true +--- + +#### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| +| `placementId` | required | The placement ID from TargetVideo. You may identify a placement using the `invCode` and `member` instead of a placement ID. The `placementID` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. Legacy code can retain the `string` value. **Prebid Server requires an integer value.** | `234234` | `integer` | diff --git a/dev-docs/bidders/teads.md b/dev-docs/bidders/teads.md index 4ca58d6654..905567f301 100644 --- a/dev-docs/bidders/teads.md +++ b/dev-docs/bidders/teads.md @@ -7,9 +7,10 @@ biddercode: teads gdpr_supported: true usp_supported: true schain_supported: true +userIds: flocId, uid2Id media_types: banner, video gvl_id: 132 -bidder_supports_deals: true +deals_supported: true --- ### Note: diff --git a/dev-docs/bidders/telaria.md b/dev-docs/bidders/telaria.md index 46ae17f350..6acbb6a5e6 100644 --- a/dev-docs/bidders/telaria.md +++ b/dev-docs/bidders/telaria.md @@ -3,16 +3,36 @@ layout: bidder title: Telaria description: Telaria Bidder Adaptor pbjs: true +pbs: false biddercode: telaria -media_types: video +media_types: video, no-display gdpr_supported: true +usp_supported: false +coppa_supported: false +schain_supported: true +floors_supported: false +prebid_member: true +safeframes_ok: false +deals_supported: false +pbs_app_supported: false +fpd_supported: false +gvl_id: 202 --- -### Overview -This documentation covers some of the parameters that the **Telaria** `(previously Tremor Video)` exchange accepts. And is intended to be referenced by publishers using prebid 1.x. Documentation for prebid 0.x can be found under [tremor](/dev-docs/bidders/tremor) +### Registration + +The Telaria adapter requires setup and approval from your Magnite account manager. Please reach out to them for more information. ### Bid Params -Please refer to the **Tag Parameters** section in the [Telaria Console](https://console.telaria.com) + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| +| adCode | required | A unique ID assigned by your Magnite account team. | `'lufip'` | `string` | +| supplyCode | required | A code assigned by your Magnite account team. | `'demo'` | `string` | +| videoId | optional | The ID of video asset. | `'myVideo'` | `string` | + +For other parameters, please refer to the **Tag Parameters** section in the [Telaria Console](https://console.telaria.com) ### Example Ad Unit ```javascript diff --git a/dev-docs/bidders/tim.md b/dev-docs/bidders/tim.md index 085c2aef4d..133c062064 100644 --- a/dev-docs/bidders/tim.md +++ b/dev-docs/bidders/tim.md @@ -4,7 +4,8 @@ title: Tim Media description: Prebid Tim Bidder Adaptor pbjs: true biddercode: tim -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/topRTB.md b/dev-docs/bidders/topRTB.md index 7e7aab5641..2c2a8f83d3 100644 --- a/dev-docs/bidders/topRTB.md +++ b/dev-docs/bidders/topRTB.md @@ -4,7 +4,8 @@ title: TOPRTB description: Prebid topRTB Bidder Adapter pbjs: true biddercode: topRTB -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/tpmn.md b/dev-docs/bidders/tpmn.md index 822dfe7308..83c4b5834a 100644 --- a/dev-docs/bidders/tpmn.md +++ b/dev-docs/bidders/tpmn.md @@ -2,12 +2,25 @@ layout: bidder title: TPMN description: Prebid TPMN Bidder Adaptor -pbjs: true biddercode: tpmn +media_types: banner gdpr_supported: false +prebid_member: false +schain_supported: false +coppa_supported: false +usp_supported: false +floors_supported: false +fpd_supported: false +pbjs: true +pbs: false --- +### Registration + +To use this bidder you will need an account and a valid unit from us. +For further information, please contact `info@tpmn.io` + ### Bid Params {: .table .table-bordered .table-striped } @@ -15,3 +28,25 @@ gdpr_supported: false |---------------|----------|--------------------------------------|------------------|-----------| | `inventoryId` | required | Inventory ID | `'1'` | `integer` | | `publisherId` | required | Publisher ID | `'TPMN'` | `string` | + +### User Sync + +Add the following code to enable user sync. +TPMN strongly recommends enabling user syncing through iFrames. +This functionality improves partners' user match rates and increases the TPMN bid rate and bid price. +Even if iFrame is not active, user sync of some partners is performed. +Be sure to call `pbjs.setConfig()` only once. + +``` +pbjs.setConfig({ + userSync: { + iframeEnabled: true, + filterSettings: { + iframe: { + bidders: '*', // '*' means all bidders + filter: 'include' + } + } + } +}); +``` diff --git a/dev-docs/bidders/trafficgate.md b/dev-docs/bidders/trafficgate.md new file mode 100644 index 0000000000..8586530137 --- /dev/null +++ b/dev-docs/bidders/trafficgate.md @@ -0,0 +1,33 @@ +--- +layout: bidder +title: TrafficGate +description: Prebid TrafficGate Bidder Adaptor +pbs: true +pbjs: true +biddercode: trafficgate +media_types: banner, video, native, audio +gdpr_supported: true +pbs_app_supported: true +multiformat_supported: will-bid-on-any +usp_supported: true +schain_supported: false +coppa_supported: true +dchain_supported: false +deals_supported: true +floors_supported: false +fpd_supported: false +prebid_member: true +--- + +### Note: + +The TrafficGate Bidding adapter requires setup before beginning. Please contact us at support@bidscube.com + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|-------------|----------| +| `placementId` | required | Placement ID | `'12345'` | `string` | +|---------------|----------|--------------|-------------|----------| +| `host` | required | Host | `'example'` | `string` | diff --git a/dev-docs/bidders/trendqube.md b/dev-docs/bidders/trendqube.md index 2b7fefe195..725ed5be74 100644 --- a/dev-docs/bidders/trendqube.md +++ b/dev-docs/bidders/trendqube.md @@ -6,7 +6,8 @@ pbjs: true biddercode: trendqube gdpr_supported: true media_types: banner, video -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/triplelift.md b/dev-docs/bidders/triplelift.md index 9406329245..894d505ca5 100644 --- a/dev-docs/bidders/triplelift.md +++ b/dev-docs/bidders/triplelift.md @@ -7,26 +7,123 @@ gdpr_supported: true usp_supported: true coppa_supported: true schain_supported: true -getFloor: true +floors_supported: true media_types: banner, video userIds: criteo, identityLink, unifiedId, pubCommonId prebid_member: true safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true pbs_app_supported: true +fpd_supported: true gvl_id: 28 --- +### Table of Contents + +- [Overview](#triplelift-overview) +- [Bid Parameters](#triplelift-bid-params) +- [Example Configuration](#triplelift-config) +- [First Party Data](#triplelift-first-party) + +     + +### Overview + +Publishers may integrate with Triplelift through our Prebid.js and/or Prebid Server adapters. See below for more information. + +{% capture version2 %} +The Triplelift Prebid Server bidding adapter and user sync endpoint require setup before beginning. Please contact us at prebid@triplelift.com. +{% endcapture %} +{% include alerts/alert_important.html content=version2 %} + + + ### Bid Params +#### Banner + +{: .table .table-bordered .table-striped } + +| Name | Scope | Description | Example | Type | +|-----------------|------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `inventoryCode` | required | TripleLift inventory code for this ad unit (provided to you by your partner manager) | `'pubname_top_banner'` | `string` | +| `floor` | optional | Bid floor | `1.00` | `float` | + + +#### Video + +The following parameters are supported for instream inventory only. + {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-----------------|------------------------------|--------------------------------------------------------------------------------------|--------------------------------------------|----------| -| `inventoryCode` | required | TripleLift inventory code for this ad unit (provided to you by your partner manager) | `'pubname_main_feed'` | `string` | -| `floor` | optional | Bid floor | `1.00` | `float` | -| `video` | required for instream video | oRTB video object | `{ mimes: ['video/mp4'], w: 640, h: 480 }` | `object` | -| `video.w` | required for instream video | oRTB video object width dimension | `640` | `int` | -| `video.h` | required for instream video | oRTB video object height dimension | `480` | `int` | +| Name | Scope | Description | Example | Type | +|-----------------|------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `inventoryCode` | required | TripleLift inventory code for this ad unit (provided to you by your partner manager) | `'pubname_instream_1'` | `string` | +| `video` | required | oRTB video object | `{ mimes: ['video/mp4'], w: 640, h: 480 }` | `object` | +| `video.context` | required | Instream or outstream - TripleLift only supports instream. | `instream` | `string` | +| `video.w` | required | oRTB video object width dimension | `640` | `int` | +| `video.h` | required | oRTB video object height dimension | `480` | `int` | + + + +### Example Configuration + +#### Banner + +``` +var adUnits = [ + { + code: 'top-banner', + mediaTypes: { + banner: { + sizes: [ + [728, 90], + [970, 250] + ] + } + }, + bids: [{ + bidder: 'triplelift', + params: { + inventoryCode: 'pubname_top_banner' + } + }] +}]; +``` + +#### Video (Instream) + +``` +var videoAdUnit = { + code: 'video1', + mediaTypes: { + video: { + playerSize: [640, 480], + context: 'instream', + mimes: ['video/mp4'] + } + }, + bids: [{ + bidder: 'triplelift', + params: { + inventoryCode: 'pubname_instream1', + video: { + w: 640, + h: 480 + } + } + }] +}; +``` + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). The following fields are supported: +- `ortb2.site.*`: Standard IAB OpenRTB 2.5 site fields +- `ortb2.user.*`: Standard IAB OpenRTB 2.5 user fields + +AdUnit-specific data is supported using `AdUnit.ortb2Imp.ext.*` \ No newline at end of file diff --git a/dev-docs/bidders/triplelift_native.md b/dev-docs/bidders/triplelift_native.md index 09829e00cf..b341adcae9 100644 --- a/dev-docs/bidders/triplelift_native.md +++ b/dev-docs/bidders/triplelift_native.md @@ -8,18 +8,33 @@ tcf2_supported: true usp_supported: true coppa_supported: true schain_supported: true -getFloor: true -media_types: banner, video, native +floors_supported: true +media_types: native userIds: criteo, identityLink, unifiedId prebid_member: true safeframes_ok: true -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true pbs_app_supported: true +fpd_supported: true gvl_id: 28 --- +{% capture version2 %} +The Triplelift Prebid Server bidding adapter and user sync endpoint require setup before beginning. Please contact us at prebid@triplelift.com. +{% endcapture %} +{% include alerts/alert_important.html content=version2 %} + +This is a Prebid Server adapter for running component native only. For the standard Prebid JS Triplelift bid adapter, see the "Triplelift" bidder. + +### Table of Contents + +- [Bid Params](#triplelift-bid-params) +- [First Party Data](#triplelift-first-party) + + + ### Bid Params {: .table .table-bordered .table-striped } @@ -27,3 +42,11 @@ gvl_id: 28 |------------|----------|------------------------|---------|----------| | inventoryCode | required | TripleLift inventory code for this ad unit (provided to you by your partner manager) | 'code1' | string | | floor | optional | the bid floor, in usd | 1.2 | number | + + + +### First Party Data + +Triplelift supports standard IAB OpenRTB 2.5 First Party Data fields, including: +- `site.*` +- `user.*` \ No newline at end of file diff --git a/dev-docs/bidders/trustx.md b/dev-docs/bidders/trustx.md index 7f530c9f1a..d3dafe9f37 100644 --- a/dev-docs/bidders/trustx.md +++ b/dev-docs/bidders/trustx.md @@ -5,18 +5,102 @@ description: Prebid TrustX Bidder Adaptor pbjs: true pbs: true biddercode: trustx +aliasCode: grid media_types: banner, video +multiformat_supported: will-bid-on-any gdpr_supported: true usp_supported: true +schain_supported: true +floors_supported: true +userIds: all +tcf2_supported: true +coppa_supported: true +fpd_supported: true +pbjs_version_notes: 7.0 and after --- +### Table of Contents + +- [Bid Params](#trustx-bid-params) +- [Bidder Config](#trustx-bidder-config) +- [First Party Data](#trustx-first-party) + + ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|----------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| -| `uid` | required | Represents the TrustX bidder system Ad Slot ID associated with the respective div id from the site page. | `42` | `integer` | -| `priceType` | optional (pbjs only) | Can take the values `gross` or `net`, default value is `net`. Net represents the header bid price with the TrustX header bidder margin already extracted. Gross price does contain the TrustX bidder margin within. | `'gross'` | `string` | -| `keywords` | optional (pbjs only) | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | -| `useNewFormat` | optional (pbjs only) | Indicates to use the new ad request format. | `true` | `boolean` | +| Name | Scope | Description | Example | Type | +|----------------|-----------|----------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| +| `uid` | required | Represents the TrustX bidder system Ad Slot ID associated with the respective div id from the site page. | `42` | `integer` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | +| `bidFloor` | optional | Floor of the impression opportunity. If present in the request overrides XML info. | `0.8` | `float` | + +Parameter `keywords` must have following format: +``` +{ + "site":{ + "publisher1":[ + { + "name":"SomeKeywordsBlockName", + "segment1Name":[ + "segment2Value" + ], + "segment2Name":[ + "segment2Value1", + "segment2Value2", + ... + ], + ... + } + ], + ... + } +} +``` + + + +### Bidder Config + +You can allow writing in localStorage `pbjs.setBidderConfig` for the bidder `trustx` +``` +pbjs.setBidderConfig({ + bidders: ["trustx"], + config: { + localStorageWriteAllowed: true + } +}) +``` +If it will be "true" this allow TheMediaGrid Bid Adapter to write userId in first party localStorage + +If you want to make alias on TrustX Bid Adapter, you must set `forceBidderName` in bidderConfig as `"trustx"`. +``` +pbjs.setBidderConfig({ + bidders: ["aliasName"], + config: { + forceBidderName: 'trustx' + } +}) +``` + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.ext.device`: Non standard arbitrary user device +- `ortb2.user.keywords`: Standard IAB OpenRTB 2.5 user.keywords field. It will be included in ext.keywords.user.ortb2 +- `ortb2.site.keywords`: Standard IAB OpenRTB 2.5 site.keywords field. It will be included in ext.keywords.site.ortb2 +- `ortb2.site.cat[]`: Standard IAB OpenRTB 2.5 site.cat field. It will be sent as part of site.cat array +- `ortb2.site.pagecat[]`: Standard IAB OpenRTB 2.5 site.pagecat field. It will be sent as part of site.cat array +- `ortb2.site.content.genre`: Standard IAB OpenRTB 2.5 site.content.genre field + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` +- `ortb2.imp[].instl` diff --git a/dev-docs/bidders/trustxstandalone.md b/dev-docs/bidders/trustxstandalone.md new file mode 100644 index 0000000000..1eca1bd86b --- /dev/null +++ b/dev-docs/bidders/trustxstandalone.md @@ -0,0 +1,48 @@ +--- +layout: bidder +title: TrustX (standalone) +description: Prebid TrustX Bidder Adaptor +pbjs: true +pbs: true +biddercode: trustx +media_types: banner, video +multiformat_supported: will-bid-on-any +gdpr_supported: true +usp_supported: true +fpd_supported: true +pbjs_version_notes: 6.x and before +--- + +### Table of Contents + +- [Bid Params](#trustx-bid-params) +- [First Party Data](#trustx-first-party) + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------| +| `uid` | required | Represents the TrustX bidder system Ad Slot ID associated with the respective div id from the site page. | `42` | `integer` | +| `priceType` | optional (pbjs only) | Can take the values `gross` or `net`, default value is `net`. Net represents the header bid price with the TrustX header bidder margin already extracted. Gross price does contain the TrustX bidder margin within. | `'gross'` | `string` | +| `keywords` | optional (pbjs only) | A set of key-value pairs applied to all ad slots on the page. Values can be empty. | `keywords: { topic: ['stress', 'fear'] }` | `object` | +| `useNewFormat` | optional (pbjs only) | Indicates to use the new ad request format. | `true` | `boolean` | + + + +### First Party Data + +Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html). + +Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields: + +- `ortb2.user.data[]`: Standard IAB segment taxonomy user data +- `ortb2.user.keywords`: Standard IAB OpenRTB 2.5 user.keywords field. It will be included in ext.keywords.user.ortb2 +- `ortb2.site.keywords`: Standard IAB OpenRTB 2.5 site.keywords field. It will be included in ext.keywords.site.ortb2 + +AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields: + +- `ortb2.imp[].ext.data.*` +- `ortb2.imp[].instl` diff --git a/dev-docs/bidders/ttd.md b/dev-docs/bidders/ttd.md new file mode 100644 index 0000000000..3093e85bca --- /dev/null +++ b/dev-docs/bidders/ttd.md @@ -0,0 +1,181 @@ +--- +layout: bidder +title: The Trade Desk +description: The Trade Desk Prebid Bidder Adapter +biddercode: ttd +gdpr_supported: true +gvl_id: 21 +usp_supported: true +coppa_supported: true +schain_supported: true +dchain_supported: false +userIds: unifiedId, uid2 +media_types: banner, video +floors_supported: true +fpd_supported: true +pbjs: true +pbs: false +prebid_member: true +--- + +### Disclosure: + +This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. + +{: .alert.alert-danger :} +Note: The Trade Desk Header Bidding adapter requires setup and approval before beginning. Please reach out to OpenPathPublishers@thetradedesk.com for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +Name | Scope | Description | Example | Type +--- | --- | --- | --- | ---- +`supplySourceId` | required | The TTD-provided supply source name. | `'supplier'` | `String` +`publisherId` | required | The publisher ID. This should be the same as the seller_id in the sellers.json for the site being trafficked. | `'1427ab10f2e448057ed3b422'` | `String` +`siteId` | required | The publisher defined site ID. This should be unique per site. Can be any string that is under 50 characters. | `'site_123'` | `String` +`placementId` | required | The publisher defined placement ID. Can be any string that is under 128 characters. | `'side-Bar_1/123'` | `String` +`banner` | optional | Display banner targeting parameters. See the banner section below. | `{}` | `object` + +### Banner Object + +The following banner parameters are supported: + +{: .table .table-bordered .table-striped } +Name | Scope | Description | Example | Type +--- | --- | --- | --- | ---- +`expdir` | optional | Directions in which the banner may expand. See "Expandable Direction" in the [OpenRTB 2.5 docs](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) for possible values. | `[1, 3]` | `Array[integer]` + +#### `mediaTypes.banner` Parameters + +The TTD adapter for banner uses certain parameters in the AdUnit's +[mediaTypes.banner](https://docs.prebid.org/dev-docs/adunit-reference.html#adUnit.mediaTypes.banner) definition. Specifically, `sizes` is required for banner ad units. `pos` is recommended. + +Here's a banner ad unit example: + +```javascript +var bannerAdUnit = { + code: 'myBannerAdUnit', + mediaTypes: { + banner: { + sizes: [400, 600], + pos: 1 + } + }, + bids: [ + { + bidder: 'ttd', + params: { + supplySourceId: 'supplier' + publisherId: '1427ab10f2e448057ed3b422', + siteId: 'site-123', + placementId: 'sidebar_1', + banner: { + expdir: [1, 3] + } + } + } + ] +} +``` + +### Video + +#### `mediaTypes.video` Parameters + +The TTD adapter for video requires certain parameters in the AdUnit's +[mediaTypes.video](https://docs.prebid.org/dev-docs/adunit-reference.html#adUnit.mediaTypes.video) definition. Specifically, `maxduration`, `api`, `mimes`, `placement`, and `protocols` are all required for video ad units. `playerSize`, `startdelay`, `playbackmethod`, and `pos` are recommended. `minduration`, `minbitrate`, `maxbitrate`, `skip`, `skipmin`, and `skipafter` are optional. + +Note: TTD does not currently support `adpod` video contexts. + +Here's a video ad unit example: + +```javascript +var videoAdUnit = { + code: 'myVideoAdUnit', + mediaTypes: { + video: { + minduration: 1, + maxduration: 60, + playerSize: [640, 480], + api: [1, 3], + mimes: ['video/mp4'], + placement: 3, + protocols: [2, 3, 5, 6], + startdelay: -1, + playbackmethod: [1], + pos: 1, + minbitrate: 0, + maxbitrate: 5000, + skip: 1, + skipmin: 5, + skipafter: 10 + } + }, + bids: [ + { + bidder: "ttd", + params: { + supplySourceId: 'supplier', + publisherId: '1427ab10f2e448057ed3b422', + siteId: 'site-123', + placementId: 'video1' + } + } + ] +} +``` + +--- +Lists of `api`, `playbackmethod`, `protocols`, `pos`, and `expdir` potential values are in the [OpenRTB 2.5 docs](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), copied here for convenience: + +`api` + +- `1` : VPAID 1.0 +- `2` : VPAID 2.0 +- `3` : MRAID-1 +- `4` : ORMMA +- `5` : MRAID-2 +- `6` : MRAID-3 +- `7` : OMID-1 + +`playbackmethod` + +- `1` : Initiates on Page Load with Sound On +- `2` : Initiates on Page Load with Sound Off by Default +- `3` : Initiates on Click with Sound On +- `4` : Initiates on Mouse-Over with Sound On +- `5` : Initiates on Entering Viewport with Sound On +- `6` : Initiates on Entering Viewport with Sound Off by Default + +`protocols` + +- `1` : VAST 1.0 +- `2` : VAST 2.0 +- `3` : VAST 3.0 +- `4` : VAST 1.0 Wrapper +- `5` : VAST 2.0 Wrapper +- `6` : VAST 3.0 Wrapper +- `7` : VAST 4.0 +- `8` : VAST 4.0 Wrapper +- `9` : DAAST 1.0 +- `10` : DAAST 1.0 Wrapper +- `11` : VAST 4.1 +- `12` : VAST 4.1 Wrapper + +`pos` + +- `0` : Unknown +- `1` : Above the Fold +- `3` : Below the Fold +- `4` : Header +- `5` : Footer +- `6` : Sidebar +- `7` : Full Screen + +`expdir` + +- `1` : Left +- `2` : Right +- `3` : Up +- `4` : Down +- `5` : Full Screen diff --git a/dev-docs/bidders/turktelekom.md b/dev-docs/bidders/turktelekom.md index a6b2395bca..d845c7e845 100644 --- a/dev-docs/bidders/turktelekom.md +++ b/dev-docs/bidders/turktelekom.md @@ -1,19 +1,29 @@ --- layout: bidder title: Türk Telekom -description: Prebid Türk Telekom Bidder Adaptor +description: Türk Telekom Bidder Adaptor pbjs: true +pbs: true biddercode: turktelekom -media_types: banner, video +aliasCode : adkernel +media_types: banner, native, video gdpr_supported: true -pbjs_version_notes: not in 5.x +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +pbjs_version_notes: v5.18+ +safeframes_ok: true --- +### Note: + +The Türk Telekom bidding adapter requires setup and approval before implementation. Please reach out to for more details. ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------| -| `uid` | required | Represents the Türk Telekom bidder system Ad Slot ID associated with the respective div id from the site page. | `42` | `integer` | -| `priceType` | optional | Can take the values `gross` or `net`, default value is `net`. Net represents the header bid price with the Türk Telekom header bidder margin already extracted. Gross price does contain the Türk Telekom bidder margin within. | `'gross'` | `string` | +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.programattik.com'` | `string` | +| `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/ucfunnel.md b/dev-docs/bidders/ucfunnel.md index 5d102e23c1..75c7140a76 100644 --- a/dev-docs/bidders/ucfunnel.md +++ b/dev-docs/bidders/ucfunnel.md @@ -15,7 +15,9 @@ gvl_id: 607 pbs_app_supported: true --- -### Bid params +### Prebid JS + +#### Bid params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | @@ -46,3 +48,14 @@ Sizes set in the `adUnit` object will also apply to the ucfunnel bid requests. - [Banner Ads](https://cdn.aralego.net/ucfad/test/ucfunnel/compliance/pbjs_banner.html) - [Instream Video Ads](https://cdn.aralego.net/ucfad/test/ucfunnel/compliance/pbjs_video.html) - [Native Ads](https://cdn.aralego.net/ucfad/test/ucfunnel/compliance/pbjs_native.html) + + +### Prebid server + +#### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|--------|----------|-------------------------------------------------|---------|----------| +| `adunitid` | required | ID for ad unit | | `string` | +| `partnerid` | required | ID for partner | | `string` | diff --git a/dev-docs/bidders/undertone.md b/dev-docs/bidders/undertone.md index 94d743d670..3c079518d2 100644 --- a/dev-docs/bidders/undertone.md +++ b/dev-docs/bidders/undertone.md @@ -6,6 +6,7 @@ biddercode: undertone media_types: display, video gdpr_supported: true usp_supported: true +schain_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId pbjs: true --- diff --git a/dev-docs/bidders/unibots.md b/dev-docs/bidders/unibots.md new file mode 100644 index 0000000000..d8b859e629 --- /dev/null +++ b/dev-docs/bidders/unibots.md @@ -0,0 +1,27 @@ +--- +layout: bidder +title: Unibots +description: Unibots Bidder Adaptor +pbjs: true +pbs: true +biddercode: unibots +aliasCode : adkernel +media_types: banner, native, video +gdpr_supported: true +usp_supported: true +coppa_supported: true +pbs_app_supported: true +schain_supported: true +--- + +### Note: + +The Unibots bidding adapter requires setup and approval before implementation. Please reach out to for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.unibots.in'` | `string` | +| `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/unicorn.md b/dev-docs/bidders/unicorn.md index 7b2e69f7d0..21a645f404 100644 --- a/dev-docs/bidders/unicorn.md +++ b/dev-docs/bidders/unicorn.md @@ -7,7 +7,6 @@ pbs: true pbs_app_supported: true media_types: banner biddercode: unicorn -pbjs_version_notes: not in 5.x --- ### bid params @@ -17,7 +16,6 @@ pbjs_version_notes: not in 5.x |---------------|----------|-------------------------------------------|------------|-----------| | `placementId` | optional | Your placement ID | `'rectangle-ad-1'` | `string` | | `accountId` | required | Account ID for charge request (provided by UNICORN) | `12345` | `integer` | -| `bidfloorCpm` | optional for Prebid.js | Floor CPM (JPY); defaults to 0. | `0.2` | `float` | | `publisherId` | optional | Account specific publisher id. | `67890` | `integer` | | `mediaId` | required for Prebid Server, optional for Prebid.js | Publisher specific media id. | `'example'` | `string` | | `bcat` | optional for Prebid.js | Blocked IAB categories | `['IAB-1', 'IAB-2']` | `[string]` | diff --git a/dev-docs/bidders/unruly.md b/dev-docs/bidders/unruly.md index 539093e5b1..89bdd181cd 100644 --- a/dev-docs/bidders/unruly.md +++ b/dev-docs/bidders/unruly.md @@ -3,17 +3,26 @@ layout: bidder title: Unruly description: Prebid Unruly Bidder Adaptor biddercode: unruly -media_types: native, video gdpr_supported: true +usp_supported: true +coppa_supported: false +schain_supported: true +floors_supported: true +media_types: banner, video +userIds: all +prebid_member: false +safeframes_ok: check with bidder +deals_supported: check with bidder pbjs: true pbs: true -gvl_id: 162 +pbs_app_supported: true +gvl_id: 36 --- ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-----------------|----------|---------------------------------------------------------------------------------------------|------------------------------------------|-----------| -| `siteId` | required | The site ID from Unruly. This will be provided to you by your Unruly account manager | `123456` | `integer` | -| `targetingUUID` | required | The targeting UUID from Unruly. This will be provided to you by your Unruly account manager | `'766220b5-3d02-46c5-aa8b-2bc60c6f7418'` | `string` | +| Name | Scope | Description | Example | Type | +|--------------------|----------------|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|-----------| +| `siteId` | required | The site ID from Unruly. This will be provided to you by your Unruly account manager. | `123456` | `integer` | +| `featureOverrides` | optional | This param is a generic object for configuring Unruly outstream demand. To run UNmissable, set ‘canRunUnmissable’ to true. | `"featureOverrides": {"canRunUnmissable": true}` | `object` | diff --git a/dev-docs/bidders/uol.md b/dev-docs/bidders/uol.md index 5caa90beb2..f86bbc7881 100644 --- a/dev-docs/bidders/uol.md +++ b/dev-docs/bidders/uol.md @@ -6,7 +6,8 @@ pbjs: true biddercode: uol gdpr_supported: false media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/valueimpression.md b/dev-docs/bidders/valueimpression.md index 75e9352402..4b47750e85 100644 --- a/dev-docs/bidders/valueimpression.md +++ b/dev-docs/bidders/valueimpression.md @@ -10,9 +10,10 @@ gdpr_supported: true schain_supported: true usp_supported: true userIds: all -getFloor: true +floors_supported: true pbs: true +pbs_app_supported: true --- # Description -Valueimpression is an aliased bidder of Apacdex bid adapter. Please refer to [Apacdex documentation](https://docs.prebid.org/dev-docs/bidders/apacdex) for bid parameters and implementation guide. \ No newline at end of file +Valueimpression is an aliased bidder of Apacdex bid adapter. Please refer to [Apacdex documentation](https://docs.prebid.org/dev-docs/bidders/apacdex) for bid parameters and implementation guide. diff --git a/dev-docs/bidders/vdoai.md b/dev-docs/bidders/vdoai.md index 287daccbc4..1ff9f59566 100644 --- a/dev-docs/bidders/vdoai.md +++ b/dev-docs/bidders/vdoai.md @@ -5,7 +5,6 @@ description: Prebid vdo.ai Bidder Adaptor pbjs: true biddercode: vdoai media_types: banner, video -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/ventes.md b/dev-docs/bidders/ventes.md new file mode 100644 index 0000000000..ce1e7c575e --- /dev/null +++ b/dev-docs/bidders/ventes.md @@ -0,0 +1,94 @@ +--- +layout: bidder +title: ventes +description: Prebid ventes Bidder Adapter +pbjs: true +biddercode: ventes +gdpr_supported: false +usp_supported: false +media_types: banner +coppa_supported: false +schain_supported: false +dchain_supported: false +prebid_member: false +--- + +### BidParams +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-----------------|----------|-----------------------------------------------------------|----------------------------------------------|---------------| +| `placementId` | required | Placement ID from Ventes Avenues | `'VA-062-0013-0183'` | `string` | +| `publisherId` | required | Publisher ID from Ventes Avenues | `'VA-062'` | `string` | +| `user` | optional | Object that specifies information about an external user. | `user: { age: 25, gender: 0, dnt: true}` | `object` | +| `app` | required | Object containing mobile app parameters. | `app : { id: 'app-id'}` | `object` | +| `device` | required | Object containing device info mandatory for mobile devices| `device : { ifa: 'device-id'}` | `object` | + +#### User Object + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|-------------------------------------------------------------------------------------------|-----------------------|-----------------------| +| `age` | The age of the user. | `35` | `integer` | +| `externalUid` | Specifies a string that corresponds to an external user ID for this user. | `'1234567890abcdefg'` | `string` | +| `segments` | Specifies the segments to which the user belongs. | `[1, 2]` | `Array` | +| `gender` | Specifies the gender of the user. Allowed values: Unknown: `0`; Male: `1`; Female: `2` | `1` | `integer` | +| `dnt` | Do not track flag. Indicates if tracking cookies should be disabled for this auction | `true` | `boolean` | +| `language` | Two-letter ANSI code for this user's language. | `EN` | `string` | + + +### Ad Unit Setup for Banner through mobile devices +```javascript +var adUnits = [ +{ + code: 'test-hb-ad-11111-1', + mediaTypes: { + banner: { + sizes: [ + [300, 250] + ] + } + }, + bids: [{ + bidder: 'ventes', + params: { + placementId: 'VA-062-0013-0183', + publisherId: '5cebea3c9eea646c7b623d5e', + IABCategories: "['IAB1', 'IAB5']", + device:{ + ip: '123.145.167.189', + ifa:"AEBE52E7-03EE-455A-B3C4-E57283966239", + }, + app: { + id: "agltb3B1Yi1pbmNyDAsSA0FwcBiJkfIUDA", + name: "Yahoo Weather", + bundle: 'com.kiloo.subwaysurf', + storeurl: 'https://play.google.com/store/apps/details?id=com.kiloo.subwaysurf&hl=en', + domain: 'somoaudience.com', + } + } + }] + } +] +``` + +### Ad Unit Setup for Banner through Websites +```javascript +var adUnits = [ +{ + code: 'test-hb-ad-11111-1', + mediaTypes: { + banner: { + sizes: [ + [300, 250] + ] + } + }, + bids: [{ + bidder: 'ventes', + params: { + placementId: 'VA-002-0007-0799', + publisherId: '5cebea3c9eea646c7b623d5e', + } + }] + } +] diff --git a/dev-docs/bidders/vertoz.md b/dev-docs/bidders/vertoz.md deleted file mode 100644 index 09023bc7cc..0000000000 --- a/dev-docs/bidders/vertoz.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: bidder -title: Vertoz -description: Prebid Vertoz Bidder Adaptor -pbjs: true -biddercode: vertoz ---- - -### Note: - -The Vertoz adapter currently doesn't support multiple sizes per ad placement and will favour the first one if multiple sizes exists. - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------------|----------|---------------------|---------------|----------| -| placementId | required | vertoz placement id | `'VH-HB-123'` | `string` | -| cpmFloor | optional | cpm floor price | `0.1` | `float` | diff --git a/dev-docs/bidders/vi.md b/dev-docs/bidders/vi.md index 20f6ff345c..6720490630 100644 --- a/dev-docs/bidders/vi.md +++ b/dev-docs/bidders/vi.md @@ -4,7 +4,8 @@ title: vi description: vi bid adapter pbjs: true biddercode: vi -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### bid params diff --git a/dev-docs/bidders/vibrantmedia.md b/dev-docs/bidders/vibrantmedia.md new file mode 100644 index 0000000000..437583bcdb --- /dev/null +++ b/dev-docs/bidders/vibrantmedia.md @@ -0,0 +1,103 @@ +--- +layout: bidder +title: Vibrant Media +description: Vibrant Media Prebid Bidder Adapter +biddercode: vibrantmedia +gdpr_supported: true +gvl_id: 7 +usp_supported: true +media_types: banner, video, native +safeframes_ok: false +pbjs: true +pbjs_version_notes: 6.4.0 and later +--- + +### Preliminaries + +The Vibrant Media Adapter requires set-up before being enabled. Please contact us at intellitxtsupport@vibrantmedia.com. + +Note: For video, we support outstream only. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|----------------------|---------------|----------| +| placementId | required | Placement id from Vibrant Media | `12345` | integer | + +#### Banner example + +```javascript +var adUnits = [{ + code: 'test-banner', + mediaTypes: { + banner: { + sizes: [[300, 250], [300, 600]] + } + }, + bids: [{ + bidder: 'vibrantmedia', + params: { + placementId: 12345 + } + }] +}]; +``` + +#### Video example + +```javascript +var adUnits = [{ + code: 'test-video-outstream', + sizes: [[300, 250]], + mediaTypes: { + video: { + playerSize: [[300, 250]], + context: 'outstream', + minduration: 1, // Minimum ad duration, in seconds + maxduration: 60, // Maximum ad duration, in seconds + skip: 0, // 1 - true, 0 - false + skipafter: 5, // Number of seconds before the video can be skipped + playbackmethod: [2], // Auto-play without sound + protocols: [1, 2, 3] // VAST 1.0, 2.0 and 3.0 + } + }, + bids: [{ + bidder: 'vibrantmedia', + params: { + placementId: 67890 + } + }] +}]; +``` + +#### Native example + +```javascript +var adUnits = [{ + code: 'test-native', + mediaTypes: { + native: { + image: { + required: true, + sizes: [300, 250] + }, + title: { + required: true + }, + sponsoredBy: { + required: true + }, + clickUrl: { + required: true + }, + } + }, + bids: [{ + bidder: 'vibrantmedia', + params: { + placementId: 13579 + } + }] +}]; +``` diff --git a/dev-docs/bidders/vidazoo.md b/dev-docs/bidders/vidazoo.md index c1540f6432..5baf2a5a15 100644 --- a/dev-docs/bidders/vidazoo.md +++ b/dev-docs/bidders/vidazoo.md @@ -7,7 +7,6 @@ userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrable gdpr_supported: true usp_supported: true pbjs: true -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/vidcrunch.md b/dev-docs/bidders/vidcrunch.md new file mode 100644 index 0000000000..41a592a164 --- /dev/null +++ b/dev-docs/bidders/vidcrunch.md @@ -0,0 +1,45 @@ +--- +layout: bidder +title: VidCrunch +description: Prebid VidCrunch Bidder Adapter +pbjs: true +biddercode: vidcrunch +aliasCode: aniview +media_types: banner, video +gdpr_supported: true +usp_supported: true +schain_supported: true +safeframes_ok: true +--- + +### Note: +For more information about [VidCrunch](https://vidcrunch.com/), please contact info@vidcrunch.com. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `AV_PUBLISHERID` | required | Publisher/Netid | `'55b88d4a181f465b3e8b4567'` | `string` | +| `AV_CHANNELID` | required | Channel id | `'5a5f17a728a06102d14c2718'` | `string` | + +### Test Parameters +``` +videoAdUnit = [ +{ + code: 'video1', + mediaTypes: { + video: { + playerSize: [[640, 480]], + context: 'outstream' + }, + }, + bids: [{ + bidder: 'vidcrunch', + params: { + AV_PUBLISHERID: '55b78633181f4603178b4568', + AV_CHANNELID: '5d19dfca4b6236688c0a2fc4' + } + }] +}]; +``` diff --git a/dev-docs/bidders/videobyte.md b/dev-docs/bidders/videobyte.md new file mode 100644 index 0000000000..c0c5710981 --- /dev/null +++ b/dev-docs/bidders/videobyte.md @@ -0,0 +1,32 @@ +--- +layout: bidder +title: VideoByte +description: Prebid VideoByte Bidder Adaptor +pbjs: true +pbs: true +biddercode: videobyte +media_types: display, video +gdpr_supported: true +usp_supported: true +schain_supported: true +--- + +### Note: + +The VideoByte Prebid.js client adapter only supports video ads while our Prebid Server adapter supports both display and video. + +See [Videobyte Prebid Client Documentation](https://videobyte.readme.io/reference/vbx-integration-prebid-client) +for more details about Prebid Client integration. + +See [Videobyte Prebid Server Documentation](https://videobyte.readme.io/reference/vbx-integration-prebid-server) +for more details about Prebid Server integration. + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------|----------|--------------|----------|----------| +| `pubId` | required | Publisher ID | `'vb12345'` | `string` | +| `placementId` | optional | Placement ID | `'1234567'` | `string` | +| `nid` | optional | Network ID | `'1234'` | `string` | diff --git a/dev-docs/bidders/videofy.md b/dev-docs/bidders/videofy.md index b3f604c325..b86bd59ee7 100644 --- a/dev-docs/bidders/videofy.md +++ b/dev-docs/bidders/videofy.md @@ -7,7 +7,8 @@ biddercode: videofy media_types: video gdpr_supported: true usp_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/videoheroes.md b/dev-docs/bidders/videoheroes.md new file mode 100644 index 0000000000..a593804c6d --- /dev/null +++ b/dev-docs/bidders/videoheroes.md @@ -0,0 +1,26 @@ +--- +layout: bidder +title: VideoHeroes +description: Prebid VideoHeroes Bidder Adapter +biddercode: videoheroes +gdpr_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +media_types: banner, video, native +safeframes_ok: true +bidder_supports_deals: true +pbjs: true +pbs: false +--- + +### Note: + +The VideoHeroes Header Bidding adapter requires setup and approval from the VideoHeroes team. Please reach out to your account manager or support@videoheroes.tv for more information + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------------------|-------------------------------------|-----------| +| `placementId` | required | VideoHeroes platform placement id | `1a8d9c22db19906cb8a5fd4518d05f62` | `string` | diff --git a/dev-docs/bidders/videonow.md b/dev-docs/bidders/videonow.md index 7a0b19a480..f7fd1a4f6c 100644 --- a/dev-docs/bidders/videonow.md +++ b/dev-docs/bidders/videonow.md @@ -5,7 +5,8 @@ description: Prebid Videonow Bidder Adaptor biddercode: videonow pbjs: true media_types: banner -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/videoreach.md b/dev-docs/bidders/videoreach.md index 621a5c9b08..a38870bea6 100644 --- a/dev-docs/bidders/videoreach.md +++ b/dev-docs/bidders/videoreach.md @@ -6,7 +6,6 @@ pbjs: true biddercode: videoreach media_types: banner, video gdpr_supported: true -pbjs_version_notes: not in 5.x --- diff --git a/dev-docs/bidders/vidoomy.md b/dev-docs/bidders/vidoomy.md new file mode 100644 index 0000000000..bb8b8f2dd2 --- /dev/null +++ b/dev-docs/bidders/vidoomy.md @@ -0,0 +1,32 @@ +--- +layout: bidder +title: Vidoomy +description: Prebid Vidoomy Bidder Adaptor +pbjs: true +biddercode: vidoomy +media_types: banner, video +gdpr_supported: true +gvl_id: 380 +usp_supported: true +coppa_supported: true +pbs: true +--- + +### Note: +[Vidoomy](https://vidoomy.com/), for more info please contact support@vidoomy.com + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `id` | required | id | `123123` | `string` | +| `pid` | required | pid | `'123123'` | `string` | + + +### Bid Params (Prebid Server) + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------|------------------------------|----------| +| `zoneId` | required | Zone Id | "123123" | `string` | diff --git a/dev-docs/bidders/viewdeos.md b/dev-docs/bidders/viewdeos.md new file mode 100644 index 0000000000..aacb4a2a6d --- /dev/null +++ b/dev-docs/bidders/viewdeos.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: Viewdeos Server +description: Prebid Server ViewDeos Adapter +pbjs: false +pbs: true +biddercode: viewdeos +media_types: banner,video +gdpr_supported: true +gvl_id: 924 +--- + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------|----------|---------------------------------|----------|-----------| +| `aid` | required | The source ID from member zone | `350975` | `integer` | + +### Test Parameters +``` + var adUnits = [ + // Banner adUnit + { + code: 'div-test-div', + mediaTypes: { + banner: { + sizes:[[300, 250]] + } + }, + bids: [{ + bidder: 'viewdeos', + params: { + aid: 672854 + } + }] + } + ]; +``` diff --git a/dev-docs/bidders/viewdeosDX.md b/dev-docs/bidders/viewdeosDX.md index 6aab7f7107..3c8ee83b72 100644 --- a/dev-docs/bidders/viewdeosDX.md +++ b/dev-docs/bidders/viewdeosDX.md @@ -1,15 +1,17 @@ --- layout: bidder -title: Viewdeos -description: Prebid ViewDeos Bidder Adaptor +title: ViewdeosDX Client +description: Prebid.js ViewDeos Bidder Adapter pbjs: true -pbs: true +pbs: false biddercode: viewdeosDX media_types: banner,video gdpr_supported: true gvl_id: 924 --- +Note that for Prebid Server, use "viewdeos" bidder code. + ### Bid params {: .table .table-bordered .table-striped } diff --git a/dev-docs/bidders/visx.md b/dev-docs/bidders/visx.md index 9fdb7cb190..53a833abf3 100644 --- a/dev-docs/bidders/visx.md +++ b/dev-docs/bidders/visx.md @@ -9,7 +9,7 @@ gvl_id: 154 schain_supported: true userIds: id5Id, unifiedId media_types: banner, video -bidder_supports_deals: true +deals_supported: true pbjs: true pbs: true --- @@ -72,7 +72,7 @@ Best practices: ### Configuration: Video -The YOC VIS.X adapter responds with VAST XML (in the 'vastXml' field) and expects client-side caching enabled. +The YOC VIS.X Prebid.js adapter responds with VAST XML (in the `vastXml` field) and expects client-side caching enabled. To enable it, use the following settings: ```javascript pbjs.setConfig({ @@ -103,12 +103,7 @@ pbjs.setConfig({ |-------|----------|-------------------------------------|------------|----------| | `context` | required | The video context, only 'instream' is allowed. | `'instream'` | `string` | | `playerSize` | required | The size (width, height) of the video player on the page, in pixels. | `[640, 480]` | `integer array` | -| `mimes` | required | Content MIME types supported. | `['video/mp4', 'video/x-ms-wmv']` | `string array` | -| `protocols` | required | Array of supported video protocols. Refer to List 5.8 of IAB OpenRTB 2.5 (e.g., VAST 3.0 Wrapper). | `[2,3,5,6]` | `integer array` | -| `api` | optional | List of supported API frameworks for this impression. Refer to List 5.6 of IAB OpenRTB 2.5 (e.g., VPAID 2.0). If an API is not explicitly listed, it is assumed not to be supported. | `[2]` | `integer array` | -| `minduration` | optional | Minimum video ad duration in seconds. | `5` | `integer` | -| `maxduration` | optional | Maximum video ad duration in seconds. | `30` | `integer` | -| `skip` | optional | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. | `1` | `integer` | +| `mimes` | optional | Content MIME types supported. | `['video/mp4', 'video/x-ms-wmv']` | `string array` | ### Example of Banner Ad unit @@ -117,13 +112,13 @@ var bannerAdUnit = { code: 'bannerAdUnit1', mediaTypes: { banner: { - sizes: [[320, 480], [728, 90]] // required + sizes: [[320, 480], [728, 90]] // required } }, bids: [{ bidder: 'visx', params: { - uid: '903536' // required + uid: '903536' // required } }] }; @@ -136,20 +131,15 @@ var videoAdUnit = { code: 'videoAdUnit1', mediaTypes: { video: { - context: 'instream', // required - playerSize: [400, 300], // required - mimes: ['video/mp4', 'video/x-ms-wmv'], // required - protocols: [2, 3, 5, 6], // required - api: [2], // optional - minduration: 5, // optional - maxduration: 30, // optional - skip: 1 // optional + context: 'instream', // required + playerSize: [400, 300], // required + mimes: ['video/mp4'] // optional, required by Prebid Server } }, bids: [{ bidder: 'visx', params: { - uid: '921068' // required + uid: '921068' // required } }] }; diff --git a/dev-docs/bidders/vlyby.md b/dev-docs/bidders/vlyby.md new file mode 100644 index 0000000000..bf0d5184a7 --- /dev/null +++ b/dev-docs/bidders/vlyby.md @@ -0,0 +1,24 @@ +--- +layout: bidder +title: VLYBY +description: Prebid VLYBY Bidder Adapter +biddercode: vlyby +media_types: banner, video +schain_supported: false +prebid_member: false +pbjs: true +--- + +### Note: + +The VLYBY Header Bidder Adapter needs a Contract with VLYBY Digital GmbH, Munich. Please contact prebid@vlyby.com for additional information. + + + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|---------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `publisherId`| required | VLYBY PublisherId | `'12345'` | `string` | +| `placement` | optional | Placement Id | `'12345'` | `string` | diff --git a/dev-docs/bidders/vmg.md b/dev-docs/bidders/vmg.md index 959ff01ab0..b15ddbdc8c 100644 --- a/dev-docs/bidders/vmg.md +++ b/dev-docs/bidders/vmg.md @@ -4,7 +4,8 @@ title: VMG description: Connects Google Ad Manager to the VMG Predict engine. pbjs: true biddercode: vmg -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/vrtcal.md b/dev-docs/bidders/vrtcal.md index c2b59324d0..b1f33622d2 100644 --- a/dev-docs/bidders/vrtcal.md +++ b/dev-docs/bidders/vrtcal.md @@ -4,11 +4,13 @@ title: VRTCAL Markets, Inc. description: VRTCAL Markets, Inc. Bid Adapter pbjs: true pbs: true -media_ytpes: banner -gdpr_supported: false +media_types: banner, video biddercode: vrtcal +gdpr_supported: true +usp_supported: true +schain_supported: true +coppa_supported: true gvl_id: 706 -pbjs_version_notes: not in 5.x --- ### Bid Params diff --git a/dev-docs/bidders/vuble.md b/dev-docs/bidders/vuble.md index 6c2308a5e8..97f05bf68a 100644 --- a/dev-docs/bidders/vuble.md +++ b/dev-docs/bidders/vuble.md @@ -6,7 +6,8 @@ pbjs: true biddercode: vuble media_types: video gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/weborama.md b/dev-docs/bidders/weborama.md deleted file mode 100644 index 0fa88f3951..0000000000 --- a/dev-docs/bidders/weborama.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: bidder -title: Weborama -description: Prebid Weborama Bidder Adaptor -pbjs: true -biddercode: weborama ---- - -### Bid Params - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | -| :----------- | :--------- | :------------ | :----------------- | -| `placementId` | required | Placement Id will be generated on Weborama Platform. | 0 | -| `traffic` | optional | Type traffic | 'banner' | diff --git a/dev-docs/bidders/welect.md b/dev-docs/bidders/welect.md index 3a099c2dc3..f1805b7f71 100644 --- a/dev-docs/bidders/welect.md +++ b/dev-docs/bidders/welect.md @@ -6,7 +6,8 @@ biddercode: welect media_types: no-display, video gvlid: 282 pbjs: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Note: diff --git a/dev-docs/bidders/windtalker.md b/dev-docs/bidders/windtalker.md index 4fae0d89e8..3988eb9a4d 100644 --- a/dev-docs/bidders/windtalker.md +++ b/dev-docs/bidders/windtalker.md @@ -6,7 +6,8 @@ pbjs: true biddercode: windtalker media_types: native, video gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Disclosure diff --git a/dev-docs/bidders/winr.md b/dev-docs/bidders/winr.md new file mode 100644 index 0000000000..09a514acd2 --- /dev/null +++ b/dev-docs/bidders/winr.md @@ -0,0 +1,29 @@ +--- +layout: bidder +title: WINR +description: Prebid WINR Bidder Adaptor +biddercode: winr +media_types: banner +prebid_member: false +userIds: criteo, unifiedId, netId, identityLink, flocId, uid2 +schain_supported: true +coppa_supported: true +usp_supported: true +floors_supported: true +pbjs: true +safeframes_ok: false +--- + +### Note: +The WINR adapter requires setup and approval from the WINR team, even for partners that already work with us. Please reach out to our team at tech@winr.com.au + +*`domParent` and `child` position settings are usually determined and remotely controlled for each publisher site by the WINR team. If you would prefer to have control over these settings, please get in touch. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------------------------------------------------------------------------|--------------|-----------| +| `placementId` | required | Placement ID can be a `string` or `integer`, however `integer` is preferred. | `21764100` | `integer` | +| `domParent`* | optional | The DOM element where the ad unit will load into. The value is passed as a parameter to the JavaScript HTML DOM querySelector() method | `.blog_post` | `string` | +| `child`* | optional | The number of child nodes of `domParent` preceding the ad unit. | `4` | `integer` | diff --git a/dev-docs/bidders/wipes.md b/dev-docs/bidders/wipes.md index 999f0fe4e5..25e1ed80cc 100644 --- a/dev-docs/bidders/wipes.md +++ b/dev-docs/bidders/wipes.md @@ -5,7 +5,6 @@ description: Prebid WIPES Bidder Adaptor pbjs: true biddercode: wipes media_types: video -pbjs_version_notes: not in 5.x --- ### Note: diff --git a/dev-docs/bidders/xhb.md b/dev-docs/bidders/xhb.md index ebd6e189e4..5e593c0c13 100644 --- a/dev-docs/bidders/xhb.md +++ b/dev-docs/bidders/xhb.md @@ -6,7 +6,8 @@ biddercode: xhb pbjs: true media_types: video, native gdpr_supported: true -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- ### Bid Params diff --git a/dev-docs/bidders/yahoossp.md b/dev-docs/bidders/yahoossp.md new file mode 100644 index 0000000000..ed30a5661d --- /dev/null +++ b/dev-docs/bidders/yahoossp.md @@ -0,0 +1,64 @@ +--- +layout: bidder +title: Yahoo SSP +description: Yahoo SSP Bid Adapter +pbs: true +pbjs: true +media_types: banner, video +biddercode: yahoossp +prebid_member: true +gdpr_supported: true +usp_supported: true +schain_supported: true +coppa_supported: true +gvl_id: 25 +userIds: All +--- + +### Important Notice (JS vs PBS) +There are differences between our Prebid.js & Prebid-Server Yahoo SSP adapters. +The Prebid-server adapter currently does not support: +1. Integration via the `pubId` method. + +### yahoossp Prebid.js Mandatory Bid Params +The 'yahoossp' bid adapter supports 2 alternate integration types: +1. **dcn & pos** (Site/App & Position explicit targeting) - For legacy "aol", "oneMobile" adapter partners/publishers. +2. **pubId** (Publisher ID) - For New partners/publishers joining Yahoo SSP and legacy "oneVideo" partners/publishers migrating to the Yahoo SSP. +### yahoossp Prebid-Server Mandatory Bid Params +Prebid-server adapter supports one integration method: +* **dcn & pos** (Site/App & Position explicit targeting) - For legacy "aol", "oneMobile" adapter partners/publishers. +#### DCN & POS Integration Parameters (JS & PBS) +For legacy "aol", "oneMobile" adapter partners/publishers. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------|----------|------------------------|---------|----------| +| dcn | Required | Site ID provided by Yahoo SSP | 'site1' | string | +| pos | Required | Placement ID provided by Yahoo SSP | 'placement1' | string | +#### PubId Integration Parameters (JS Only) +For New partners/publishers joining Yahoo SSP +floors_supported: true and legacy "oneVideo" partners/publishers migrating to the Yahoo SSP. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------|----------|------------------------|---------|----------| +| pubId | Required | Your Publisher External ID provided by Yahoo SSP | 'DemoPublisher' | string | +| siteId | Optional | Ability to target a specific Site using an External ID provided by Yahoo SSP | '1234567' | string | +| placementId | Optional | Ability to target a specific Placement using an External ID provided by Yahoo SSP | 'header' | string | + +### Prebid.js Adapter Supported Features +For further setup details & examples please see https://github.com/prebid/Prebid.js/blob/master/modules/yahoosspBidAdapter.md +* Media Types: Banner & Video +* Outstream renderer +* Multi-format adUnits +* Schain module +* Price floors module +* Advertiser domains +* End-2-End self-served testing mode +* Outstream renderer/Player +* User ID Modules - ConnectId and others +* First Party Data (ortb2 & ortb2Imp) +* Custom TTL (time to live) + +Thanks you, +Yahoo SSP \ No newline at end of file diff --git a/dev-docs/bidders/yandex.md b/dev-docs/bidders/yandex.md new file mode 100644 index 0000000000..05dc4c3025 --- /dev/null +++ b/dev-docs/bidders/yandex.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: Yandex +description: Prebid Yandex Bidder Adapter +pbjs: true +biddercode: yandex +media_types: banner +--- + + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-------------------------|-----------|-----------| +| `pageId` | required | Page ID | `123` | `Integer` | +| `impId` | required | Block ID | `1` | `Integer` | + +### Test Parameters + +``` +var adUnits = [{ + code: 'banner-1', + mediaTypes: { + banner: { + sizes: [[240, 400]], + } + }, + bids: [{ + { + bidder: 'yandex', + params: { + pageId: 346580, + impId: 143, + }, + } + }] +}]; +``` diff --git a/dev-docs/bidders/yieldlab.md b/dev-docs/bidders/yieldlab.md index 20c19e400a..32644d6782 100644 --- a/dev-docs/bidders/yieldlab.md +++ b/dev-docs/bidders/yieldlab.md @@ -3,7 +3,7 @@ layout: bidder title: Yieldlab description: Prebid Yieldlab Bidder Adapter biddercode: yieldlab -media_types: video +media_types: video, banner, native gdpr_supported: true schain_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId @@ -24,4 +24,29 @@ pbs: true | `adSize` | optional | Override the default prebid size | `'970x250'` | `string` | | `targeting` | optional | Key-Value Targeting | `{ 'key1': 'value1', 'key2': 'value2' }` | `object` | | `extId` | optional | External Id | `'abc'` | `string` | +| `iabContent` | optional | Object of content information, see [IAB Content Object](#iab_content) for details. It will override the content object passed in [First Party Data](https://docs.prebid.org/features/firstPartyData.html) | `{ 'id': 'foo', 'title': 'bar' }` | `object` | | `customParams` | optional | Custom parameters to append to the query string of the bidding endpoint. | `{ 'param': 'value1', 'param2': 'value2' }` | `object` | + + + +#### IAB Content Object + +Yieldlab supports passing the IAB content object in correspond to the OpenRTB Specifications. +The following attributes are supported, and all of them are optional. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|-----------------------------------------------------------------------------------------------|---------------------------------------------|------------------| +| `id` | optional | Id uniquely identifying the content | `'12345'` | `string` | +| `episode` | optional | Episode number | `'42'` | `string` | +| `title` | optional | Content title | `'some title'` | `string` | +| `series` | optional | Content series | `'some series'` | `string` | +| `season` | optional | Content season | `'s1'` | `string` | +| `artist` | optional | Artist credited with the content | `'John Doe'` | `string` | +| `genre` | optional | Genre that best describes the content | `'some genre'` | `string` | +| `isrc` | optional | International Standard Recording Code conforming to ISO3901 | `'CC-XXX-YY-NNNNN'` | `string` | +| `url` | optional | URL of the content, for buy-side contextualization or review | `'https://yieldlab.com'` | `string` | +| `cat` | optional | Array of IAB content categories that describe the content producer | `['IAB1-1', 'IAB1-2']` | `Array` | +| `context` | optional | Type of content - 1: video, 2: game, 3: music, 4: application, 5: text, 6: other, 7: unknown | `'7'` | `string` | +| `keywords` | optional | Array of keywords describing the content | `['k1', 'k2', 'k3']` | `Array` | +| `live` | optional | 0 = not live, 1 = content is live | `'0'` | `string` | diff --git a/dev-docs/bidders/yieldmo.md b/dev-docs/bidders/yieldmo.md index 8cfd38f626..86998b1c85 100644 --- a/dev-docs/bidders/yieldmo.md +++ b/dev-docs/bidders/yieldmo.md @@ -4,7 +4,7 @@ title: Yieldmo description: Prebid Yieldmo Bidder Adaptor biddercode: yieldmo media_types: banner, video -userIds: pubCommonId, unifiedId, criteo +userIds: pubCommonId, unifiedId, criteo, sharedId gdpr_supported: true usp_supported: true schain_supported: true @@ -14,15 +14,16 @@ pbs: true --- # Registration -## In order to use Yieldmo adapter please reach out to your Yieldmo account's person or support@yieldmo.com for more information. +### Note: In order to use Yieldmo adapter please reach out to your Yieldmo account's person or support@yieldmo.com for more information.
    ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|----------------------|------------------------|----------| -| `placementId` | required | Yieldmo placement id | `'825209316101005155'` | `string` | -| `bidFloor` | optional | Bid Floor | `0.1` | `float` | +| Name | Scope | Description | Example | Type | +|---------------|----------|------------------------|------------------------|----------| +| `placementId` | required | Yieldmo placement id | `'825209316101005155'` | `string` | +| `bidFloor` | optional | Bid Floor | `0.1` | `float` | +| `lr_env` | optional | Live Ramp ATS envelope | `e3b0c44298fc1c149a` | `string` | ### video parameters The Yieldmo adapter supports in-stream video as of Prebid v4.18. Out-stream will be supported as of Prebid v4.35.0. @@ -51,7 +52,6 @@ In addition, Yieldmo adapter relies on parameters specified in the `mediaTypes.v |-------------------|----------|--------------------------------------------------------|-----------------|------------------| | `playerSize` | required | Width and height of the player | `[640, 480]` | `Array` | | `context` | required | `instream` or `outstream ` are only supported | `instream` | `string` | - ### Example of in-stream Video Ad-unit ```javascript var videoAdUnits = [{ @@ -76,7 +76,7 @@ var videoAdUnits = [{ bids: [{ bidder: 'yieldmo', params: { - placementId: '1524592390382976659' // required + placementId: '1524592390382976659',// required, } }] }]; @@ -87,23 +87,23 @@ var videoAdUnit = [{ code: 'div-video-ad-1234567890', mediaTypes: { video: { - playerSize: [640, 480], // required + playerSize: [640, 480], // required context: 'outstream', - mimes: ['video/mp4'], // required, array of strings - placement: 3, // required, integer ( 3,4,5 ) - maxduration: 30, // required, integer - protocols: [2, 3], // required, array of integers - api: [2, 3], // required, array of integers - playbackmethod: [1,2] // required, array of integers + mimes: ['video/mp4'], // required, array of strings + placement: 3, // required, integer ( 3,4,5 ) + maxduration: 30, // required, integer + protocols: [2, 3], // required, array of integers + api: [2, 3], // required, array of integers + playbackmethod: [1,2] // required, array of integers } }, bids: [{ bidder: 'yieldmo', params: { - placementId: '1524592390382976659' // required + placementId: '1524592390382976659', // required } }] }]; ``` -> Prebid out-stream demo - https://prebid-outstream-qa.yieldmo.com/prebid-outstream.html +> [Prebid out-stream demo](https://prebid-outstream-qa.yieldmo.com/prebid-outstream.html) diff --git a/dev-docs/bidders/yieldone.md b/dev-docs/bidders/yieldone.md index 43991a3439..5f937bbbf5 100644 --- a/dev-docs/bidders/yieldone.md +++ b/dev-docs/bidders/yieldone.md @@ -1,21 +1,187 @@ --- layout: bidder -title: YIELDONE -description: Prebid YIELDONE Bidder Adaptor -pbjs: true -pbs: true +title: YieldOne +description: Prebid YieldOne Bidder Adaptor biddercode: yieldone media_types: banner, video +userIds: identityLink, imuid, AudienceOne ID, ID5 +pbjs: true +pbs: true +multiformat_supported: will-bid-on-any --- ### Note: -THE YIELDONE adapter requires setup and approval from the YIELDONE team. +THE YieldOne adapter requires setup and approval from the YieldOne team.
    Please reach out to your account team or y1s@platform-one.co.jp for more information. + ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|------------------|---------|----------| -| `placementId` | required | The placement ID | `'36891'` | `string` | +| Name | Scope | Description | Example | Type | +|-----------------|----------|----------------------------------|--------------|-------------------| +| `placementId` | required | The placement ID | `"36891"` | `string` | +| `playerSize` | optional | Video Resolution Size
    (This field is mandatory if mediaTypes.video.playerSize is [1, 1]) | `[640, 360]` | `array of number` | +| `playerParams` | optional | Video Player Params (see below) | `{}` | `object` | +| `playerParams.wrapperWidth` | optional | Video Player Width | `"320px"` | `string` | +| `playerParams.wrapperHeight` | optional | Video Player Height | `"180px"` | `string` | + + +### Multi-Format Ad Units + +If you use Multi-Format Ad Units, "video" bid object should be placed before "banner" bid object.
    +And if Bid Params contains playerParams, it will request a "video" media type ad.
    +If it does not, it will request a "banner" media type ad. + + +### AdUnit Format Example + +#### AdUnit Format for Banner +```javascript +var bannerAdUnits = [{ + code: "test-div-banner", + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [1, 1] + ] + }, + }, + bids: [{ + bidder: "yieldone", + params: { + placementId: "36891" // required + } + }] +}] +``` + + +#### AdUnit Format for Video +```javascript +var videoAdUnits = [{ + code: "test-div-video", + mediaTypes: { + video: { + playerSize: [640, 360], + context: "outstream" + } + }, + bids: [{ + bidder: "yieldone", + params: { + placementId: "36892", // required + playerParams: { // optional + wrapperWidth: "320px", // optional + wrapperHeight: "180px" // optional + }, + } + }] +}] +``` + + +#### AdUnit Format for Multi Ads +```javascript +var multiAdUnits = [{ + code: "test-div-multi", + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [1, 1] + ] + }, + video: { + playerSize: [640, 360], + context: "outstream" + } + }, + bids: [{ + // * "video" bid object should be placed before "banner" bid object. + // This bid will request a "video" media type ad. + bidder: "yieldone", + params: { + placementId: "36892", // required + playerParams: { // required + wrapperWidth: "320px", // optional + wrapperHeight: "180px" // optional + }, + } + }, + { + // This bid will request a "banner" media type ad. + bidder: "yieldone", + params: { + placementId: "36891" // required + } + }] +}]; +``` + + +#### AdUnit Format for Video (mediaTypes.video.playerSize: [1,1]) +```javascript +var videoAdUnits = [{ + code: "test-div-video", + mediaTypes: { + video: { + playerSize: [1, 1], + context: "outstream" + } + }, + bids: [{ + bidder: "yieldone", + params: { + placementId: "36892", // required + playerSize: [640, 360], // required + playerParams: { // optional + wrapperWidth: "320px", // optional + wrapperHeight: "180px" // optional + }, + } + }] +}] +``` + + +#### AdUnit Format for Multi Ads (mediaTypes.video.playerSize: [1,1]) +```javascript +var multiAdUnits = [{ + code: "test-div-multi", + mediaTypes: { + banner: { + sizes: [ + [300, 250], + [1, 1] + ] + }, + video: { + playerSize: [1, 1], + context: "outstream" + } + }, + bids: [{ + // * "video" bid object should be placed before "banner" bid object. + // This bid will request a "video" media type ad. + bidder: "yieldone", + params: { + placementId: "36892", // required + playerSize: [640, 360], // required + playerParams: { // required + wrapperWidth: "320px", // optional + wrapperHeight: "180px" // optional + }, + } + }, + { + // This bid will request a "banner" media type ad. + bidder: "yieldone", + params: { + placementId: "36891" // required + } + }] +}]; +``` diff --git a/dev-docs/bidders/zedo.md b/dev-docs/bidders/zedo.md index 7fb66abe20..7584492769 100644 --- a/dev-docs/bidders/zedo.md +++ b/dev-docs/bidders/zedo.md @@ -4,7 +4,8 @@ title: ZEDO description: Prebid ZEDO Bidder Adapter pbjs: true biddercode: zedo -pbjs_version_notes: not in 5.x +enable_download: false +pbjs_version_notes: not ported to 5.x --- diff --git a/dev-docs/bidders/zeroclickfraud.md b/dev-docs/bidders/zeroclickfraud.md index fd45bea32c..cb7013756a 100644 --- a/dev-docs/bidders/zeroclickfraud.md +++ b/dev-docs/bidders/zeroclickfraud.md @@ -12,4 +12,4 @@ biddercode: zeroclickfraud | Name | Scope | Description | Example | Type | |------------|----------|------------------------|---------|----------| | sourceId | required | Website Source Id | 111 | integer | -| host | requird | Network Host to request from | 'host1' | string | +| host | required | Network Host to request from | 'host1' | string | diff --git a/dev-docs/bidders/zeta_global.md b/dev-docs/bidders/zeta_global.md index 1167b31a9c..08a51def28 100644 --- a/dev-docs/bidders/zeta_global.md +++ b/dev-docs/bidders/zeta_global.md @@ -4,7 +4,7 @@ title: Zeta Global description: Zeta Global Prebid Bidder Adapter pbjs: true biddercode: zeta_global -bidder_supports_deals: false +deals_supported: false media_types: banner gdpr_supported: true tcf2_supported: true diff --git a/dev-docs/bidders/zeta_global_ssp.md b/dev-docs/bidders/zeta_global_ssp.md index 74c092c0fb..6d594b4775 100644 --- a/dev-docs/bidders/zeta_global_ssp.md +++ b/dev-docs/bidders/zeta_global_ssp.md @@ -4,7 +4,7 @@ title: Zeta Global Ssp description: Zeta Global Ssp Prebid Bidder Adapter pbjs: true biddercode: zeta_global_ssp -bidder_supports_deals: false +deals_supported: false media_types: banner gdpr_supported: true usp_supported: true @@ -18,16 +18,17 @@ gvl_id: 833 All references to the OpenRTB spec refer to OpenRtb v2.5 (https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) +The Zeta Global SSP adapter requires setup and approval from the Zeta Global SSP team. Please reach out to your account team or rcomolli@zetaglobal.com for more information. + ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |----------------------|----------|---------------------------------------------------------------------------------------------------------------------|--------------|-----------| -| `user` | optional | The object containing user data (See OpenRTB spec) | `user: {}` | `object` | -| `user.buyeruid` | optional | Zeta's user id | `"12345"` | `string` | +| `sid` | required | Seller ID. The identifier associated with the seller or reseller account within the advertising system | `"sid123"` | `string` | +| `shortname` | required | Publisher Name. The unique name associated with the seller or reseller account within the advertising system | `"pub_name"` | `string` | | `tags` | optional | The object containing set of Zeta's custom tags witch publisher have to supply | `tags: {}` | `object` | | `site` | optional | The object containing site data (See OpenRTB spec) | `site: {}` | `object` | | `app` | optional | The object containing app data (See OpenRTB spec) | `app: {}` | `object` | -| `sid` | optional | Seller ID. The identifier associated with the seller or reseller account within the advertising system | `"1q2w3e"` | `string` | | `test` | optional | Flag which will induce a sample bid response when true; only set to true for testing purposes (1 = true, 0 = false) | `1` | `integer` | diff --git a/dev-docs/common-issues.md b/dev-docs/common-issues.md index 66eb3693ab..ac9cd05993 100644 --- a/dev-docs/common-issues.md +++ b/dev-docs/common-issues.md @@ -38,6 +38,6 @@ Check the bid prices. If they are low and are getting reduced to $0 due to price {:toc} + [Prebid.js FAQ](/dev-docs/faq.html) -+ [Prebid Tips for Troubleshooting]({{site.github.url}}/dev-docs/troubleshooting-tips.html) ++ [Prebid Tips for Troubleshooting](/troubleshooting/troubleshooting-guide.html) diff --git a/dev-docs/examples/adunit-refresh.md b/dev-docs/examples/adunit-refresh.md index 07362a534c..b5fb6488ce 100644 --- a/dev-docs/examples/adunit-refresh.md +++ b/dev-docs/examples/adunit-refresh.md @@ -9,7 +9,7 @@ about: - Ability to refresh individual ad units - useful for infinite scrolling ad slots - When auto-refreshing is done incorrectly, it could cause the same bids to be rendered repeatedly. For instance, when googletag.pubads.refresh() is called directly without removing the PBJS targeting, the same hb_ variables get re-sent to GAM, re-chosen, and re-rendered. Over and over without ever asking PBJS for updated targeting variables. Please see     Auction Options for more info. -jsfiddle_link: jsfiddle.net/Prebid_Examples/cu7tpexf/2/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/cu7tpexf/embedded/html,result code_height: 1540 diff --git a/dev-docs/examples/basic-example.md b/dev-docs/examples/basic-example.md index 982bb60b62..929567b8d4 100644 --- a/dev-docs/examples/basic-example.md +++ b/dev-docs/examples/basic-example.md @@ -11,7 +11,7 @@ about: - Default keyword targeting setup (reference) - Default price granularity -jsfiddle_link: jsfiddle.net/Prebid_Examples/94jt62b8/7/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/94jt62b8/embedded/html,result code_height: 2300 diff --git a/dev-docs/examples/custom-price-buckets.md b/dev-docs/examples/custom-price-buckets.md index 6f914011e7..b3097c781d 100644 --- a/dev-docs/examples/custom-price-buckets.md +++ b/dev-docs/examples/custom-price-buckets.md @@ -9,7 +9,7 @@ about: - Custom price granularity buckets using pbjs.setConfig() - See the the API reference for more detail. -jsfiddle_link: jsfiddle.net/Prebid_Examples/vq05dhnj/2/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/vq05dhnj/embedded/html,result code_height: 2152 diff --git a/dev-docs/examples/instream-banner-mix.md b/dev-docs/examples/instream-banner-mix.md index 71de271dd1..2a315ef437 100644 --- a/dev-docs/examples/instream-banner-mix.md +++ b/dev-docs/examples/instream-banner-mix.md @@ -5,7 +5,7 @@ description: An example of displaying both instream video and banner ads using P sidebarType: 1 -jsfiddle_link: jsfiddle.net/Prebid_Examples/nowfejh7/2/embedded/html,result/ +jsfiddle_link: jsfiddle.net/Prebid_Examples/nowfejh7/embedded/html,result/ code_height: 3050 diff --git a/dev-docs/examples/legacy-browser-example.md b/dev-docs/examples/legacy-browser-example.md new file mode 100644 index 0000000000..253e67c547 --- /dev/null +++ b/dev-docs/examples/legacy-browser-example.md @@ -0,0 +1,19 @@ +--- +layout: example +title: Legacy Browser Support +description: Legacy Browser Support + +sidebarType: 1 + +about: +- In Prebid 6.0, support for legacy browsers is no longer assured. +- Publishers may conditionally deploy the 5.x branch and add polyfills +- One strategy to do this is simply the module/nomodule approach discussed here https://philipwalton.com/articles/deploying-es2015-code-in-production-today/ +- Another strategy is to detect the user agent or the 'currentScript' mechanism as described here https://stackoverflow.com/questions/29987969/how-to-load-a-script-only-in-ie +- Another strategy is to conditionally serve one file or another based on instructions to your cdn + +jsfiddle_link: jsfiddle.net/Prebid_Examples/kqe8L2jf/embedded/html,result + +code_height: 3050 + +--- diff --git a/dev-docs/examples/meta-bid-filtering.md b/dev-docs/examples/meta-bid-filtering.md new file mode 100644 index 0000000000..0d6433a202 --- /dev/null +++ b/dev-docs/examples/meta-bid-filtering.md @@ -0,0 +1,15 @@ +--- +layout: example +title: Meta Bid Filtering +left_nav_override: Examples +description: Bid filtering on meta object example +sidebarType: 1 + +about: +- Bidders can supply metadata about the bid such as advertiser domain. See the "meta" fields in the bid response for the full list. +- This is an example that filters bid responses based on the metadata object. + +jsfiddle_link: jsfiddle.net/Prebid_Examples/0s4eug1d/embedded/html,result + +code_height: 2300 +--- diff --git a/dev-docs/examples/multi-format-example.md b/dev-docs/examples/multi-format-example.md index 86edf69eb3..4869e1e6a4 100644 --- a/dev-docs/examples/multi-format-example.md +++ b/dev-docs/examples/multi-format-example.md @@ -11,7 +11,7 @@ about: - For engineering setup instructions, see Show Multi-Format Ads - For ad ops setup instructions, see Setting up Prebid Multi-Format in Google Ad Manager -jsfiddle_link: jsfiddle.net/Prebid_Examples/yxsgcj71/2/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/yxsgcj71/embedded/html,result code_height: 3050 diff --git a/dev-docs/examples/native-ad-example.md b/dev-docs/examples/native-ad-example.md index 290d3247e7..89beabd189 100644 --- a/dev-docs/examples/native-ad-example.md +++ b/dev-docs/examples/native-ad-example.md @@ -10,7 +10,7 @@ about: - For engineering setup instructions, see Show Native Ads - For ad ops setup instructions, see Setting up Prebid Native in Google Ad Manager (Alpha) -jsfiddle_link: jsfiddle.net/Prebid_Examples/s5L7p3yd/2/embedded/html,result/ +jsfiddle_link: jsfiddle.net/Prebid_Examples/s5L7p3yd/embedded/html,result/ code_height: 3050 diff --git a/dev-docs/examples/postbid.md b/dev-docs/examples/postbid.md index 9ca0a03c16..426eb32234 100644 --- a/dev-docs/examples/postbid.md +++ b/dev-docs/examples/postbid.md @@ -14,7 +14,7 @@ about: - There is no need to create line items for each price bucket as the postbid creative is served after the ad server has chosen the line item. - This postbid creative supports passback. See how this works below. -jsfiddle_link: jsfiddle.net/Prebid_Examples/mtuq7kz0/2/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/mtuq7kz0/embedded/html,result code_height: 1450 --- diff --git a/dev-docs/examples/size-mapping.md b/dev-docs/examples/size-mapping.md index 162b2326d8..fc96faeefe 100644 --- a/dev-docs/examples/size-mapping.md +++ b/dev-docs/examples/size-mapping.md @@ -10,7 +10,7 @@ about: - Dynamic filtering on ad unit sizes - Ad unit labels applied based on CSS media queries -jsfiddle_link: jsfiddle.net/Prebid_Examples/qourvse1/3/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/qourvse1/embedded/html,result code_height: 2400 diff --git a/dev-docs/examples/use-prebid-with-appnexus-ad-server.md b/dev-docs/examples/use-prebid-with-appnexus-ad-server.md index 4339532f37..dba3c03674 100644 --- a/dev-docs/examples/use-prebid-with-appnexus-ad-server.md +++ b/dev-docs/examples/use-prebid-with-appnexus-ad-server.md @@ -10,6 +10,6 @@ about: - See the Seller Tag (AST) documentation for more information - To configure the Seller Tag to use SafeFrames, refer to the SafeFrame API Reference. -jsfiddle_link: jsfiddle.net/Prebid_Examples/tr1djf9e/3/embedded/html,result +jsfiddle_link: jsfiddle.net/Prebid_Examples/tr1djf9e/embedded/html,result code_height: 2404 --- diff --git a/dev-docs/faq.md b/dev-docs/faq.md index 6fb525a246..ee86bffc6d 100644 --- a/dev-docs/faq.md +++ b/dev-docs/faq.md @@ -5,8 +5,6 @@ description: FAQ on Prebid.js for header bidding. sidebarType: 1 --- - - # Prebid.js FAQ {:.no_toc} @@ -116,7 +114,7 @@ All prebid adapters that get merged should automatically detect if they're servi In other words, you shouldn't have to do anything other than make sure your own page loads Prebid.js securely, e.g., ```html - ### Next Steps 1. Set up your ad server using the [corresponding Ad Ops setup instructions]({{site.baseurl}}/adops/send-all-bids-adops.html) 2. Once you're comfortable with the basic setup, check out [the examples showing other use cases]({{site.baseurl}}/dev-docs/examples/basic-example.html) - - diff --git a/dev-docs/integrate-with-the-prebid-analytics-api.md b/dev-docs/integrate-with-the-prebid-analytics-api.md index 15aec64b6b..9a5e6514e3 100644 --- a/dev-docs/integrate-with-the-prebid-analytics-api.md +++ b/dev-docs/integrate-with-the-prebid-analytics-api.md @@ -135,6 +135,9 @@ The callback will receive an object with the following attributes: } ``` +Note that analytics adapters can read the TCF string directly from the auction object -- look for the gdprConsent object, which contains three attributes: +gdprApplies, consentString, and apiVersion + #### Listening for errors There are two error events analytics modules may wish to listen for: auctionDebug and adRenderFailed. The former is any error that would be normally logged to console and there can be a great many. The latter may happen for the following reasons: (PREVENT_WRITING_ON_MAIN_DOCUMENT, NO_AD, CANNOT_FIND_AD, EXCEPTION, MISSING_DOC_OR_ADID) diff --git a/dev-docs/modules/1plusXRtdProvider.md b/dev-docs/modules/1plusXRtdProvider.md new file mode 100644 index 0000000000..bea7a183e3 --- /dev/null +++ b/dev-docs/modules/1plusXRtdProvider.md @@ -0,0 +1,67 @@ +--- +layout: page_v2 +title: 1plusX RTD Module +display_name: 1plusX RTD Module +description: 1plusX Real Time Data Module +page_type: module +module_type: rtd +module_code : 1plusXRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# 1plusX RTD Module +{:.no_toc} + +* TOC +{:toc} + +## Description + +The 1plusX RTD module appends User and Contextual segments to the bidding object. + +## Integration + +1) Compile the 1plusX RTD Module along with your bid adapter and other modules into your Prebid build: + + +``` +gulp build --modules="rtdModule,1plusXRtdProvider,appnexusBidAdapter,..." +``` + +2) Use `setConfig` to instruct Prebid.js to initilize the 1plusX RTD module, as specified below. + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` + +```javascript +var TIMEOUT = 1000; +pbjs.setConfig({ + realTimeData: { + auctionDelay: TIMEOUT, + dataProviders: [{ + name: '1plusX', + waitForIt: true, + params: { + customerId: 'acme', + bidders: ['appnexus', 'rubicon'], + timeout: TIMEOUT + } + }] + } +}); +``` + +## Parameters + +{: .table .table-bordered .table-striped } +| Name | Type | Description | Default | +| :---------------- | :------------ | :--------------------------------------------------------------- |:----------------- | +| name | String | Real time data module name | Always '1plusX' | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | +| params | Object | | | +| params.customerId | String | Your 1plusX customer id | | +| params.bidders | Array | List of bidders for which you would like data to be set | | +| params.timeout | Integer | timeout (ms) | 1000ms | diff --git a/dev-docs/modules/adnuntiusRtdProvider.md b/dev-docs/modules/adnuntiusRtdProvider.md new file mode 100644 index 0000000000..db4b5b757e --- /dev/null +++ b/dev-docs/modules/adnuntiusRtdProvider.md @@ -0,0 +1,65 @@ +--- +layout: page_v2 +title: Adnuntius Data Segment Module +display_name: Adnuntius Data Segments +description: Adnuntius Data Segments +page_type: module +module_type: rtd +module_code: adnuntiusRtdProvider +enable_download: true +vendor_specific: true +sidebarType: 1 +--- + +# Adnuntius Data Segment Module + +## Integration + +1. Compile the Adnuntius RTD Module and Adnuntius Bid Adapter into your Prebid build: + +``` +gulp build --modules="adnuntiusRtdProvider,adnuntiusBidAdapter,..." +``` + +2. Use `setConfig` to instruct Prebid.js to initilize the adnuntius module, as specified below. + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` + +```javascript +var pbjs = pbjs || { que: [] } +pbjs.que.push(function () { + pbjs.setConfig({ + realTimeData: { + auctionDelay: 300, + dataProviders: [ + { + name: 'adnuntius', + waitForIt: true, + params: { + bidders: ['adnuntius'], + providers: [ + { + siteId: 'site123', + userId: 'user123', + }, + ], + }, + }, + ], + }, + }) +}) +``` + +Syntax details: + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Always 'adnuntius' | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | +| params | Object | | | +| params.bidders | Array | A list of bidders that the module should affect | | +| params.bidders | Array | An array of users users and site ID that to send to Adnuntius data | | diff --git a/dev-docs/modules/adpod.md b/dev-docs/modules/adpod.md index 519b1a1a87..0519cd9db6 100644 --- a/dev-docs/modules/adpod.md +++ b/dev-docs/modules/adpod.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Adpod -description: Adds functions to validate, cache, and modify long-form video bids. +description: Enables developers to add support for a new adserver that handles ad pod (long-form) videos. module_code : adpod display_name : Adpod enable_download : true diff --git a/dev-docs/modules/airgridRtdProvider.md b/dev-docs/modules/airgridRtdProvider.md new file mode 100644 index 0000000000..6251c63fce --- /dev/null +++ b/dev-docs/modules/airgridRtdProvider.md @@ -0,0 +1,102 @@ +--- +layout: page_v2 +title: AirGrid RTD Provider +display_name: AirGrid RTD Provider +description: Client-side, cookieless and privacy-first audiences. +page_type: module +module_type: rtd +module_code : airgridRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# AirGrid RTD Provider + +AirGrid is a privacy-first, cookie-less audience platform. Designed to help publishers increase inventory yield, +whilst providing audience signal to buyers in the bid request, without exposing raw user level data to any party. + +This real-time data module provides quality first-party data, contextual data, site-level data and more that is +injected into bid request objects destined for different bidders in order to optimize targeting. + +{:.no_toc} +* TOC +{:toc} + +## Usage + +Compile the AirGrid RTD module (`airgridRtdProvider`) into your Prebid build, along with the parent RTD Module (`rtdModule`): + +`gulp build --modules=rtdModule,airgridRtdProvider,appnexusBidAdapter` + +Next we configure the module, via `pbjs.setConfig`. See the **Parameter Descriptions** below for more detailed information of the configuration parameters. + +```js +pbjs.setConfig( + ... + realTimeData: { + auctionDelay: 1000, + dataProviders: [ + { + name: 'airgrid', + waitForIt: true, + params: { + // These are unique values for each account. + apiKey: 'apiKey', + accountId: 'accountId', + publisherId: 'publisherId', + bidders: ['appnexus', 'pubmatic'] + } + } + ] + } + ... +} +``` + +### Parameter Descriptions + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | `String` | RTD sub module name | Always 'airgrid' | +| waitForIt | `Boolean` | Wether to delay auction for module response | Optional. Defaults to false | +| params.apiKey | `Boolean` | Publisher partner specific API key | Required | +| params.accountId | `String` | Publisher partner specific account ID | Required | +| params.publisherId | `String` | Publisher partner specific publisher ID | Required | +| params.bidders | `Array` | Bidders with which to share segment information | Optional | + +_Note: Although the module supports passing segment data to any bidder using the ORTB2 spec, there is no way for this to be currently monetised. Please reach out to support, to discuss using bidders other than Xandr/AppNexus._ + +If you do not have your own `apiKey`, `accountId` & `publisherId` please reach out to [support@airgrid.io](mailto:support@airgrid.io) or you can sign up via the [AirGrid platform](https://app.airgrid.io). + +## Testing + +To view an example of the on page setup required: + +```bash +gulp serve-fast --modules=rtdModule,airgridRtdProvider,appnexusBidAdapter +``` + +Then in your browser access: + +``` +http://localhost:9999/integrationExamples/gpt/airgridRtdProvider_example.html +``` + +Run the unit tests, just on the AirGrid RTD module test file: + +```bash +gulp test --file "test/spec/modules/airgridRtdProvider_spec.js" +``` + +## Support + +If you require further assistance or are interested in discussing the module functionality please reach out to: +- [hello@airgrid.io](mailto:hello@airgrid.io) for general questions. +- [support@airgrid.io](mailto:support@airgrid.io) for technical questions. + +You are also able to find more examples and other integration routes on the [AirGrid docs site](https://docs.airgrid.io), or learn more on our [site](https://airgrid.io)! + +Happy Coding! 😊 +The AirGrid Team. diff --git a/dev-docs/modules/akamaiDapRtdProvider.md b/dev-docs/modules/akamaiDapRtdProvider.md new file mode 100644 index 0000000000..e78df14957 --- /dev/null +++ b/dev-docs/modules/akamaiDapRtdProvider.md @@ -0,0 +1,82 @@ +--- +layout: page_v2 +title: Akamai DAP Real Time Data Provider Module +display_name: Akamai DAP Real Time Data Provider Module +description: Akamai DAP Real Time Data Provider Module +page_type: module +module_type: rtd +module_code : akamaiDapRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Akamai DAP Real Time Data Provider Module +{:.no_toc} + +* TOC +{:toc} + +The Akamai Data Activation Platform (DAP) is a privacy-first system that protects end-user privacy by only allowing them to be targeted as part of a larger cohort. Akamai DAP Real time data Provider automatically invokes the DAP APIs and submit audience segments and the Secure Ad ID(SAID) to the bid-stream. SAID is a JWT/JWE which carries with it the cohorts and only a side-car or trusted server in the demand-side platform is allowed to see its contents. + + +## Publisher Usage + +1) Build the akamaiDapRTD module into the Prebid.js package with: + +``` +gulp build --modules=akamaiDapRtdProvider,... +``` + +2) Use `setConfig` to instruct Prebid.js to initilaize the akamaiDapRtdProvider module, as specified below. + +### Configuration + +``` +pbjs.setConfig({ + realTimeData: { + auctionDelay: 2000, + dataProviders: [ + { + name: "dap", + waitForIt: true, + params: { + apiHostname: '', + apiVersion: "x1", + domain: 'your-domain.com', + identityType: 'email' | 'mobile' | ... | 'dap-signature:1.3.0', + segtax: 504, + dapEntropyUrl: 'https://dap-dist.akamaized.net/dapentropy.js', + dapEntropyTimeout: 1500 + } + } + ] + } +}); +``` + +Please reach out to your Akamai account representative(Prebid@akamai.com) to get provisioned on the DAP platform. + + +**Config Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Akamai Dap Rtd module name | 'dap' always| +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| apiHostname | String | Hostname provided by Akamai | Please reach out to your Akamai account representative(Prebid@akamai.com) for this value| +| apiVersion | String | This holds the API version | It should be "x1" always | +| domain | String | The domain name of your webpage | | +| identityType | String | Something like this 'email', 'mobile', ... 'dap-signature:1.3.0' | | +| segtax | Integer | The taxonomy for Akamai | The value should be 504 | +| dapEntropyUrl | String | URL to dap entropy script | Optional if the script is directly included on the webpage. Contact your Akamai account rep for more details | +| dapEntropyTimeout | Integer | Maximum time allotted for the entropy calculation to happen | | + +### Testing +To view an example of available segments returned by dap: +``` +‘gulp serve --modules=rtdModule,akamaiDapRtdProvider,appnexusBidAdapter,sovrnBidAdapter’ +``` +and then point your browser at: +"http://localhost:9999/integrationExamples/gpt/akamaidap_segments_example.html" diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index b76fb8bf98..a9da963a12 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -1,15 +1,16 @@ --- layout: page_v2 page_type: module -title: Module - Bid Viewable Event -description: Triggers BID_VIEWABLE event when a rendered PBJS-Bid is viewable according to [Active View criteria](https://support.google.com/admanager/answer/4524488) +title: Module - Bid Viewability - GAM +description: Triggers a BID_VIEWABLE event when a rendered bid is viewable according to Active View criteria module_code : bidViewability -display_name : Bid Viewable Event +display_name : Bid Viewability - GAM enable_download : true +vendor_specific: true sidebarType : 1 --- -# Bid Viewable Event +# Bid Viewability - GAM {:.no_toc} * TOC @@ -19,33 +20,37 @@ sidebarType : 1 This optional module will trigger a BID_VIEWABLE event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event. - Notes: -- The module does not work with adservers other than GAM and only with GPT integration. -- The GPT API is used to find when a bid is viewable, See https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent . +- The module does not work with adservers other than GAM and only with GPT integration. See the [other Bid Viewable Event](/dev-docs/modules/bidViewableIO.html) module for an ad server independent version. +- The GPT API is used to find when a bid is viewable. See [GPT documentation](https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent) for more details. - This event is fired when an impression becomes viewable, according to [Active View criteria](https://support.google.com/admanager/answer/4524488). -- Logic used to find a matching Prebid.js bid for a GPT slot is ` (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` this logic can be changed by using param ` customMatchFunction ` - When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters - The module works with Banner, Outsteam and Native creatives -Instead of listening for events, bidders may supply a ` bid.vurls ` array and this module may fire those pixels when the viewability signal is received. Publishers can control this with module config ` firePixels: true `. Please note that GDPR and USP related parameters will be added to the given URLs. +Instead of listening for events, bidders may supply a `bid.vurls` array and this module may fire those pixels when the viewability signal is received. Publishers can control this with module config ` firePixels: true `. Please note that GDPR and USP related parameters will be added to the given URLs. {: .alert.alert-warning :} -This feature doesn't seem to work with [Instream Video](/dev-docs/examples/instream-banner-mix.html), as GPT's impressionViewable event is not triggered for instream-video-creative +This feature doesn't work with [Instream Video](/dev-docs/examples/instream-banner-mix.html), as GPT's impressionViewable event is not triggered for instream-video-creative + +The default logic used to find a matching Prebid.js bid for a GPT slot is +``` +(bid, slot) => (slot.getAdUnitPath() === bid.adUnitCode || + slot.getSlotElementId() === bid.adUnitCode) +``` ## Configuration {: .table .table-bordered .table-striped } -| Field | Scope | Type | Description | -|----------+---------+--------+---------------------------------------------------------------------------------------| -| `bidViewability` | Required | Object | Configuration object for instream tracking | +| Field | Scope | Type | Description | +|----------+---------+--------+-----------------------------------------| +| `bidViewability` | Required | Object | Configuration object | | `bidViewability.enabled` | Required | Boolean | when set to true, the module will emit BID_VIEWABLE when applicable. Default: `false` | | `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. Default: `false` | -| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | when passed this function will be used to `find` the matching winning bid for the GPT slot. Default value is ` (bid, slot) => (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` | +| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | this function will be used to find the matching winning bid for the GPT slot. See above for the default. | ## Example of setting module config {% highlight js %} - pbjs.setConfig({ + pbjs.setConfig({ bidViewability: { enabled: true, firePixels: true, diff --git a/dev-docs/modules/bidViewableIO.md b/dev-docs/modules/bidViewableIO.md new file mode 100644 index 0000000000..b483bc5b80 --- /dev/null +++ b/dev-docs/modules/bidViewableIO.md @@ -0,0 +1,66 @@ +--- +layout: page_v2 +page_type: module +title: Module - Bid Viewability - Ad Server Independent +description: Triggers a BID_VIEWABLE event when a rendered bid is viewable according to an approximation of IAB viewability criteria +module_code : bidViewabilityIO +display_name : Bid Viewability - Ad Server Independent +enable_download : true +sidebarType : 1 +--- + +# Bid Viewability - Ad Server Independent +{:.no_toc} + +* TOC +{:toc} + +## Overview + +This optional module will trigger a BID_VIEWABLE event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event. + +Notes: +- The module works with any adserver, or with no ad server at all. +- Publishers using GAM/GPT might consider using the [Bid Viewable Event - GAM](/dev-docs/modules/bidViewable.html) module +- Requires the site to polyfill the [IntersectionObserver API](https://github.com/w3c/IntersectionObserver/tree/main/polyfill) (v1) to find when a bid is viewable. This implementation assumes that the publisher and the bidder are acting in good faith, and does not attempt to detect any bad behavior from either party. We assume that the ad is rendered into the element it has been told to render into, and is not hidden or obfuscated at any time. +- This event is fired when an impression becomes viewable, according to IAB's viewability guidelines +- When a rendered PBJS bid is determined to be viewable this module will trigger a BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters +- The module works with Banner creatives, with additional support to come. + +## Known Issues + +{: .alert.alert-warning :} +This feature is not intended to be a perfect measure of viewability. It is however intended to be a reasonable approximation of a bids viewability for creative types that are supported. + +1. Only supports Banner creatives +2. Only works on browsers that support or on sites that have [polyfilled the IntersectionObserver API](https://github.com/w3c/IntersectionObserver/tree/main/polyfill) +3. Results can only be trusted if both the publisher and winning bidder are assumed to be acting in good faith. + +## Configuration + +{: .table .table-bordered .table-striped } +| Field | Scope | Type | Description | +|----------+---------+--------+---------------------------------------------------------------------------------------| +| `bidViewabilityIO` | Required | Object | Configuration object for viewability tracking for supported media types (IO stands for IntersectionObserver) | +| `bidViewabilityIO.enabled` | Required | Boolean | when set to true, the module will emit BID_VIEWABLE when applicable. Default: `false` | + +## Example of setting module config +{% highlight js %} + pbjs.setConfig({ + bidViewabilityIO: { + enabled: true, + } + }); +{% endhighlight %} + +## Example of consuming BID_VIEWABLE event +{% highlight js %} + pbjs.onEvent('bidViewable', function(bid){ + console.log('got bid details in bidViewable event', bid); + }); +{% endhighlight %} + +## Related Reading + +- [Building a PBJS analytics adapter](/dev-docs/integrate-with-the-prebid-analytics-api.html) +- [Building a PBJS bidder adapter](/dev-docs/bidder-adaptor.html) diff --git a/dev-docs/modules/blueconicRtdProvider.md b/dev-docs/modules/blueconicRtdProvider.md new file mode 100644 index 0000000000..c715c5e19f --- /dev/null +++ b/dev-docs/modules/blueconicRtdProvider.md @@ -0,0 +1,85 @@ +--- +layout: page_v2 +title: BlueConic Real Time Data Provider +display_name: BlueConic Real-time Module +description: BlueConic Real-time Data Module +page_type: module +module_type: rtd +module_code : blueconicRtdProvider +enable_download : true +coppa_supported: true +vendor_specific: true +sidebarType : 1 +--- + +# BlueConic Real-time Data Submodule +{:.no_toc} + +* TOC +{:toc} + +BlueConic's Real-time Data Provider automatically obtains segmentation data and other user level data from the BlueConic script (via `localStorage`) and passes them to the bid-stream. Please reach out to BlueConic team(info@blueconic.com) or visit our [website](https://support.blueconic.com/hc/en-us) if you have any questions or need further help to integrate Prebid or blueconicRtdProvider. + +## Publisher Usage + +Compile the BlueConic RTD module into your Prebid build: + +`gulp build --modules=rtdModule,blueconicRtdProvider,appnexusBidAdapter` + +Add the BlueConic RTD provider to your Prebid config. In this example we will configure +publisher 1234 to retrieve segments, profile data from BlueConic. See the +"Parameter Descriptions" below for more detailed information of the +configuration parameters. Please work with your BlueConic Prebid support team +(info@blueconic.com) on which version of Prebid.js supports different bidder +and segment configurations. + +``` +pbjs.setConfig( + ... + realTimeData: { + auctionDelay: 1000, + dataProviders: [ + { + name: "blueconic", + waitForIt: true, + params: { + requestParams: { + publisherId: 1234 + } + } + } + ] + } + ... +} +``` + +## BlueConic Configuration Parameters + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Always 'blueconic' | +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| params | Object | | | +| params.requestParams | Object | Publisher partner specific configuration options, such as optional publisher id and other segment query related metadata | Optional | + + +Please see the examples available in the blueconicRtdProvider_spec.js +tests. + +## Testing + +To run test suite for blueconic: + +`gulp test --modules=rtdModule,blueconicRtdProvider,appnexusBidAdapter` + +## Example + +To view an example of available segments & profile data: + +`gulp serve --modules=rtdModule,blueconicRtdProvider,appnexusBidAdapter` + +and then point your browser at: + +`http://localhost:9999/integrationExamples/gpt/blueconicRtdProvider_example.html` \ No newline at end of file diff --git a/dev-docs/modules/brandmetricsRtdProvider.md b/dev-docs/modules/brandmetricsRtdProvider.md new file mode 100644 index 0000000000..ef2595d6e6 --- /dev/null +++ b/dev-docs/modules/brandmetricsRtdProvider.md @@ -0,0 +1,76 @@ +--- +layout: page_v2 +title: brandmetrics Real Time Data Provider Module +display_name: brandmetrics Real Time Data Provider Module +description: brandmetricsReal Time Data Provider Module +page_type: module +module_type: rtd +module_code : brandmetricsRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# brandmetrics Real Time Data Provider Module +{:.no_toc} + +* TOC +{:toc} + +This module is intended to be used by brandmetrics (https://brandmetrics.com) partners and sets targeting keywords to bids if the browser is eligeble to see a brandmetrics survey. +The module hooks in to brandmetrics events and requires a brandmetrics script to be running. The module can optionally load and initialize brandmetrics by providing the 'scriptId'- parameter. + + +## Publisher Usage + +1) Build the brandmetricsRtd module into the Prebid.js package with: + +``` +gulp build --modules=brandmetricsRtdProvider,... +``` + +2) Use `setConfig` to instruct Prebid.js to initilaize the brandmetricsRtdProvider module, as specified below. + +### Configuration + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 500, + dataProviders: [ + { + name: "brandmetrics", + waitForIt: true, + params: { + scriptId: '00000000-0000-0000-0000-000000000000', + bidders: ['ozone'] + } + } + ] + } +}); +``` + +The scriptId- parameter is provided by brandmetrics or a brandmetrics partner. + + +## Supported bidders + +The module currently supports the following bidders: + +{: .table .table-bordered .table-striped } +| Bidder | Id | +| :----- | :---- | +| Ozone | ozone | + + +## Parameters + +{: .table .table-bordered .table-striped } +| Name | Type | Description | Default | +| :---------------- | :------------------- | :----------------- | :------------- | +| name | String | This should always be `brandmetrics` | - | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (recommended) | `false` | +| params | Object | | - | +| params.bidders | String[] | An array of bidders the module operates on. | `[]` | +| params.scriptId | String | A script- id GUID if the brandmetrics- script should be initialized. | `undefined` | diff --git a/dev-docs/modules/browsiRtdProvider.md b/dev-docs/modules/browsiRtdProvider.md index 6d269adf3a..062f47f45f 100644 --- a/dev-docs/modules/browsiRtdProvider.md +++ b/dev-docs/modules/browsiRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : browsiRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/categoryTranslation.md b/dev-docs/modules/categoryTranslation.md index 4102eb82c6..cb1bd0f987 100644 --- a/dev-docs/modules/categoryTranslation.md +++ b/dev-docs/modules/categoryTranslation.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Category Translation -description: Converts IAB sub category to ad server group. +description: Converts IAB category to ad server category for long-form videos. module_code : categoryTranslation display_name : CategoryTranslation enable_download : true diff --git a/dev-docs/modules/cleanioRtdProvider.md b/dev-docs/modules/cleanioRtdProvider.md new file mode 100644 index 0000000000..5f7cf7923b --- /dev/null +++ b/dev-docs/modules/cleanioRtdProvider.md @@ -0,0 +1,67 @@ +--- +layout: page_v2 +title: clean.io Real Time Data Provider +display_name: clean.io Real-time Anti-Malvertising Module +description: clean.io Real-time Anti-Malvertising Module +page_type: module +module_type: rtd +module_code : cleanioRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# clean.io Real-time Anti-Malvertising Module + +## Overview + +The clean.io Realtime module provides effective anti-malvertising solution for publishers, including, but not limited to, +blocking unwanted 0- and 1-click redirects, deceptive ads or those with malicious landing pages, and various types of affiliate fraud. + +Using this module requires prior agreement with [clean.io](https://clean.io) to obtain the necessary distribution key. + +## Integration + +clean.io Realtime module can be built just like any other prebid module: + +``` +gulp build --modules=cleanioRtdProvider,... +``` + + +## Configuration + +When built into prebid.js, this module can be configured through the following `pbjs.setConfig` call: + +```javascript +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: 'clean.io', + params: { + cdnUrl: 'https://abc1234567890.cloudfront.net/script.js', ///< Contact clean.io to get your own CDN URL + protectionMode: 'full', ///< Supported modes are 'full', 'bids' and 'bids-nowait', see below. + } + }] + } +}); +``` + + +### Configuration parameters + +{: .table .table-bordered .table-striped } +| Name | Type | Scope | Description | +| :------------ | :------------ | :------------ |:------------ | +| ``cdnUrl`` | ``string`` | Required | CDN URL of the script, which is to be used for protection. | +| ``protectionMode`` | ``'full' or 'bids' or 'bids-nowait'`` | Required | Integration mode. Please refer to the "Integration modes" section for details. | + + +## Integration modes + +{: .table .table-bordered .table-striped } +| Integration Mode | Parameter Value | Description | +| :------------ | :------------ | :------------ | +| Full page protection | ``'full'`` | Preferred mode. The module will add the protector agent script directly to the page, and it will protect all placements. This mode will make the most out of various behavioral detection mechanisms, and will also prevent typical malicious behaviors. Please note that in this mode, depending on Prebid library naming, Chrome may mistakenly tag non-ad-related content as ads: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/ad_tagging.md. | +| Bids-only protection | ``'bids'`` | The module will protect specific bid responses, more specifically, the HTML representing ad payload, by wrapping it into the agent script. Please note that in this mode, ads delivered directly, outside of Prebid integration, will not be protected, since the module can only access the ads coming through Prebid. | +| Bids-only protection with no delay on bid rendering | ``'bids-nowait'`` | Same as above, but in this mode, the script will also *not* wrap those bid responses, which arrived prior to successful preloading of agent script. | diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index a1dc9b9794..d0d4ea46f5 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Consent Management - GDPR -description: Module to consume and distribute GDPR consent information to bidder adapters +description: If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the GDPR Enforcement module. module_code : consentManagement display_name : Consent Management - GDPR enable_download : true +recommended: true sidebarType : 1 --- @@ -21,9 +22,6 @@ sidebarType : 1 {% include /alerts/alert_important.html content=legalNotice %} -{: .alert.alert-warning :} -Prebid.org is working on updates that will enable support for reading and parsing TCF 2.0 consent strings. See the [blog post](https://prebid.org/blog/tcf2) for timelines. - ## Overview This consent management module is designed to support the EU General Data Protection Regulation ([GDPR](https://www.iab.com/topics/consumer-privacy/gdpr/)) @@ -56,7 +54,7 @@ If the timeout period expires or an error from the CMP is thrown, one of these a Please start by understanding the IAB's [TCF Implementation Guide](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md). -To utilize this module, a Consent Management Platform (CMP) compatible with the [IAB TCF v1.1 spec](https://iabeurope.eu/all-news/the-iab-europe-transparency-consent-framework-tcf-steering-group-votes-to-extend-technical-support-for-tcf-v1-1/) or [IAB TCF v2.0 spec](https://iabeurope.eu/tcf-2-0/) needs to be implemented on the site to interact with the user and obtain their consent choices. It's important to understand the details of how the CMP works before integrating it with Prebid.js +To utilize this module, a Consent Management Platform (CMP) compatible with the [IAB TCF v2.0 spec](https://iabeurope.eu/tcf-2-0/) needs to be implemented on the site to interact with the user and obtain their consent choices. It's important to understand the details of how the CMP works before integrating it with Prebid.js In general, implementation details for CMPs are not covered by Prebid.org, but we do recommend to that you place the CMP code before the Prebid.js code in the head of the page in order to ensure the CMP's framework is loaded before the Prebid code executes. In addition, the community is collecting a set of [CMP best practices](/dev-docs/cmp-best-practices.html). @@ -75,22 +73,14 @@ but we recommend migrating to the new config structure as soon as possible. | gdpr.cmpApi | `string` | The CMP interface that is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted consent strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | | gdpr.timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000`. | `10000` | | gdpr.defaultGdprScope | `boolean` | Defines what the `gdprApplies` flag should be when the CMP doesn't respond in time or the static data doesn't supply. Defaults to `false`. | `true` | -| gdpr.allowAuctionWithoutConsent | `boolean` | (TCF v1.1 only) Determines what will happen if obtaining consent information from the CMP fails; either allow the auction to proceed (`true`) or cancel the auction (`false`). Default is `true` | `true` | | gdpr.consentData | `Object` | An object representing the GDPR consent data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. | | -| gdpr.consentData.getTCData.tcString | `string` | (TCF v2.0 only) Base64url-encoded TCF v2.0 string with segments. | | -| gdpr.consentData.getTCData.addtlConsent | `string` | (TCF v2.0 only) Additional consent string if available from the cmp TCData object | | -| gdpr.consentData.getTCData.gdprApplies | `boolean` | (TCF v2.0 only) Defines whether or not this pageview is in GDPR scope. | | -| gdpr.consentData.getTCData.purpose.consents | `Object` | (TCF v2.0 only) An object representing the user's consent status for specific purpose IDs. | | -| gdpr.consentData.getTCData.purpose.legitimateInterests | `Object` | (TCF v2.0 only) An object representing the user's legitimate interest status for specific purpose IDs. | | -| gdpr.consentData.getTCData.vendor.consents | `Object` | (TCF v2.0 only) An object representing the user's consent status for specific vendor IDs. | | -| gdpr.consentData.getTCData.vendor.legitimateInterests | `Object` | (TCF v2.0 only) An object representing the user's legitimate interest status for specific vendors IDs. | | -| gdpr.consentData.getConsentData.gdprApplies | `boolean` | (TCF v1.1 only) Defines whether or not this pageview is in GDPR scope. | | -| gdpr.consentData.getConsentData.hasGlobalScope | `boolean` | (TCF v1.1 only) True if consent data is global, false if it's publisher specific. | | -| gdpr.consentData.getConsentData.consentData | `string` | (TCF v1.1 only) Encoded TCF v1.1 string. | | -| gdpr.consentData.getVendorConsents.metadata | `string` | (TCF v1.1 only) Encoded TCF v1.1 string. | | - -{: .alert.alert-info :} -NOTE: The `allowAuctionWithoutConsent` parameter supported for TCF v1.1 refers to the entire consent string, not to any individual consent option. Prebid.js does not parse the GDPR consent string, so it doesn't know if the user has consented to any particular action. +| gdpr.consentData.getTCData.tcString | `string` | Base64url-encoded TCF v2.0 string with segments. | | +| gdpr.consentData.getTCData.addtlConsent | `string` | Additional consent string if available from the cmp TCData object | | +| gdpr.consentData.getTCData.gdprApplies | `boolean` | Defines whether or not this pageview is in GDPR scope. | | +| gdpr.consentData.getTCData.purpose.consents | `Object` | An object representing the user's consent status for specific purpose IDs. | | +| gdpr.consentData.getTCData.purpose.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific purpose IDs. | | +| gdpr.consentData.getTCData.vendor.consents | `Object` | An object representing the user's consent status for specific vendor IDs. | | +| gdpr.consentData.getTCData.vendor.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific vendors IDs. | | {: .alert.alert-info :} NOTE: The `purpose` and `vendor` objects are required if you are using the `gdprEnforcement` module. If the data is not included, your bid adpaters, analytics adapters, and/or userId systems will likely be excluded from the auction as Prebid will assume the user has not given consent for these entities. @@ -165,54 +155,6 @@ Example 2: Static CMP using custom data passing. }); {% endhighlight %} -### TCF v1.1 Examples - -Example 1: IAB CMP using custom timeout and cancel-auction options. - -{% highlight js %} - var pbjs = pbjs || {}; - pbjs.que = pbjs.que || []; - pbjs.que.push(function() { - pbjs.setConfig({ - consentManagement: { - gdpr: { - cmpApi: 'iab', - timeout: 8000, - allowAuctionWithoutConsent: false - } - } - }); - }); -{% endhighlight %} - -Example 2: Static CMP using custom data passing. - -{% highlight js %} - var pbjs = pbjs || {}; - pbjs.que = pbjs.que || []; - pbjs.que.push(function() { - pbjs.setConfig({ - consentManagement: { - gdpr: { - cmpApi: 'static', - allowAuctionWithoutConsent: false, - consentData: { - getConsentData: { - 'gdprApplies': true, - 'hasGlobalScope': false, - 'consentData': 'BOOgjO9OOgjO9APABAENAi-AAAAWd7_______9____7_9uz_Gv_r_ff_3nW0739P1A_r_Oz_rm_-zzV44_lpQQRCEA' - }, - getVendorConsents: { - 'metadata': 'BOOgjO9OOgjO9APABAENAi-AAAAWd7_______9____7_9uz_Gv_r_ff_3nW0739P1A_r_Oz_rm_-zzV44_lpQQRCEA', - ... - } - } - } - } - }); - }); -{% endhighlight %} - ## Build the Package Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the **gulp build** command: @@ -226,9 +168,8 @@ You can also use the [Prebid.js Download](/download.html) page. ## Adapter Integration {: .alert.alert-info :} -Prebid.js adapters don't need to change to support TCF v2.0 if they already support TCF 1.1 -- the consent string is passed through the same bidrequest location. The bidder's endpoint, however, will need to change to support TCF v2.0. Once the endpoint supports TCF2, you can update the documentation.md file as described below above the table showing the list of TCF2-compliant bidders. -If you are submitting changes to an adapter to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gdpr_supported: true` variable to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GDPR.** +If you are submitting changes to an adapter to support TCF v2.0, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gdpr_supported: true` variable to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GDPR.** ### Bidder Adapter GDPR Integration @@ -254,7 +195,7 @@ Here is a sample of how the data is structured in the `bidderRequest` object: **_consentString_** -This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error during the CMP interaction and the publisher had the config option `allowAuctionWithoutConsent` set to `true`. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the *consent_required* code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. +This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error (or timeout) during the CMP interaction and the publisher turned off GDPR enforcement. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the *consent_required* code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. **_addtlConsent_** @@ -330,7 +271,7 @@ Here are some things that publishers can do to control various activities: Prebid.js and much of the ad industry rely on the IAB CMP standard for GDPR support, but there might be some publishers who have implemented a different approach to meeting the privacy rules. Those publishers can utilize Prebid.js and the whole header bidding ecosystem by building a translation layer between their consent method and the IAB method. At a high level, this could be done as follows: -1. Build a `window.__cmp()` function, which will be seen by Prebid. +1. Build a `window.__tcfapi()` function, which will be seen by Prebid. 2. If SafeFrames are in use, build a message receiver function. 3. Format consent data in a string according to the [IAB standard](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework). @@ -339,17 +280,15 @@ Below is sample code for implementing the stub functions. Sample code for format {% highlight js %} var iabConsentData; // build the IAB consent string var gdprApplies; // true if gdpr applies to the user, else false -var hasGlobalScope; // true if consent data was retrieved globally var responseCode; // false if there was an error, else true -var cmpLoaded; // true if iabConsentData was loaded and processed (function(window, document) { function addFrame() { - if (window.frames['__cmpLocator']) + if (window.frames['____tcfapiLocator']) return; if ( document.body ) { var body = document.body, iframe = document.createElement('iframe'); - iframe.name = '__cmpLocator'; + iframe.name = '____tcfapiLocator'; iframe.style.display = 'none'; body.appendChild(iframe); } else { @@ -364,11 +303,11 @@ var cmpLoaded; // true if iabConsentData was loaded and processed if ( msgIsString ) { json = JSON.parse(json); } - var call = json.__cmpCall; + var call = json.__tcfapiCall; if (call) { - window.__cmp(call.command, call.parameter, function(retValue, success) { + window.__tcfapi(call.command, call.parameter, function(retValue, success) { var returnMsg = { - __cmpReturn: { + __tcfapiReturn: { returnValue: retValue, success: success, callId: call.callId } }; @@ -378,19 +317,15 @@ var cmpLoaded; // true if iabConsentData was loaded and processed } catch (e) {} // do nothing } var cmpFunc = function(command, version, callback) { - if (command === 'ping') { - callback({gdprAppliesGlobally: gdprApplies, cmpLoaded: cmpLoaded}, responseCode); - } else if (command === 'getConsentData') { - callback({consentData: iabConsentData, gdprApplies: gdprApplies, hasGlobalScope: hasGlobalScope}, responseCode); - } else if (command === 'getVendorConsents') { - callback({metadata: iabConsentData, gdprApplies: gdprApplies, hasGlobalScope: hasGlobalScope}, responseCode); + if (command === 'addEventListener') { + callback({eventStatus: 'tcloaded', tcString: iabConsentData, gdprApplies}, responseCode) } else { - callback(undefined, false); + callback(undefined, false); } }; - if ( typeof (__cmp) !== 'function' ) { - window.__cmp = cmpFunc; - window.__cmp.msgHandler = cmpMsgHandler; + if ( typeof (__tcfapi) !== 'function' ) { + window.__tcfapi = cmpFunc; + window.__tcfapi.msgHandler = cmpMsgHandler; if ( window.addEventListener ) { window.addEventListener('message', cmpMsgHandler, false); } else { @@ -403,7 +338,7 @@ var cmpLoaded; // true if iabConsentData was loaded and processed #### Explanation of Parameters **_iabConsentData_** -For instructions on how to generate the IAB consent string see the [IAB CMP 1.1 Spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and [IAB Consent String SDK](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/Consent%20String%20SDK). +For instructions on how to generate the IAB consent string see the [IAB CMP 2 Spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and [IAB Consent String SDK](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/Consent%20String%20SDK). **_gdprApplies_** Use the following values in the _gdprApplies_ field: @@ -411,15 +346,9 @@ Use the following values in the _gdprApplies_ field: - False: It's known that the user is outside the EEA. - Leave the attribute unspecified if user's location is unknown. -**_hasGlobalScope_** -This should be set to true if consent data was retrieved from global "euconsent" cookie, or it was publisher-specific. For general purpose, set this to false. - **_responseCode_** This should be false if there was some error in the consent data; otherwise set to true. False is the same as calling the callback with no parameters. -**_cmpLoaded_** -This should be be set to true once the parameters listed above are processed. - ## Adapters Supporting GDPR Bidders on this list have self-declared their GDPR support in their https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders md file by adding "gdpr_supported: true". diff --git a/dev-docs/modules/consentManagementUsp.md b/dev-docs/modules/consentManagementUsp.md index c365dd0ce5..b1f7c26fe1 100644 --- a/dev-docs/modules/consentManagementUsp.md +++ b/dev-docs/modules/consentManagementUsp.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Consent Management - US Privacy -description: Module to consume and distribute US Privacy information to bidder adapters +description: If you have users in California, this module works with your Consent Management Platform to pass CCPA/US-Privacy data to bidders. module_code : consentManagementUsp display_name : Consent Management - US Privacy enable_download : true +recommended: true sidebarType : 1 --- @@ -26,7 +27,7 @@ sidebarType : 1 This consent management module is designed to support the California Consumer Privacy Act ([CCPA](https://www.iab.com/guidelines/ccpa-framework/)). The IAB has generalized these guidelines to cover future regulations, referring to the feature as "US Privacy." -This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. +This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect. {: .alert.alert-info :} See also the [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagement.html) for supporting the EU General Data Protection Regulation (GDPR) @@ -37,20 +38,28 @@ Here's a summary of the interaction process: 2. Incorporate this data into the auction objects for adapters to collect. 3. Proceed with the auction. -In the the case of a new user, the USP-API will generally respond only after there is notice and opt-out status information available (i.e., the user has made their choices). -Making these selections can take some time for the average user, so the module provides timeout settings. +The IAB USP-API will respond immediately if it is available. The module timeout settings are not related to user selection, but only to API availability. +If the timeout period expires or an error from the USP-API is thrown, the auction proceeds without a US Privacy string attached. -If the timeout period expires or an error from the USP-API is thrown, the auction proceeds without the user's notice and opt-out status information. + The string has four characters: + +{: .table .table-bordered .table-striped } +| String Component | Values | +| --- | --- | +| 1) Specification Version| 1| +| 2) Explicit Notice/Opportunity to Opt Out| (N = No,Y = Yes,– = Not Applicable)| +| 3) Has user opted-out of the sale of his or her personal information?| (N = No,Y = Yes,– = Not Applicable)| +| 4) Publisher is a signatory to the IAB Limited Service Provider Agreement| (N = No,Y = Yes,– = Not Applicable)| ## Page Integration To utilize this module, software that provides the [USP-API](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/USP%20API.md) must to be implemented on the site to interact with the user and obtain their notice and opt-out status. -Though implementation details for the USP-API are not covered by Prebid.org, we do recommend to that you place the code before the Prebid.js code in the head of the page in order to ensure the framework is loaded before the Prebid code executes. +Though implementation details for the USP-API are not covered by Prebid.org, we do recommend to that you place the code before the Prebid.js code in the head of the page in order to ensure the framework is loaded before the Prebid code executes. Many publishers who ensure the prior availability of the `__uspapi` set the timeout parameter to zero. -Once the USP-API is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will then be able to retrieve the notice and opt-out status information and incorporate it in their requests. +Once the USP-API is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Without configuration, Prebid will throw a warning that the module is unconfigured, and will proceed with the default configuration parameter `cmpApi` as 'iab'. Adapters that support this feature will then be able to retrieve the notice and opt-out status information and incorporate it in their requests. Here are the parameters supported in the `consentManagement` object: @@ -59,13 +68,16 @@ Here are the parameters supported in the `consentManagement` object: | --- | --- | --- | --- | | usp | `Object` | | | | usp.cmpApi | `string` | The USP-API interface that is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | -| usp.timeout | `integer` | Length of time (in milliseconds) to allow the USP-API to obtain the CCPA string. Default is `10000`. | `10000` | +| usp.timeout | `integer` | Length of time (in milliseconds) to allow the USP-API to obtain the CCPA string. Default is `50`. | `50` | | usp.consentData | `Object` | An object representing the CCPA notice and opt-out status data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. | | {: .alert.alert-info :} Note that the term 'CMP' (Consent Management Platform) was chosen in Prebid to keep the interface similar to the GDPR implementation, though US-Privacy doesn't specifically use that term. + + + ### Examples Example 1: Support both US Privacy and GDPR @@ -89,7 +101,7 @@ Example 1: Support both US Privacy and GDPR }); {% endhighlight %} -Example 2: Support US Privacy +Example 2: Support US Privacy; timeout the api availability at zero because it is always available if it applies {% highlight js %} var pbjs = pbjs || {}; @@ -99,14 +111,14 @@ Example 2: Support US Privacy consentManagement: { usp: { cmpApi: 'iab', - timeout: 100 // US Privacy timeout 100ms + timeout: 0 // US Privacy timeout 100ms } } }); }); {% endhighlight %} -Example 3: Static CMP using custom data passing. +Example 3: Static CMP using custom data passing. Placing this config call in the command queue before loading Prebid is important to ensure the string is available before Prebid begins making external calls. {% highlight js %} var pbjs = pbjs || {}; @@ -127,6 +139,26 @@ Example 3: Static CMP using custom data passing. }); {% endhighlight %} +Example 4: Static CMP with USP string set to does not apply for all fields, which may be useful to prevent excessive interaction with the `__uspapi` outside of the geographic scope. Placing this config call in the command queue before loading Prebid is important to ensure it is available early. + +{% highlight js %} + var pbjs = pbjs || {}; + pbjs.que = pbjs.que || []; + pbjs.que.push(function() { + pbjs.setConfig({ + consentManagement: { + usp: { + cmpApi: 'static', + consentData: { + getUSPData: { + uspString: '1---' + } + } + } + } + }); + }); +{% endhighlight %} ## Build the Package Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the the **gulp build** command: diff --git a/dev-docs/modules/currency.md b/dev-docs/modules/currency.md index 5f51829cf8..bc8dd3562d 100644 --- a/dev-docs/modules/currency.md +++ b/dev-docs/modules/currency.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Currency -description: Converts bids to the ad server currency +description: Converts bid currency into ad server currency based on data in a supplied exchange rate file. module_code : currency display_name : Currency enable_download : true diff --git a/dev-docs/modules/dchain.md b/dev-docs/modules/dchain.md new file mode 100644 index 0000000000..2106862079 --- /dev/null +++ b/dev-docs/modules/dchain.md @@ -0,0 +1,89 @@ +--- +layout: page_v2 +page_type: module +title: Module - Demand Chain Object +description: Validates the Demand Chain object, provided by bidders, stored in the Prebid bid object. +module_code : dchain +display_name : Demand Chain Object +enable_download : true +sidebarType : 1 +--- + +# Demand Chain Object Module +{:.no_toc} + +* TOC +{:toc} + +Publishers that interact with bidders that support the [IAB Buyers.json and DemandChain Object Specification](https://iabtechlab.com/buyers-json-demand-chain/) may ensure the incoming dchain object complies to the IAB specification, as well as automatically representing the Prebid bidder in the buying process. Including this dchain module can address these concerns and perform the needed tasks automatically for any DChain compliant bidder. + +## How to Use the Module + +First, build the dchain module into your Prebid.js package: +``` +gulp build --modules=dchain,... +``` + +The module will then automatically perform validations on the dchain data, provided by compliant bidders, stored in the Prebid bid object. Assuming the object is present and valid, the module will also include a final node to the dchain object to represent the Prebid.js bidder in its part of the process. + +## DChain Config Syntax + +{: .table .table-bordered .table-striped } +| DChain Param | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| validation | optional | string | `'strict'`: In this mode, dchain object will not be accepted by Prebid.js if it is invalid. Errors are thrown for invalid dchain object. `'relaxed'`: Errors are thrown for an invalid dchain object but the invalid dchain object is still accpeted. `'off'`: No validations are performed and dchain object is accepted as-is. The default value is `'strict'`. | 'strict' | + +For example: +``` +pbjs.setConfig({ + "dchain": { + "validation": "strict" + } +}); +``` + +## Adapter Information + +Adapters who choose to support DChain should assign their ad server's IAB compliant dchain config object to the `bid.meta.dchain` field when creating their Prebid.js bidresponse object. When the module is enabled, this dchain object will be evaluated per the publisher's config settings. + +``` +bid.meta.dchain: { + "complete": 0, + "ver": "1.0", + "ext": {...}, + "nodes": [ + ..., + { + "asi": "domain.com", + "bsid": "123", + "name": "companyname", + ... + }, + ...] +} +``` + +## Adapters Supporting the dchain Module + +{% assign bidder_pages = site.pages | where: "layout", "bidder" %} + +
    +{% for page in bidder_pages %} +
    + {{ page.title }} +
    +{% endfor %} +
    + + + +
    + +## Further Reading + +- [IAB Buyers.json and DemandChain Object Specification](https://iabtechlab.com/buyers-json-demand-chain/) diff --git a/dev-docs/modules/debugging.md b/dev-docs/modules/debugging.md new file mode 100644 index 0000000000..23538a64ff --- /dev/null +++ b/dev-docs/modules/debugging.md @@ -0,0 +1,153 @@ +--- +layout: page_v2 +page_type: module +title: Module - Debugging +description: Debugging tools to intercept bid requests and mock their response +module_code : debugging +display_name : Debugging +enable_download : true +sidebarType : 1 +--- + +# Debugging module + +This module allows to "intercept" bids and replace their contents with arbitrary data for the purposes of testing and development. + +Bids intercepted in this way are never seen by bid adapters or their backend SSPs, but they are nonetheless injected into the auction as if they originated from them. + +{: .pb-alert .pb-alert-warning :} +For convenience, `debugging` configuration is persisted to the browser's session storage, so that you may type `pbjs.setConfig({debugging: ...})` in the console and reload the page to immediately see the effects. This means that you need to remember to **deactivate debuggging (or clear session storage) when you are done**. + + +### Usage example + +The following will intercept all bids for the ad unit with code "test-div", and replace them with mocks that have `cpm: 10`: + +```javascript +pbjs.setConfig({ + debugging: { + enabled: true, + intercept: [ + { + when: { + // intercept all bids that have adUnitCode === 'test-div' + adUnitCode: 'test-div', + }, + then: { + // mock their response with sane defaults and `cpm: 10` + cpm: 10 + } + }, + ] + } +}); +``` + +## Intercept rules + +`intercept` is a list of objects each containing the following: + +{: .table .table-bordered .table-striped } +|Property |Type |Required? |Description| +|---------+------------------+----------+----------------------------------------------------------------------------------------------| +|`when` |Function or Object|yes |[Match rule](#match) - decides which bids should be intercepted by this rule | +|`then` |Function or Object|no |[Replace rule](#replace) - decides the contents of the bids that are intercepted by this rule | +|`options`|Object |no |[Rule options](#options) | + +Rules are evaluated on each bid in the order they are provided: the first one that has a matching `when` definition takes the bid out of the normal auction flow and replaces it according to its `then` definition. + + +### Match rules + +The match rule can be provided as a function that takes the bid request as its only argument and returns `true` if the bid should be intercepted, `false` otherwise. The [example above](#example) could be written as: + +```javascript +pbjs.setConfig({ + debugging: { + enabled: true, + intercept: [ + { + when: (bidRequest) => bidRequest.adUnitCode === 'test-div', + then: { + cpm: 10 + } + } + ] + } +}) +``` + +Alternatively, the rule can be expressed as an object, and it matches if for each `key`-`value` pair: + + - `bidRequest[key] === value`, or + - `value` is a function and `value(bidRequest[key])` is `true`, or + - `value` is a regular expression and it matches `bidRequest[key]`. + +To illustrate, these definitions are equivalent: + +```javascript +{ + when: { + adUnitCode: 'test-div' + } +}; +{ + when: { + adUnitCode: (code) => code === 'test-div' + } +}; +{ + when: { + adUnitCode: /^test-div$/ + } +}; +``` + + +### Replace rules + +The replace rule can be provided as a function that takes the bid request as its only argument and returns an object with the desired response properties. The [first example above](#example) could be written as: + +```javascript +pbjs.setConfig({ + debugging: { + enabled: true, + intercept: [ + { + when: { + adUnitCode: 'test-div', + }, + then: (bidRequest) => ({cpm: 10}) + }, + ] + } +}); +``` + +Alternatively, the rule can be expressed as an object, and its `key`-`value` pairs will appear in the response as follows: + +- if `value` is a function, then `bidResponse[key]` will be set to `value(bidRequest)`; +- otherwise, `bidResponse[key]` will be set to `value`. + +To illustrate, the following definitions are equivalent: + +```javascript +{ + then: { + cpm: 10 + } +}; +{ + then: { + cpm: (bidRequest) => 10 + } +} +``` + + +### Rule options + +{: .table .table-bordered .table-striped } +|Property |Type |Default value |Description | +|---------+------------------+--------------+------------------------------------------------------------------------------------------------------------------------| +|`delay` |Number |0 |Delay (in milliseconds) before intercepted bids are injected into the auction. Can be used to simulate network latency. | diff --git a/dev-docs/modules/dfp_express.md b/dev-docs/modules/dfp_express.md index 598fb1c126..fef264c9db 100644 --- a/dev-docs/modules/dfp_express.md +++ b/dev-docs/modules/dfp_express.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Module - Google Ad Manager Express -description: Simplified installation mechanism for publishers that have Google Ad Manager in their pages +description: A simplified installation mechanism for publishers that have Google Publisher Tag (GPT) ad calls in their pages. module_code : express display_name : Google Ad Manager Express enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/dfp_video.md b/dev-docs/modules/dfp_video.md index 57a3ff9bc2..e9219ac3b6 100644 --- a/dev-docs/modules/dfp_video.md +++ b/dev-docs/modules/dfp_video.md @@ -2,26 +2,27 @@ layout: page_v2 page_type: module title: Module - Google Ad Manager Video -description: Addition of DFP Video to the Prebid package +description: Required for serving instream video through Google Ad Manager. module_code : dfpAdServerVideo -display_name : DFP Video +display_name : Google Ad Manager Video Support enable_download : true +vendor_specific: true sidebarType : 1 --- -# DFP Video +# Google Ad Manager Video {:.no_toc} -This module is required to use the Prebid Instream video examples with DFP Adserver. For instructions showing how to add this module to Prebid.js, see below. +This module is required to use the Prebid Instream video examples with Google Ad Manager. For instructions showing how to add this module to Prebid.js, see below. ### Step 1: Prepare the base Prebid file as usual The standard options: - Build from a locally-cloned git repo -- Receive the email package from the Prebid [Download]({{site.baseurl}}/download.html) page +- Receive the email package from the Prebid [Download](/download.html) page ### Step 2: Integrate into your prebid.js configuration @@ -29,4 +30,4 @@ The method exposes the [`pbjs.adServers.dfp.buildVideoUrl`]({{site.baseurl}}/dev ## Further Reading -+ [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html) ++ [Show Video Ads with GAM](/dev-docs/show-video-with-a-dfp-video-tag.html) diff --git a/dev-docs/modules/dgkeywordRtdProvider.md b/dev-docs/modules/dgkeywordRtdProvider.md index 2153cddc64..217971cc31 100644 --- a/dev-docs/modules/dgkeywordRtdProvider.md +++ b/dev-docs/modules/dgkeywordRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : dgkeywordRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/enrichmentFpdModule.md b/dev-docs/modules/enrichmentFpdModule.md index 833b8c88e7..3a8d60a0c1 100644 --- a/dev-docs/modules/enrichmentFpdModule.md +++ b/dev-docs/modules/enrichmentFpdModule.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Module - First Party Data Enrichment -description: Enriches First Party Data +description: Injects additional data into the auction stream, including: domain, keywords, and page url. module_code : enrichmentFpdModule display_name : First Party Data Enrichment enable_download : true +recommended: true sidebarType : 1 --- @@ -31,22 +32,17 @@ pbjs.setConfig({ ## How it works -When the first auction on the page is run, this module merges a number of values into the `ortb2` object. Specific details below. - -If the publisher needs to refresh the enriched FPD after the first auction, this can be done using a function provided by this module: - -``` -pbjs.refreshFpd(); -``` +At the beginning of each auction, this module merges a number of values into the `ortb2` [requestBids parameter](/dev-docs/publisher-api-reference/requestBids.html). Specific details below. ## Enrichments {: .table .table-bordered .table-striped } | Page Source | ortb2 field | Notes | |---+---+---| -| page URL | site.page | Uses pbjs getRefererInfo().canonicalUrl | -| referer URL | site.ref | Uses pbjs getRefererInfo().referer | -| domain | site.domain | Pulled from the getRefererInfo().canonicalUrl, the host domain is used, with www dropped. | +| page URL | site.page | Uses pbjs getRefererInfo().page | +| referer URL | site.ref | Uses pbjs getRefererInfo().ref | +| host domain | site.domain | Pulled from the getRefererInfo().page the host domain is used with the www component dropped. | +| aggregated domain | site.publisher.domain | The highest level domain in which cookies can be set. | | viewport width | device.w | Hunts for window.innerWidth, window.document.documentElement.clientWidth, window.document.body.clientWidth | | viewport height | device.w | Hunts for window.innerHeight, window.document.documentElement.clientHeight, window.document.body.clientHeight | | meta keywords | site.keywords | Looks for a meta tag. e.g. | diff --git a/dev-docs/modules/floors.md b/dev-docs/modules/floors.md index 054907fa5f..11246f2e6c 100644 --- a/dev-docs/modules/floors.md +++ b/dev-docs/modules/floors.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Price Floors -description: Determine and enforce auction price floors +description: Configure and enforce minimum bids. module_code : priceFloors display_name : Price Floors enable_download : true @@ -17,12 +17,11 @@ sidebarType : 1 ## Overview -The Floors module provides an open source framework in Prebid for Publishers to configure Prebid price floors on their own or to work with a vendor who can provide floors. +The Price Floors Module provides an open source framework in Prebid for Publishers to configure Prebid price floors on their own or to work with a vendor who can provide floors. A ‘floor’ is defined as the lowest CPM price a bid will need to meet for each Prebid auction. It’s a way for publishers to signal to bidders the price to beat, thereby protecting the value of their inventory. -The module provides several ways for Prebid floors to be defined, that are used by bidder adapters to read floors and enforced on bid responses in any supported currency. The floors utilized by the Prebid.js floors module are defined by one or more set of rules containing any or all of the following dimensions: - +The module provides several ways for Prebid floors to be defined, that are used by bidder adapters to read floors and enforced on bid responses in any supported currency. The floors utilized by the Price Floors Module are defined by one or more set of rules containing any or all of the following dimensions: - AdUnit - GPT Slot Name @@ -32,31 +31,34 @@ The module provides several ways for Prebid floors to be defined, that are used - "custom dimensions" {: .alert.alert-warning :} -When using GPT Slot name, the gpt library is required to load first. Failing to do so may yield unexpected results and could impact revenue performance. +When using GPT Slot name, the GPT library is required to load first. Failing to do so may yield unexpected results and could impact revenue performance. -The entire set of Prebid floors selected by the Floors Module for a given auction is called a “Rule Location”. A Rule Location can be any one of: +The entire set of floors selected by the Price Floors Module for a given auction is called a "Rule Location". A Rule Location can be any one of: 1. Within the AdUnit (AdUnit) 2. Within setConfig (Package) 3. Retrieved from a real-time data service (Dynamic) - {: .alert.alert-info :} -Even though floors are defined with five pre-configured dimensions, it’s possible to extend the list of dimensions to attributes of the page, user, auction or other data by supplying a dimension matching function. For example, a publisher can provide a matching function that returns the device type to allow the price floor module to use device type as an attribute within a prebid floor rules file. +Even though floors are defined with five pre-configured dimensions, it’s possible to extend the list of dimensions to attributes of the page, user, auction or other data by supplying a dimension matching function. For example, a publisher can provide a matching function that returns the device type to allow the Floor module to use device type as an attribute within a prebid floor rules file. +Note that Prebid Server also supports a [floors feature](/prebid-server/features/pbs-floors.html) that is very similar to the Prebid.js module. They both share Schema 2, and there are PBS-specific notes below. +The expectation with the Prebid Server floors feature is that +Publishers will use it mainly for mobile app and AMP scenarios. +Web sites running Prebid.js will utilize this client-side module. ## How it Works -There are several places where the Floor module changes the behavior of the Prebid.js auction process. Below is a diagram describing the general flow of the Floors Module: +There are several places where the Floor module changes the behavior of the Prebid.js auction process. Below is a diagram describing the general flow of the Price Floors Module: ![Floors Module Flow](/assets/images/floors/floors_flow.png) -1. When building the Prebid.js package, the Floors module (and any analytics adapters) needs to be included with 'gulp build --modules=priceFloors,...' -2. As soon as the setConfig({floors}) call is initiated, the Floors Module will build an internal hash table for each auction derived from a Rule Location (one of Dynamic, setConfig or adUnit) - - a. If an endpoint URL (a Dynamic Floor) is defined, the Floors Module will attempt to fetch floor data from the Floor Provider's endpoint. When requestBids is called, the Floors Module will delay the auction up to the supplied amount of time in floors.auctionDelay or as soon as the dynamic endpoint returns data, whichever is first. -3. Bid Adapters are responsible for utilizing the getFloors() from the bidRequest object for each ad slot media type, size combination. The Floors Module will perform currency conversion if the bid adapter requests floors in a different currency from the defined floor data currency. +1. When building the Prebid.js package, the Price Floors Module (and any analytics adapters) needs to be included with 'gulp build --modules=priceFloors,...' +2. As soon as the setConfig({floors}) call is initiated, the Price Floors Module will build an internal hash table for each auction derived from a Rule Location (one of Dynamic, setConfig or adUnit) + - a. If an endpoint URL (a Dynamic Floor) is defined, the Price Floors Module will attempt to fetch floor data from the Floor Provider's endpoint. When requestBids is called, the Price Floors Module will delay the auction up to the supplied amount of time in floors.auctionDelay or as soon as the dynamic endpoint returns data, whichever is first. +3. Bid Adapters are responsible for utilizing the getFloor() from the bidRequest object for each ad slot media type, size combination. The Price Floors Module will perform currency conversion if the bid adapter requests floors in a different currency from the defined floor data currency. 4. Bid Adapters will pass the floor values to their bidding endpoints, to request bids, responding with any bids that meet or exceed the provided floor -5. Bid adapters will submit bids to back to Prebid core, where the Floors Module will perform enforcement on each bid -6. The Floors Module will mark all bids below the floor as bids rejected. Prebid core will submit all eligible bids to the publisher ad server - - a. The Floors module emits floor event / bid data to Analytics adapters to allow Floor Providers a feedback loop on floor performance for model training +5. Bid adapters will submit bids to back to Prebid core, where the Price Floors Module will perform enforcement on each bid +6. The Price Floors Module will mark all bids below the floor as bids rejected. Prebid core will submit all eligible bids to the publisher ad server + - a. The Price Floors Module emits floor event / bid data to Analytics adapters to allow Floor Providers a feedback loop on floor performance for model training ## Defining Floors @@ -107,7 +109,7 @@ Below are some basic principles of ad unit floor definitions: {% endhighlight %} {: .alert.alert-info :} -When defining floors at the adUnit level, the Floors Module requires the floors object to be defined in setConfig, even if the definition is an empty object as shown below: {% highlight js %}pbjs.setConfig({ floors: {} });{% endhighlight %} +When defining floors at the adUnit level, the Price Floors Module requires the floors object to be defined in setConfig, even if the definition is an empty object as shown below: {% highlight js %}pbjs.setConfig({ floors: {} });{% endhighlight %} Floor definitions are set in the “values” object containing one or more rules, where the rule is the criteria that needs to be met for that given ad unit, with an associated CPM floor. In the above example, the floors are enforced when the bid from a bidder matches the “mediaType” and “size” combination. Since many bid adapters are not able to ingest floors per size, a simpler setup can be: @@ -126,7 +128,7 @@ floors: { } {% endhighlight %} -For more advanced publisher setups, values can accept a “\*” to denote a catch all when a bid comes back that the floors module does not have an exact match and for bid adapters who are not able to use a floor per size, the bid adapter will automatically receive the “\*” rule’s floor if available. Example setup can be: +For more advanced publisher setups, values can accept a “\*” to denote a catch-all when a bid comes back that the Price Floors Module does not have an exact match and for bid adapters who are not able to use a floor per size, the bid adapter will automatically receive the “\*” rule’s floor if available. Example setup can be: {% highlight js %} floors: { @@ -191,7 +193,7 @@ pbjs.setConfig({ }); {% endhighlight %} -By defining floor data with setConfig, the Floors module will map GPT ad slots to AdUnits as needed. It does this in the same way as the setTargetingForGPTAsync() function – first looking for an AdUnit.code that matches the slot name, then looking for an AdUnit.code that matches the div id of the named GPT slot. +By defining floor data with setConfig, the Price Floors Module will map GPT ad slots to AdUnits as needed. It does this in the same way as the setTargetingForGPTAsync() function – first looking for an AdUnit.code that matches the slot name, then looking for an AdUnit.code that matches the div id of the named GPT slot. Here’s another example that includes more fields: @@ -206,10 +208,10 @@ pbjs.setConfig({ fields: [ 'domain', 'gptSlot', 'mediaType', 'size'] }, values: { - 'www.plublisher.com|/1111/homepage/top-rect|banner|300x250': 0.80, - 'www.publisher.com|/1111/homepage/top-rect|video|300x250': 2.20, - 'www.plublisher.com|/1111/homepage/left-nav|banner|300x250': 1.77, - 'www.publisher.com|/1111/homepage/left-nav|video|300x250': 2.88 + 'www.examplepub.com|/1111/homepage/top-rect|banner|300x250': 0.80, + 'www.examplepub.com|/1111/homepage/top-rect|video|300x250': 2.20, + 'www.examplepub.com|/1111/homepage/left-nav|banner|300x250': 1.77, + 'www.examplepub.com|/1111/homepage/left-nav|video|300x250': 2.88 ... } } @@ -240,7 +242,7 @@ pbjs.setConfig({ }); {% endhighlight %} -The floors module is flexible to handle floors set in multiple locations. Like in the below example a publisher can configure Dynamic floors in addition to Package floors (in setConfig). While the floors module is only able to use one set of rules (either Package, adUnit or Dynamic) defined as a Floor Location, setting floors in the Package will be utilized when the Dynamic floors fail to return data or another error condition occurs with the Dynamic fetch. +The Price Floors Module is flexible to handle floors set in multiple locations. Like in the below example a publisher can configure Dynamic floors in addition to Package floors (in setConfig). While the Price Floors Module is only able to use one set of rules (either Package, adUnit or Dynamic) defined as a Floor Location, setting floors in the Package will be utilized when the Dynamic floors fail to return data or another error condition occurs with the Dynamic fetch. {% highlight js %} pbjs.setConfig({ @@ -272,36 +274,40 @@ pbjs.setConfig({ ## Floors Syntax -The examples above covered several different scenarios where floors can be applied. Below we will cover the syntax and definition of the floors data schema. As of Prebid.js version 3.24, the Floors module supports a second data schema with the ability to add new schemas to future-proof the needs of additional design changes while keeping backwards compatibility. +The examples above covered several different scenarios where floors can be applied. Below we will cover the syntax and definition of the floors data schema. As of Prebid.js version 3.24, the Price Floors Module supports a second data schema with the ability to add new schemas to future-proof the needs of additional design changes while keeping backwards compatibility. ### Schema 1 Schema 1 restricts floors providers or publishers to applying only one data group. To test more than one floor group, floor providers or publishers are required to reset the data set with new rules after each request bids. +{: .alert.alert-info :} +Note: if you're a dynamic floor provider service, your response must be +a subset that will be merged under the 'data' object. + {: .table .table-bordered .table-striped } | Param | Type | Description | Default | |---+---+---+---+---| -| floorMin | float | The mimimum CPM floor used by the Floors Module (as of 4.13). The Floors Module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. | - | +| floorMin | float | The mimimum CPM floor used by the Price Floors Module (as of 4.13). The Price Floors Module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. | - | | floorProvider | string | Optional atribute (as of prebid version 4.1) used to signal to the Floor Provider's Analytics adapter their floors are being applied. They can opt to log only floors that are applied when they are the provider. If floorProvider is supplied in both the top level of the floors object and within the data object, the data object's configuration shall prevail.| - | -| enforcement | object | Controls the enforcement behavior within the Floors Module.| - | -| skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | -| enforcement.enforceJS | boolean | If set to true, the floors module will provide floors to bid adapters for bid request matched rules and suppress any bids not exceeding a matching floor. If set to false, the prebid floors module will still provide floors for bid adapters, there will be no floor enforcement.| true | -| enforcement.enforcePBS | boolean | If set to true, the Prebid.js floors module will signal to Prebid Server to pass floors to it’s bid adapters and enforce floors. If set to false, the pbjs should still pass matched bid request floor data to PBS, however no enforcement will take place. | false | +| enforcement | object | Controls the enforcement behavior within the Price Floors Module.| - | +| skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Price Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | +| enforcement.enforceJS | boolean | If set to true, the Price Floors Module will provide floors to bid adapters for bid request matched rules and suppress any bids not exceeding a matching floor. If set to false, the Price Floors Module will still provide floors for bid adapters, there will be no floor enforcement.| true | +| enforcement.enforcePBS | boolean | If set to true, the Price Floors Module will signal to Prebid Server to pass floors to it’s bid adapters and enforce floors. If set to false, the pbjs should still pass matched bid request floor data to PBS, however no enforcement will take place. | false | | enforcement.floorDeals | boolean | Enforce floors for deal bid requests. | false | -| enforcement.bidAdjustment | boolean | If true, the Floors Module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | -| endpoint | object | Controls behavior for dynamically retrieving floors. | - | +| enforcement.bidAdjustment | boolean | If true, the Price Floors Module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | +| endpoint | object | Prebid.js only: controls behavior for dynamically retrieving floors. | - | | endpoint.url | string | URL of endpoint to retrieve dynamic floor data. | - | -| data | object (required) | Floor data used by the Floors Module to pass floor data to bidders and floor enforcement. | - | +| data | object (required) | Floor data used by the Price Floors Module to pass floor data to bidders and floor enforcement. | - | | data.floorProvider | string | Optional atribute (as of prebid version 4.2) used to signal to the Floor Provider's Analytics adapter their floors are being applied. They can opt to log only floors that are applied when they are the provider. If floorProvider is supplied in both the top level of the floors object and within the data object, the data object's configuration shall prevail.| - | | data.currency | string | Currency of floor data. Floor Module will convert currency where necessary. See Currency section for more details. | 'USD' | -| data.skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | -| data.floorsSchemaVersion | string | The Floors Module supports two versions of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the Floors Module will assume version 1 for the sake of backwards compatiblity. For schema version 2 see the next section. | 1 | +| data.skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Price Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | +| data.floorsSchemaVersion | integer | The module supports two versions of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the module will assume version 1 for the sake of backwards compatiblity. For schema version 2 see the next section. | 1 | | data.modelVersion | string | Used by floor providers to train on model version performance. The expectation is a floor provider’s analytics adapter will pass the model verson back for algorithm training. | - | -| data.modelTimestamp | int | Epoch timestamp associated with modelVersion. Can be used to track model creation of floor file for post auction analysis.| - | +| data.modelTimestamp | integer | Epoch timestamp associated with modelVersion. Can be used to track model creation of floor file for post auction analysis.| - | | data.schema | object |allows for flexible definition of how floor data is formatted. | - | | data.schema.delimiter | string | Character separating the floor keys. | '\|' | -| data.schema.fields | array of strings | Supported values are: gptSlot, adUnitCode, mediaType, size | - | +| data.schema.fields | array of strings | Supported values are: gptSlot, adUnitCode, mediaType, size, domain | - | | data.values | key / values | A series of attributes representing a hash of floor data in a format defined by the schema object. | - | | data.values."rule key" | string | Delimited field of attribute values that define a floor. | - | | data.values."rule floor value" | float | The floor value for this key. | - | @@ -314,54 +320,63 @@ Schema 1 restricts floors providers or publishers to applying only one data grou ### Schema 2 -Schema 2 allows floors providers to A / B one or more floor groups, determined at auction time. +Schema 2 allows floors providers to A/B-test one or more floor groups, determined at auction time. -The following principles apply to schema 2: -- The below attributes are required: +The following principles apply to Schema 2: +- These attributes are required: - data.floorsSchemaVersion to be set to 2 - A valid modelGroups object must be set - The field modelGroups.modelWeight is required for each model group - - If one of the model weights is missing, no schema 2 floor will be set and the Floors Module will look in other locations for floor definitions + - If one of the model weights is missing, no schema 2 floor will be set and the Price Floors Module will look in other locations for floor definitions - If common attributes are set in both the modelGroups and root level of the data object, modelGroups attributes prevail - The Schema 2 data model can only be applied in Package level (i.e. directly in setConfig) or Dynamic level -- Sampling weights are applied at the auction level. Each new auction the dice will be rolled +- Sampling weights are applied at the auction level. Each new auction the dice will be rolled. - If the data.modelGroups object and the data.values (schema 1 field) are set, the data.floorsSchemaVersion will dictate what schema version is applied - While some attributes are common in both schema versions, for completeness, all valid schema 2 attributes are provided: +{: .alert.alert-info :} +Note: if you're a dynamic floor provider service, your response must be +a subset that will be merged under the 'data' object. + {: .table .table-bordered .table-striped } | Param | Type | Description | Default | |---+---+---+---+---| -| floorMin | float | The mimimum CPM floor used by the Floors Module (as of 4.13). The Floors Module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. | - | +| floorMin | float | The mimimum CPM floor used by the module (as of 4.13). The module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. | - | +| floorMinCur | float | Prebid Server only: the currency used for the floorMin value. | - | | floorProvider | string | Optional atribute (as of prebid version 4.1) used to signal to the Floor Provider's Analytics adapter their floors are being applied. They can opt to log only floors that are applied when they are the provider. If floorProvider is supplied in both the top level of the floors object and within the data object, the data object's configuration shall prevail.| - | -| enforcement | object | Controls the enforcement behavior within the Floors Module.| - | -| skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | -| enforcement.enforceJS | boolean | If set to true, the floors module will provide floors to bid adapters for bid request matched rules and suppress any bids not exceeding a matching floor. If set to false, the prebid floors module will still provide floors for bid adapters, but there will be no floor enforcement.| true | -| enforcement.enforcePBS | boolean | If set to true, the Prebid.js floors module will signal to Prebid Server to pass floors to it’s bid adapters and enforce floors. If set to false, Prebid.js should still pass matched bid request floor data to Prebid Server, however no enforcement will take place. | false | +| skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail. | 0 | +| enabled | boolean | Prebid Server only: provides a request level override to disable server-side floor activity. If there's server-side floor config, it must also be true in order for floor activity to take place. | true | +| fetchStatus | string | Prebid Server only: this is a read-only field set by the Prebid-Server floors feature to let analytics adapters know whether the floors data used was dynamically fetched. | n/a | +| skipped | boolean | Prebid Server only: this is a read-only field set by the Prebid-Server floors feature to let analytics adapters know whether the 'skipRate' feature was invoked. i.e. this value is 'true' when the floor activity has been turned off by the skipRate, and 'false' otherwise. | n/a | +| location | string | Prebid Server only: this is a read-only field set by the Prebid-Server floors feature to let analytics adapters know where the floors data came from. Possible values are: 'request', 'fetch' or 'noData'. | n/a | +| enforcement | object | Controls the enforcement behavior within the module.| - | +| enforcement.enforceJS | boolean | If set to true, the module will provide floors to bid adapters for bid request matched rules and suppress any bids not exceeding a matching floor. If set to false, the module will still provide floors for bid adapters, but there will be no floor enforcement.| true | +| enforcement.enforcePBS | boolean | If set to true, the module will signal to Prebid Server to pass floors to it’s bid adapters and enforce floors. If set to false, Prebid.js should still pass matched bid request floor data to Prebid Server, however no enforcement will take place. | false | | enforcement.floorDeals | boolean | Enforce floors for deal bid requests. | false | -| enforcement.bidAdjustment | boolean | If true, the Floors Module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | +| enforcement.bidAdjustment | boolean | If true, the module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | +| enforcement.enforceRate | integer | Prebid Server only: Defines a percentage for how often bid response enforcement activity should take place given that the floors feature is active. If the floors feature is skipped due to skipRate, this has no affect. For every non-skipped auction, this percent of them should be enforced: i.e. bids discarded. This feature lets publishers ease into enforcement in case bidders aren't adhering to floor rules. | 100 | | endpoint | object | Controls behavior for dynamically retrieving floors. | - | | endpoint.url | string | URL of endpoint to retrieve dynamic floor data. | - | -| data | object (required) | Floor data used by the Floors Module to pass floor data to bidders and floor enforcement. | - | +| data | object (required) | Floor data used by the module to pass floor data to bidders and floor enforcement. | - | | data.floorProvider | string | Optional atribute (as of prebid version 4.2) used to signal to the Floor Provider's Analytics adapter their floors are being applied. They can opt to log only floors that are applied when they are the provider. If floorProvider is supplied in both the top level of the floors object and within the data object, the data object's configuration shall prevail.| - | -| data.currency | string | Currency of floor data. Floors Module will convert currency where necessary. See Currency section for more details. | 'USD' | -| data.skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Floors Module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail.| 0 | -| data.floorsSchemaVersion | string | The Floors Module supports two version of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the Floors Module will assume version 1 for the sake of backwards compatiblity.| 1 | +| data.currency | string | Currency of floor data. The module will convert currency where necessary. See Currency section for more details. | 'USD' | +| data.skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail.| 0 | +| data.floorsSchemaVersion | string | The module supports two version of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the module will assume version 1 for the sake of backwards compatiblity.| 1 | | data.modelTimestamp | int | Epoch timestamp associated with modelVersion. Can be used to track model creation of floor file for post auction analysis.| - | | data.modelGroups | array of objects | Array of model objects to be used for A/B sampling multiple models. This field is only used when data.floorsSchemaVersion = 2 | - | | data.modelGroups[].currency | string | Currency of floor data. Floor Module will convert currency where necessary. See Currency section for more details. | 'USD' | -| data.modelGroups[].skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the Floors Module is in floors mode. | 0 | +| data.modelGroups[].skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. | 0 | | data.modelGroups[].modelVersion | string | Used by floor providers to train on model version performance. The expectation is a floor provider’s analytics adapter will pass the model verson back for algorithm training. | - | -| data.modelGroups[].modelWeight | integer | Used by the Floors Module to determine when to apply the specific model. All weights will be normalized and appllied at runtime. Futher clarification will be provided in examples below. | - | -| data.schema | object | Allows for flexible definition of how floor data is formatted. | - | +| data.modelGroups[].modelWeight | integer | Used by the module to determine when to apply the specific model. All weights will be normalized and applied at runtime. Futher clarification will be provided in examples below. | - | +| data.modelGroups[].schema | object | Allows for flexible definition of how floor data is formatted. | - | | data.modelGroups[].schema.delimiter | string | Character separating the floor keys. | '\|' | | data.modelGroups[].schema.fields | array of strings | Supported pre-defined values are: gptSlot, adUnitCode, mediaType, size | - | | data.modelGroups[].values | key / values | A series of attributes representing a hash of floor data in a format defined by the schema object. | - | | data.modelGroups[].values."rule key" | string | Delimited field of attribute values that define a floor. | - | | data.modelGroups[].values."rule floor value" | float | The floor value for this key. | - | | data.modelGroups[].default | float | Floor used if no matching rules are found. | - | -| additionalSchemaFields | object | Object contain the lookup function to map custom schema.fields | - | +| additionalSchemaFields | object | Object contain the lookup function to map custom schema.fields. Not supported by Prebid Server. | - | | additionalSchemaFields."custom key" | string | custom key name | - | | additionalSchemaFields."key map function" | function | Function used to lookup the value for that particular custom key | - | @@ -370,65 +385,70 @@ While some attributes are common in both schema versions, for completeness, all Model weights add up to 100 and are sampled at a 25%, 25%, 50% distribution. Additionally, each model group has diffirent schema fields: {% highlight js %} -{ - "currency": "EU", - "skipRate": 20, - "floorsSchemaVersion":2, - "modelGroups": [ - { - "modelWeight":25, - "modelVersion": "Model1", - "schema": { - "fields": [ "domain", "gptSlot", "mediaType", "size" ] - }, - "values": { - "www.publisher.com|/1111/homepage/top-banner|banner|728x90": 1.00, - "www.publisher.com|/1111/homepage/top-rect|banner|300x250": 1.20, - "www.publisher.com|/1111/homepage/top-rect|banner|300x600": 1.80, - ... - "www.domain.com|/1111/homepage/top-banner|banner|728x90": 2.11 - ... - "www.publisher.com|*|*|*": 0.80, - }, - "default": 0.75 - }, - { - "modelWeight": 25, - "modelVersion": "Model2", - "schema": { - "fields": [ "domain", "mediaType", "size" ] - }, - "values": { - "www.publisher.com|banner|728x90": 1.00, - "www.publisher.com|banner|300x250": 1.20, - "www.publisher.com|banner|300x600": 1.80, - ... - "www.domain.com|banner|728x90": 2.11 - ... - "www.publisher.com|*|*|*": 0.80, - }, - "default": 0.75 - }, - { - "modelWeight": 50, - "modelVersion": "Model3", - "schema": { - "fields": [ "gptSlot", "mediaType", "size" ] - }, - "values": { - "/1111/homepage/top-banner|banner|728x90": 1.00, - "/1111/homepage/top-rect|banner|300x250": 1.20, - "/1111/homepage/top-rect|banner|300x600": 1.80, - ... - "/1111/homepage/top-banner|banner|728x90": 2.11 - ... - "*|banner|*": 0.80, - }, - "default": 0.75 - } - ] - -} +pbjs.setConfig({ + floors: { + enforcement: { ... }, + ... + data: { + "currency": "EU", + "skipRate": 20, + "floorsSchemaVersion":2, + "modelGroups": [ + { + "modelWeight":25, + "modelVersion": "Model1", + "schema": { + "fields": [ "domain", "gptSlot", "mediaType", "size" ] + }, + "values": { + "www.publisher.com|/1111/homepage/top-banner|banner|728x90": 1.00, + "www.publisher.com|/1111/homepage/top-rect|banner|300x250": 1.20, + "www.publisher.com|/1111/homepage/top-rect|banner|300x600": 1.80, + ... + "www.domain.com|/1111/homepage/top-banner|banner|728x90": 2.11 + ... + "www.publisher.com|*|*|*": 0.80, + }, + "default": 0.75 + }, + { + "modelWeight": 25, + "modelVersion": "Model2", + "schema": { + "fields": [ "domain", "mediaType", "size" ] + }, + "values": { + "www.publisher.com|banner|728x90": 1.00, + "www.publisher.com|banner|300x250": 1.20, + "www.publisher.com|banner|300x600": 1.80, + ... + "www.domain.com|banner|728x90": 2.11 + ... + "www.publisher.com|*|*|*": 0.80, + }, + "default": 0.75 + }, + { + "modelWeight": 50, + "modelVersion": "Model3", + "schema": { + "fields": [ "gptSlot", "mediaType", "size" ] + }, + "values": { + "/1111/homepage/top-banner|banner|728x90": 1.00, + "/1111/homepage/top-rect|banner|300x250": 1.20, + "/1111/homepage/top-rect|banner|300x600": 1.80, + ... + "/1111/homepage/top-banner|banner|728x90": 2.11 + ... + "*|banner|*": 0.80, + }, + "default": 0.75 + } + ] + } + } +}); {% endhighlight %} *Example 2* @@ -439,66 +459,69 @@ model2 = 50 -> 50 / (20 + 50) = 71% of auctions model 2 will be applied Additionally skipRate is supplied at model group level where model1 will skip floors 20% of times when model1 is selected, whereas model2 will skip 50% of auctions when model2 is selected. {% highlight js %} -{ - "currency": "EU", - "floorsSchemaVersion":2, - "modelGroups": [ - { - "modelWeight":25, - "skipRate": 20, - "modelVersion": "Model1", - "schema": { - "fields": [ "domain", "gptSlot", "mediaType", "size" ] - }, - "values": { - "www.publisher.com|/1111/homepage/top-banner|banner|728x90": 1.00, - "www.publisher.com|/1111/homepage/top-rect|banner|300x250": 1.20, - "www.publisher.com|/1111/homepage/top-rect|banner|300x600": 1.80, - ... - "www.domain.com|/1111/homepage/top-banner|banner|728x90": 2.11 - ... - "www.publisher.com|*|*|*": 0.80, - }, - "default": 0.75 - }, - { - "modelWeight": 50, - "skipRate": 50, - "modelVersion": "Model2", - "schema": { - "fields": [ "gptSlot", "mediaType", "size" ] - }, - "values": { - "/1111/homepage/top-banner|banner|728x90": 1.00, - "/1111/homepage/top-rect|banner|300x250": 1.20, - "/1111/homepage/top-rect|banner|300x600": 1.80, - ... - "/1111/homepage/top-banner|banner|728x90": 2.11 - ... - "*|banner|*": 0.80, - }, - "default": 0.75 - } - ] - -} +pbjs.setConfig({ + floors: { + enforcement: { ... }, + ... + data: { + "currency": "EU", + "floorsSchemaVersion":2, + "modelGroups": [ + { + "modelWeight":25, + "skipRate": 20, + "modelVersion": "Model1", + "schema": { + "fields": [ "domain", "gptSlot", "mediaType", "size" ] + }, + "values": { + "www.publisher.com|/1111/homepage/top-banner|banner|728x90": 1.00, + "www.publisher.com|/1111/homepage/top-rect|banner|300x250": 1.20, + "www.publisher.com|/1111/homepage/top-rect|banner|300x600": 1.80, + ... + "www.domain.com|/1111/homepage/top-banner|banner|728x90": 2.11 + ... + "www.publisher.com|*|*|*": 0.80, + }, + "default": 0.75 + }, + { + "modelWeight": 50, + "skipRate": 50, + "modelVersion": "Model2", + "schema": { + "fields": [ "gptSlot", "mediaType", "size" ] + }, + "values": { + "/1111/homepage/top-banner|banner|728x90": 1.00, + "/1111/homepage/top-rect|banner|300x250": 1.20, + "/1111/homepage/top-rect|banner|300x600": 1.80, + ... + "/1111/homepage/top-banner|banner|728x90": 2.11 + ... + "*|banner|*": 0.80, + }, + "default": 0.75 + } + ] + } + } +}); {% endhighlight %} ## Custom Schema Fields -Custom schema fields are fields the Floors Module does not support out of the box. To use a custom schema field, one needs to perform twp steps: +Out of the box, the Price Floors Module only supports looking up floors by AdUnit, GPT Slot, MediaType, ad size, and domain. Custom schema fields can be added to support other lookup dimensions. Here are the steps: -1. Create lookup function to give the Floors Module context of the value of custom fields for that given auction +1. Create a lookup function to give context of the value of custom fields for that given auction 1. Define, Set and Map Custom Schema Attributes ### Create Lookup Function -Create a function to allow the Floors Module to understand context of a given auction. In the below example, we must create a lookup function to give the Floors Module what deviceType this auction is. - -Here is an example lookup function: +Create a function to allow the module to understand context of a given auction. In the below example, a lookup function provides details about what deviceType this auction is for. +e.g. {% highlight js %} - function deviceTypes (bidRequest, bidResponse) { //while bidRequest and bidResponse are not required for this function, they are available for custom attribute mapping @@ -517,9 +540,9 @@ Here is an example lookup function: ### Define, Set and Map Custom Schema Attributes -After defining a lookup function for the given context of the auction, the custom schema field(s) need to be defined in the `floors.schema.fields` array. Once your custom field is defined you can assign rule values in `floors.data.values` derived from said field(s). The last step would be to supply the lookup function(s) that map from each custom field to a value of the context wthin that auction by using the `floors.additionalSchemaFields` attribute as seen below. +After defining a lookup function for the given context of the auction, the custom schema field(s) need to be defined in the `floors.schema.fields` array. Once your custom field is defined you can assign rule values in `floors.data.values` derived from these field(s). The last step would be to supply the lookup function(s) that map from each custom field to a value of the context wthin that auction by using the `floors.additionalSchemaFields` attribute as seen below. -In the below example, `deviceType` is a custom field not currently supported by default in the Floors Module whose values are one of "mobile", "desktop" or "tablet". +In the below example, `deviceType` is a custom field not currently supported by default in the Price Floors Module whose values are one of "mobile", "desktop" or "tablet". {% highlight js %} @@ -554,28 +577,26 @@ In the below example, `deviceType` is a custom field not currently supported by {% endhighlight %} - - ## Rule Handling ### Rule Location Priority -As defined in the overview, a Rule Location is where a particular rule is located, either defined in the Ad Unit, within setConfig or via a fetch from the browser (named Dynamic) for fresh rules. It may be possible (rather more than likely) that floor rules can be set in one or more locations for a given Prebid auction (i.e. on requestBids). At auction, the Floors Module will only ever use rules from one Rule Location, decided at run-time. Each auction will be assigned an immutable set of rules from one Rule Location, even if the rules change prior to auction complete. +As defined in the overview, a Rule Location is where a particular rule is located, either defined in (1) the Ad Unit, (2) within setConfig or (3) via a fetch from the browser. It's likely that floor rules are set in one or more location for a given Prebid auction. During an auction, the Price Floors Module will only ever use rules from one Rule Location, decided at run-time. Each auction will be assigned an immutable set of rules from one Rule Location, even if the rules change prior to auction complete. -The Floors Module will use the below prioritization scheme on determining which Rule Location is selected at run-time: +The module uses the below prioritization scheme on determining which Rule Location is selected at run-time: -- Dynamic +- dynamic - setConfig - adUnit ### Rule Selection Process -The job of the Prebid floors module is to select a matching Prebid floor rule for enforcement \(when a bid adapter bids in the auction\) given the context of each Ad Unit. With the usage of “\*” values in rules definitions \(where “\*” applies when no specific value matches\) multiple Prebid floor rules can match for a given ad unit auction. +The job of the Price Floors Module is to select a matching floor rule for enforcement given the context of each Ad Unit. With the usage of “\*” values in rules definitions multiple floor rules can match for a given ad unit auction. -The Prebid Floors module algorithm will produce a list of every possible permutation for each ad unit auction based on the defined schema types. The best matching rule for each enforced bid request and getFloor is based on specificity of values \(meaning match an exact value\) weighted from left to right, where the specificity of a value in the left most column would match over a rule with it’s “\*” equivalent if “\*” is supplied. +The module algorithm will produce a list of every possible permutation for each ad unit auction based on the defined schema types. The best matching rule for each enforced bid request and call to `getFloor()` is based on specificity of values \(meaning match an exact value\) weighted from left to right, where the specificity of a value in the left most column would match over a rule with its “\*” equivalent if “\*” is supplied. -Priority order behavior where “\_” is a specific value, and the “\*” is a catch all +Priority order behavior where “\_” is a specific value, and the “\*” is a catch-all Priority order for one column rule sets: @@ -595,7 +616,6 @@ Priority order for three column rule sets: \_ \| \_ \| \* \_ \| \* \| \_ \* \| \_ \| \_ - \* \| \_ \| \* \_ \| \* \| \* \* \| \_ \| \* \* \| \* \| \_ @@ -646,7 +666,7 @@ mediaType = banner Size = 300x600 Domain context = www.website.com -The Price Floor Module produces an internal hash table of all possible permutations of “banner”, “300x600”, “www.website.com” and “\*” with the most specific hash values up top, weighting rules priority from left column specific values to right. Each left value will weigh more than the subsequent column’s specific values. The Floors Module attempt to find the matching rule by cycling through each below possible rule (from top to bottom) against the above rule provider data set. +The Floor module produces an internal hash table of all possible permutations of “banner”, “300x600”, “www.website.com” and “\*” with the most specific hash values up top, weighting rules priority from left column specific values to right. Each left value will weigh more than the subsequent column’s specific values. The module attempts to find the matching rule by cycling through each below possible rule (from top to bottom) against the above rule provider data set. {% highlight js %} { @@ -832,12 +852,10 @@ Enforced floor: 10.01 ### Floor Data Provider Interface -Floor data providers can supply data to publishers either within the setConfig as part of a Prebid.js Package if the provider is also a host provider of the Prebid library, or via a real-time Dynamic fetch, prior to the auction. +Floor data can be supplied to publishers either within the setConfig as part of a Prebid.js Package if the provider is also a host provider of the Prebid library, or via a real-time Dynamic fetch, prior to the auction. Data providers can optionally build Analytics Adapters to ingest bid data within Prebid for algorithm learning and review floor performance. Please refer to the Analytics Interface section for more details. - - {% capture warning_note %} As a floor provider, your goal is to provide effective floors, with minimal page impact. If you are performing a Dynamic fetch to retrieve data prior to auctions, the following recommendations are advised to reduce page performance issues: @@ -845,14 +863,13 @@ As a floor provider, your goal is to provide effective floors, with minimal page - Work with publishers on setting appropriate auction delays to retrieve dynamic data - Implement client-side caching (such as max-age headers) whenever possible - Evaluate data freshness vs frequency of new fetches to the CDN to reduce unnecessary calls -- Be aware of file sizes returned to the browser, implementing trimmiming algorithms for extremely large data sets +- Be aware of file sizes returned to the browser, implementing trimming algorithms for extremely large data sets {% endcapture %} {% include /alerts/alert_important.html content=warning_note %} -For Dynamic fetches, the floors module will perform a GET request to the supplied endpoint, that must return valid JSON, formatted like the data object in the “setConfig” Package configuration. +For Dynamic fetches, the Price Floors Module will perform a GET request to the supplied endpoint, that must return valid JSON, which will be merged into the data object in the “setConfig” Package configuration. In otherwords, the schema used for dynamic fetches is a subset of the full schema. - -On rule creation, we recommend supplying various rules with catch all \(“\*”\) values with associated floors. This is to accommodate bid adapters who cannot retrieving floors on a per size basis, as well as using various permutations of rules with “\*” values to match auctions that do not have an exact match on a specific rule. Please refer to the Rule Selection Process when determining floors as attribute order and number of “\*”s may have an impact on which rule is selected. +On rule creation, we recommend supplying various rules with catch-all \(“\*”\) values with associated floors. This is to accommodate bid adapters who cannot retrieve floors on a per size basis, as well as using various permutations of rules with “\*” values to match auctions that do not have an exact match on a specific rule. Please refer to the Rule Selection Process when determining floors as attribute order and number of “\*”s may have an impact on which rule is selected. #### Example Dynamic fetch @@ -872,9 +889,9 @@ pbjs.setConfig({ {% endhighlight %} -#### Example Response 1 +#### Example Dynamic Response 1 - Schema 1 -floor determined by AdUnit code and Media Type: +In this example, the floor is determined by AdUnit code and Media Type. Note that the response does not contain the 'data' object because everything in the response is merged there. {% highlight js %} @@ -898,9 +915,9 @@ floor determined by AdUnit code and Media Type: {% endhighlight %} -#### Example Response 2 +#### Example Response 2 - Schema 1 -floor determined by Domain, GPT Slot, Media Type and Size: +In this example, the floor is determined by Domain, GPT Slot, Media Type and Size: {% highlight js %} @@ -908,6 +925,7 @@ floor determined by Domain, GPT Slot, Media Type and Size: currency: 'EU', skipRate: 20, modelVersion: ‘High_skip_rate’ + schema: { fields: [ 'domain', 'gptSlot', 'mediaType', 'size' ] }, @@ -926,12 +944,11 @@ floor determined by Domain, GPT Slot, Media Type and Size: {% endhighlight %} -#### Example Response 3 +#### Example Response 3 - Schema 2 -Floors Schema version 2 +In this example, the floor is determined by domain, gptSlot, mediaType, and size. Note again that dynamic floor responses are merged into the 'data' level of the schema. {% highlight js %} - { "currency": "USD", "floorsSchemaVersion":2, @@ -980,31 +997,29 @@ Floors Schema version 2 ### Bid Adapter Interface -The Prebid Floors Module is capable of handling an arbitrarily large set of floor rules of any combination of supported dimensions. To reduce the need for each bid adapter to process each and every rule in the selected rule data set, an encapsulated function (getFloor) was created to allow bid adapters to query the Floors Module for a floor for each mediaType, size and currency the bid adapter needs. - -If the price floors module is enabled for a given auction, the Floors Module will add to the bidRequest object the getFloor function. All bid adapters are recommended to call getFloor to retrieve a desired floor. The job of the getFloor function will be to return the floor CPM of a matched rule based on the rule selection process (written out above), using the getFloor inputs. +The Prebid Floors Module is capable of handling an arbitrarily large set of floor rules of any combination of supported dimensions. To reduce the need for each bid adapter to process each and every rule in the selected rule data set, an encapsulated function (getFloor) was created to allow bid adapters to query the module for a floor for each mediaType, size and currency the bid adapter needs. -Intended changes for bid adapters: +If the Price Floors Module is enabled for a given auction, it will add the getFloor() function to the bidRequest object. All bid adapters are recommended to call the getFloor() to retrieve a desired floor. The job of this function is to return the floor CPM of a matched rule based on the rule selection process (written out above), using the getFloor() inputs. +Changes for bid adapters: -1. Check for presence of getFloor within the bidRequest obect -1. If getFloors exists, call getFloor with desired parameters +1. Check for presence of getFloor() within the bidRequest obect +1. If getFloor() exists, call it with desired parameters 1. Parse floor and currency response 1. Pass floor and / or currency to bid adapter endpoint -getFloor takes in a single object with the following params: +getFloor() takes in a single object with the following params: {% highlight js %} - - getFloor({ + if (typeof bidRequest.getFloor === 'function') { + floorInfo = bidRequest.getFloor({ currency: string, - mediaType: string //Required + mediaType: string, size : [ w, h] OR "*" }); - +} {% endhighlight %} - {: .alert.alert-warning :} Consider how floors will behave in multi-currency scenarios. A common pitfall is requesting floors without specifying currency, or specifying the wrong currency back to the bid adapter's platform. This may lead to bidders requesting one currency and bidding in an alternate currency. @@ -1012,12 +1027,11 @@ Consider how floors will behave in multi-currency scenarios. A common pitfall is {: .table .table-bordered .table-striped } | Param | Type | Description | Default | |---+---+---+---| -| bidRequest | object | bidRequest object passed to buildRequests function | none | -| mediaType | string | The media type within the current bidRequest context to receive a floor from the Floors Module. Floors Module will return best matching floor. Possible values are one of “banner”, “video”, “Native” or "\*" | "banner" | -| size | Size array or ‘\*’ (required) | The size within the current bidRequest context to receive a floor from the Floors Module. Defaults to ‘\*’Array of size [w, h] for a specific size. If your bid adapter cannot handle size specific floors, use ‘\*’ to retrieve catch all size floor if defined by the publisher or floor provider | "\*" | +| mediaType | string | The media type within the current bidRequest context to receive a floor from the module. It will return best matching floor. Possible values are one of “banner”, “video”, “Native” or "\*" | "banner" | +| size | Size array or ‘\*’ (required) | The size within the current bidRequest context to receive a floor from the module. Defaults to ‘\*’Array of size [w, h] for a specific size. If your bid adapter cannot handle size specific floors, use ‘\*’ to retrieve catch-all size floor if defined by the publisher or floor provider | "\*" | | currency | String | The desired currency to return the floor in. Please refer to the currency section to understand how currency conversion is applied. If no currency is supplied, the floor module will assume USD. If the Floor Module cannot convert a floor to the supplied currency, bid adapters will be required to handle the supplied floor. | "USD" | -#### getFloor Response +#### getFloor() Response {% highlight js %} @@ -1036,9 +1050,9 @@ Or empty object if a floor was not found for a given input {% endhighlight %} -#### Example getFloor scenarios +#### Example getFloor() scenarios -Example rules file used for getFloor +Example rules file used for getFloor() {% highlight js %} @@ -1061,16 +1075,16 @@ Example rules file used for getFloor {% endhighlight %} -**Example getFloor 1** +**Example getFloor() 1** -getFloor for media type Banner for a bid request in the context of the gpt slot “/1111/homepage/top-rect” where the bid adapter does not support floors per size. +getFloor() for media type Banner for a bid request in GPT slot “/1111/homepage/top-rect” where the bid adapter does not support floors per size. {% highlight js %} getFloor({ currency: 'USD', mediatype: ‘banner’, - Size: ‘*’ + size: ‘*’ }); {% endhighlight %} @@ -1083,7 +1097,7 @@ getFloor for media type Banner for a bid request in the context of the gpt slot } {% endhighlight %} -To aid in the accuracy of floor selection when using size ”\*” in getFloor, the Floors Module has built-in smart rule selection when an ad unit in the internal bidRequest to the bid adapters interface has one ad unit type and one size. In the above example, if the ad unit within the bidRequest object has an ad unit type of “banner” with only one size, say “300x250”, the Floors Module will intelligently select the rule with "banner\|300x250" in it, as opposed to the "banner\|\*" rule producing the following response: +To aid in the accuracy of floor selection when using size ”\*” in getFloor(), the Price Floors Module has built-in smart rule selection when an ad unit in the internal bidRequest to the bid adapters interface has one ad unit type and one size. In the above example, if the ad unit within the bidRequest object has an ad unit type of “banner” with only one size, say “300x250”, the module will intelligently select the rule with "banner\|300x250" in it, as opposed to the "banner\|\*" rule producing the following response: {% highlight js %} { @@ -1093,9 +1107,9 @@ To aid in the accuracy of floor selection when using size ”\*” in getFloor, {% endhighlight %} -**Example getFloor 2** +**Example getFloor() 2** -getFloor for media type Banner for a bid requests in the context of the gpt slot “/1111/homepage/top-rect” with size of 300x600 where bid adapter does support floors per size. +getFloor() for media type Banner for a bid requests in GPT slot “/1111/homepage/top-rect” with size of 300x600 where bid adapter does support floors per size. {% highlight js %} getFloor({ @@ -1114,7 +1128,7 @@ getFloor({ } {% endhighlight %} -Here are some examples of how a bid adapter may wish to configure their adapter to handle getFloor function: +Here are some examples of how a bid adapter may wish to configure their adapter to handle getFloor() function: For a bid adapter who does not wish to handle making a request for each size in a given bid request they can leverage the \* attribute which is meant to be a skewed average for a floor. @@ -1131,23 +1145,23 @@ For a bid adapter who does not wish to handle making a request for each size in ### Analytics Adapter Interface -Price Floors providers will most likely rely heavily on their associated (or their partner’s) prebid analytics adapter in order to make the most informed and optimal price floor rule sets. Because of this, the price floors module needs to relay important information about the flooring and decisions made in the lifecycle of an auction. +Floor providers rely on an analytics adapter in order to make the most informed and optimal price floor rule sets. Because of this, the Price Floors Module needs to relay important information about the flooring and decisions made in the lifecycle of an auction. -The price floors module will do this by leveraging the already existing implementation for prebid analytics adapters by exposing floorData information onto the bidRequest and bidResponse objects. Thus, when an analytics adapter hooks into these prebid events, it will be able to pick out the price floors data and pass it along to their servers. +The module will do this by leveraging the already-existing implementation for analytics adapters by exposing floorData information onto the bidRequest and bidResponse objects. Thus, when an analytics adapter hooks into these objects, it will be able to pick out the price floors data and pass it along to their servers. **bidRequest**: Bid Requests objects are updated to contain some basic top level information which a floor provider may need: {: .table .table-bordered .table-striped } | bidRequest.floorData. | Type | Description | example | |---+---+---+---+---| -| fetchStatus | String | Provides details on the status of a fetch for a JSON floors file when fetches are attempted. Valid values are: 'success' (when fetch returns an http 200 status), 'timeout' (when fetch results not returned before either auction delay or prebid timeout) or 'error' (any http status other than 200 or other error condition). To determine if fetch succeeds but returns invalid floors data, refer to the location field to infer invalid data if 'fetch' is not resultant value. | ‘success’ | -| floorMin | float | The mimimum CPM floor used by the Floors Module (as of 4.13). The Floors Module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. | 0.10 | +| fetchStatus | String | Provides details on the status of a fetch for a JSON floors file when fetches are attempted. Valid values are: 'success' (when fetch returns an http 200 status), 'timeout' (when fetch results not returned before either auction delay or prebid timeout) or 'error' (any http status other than 200 or other error condition). Note: if data is received successfully, but isn't valid upon parsing, fetchStatus will be 'success', but the `location` field (below) will have a value other than 'fetch' because the system will fall back to another source. | ‘success’ | +| floorMin | float | The mimimum CPM floor used by the module (as of 4.13). The module will take the greater of floorMin and the matched rule CPM when evaluating getFloor() and enforcing floors. Note that the currency of this floor is the same as bidResponse.floorData.floorCurrency. | 0.10 | | floorProvider | string | Optional atribute (as of prebid version 4.1) used to signal to the Floor Provider's Analytics adapter their floors are being applied. They can opt to log only floors that are applied when they are the provider. If floorProvider is supplied in both the top level of the floors object and within the data object, the data object's configuration shall prevail.| "rubicon" | -| location | String | Where the Floors Module derived the rule set. Values are one of 'adUnit', 'setConfig', 'fetch' or 'noData'. If the Floors Module code is invoked and no floors object is able to be found (either by error or other condition) the floorsModule will set location to 'noData'. When on data is found, it is up to the analtyics adapter to decide what to log. All available values will be provided in teh bidRequest object. | ‘fetch’ | +| location | String | Where the module derived the rule set. Values are one of 'adUnit', 'setConfig', 'fetch' or 'noData'. If the module code is invoked and no floors object is able to be found (either by error or other condition) the floorsModule will set location to 'noData'. When on data is found, it is up to the analtyics adapter to decide what to log. All available values will be provided in the bidRequest object. | ‘fetch’ | | modelVersion | String | The name of the model| ‘floor-model-4.3’ | | modelWeight | integer | The weight of the model selected (for schema 2 version only)| 50 | | modelTimestamp | integer | Epoch timestamp associated with the modelVersion to be used for post auction analysis.| 1607126814 | -| skipRate | integer | skipRate will be populated when a skip rate is configured in the Prebid Floors Module, even if the skipRate is evaluated to false. Skip Rate is used to determine when to skip all floors logic. | 15 | +| skipRate | integer | skipRate will be populated when a skip rate is configured in the module, even if the skipRate is evaluated to false. Skip Rate is used to determine when to skip all floors logic. | 15 | | skipped | Boolean | Whether the skipRate resolved to be true or false| true | **bidResponse**: When a bid response is being processed it is important for analytics adapters to know the decision which was made and the context of the rule selection. Here is the data which is attached to each bidResponse: @@ -1165,28 +1179,88 @@ The price floors module will do this by leveraging the already existing implemen ### Prebid Server Interface -Not supported in initial build. S2S config support will be coming in the subsequent release. +The PrebidServerBidAdapter calls `getFloor()` like any other bid adapter +and passes it to the server side as imp.bidfloor and imp.bidfloorcur. + +### In-Page Interface +If a publisher is defining their own floors, then all of the fields in the floors schema may be defined in the page. + +Even if a publisher is using a floors provider, they may wish to provide additional data: +1. default floor data if dynamic data fails to load on time +2. global floorMin: allows the publisher to constrain dynamic floors with a global min +3. impression-level floor min (PBJS 6.24+): allows the publisher to constrain dynamic floors with an adunit-specific value + +Here's an example covering the first two scenarios: +``` +pbjs.setConfig({ + floors: { + enforcement: { + floorDeals: false //default to false + }, + floorMin: 0.05, // global default + auctionDelay: 100, // in milliseconds + endpoint: { // where to get the dynamic floors + url: 'https://floorprovider.com/a1001-mysite.json' + }, + data: { + currency: 'USD', + skipRate: 10, + modelVersion: 'some setconfig model version', + schema: { + fields: [ 'gptSlot', 'mediaType' ] + }, + values: { + '*|banner': 0.98, + '*|video': 1.74 + } + } + } +}); +``` + +And here's an example of imp-level floorMin, which is like a form of imp-level [first party data](/features/firstPartyData.html#supplying-adunit-specific-data): +``` +pbjs.addAdUnits({ + code: "test-div", + mediaTypes: { + banner: { + sizes: [[300,250]] + } + }, + ortb2Imp: { + ext: { + prebid: { + data: { + floorMin: 0.25, + floorMinCur: "USD" + } + } + } + }, + ... +}); +``` ## Currency -The floors module will default the floor CPM currency with any associated rule to USD if none is supplied in the data object of the floors configuration. For any non-USD currency support, a publisher is required to specify the desired currency. If you are working with a floor provider, please speak to them about supplying the desired currency for your integration. +The Price Floors Module defaults the floor currency to USD if none is supplied in the data object of the floors configuration. For any non-USD currency support, a publisher is required to specify the desired currency. If you are working with a floor provider, please speak to them about supplying the desired currency for your integration. {% capture warning_note %} -For publishers seeking to perform currency conversions within the floors module (for example if the floors data currency is not the same as a bid adapter’s supported currency), failure to include the currency module may result in unexpected behavior and / or may impact revenue performance. +For publishers requiring currency conversions (for example if the floors data currency is not the same as a bid adapter’s supported currency), **failure to include the currency module may result in unexpected behavior** and / or may impact revenue performance. {% endcapture %} {% include /alerts/alert_warning.html content=warning_note %} Currency conversion can occur in two areas of the Floor Module code: -- On the **getFloor** call when Bid Adapters request a floor +- On the **getFloor()** call when Bid Adapters request a floor - On the **enforcement** side when each bidder submits a bidResponse -**getFloor** +**Currency and getFloor()** -The job of the getFloor method is to retrieve an appropriate floor for the requesting Bid Adapter, for a given auction context. If a Bid Adapter performs a getFloor call with a currency different than the currency of the floor data, the Floors Module will attempt to perform a currency conversion, utilizing the convertCurrency function in the global Prebid object. +The job of the getFloor() function is to retrieve an appropriate floor for the requesting Bid Adapter, for a given auction context. If a Bid Adapter performs a getFloor() call with a currency different than the currency of the floor data, the module will attempt to perform a currency conversion, utilizing the convertCurrency function in the global Prebid object. -If a currency conversion is successful in getFloor, the resulting floor will be returned to the requesting Bid Adapter. If the conversion failed, the Floors Module will return the original floor currency defined within the selected rule location data set. +If a currency conversion is successful in getFloor(), the resulting floor will be returned to the requesting Bid Adapter. If the conversion failed, the module will return the original floor currency defined within the selected rule location data set. Example Rule: currency = ‘USD’, @@ -1209,7 +1283,7 @@ If successfully returned the requested currency: } {% endhighlight %} -If unsuccessfully returned the requested currency: +If currency conversion is unsuccessful: {% highlight js %} { @@ -1228,9 +1302,9 @@ Currency conversion can fail for the following reasons: - Bidder passes in a currency code which does not have a conversion rate - Floors was set with a currency which does not have a conversion rate -**Enforcement** +**Currency and Floor Enforcement** -Enforcement in the Floors module occurs when bidders respond (i.e. bid) with a bidResponse object into the Prebid auction. The Floors Module will read the bid submitted within each valid bidResponse and its associated currency, performing currency conversion where necessary. +Enforcement in the Price Floors Module occurs when bidders respond with a bidResponse object into the Prebid auction. The module reads the bid submitted within each valid bidResponse and its associated currency, performing currency conversion where necessary. There exist three locations where currencies can differ within enforcement: @@ -1238,14 +1312,14 @@ There exist three locations where currencies can differ within enforcement: - Price Floor Currency: Currency set in the price floors data object - bidResponse Currency: The currency the bidder returned with their bidResponse back to Prebid -When a bid adapter submits a bid into the auction, the currency module will first determine if any conversion logic is necessary, afterwhich the bid is passed to the Floors Module. If currency conversion occurs at this stage, the bidResponse object will have the following attributes: +When a bid adapter submits a bid into the auction, the currency module will first determine if any conversion logic is necessary, afterwhich the bid is passed to the module. If currency conversion occurs at this stage, the bidResponse object will have the following attributes: - Cpm: The adServerCurrency converted CPM currency - Currency: The currency the adServerCurrency was set in - originalCpm: The original CPM the bidder responded with - originalCurrency: The original currency the bidder responded with -Below is a chart explaining the behavior of currency conversion, if necessary, within the Floors Module when comparing bid CPM to floor CPM for enforcement: +Below is a chart explaining the behavior of currency conversion, if necessary, within the module when comparing bid CPM to floor CPM for enforcement: {: .table .table-bordered .table-striped } | bid.currency | bid.originalCurrency | floor.currency | result | @@ -1265,6 +1339,8 @@ If the currency function is unable to derive the correct cpm in any of the scena {: .table } | Partner | Contact | About | -| | Contact Magnite (Formerly Rubicon Project) support at [globalsupport@mangite.com](mailto:globalsupport@magnite.com) to use Magnite as a floor provider. | | -| pubx.ai | Reach out to PubX at [hello@pubx.ai](mailto:hello@pubx.ai) to learn more about our AI-powered dynamic floor optimization. | | -| Assertive Yield | [assertiveyield.com] | Holistic flooring covering Prebid, Amazon, GAM UPR, RTB and more | +| | [globalsupport@magnite.com](mailto:globalsupport@magnite.com) | Magnite data-science applied to dynamic floors | +| | Reach out to OpenX at [apollo@openx.com](mailto:apollo@openx.com) | Dynamic floor optimization and more | +| | [header-bidding@pubmatic.com](mailto:header-bidding@pubmatic.com) | PubMatic's ML powered dynamic Floor Optimization | +| Assertive Yield | [assertiveyield.com](https://assertiveyield.com) | Holistic flooring covering Prebid, Amazon, GAM UPR, RTB and more | +| pubx.ai | [hello@pubx.ai](mailto:hello@pubx.ai) | AI-powered dynamic floor optimization | diff --git a/dev-docs/modules/freewheel.md b/dev-docs/modules/freewheel.md index 24cba9286f..2aa357c750 100644 --- a/dev-docs/modules/freewheel.md +++ b/dev-docs/modules/freewheel.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Module - Freewheel -description: Returns targeting key/value pairs for adpod mediaType adUnits. +description: Passes key value targeting to Freewheel SDK for adpod mediaType adUnits. module_code : freeWheelAdserverVideo -display_name : Freewheel +display_name : Freewheel Video Support enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/gdprEnforcement.md b/dev-docs/modules/gdprEnforcement.md index 03acfeb352..2afd260ac9 100644 --- a/dev-docs/modules/gdprEnforcement.md +++ b/dev-docs/modules/gdprEnforcement.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: GDPR Enforcement Module -description: Module to enforce GDPR consent +description: If you have users in Europe, you'll want this module that enforces GDPR consent module_code : gdprEnforcement display_name : GDPR Enforcement enable_download : true +recommended: true sidebarType : 1 --- diff --git a/dev-docs/modules/geoedgeRtdProvider.md b/dev-docs/modules/geoedgeRtdProvider.md index a9c4367cef..42113e0086 100644 --- a/dev-docs/modules/geoedgeRtdProvider.md +++ b/dev-docs/modules/geoedgeRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : geoedgeRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/gpt-pre-auction.md b/dev-docs/modules/gpt-pre-auction.md index a701cc8796..db71b18ce6 100644 --- a/dev-docs/modules/gpt-pre-auction.md +++ b/dev-docs/modules/gpt-pre-auction.md @@ -2,10 +2,12 @@ layout: page_v2 page_type: module title: Module - GPT Pre-Auction -description: Adds PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters +description: If you run GAM, this module generates the 'global placement id' that's becoming required for successful auctions. module_code : gptPreAuction display_name : GPT Pre-Auction enable_download : true +recommended: true +vendor_specific: true sidebarType : 1 --- @@ -17,19 +19,25 @@ sidebarType : 1 ## Overview -This module enables targeting and tracking at the ad server adunit level. +This module enables bidder targeting and tracking at the ad server ad slot level. -Enabled by default if compiled into your package, this module will add the [Prebid Ad Slot](/features/pbAdSlot.html) and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. +This module is enabled by default if it's compiled into your PBJS package. It will add the [Prebid Ad Slot and GPID](/features/pbAdSlot.html) along with the matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. * **Prebid.js Adapters** - will be able to utilize these values as: - * AdUnit.ortb2imp.ext.data.adserver.name="gam" - * AdUnit.ortb2imp.ext.data.adserver.adslot="/1111/home" - * AdUnit.ortb2imp.ext.data.pbadslot="/1111/home-left" + * AdUnit.ortb2Imp.ext.gpid="/1111/home-left" + * AdUnit.ortb2Imp.ext.data.adserver.name="gam" + * AdUnit.ortb2Imp.ext.data.adserver.adslot="/1111/home" + * AdUnit.ortb2Imp.ext.data.pbadslot="/1111/home-left" * **Prebid Server Adapters** - will see the OpenRTB as: + * imp[].ext.gpid * imp[].ext.data.adserver.name * imp[].ext.data.adserver.adslot * imp[].ext.data.pbadslot +{: .alert.alert-info :} +The Prebid Ad Slot didn't get broad adoption, so it's likely that +someday we'll deprecate it in favor of the more standard GPID. + ## Configuration {: .alert.alert-info :} @@ -38,45 +46,121 @@ into the Prebid.js package. Optional initialization parameters: -- enabled (on by default) -- customGptSlotMatching function -- customPbAdSlot function +{: .table .table-bordered .table-striped } +| Param | Required? | Type | Description | Example | +| enabled | no | boolean | allows turning off of module. Default value is true | true | +| customGptSlotMatching | no | function | GPT slot matching function should match the customSlotMatching function sent to [setTargetingForGptAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) | | +| useDefaultPreAuction | no | boolean | (PBJS 6.5+) If true, use default behavior for determining GPID and PbAdSlot. Defaults to false. | true | +| customPreAuction | no | function | (PBJS 6.5+) Custom function for defining the GPID and PbAdSlot. | | +| customPbAdSlot | no | function | Custom PB AdSlot function. (Note, this function will be deprecated in the future.) | | +| mcmEnabled | no | boolean | Removes extra network IDs when Multiple Customer Management is active. Default is false. | true | +For example: ``` pbjs.setConfig({ gptPreAuction: { enabled: true, // enabled by default - customPbAdSlot: function(adUnitCode, adServerAdSlot) { + useDefaultPreAuction: false, + customPreAuction: function(adUnit, adServerAdSlot) { ... return "customPbAdSlot"; }, customGptSlotMatching: function(gptSlotObj) { ... return true; // or false - } + }, + mcmEnabled: true } }); ``` ## How It Works -When this module is on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that: +When this module is turned on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that: - loops through each adunit in the auction -- maps the adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching +- maps the PBJS adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching + +### Defining the AdServer name and adslot If GPT slot matching succeeds: -- it sets the Adunit ortb2imp.ext.data.adserver.name to 'gam' -- it copies the resulting GPT slot name to ortb2imp.ext.data.adserver.adslot +- it sets the Adunit ortb2Imp.ext.data.adserver.name to 'gam' +- it copies the resulting GPT slot name to ortb2Imp.ext.data.adserver.adslot + +### Defining PbAdSlot and GPID + +Here's what the module does to define these values: + +1. If AdUnit.ortb2Imp.ext.gpid already exists, use that for GPID. +1. If AdUnit.ortb2Imp.ext.data.pbadslot already exists, use that for PbAdSlot. +1. Otherwise, if a customPreAuction function is specified, run that. If the result isn't empty, place it in pbAdSlot and GPID. +1. Otherwise, if useDefaultPreAuction is true, run the default logic and place the return value in both pbAdSlot and GPID + 1. If ortb2Imp.ext.data.pbadslot is specified, use that. + 1. If ortb2Imp.ext.gpid is specified, use that. + 1. If GPT isn't in the page, give up. + 1. Query GPT slots with the adunit.code + 1. If there aren't any, give up. + 1. If there's just one, use that slot name as the GPID + 1. If there's more than on slot with the same name, append the div-id +1. Otherwise, if a customPbAdSlot function is specified and the result is not empty, place it in pbAdSlot and GPID. +1. Otherwise, if the AdUnit.code matched one or more GAM AdSlots, use that for both PbAdSlot and GPID +1. Otherwise use the AdUnit.code for PbAdSlot. + + +## Example customPbAdSlot function -The customPbAdSlot function is called if it was specified, writing the results to ortb2imp.ext.data.pbadslot. -If there's no customPbAdSlot, a default algorithm is used to determine ortb2imp.ext.data.pbadslot: +{: .alert.alert-info :} +In PBJS 6.5 and later, we recommend using the useDefaultPreAuction flag or the customPreAuction function. + +The following customPbAdSlot function will work for many publishers. Assumptions: +- AdUnits have been registered with [pbjs.addAdUnits](/dev-docs/publisher-api-reference/addAdUnits.html). +- AdUnit.code is either the GPT slot name or the div-id. +- The site has unique (non-random) div-ids. + +If either of these isn't the case, you'll need to supply your own function. -- first use the AdUnit's ortb2imp.ext.data.pbadslot if defined -- else, see if the AdUnit.code corresponds to a div and if so, try to retrieve a data element from the div called data-adslotid. -- else if the GPT slot matching succeeded, use the GPT slot name -- else, just use the AdUnit.code, assuming that that's the ad unit slot +``` +// Use adunit.ortb2Imp.ext.data.pbadslot if it exists. +// compare adunit.code to find a single matching slot in GPT +// if there is a single slot match, just use that slot name +// finally, there must be multiple slots that match. Define pbadslot as slot#div + +pbjs.setConfig({ + gptPreAuction: { + enabled: true, // enabled by default + customPbAdSlot: function(adUnitCode, adServerAdSlot) { + // get adunit object + au=pbjs.adUnits.filter(au => au.code==adUnitCode); + if (au.length==0) { + return; + } + + // use pbadslot if supplied + if (au[0].ort2bImp && au[0].ort2bImp.ext && au[0].ort2bImp.ext.data && au[0].ort2bImp.ext.data.pbadslot) { + return au[0].ort2bImp.ext.data.pbadslot; + } + + // confirm that GPT is set up + if (!(googletag && googletag.apiReady)) { + return; + } + // find all GPT slots with this name + var gptSlots = googletag.pubads().getSlots().filter(function(gpt) { + return gpt.getAdUnitPath() == adServerAdSlot; + }); + if (gptSlots.length==0) { + return; // should never happen + } + if (gptSlots.length==1) { + return adServerAdSlot; + } + // else the adunit code must be div id. append it. + return adServerAdSlot+"#"+adUnitCode; + } + }); +}; +``` # Further Reading -- [Prebid Ad Slot](/features/pbAdSlot.html) +- [Prebid Ad Slot and GPID](/features/pbAdSlot.html) diff --git a/dev-docs/modules/hadronRtdProvider.md b/dev-docs/modules/hadronRtdProvider.md new file mode 100644 index 0000000000..52513e7172 --- /dev/null +++ b/dev-docs/modules/hadronRtdProvider.md @@ -0,0 +1,142 @@ +--- +layout: page_v2 +title: Audigent Hadron Real Time Data Provider +display_name: Audigent Hadron Real-time Segmentation Module +description: Audigent Hadron Real-time Segmentation Module +page_type: module +module_type: rtd +module_code : hadronRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Audigent Hadron Real-time Data Submodule +{:.no_toc} + +* TOC +{:toc} + +Audigent is a next-generation, first-party data management platform and the +world’s first "data agency", powering the programmatic landscape and DTC +eCommerce with actionable first-party audience and contextual data from +retailers, lifestyle publishers, content creators, athletes and artists. + +The Hadron real-time data module in Prebid has been built so publishers +can maximize the power of their first-party audiences and contextual data. +This module provides both an integrated cookieless Hadron identity, contextual +targeting and audience segmentation solution that seamlessly and easily +integrates into your existing Prebid deployment. + +Users, devices, content, cohorts and other features are identified and utilized +to augment every bid request with targeted, first-party data-derived segments +before being submitted to supply-side platforms. Enriching the bid request with +robust first-party audience and contextual data, Audigent's Hadron RTD module +helps optimize targeting and header-bidding performance. For more information, +please visit https://audigent.com or contact our Prebid integration team at +prebid@audigent.com. + + +## Publisher Usage + +Compile the Hadron RTD module into your Prebid build: + +`gulp build --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,appnexusBidAdapter` + +Add the Hadron RTD provider to your Prebid config. In this example we will configure +publisher 1234 to retrieve segments from Audigent. See the +"Parameter Descriptions" below for more detailed information of the +configuration parameters. Please work with your Audigent Prebid support team +(prebid@audigent.com) on which version of Prebid.js supports different bidder +and segment configurations. + +``` +pbjs.setConfig( + ... + realTimeData: { + auctionDelay: auctionDelay, + dataProviders: [ + { + name: "hadron", + waitForIt: true, + params: { + segmentCache: false, + partnerId: 1234 + } + } + ] + } + ... +} +``` + +**Config Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Always 'hadron' | +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| params | Object | | | +| params.handleRtd | Function | A passable RTD handler that allows custom adunit and ortb2 logic to be configured. The function signature is (bidConfig, rtd, rtdConfig, pbConfig) => {}. | Optional | +| params.segmentCache | Boolean | This parameter tells the Hadron RTD module to attempt reading segments from a local storage cache instead of always requesting them from the Audigent server. | Optional. Defaults to false. | +| params.partnerId | Number | This is the Audigent Partner ID obtained from Audigent. | Required | +| params.hadronIdUrl | String | Parameter to specify alternate hadronid endpoint url. | Optional | + +## Publisher Customized RTD Handling + +As indicated above, it is possible to provide your own bid augmentation +functions rather than simply merging supplied data. This is useful if you +want to perform custom bid augmentation and logic with Hadron real-time data +prior to the bid request being sent. Simply add your custom logic to the +optional handleRtd parameter and provide your custom RTD handling logic there. + +Please see the following example, which provides a function to modify bids for +a bid adapter called adBuzz and perform custom logic on bidder parameters. + +``` +pbjs.setConfig( + ... + realTimeData: { + auctionDelay: auctionDelay, + dataProviders: [ + { + name: "hadron", + waitForIt: true, + params: { + handleRtd: function(bidConfig, rtd, rtdConfig, pbConfig) { + var adUnits = bidConfig.adUnits; + for (var i = 0; i < adUnits.length; i++) { + var adUnit = adUnits[i]; + for (var j = 0; j < adUnit.bids.length; j++) { + var bid = adUnit.bids[j]; + if (bid.bidder == 'adBuzz' && rtd['adBuzz'][0].value != 'excludeSeg') { + bid.params.adBuzzCustomSegments.push(rtd['adBuzz'][0].id); + } + } + } + }, + segmentCache: false, + partnerId: 1234 + } + } + ] + } + ... +} +``` + +The handleRtd function can also be used to configure custom ortb2 data +processing. Please see the examples available in the hadronRtdProvider_spec.js +tests and work with your Audigent Prebid integration team (prebid@audigent.com) +on how to best configure your own Hadron RTD & Open RTB data handlers. + +## Testing + +To view an example of available segments returned by Audigent's backends: + +`gulp serve --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,appnexusBidAdapter` + +and then point your browser at: + +`http://localhost:9999/integrationExamples/gpt/hadronRtdProvider_example.html` diff --git a/dev-docs/modules/haloRtdProvider.md b/dev-docs/modules/haloRtdProvider.md index 3f36b19946..3728bb185d 100644 --- a/dev-docs/modules/haloRtdProvider.md +++ b/dev-docs/modules/haloRtdProvider.md @@ -5,142 +5,16 @@ display_name: Audigent Halo Real-time Segmentation Module description: Audigent Halo Real-time Segmentation Module page_type: module module_type: rtd -module_code : haloRtdProvider -enable_download : true +module_code: haloRtdProvider +enable_download: false +vendor_specific: true sidebarType : 1 --- # Audigent Halo Real-time Data Submodule -{:.no_toc} - -* TOC -{:toc} - -Audigent is a next-generation data management platform and a first-of-a-kind -"data agency" containing some of the most exclusive content-consuming audiences -across desktop, mobile and social platforms. - -This real-time data module provides an integrated post-cookie Halo identity and -real-time user segmentation solution that seamlessly integrates into your bid -request cycle. Users are identified and bid request objects are augmented -with first-party data derived segments prior to being sent to exchange/ssp -services in order to optimize targeting and increase publisher revenue. - -Audigent maintains a large database of first-party Tradedesk Unified ID, -Audigent Halo ID and other id provider mappings to various third-party segment -types that are utilizable across different backends. With the Halo RTD module, -these segments and other data can be retrieved and utilized by supporting -exchange and SSP backends in real-time during your bid request cycle. - - -## Publisher Usage - -Compile the Halo RTD module into your Prebid build: - -`gulp build --modules=userId,unifiedIdSystem,rtdModule,haloRtdProvider,appnexusBidAdapter` - -Add the Halo RTD provider to your Prebid config. In this example we will configure -publisher 1234 to retrieve segments from Audigent. See the -"Parameter Descriptions" below for more detailed information of the -configuration parameters. Please work with your Audigent Prebid support team -(prebid@audigent.com) on which version of Prebid.js supports different bidder -and segment configurations. - -``` -pbjs.setConfig( - ... - realTimeData: { - auctionDelay: auctionDelay, - dataProviders: [ - { - name: "halo", - waitForIt: true, - params: { - segmentCache: false, - requestParams: { - publisherId: 1234 - } - } - } - ] - } - ... -} -``` - -**Config Syntax details:** - -{: .table .table-bordered .table-striped } -| Name |Type | Description | Notes | -| :------------ | :------------ | :------------ |:------------ | -| name | String | Real time data module name | Always 'halo' | -| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | -| params | Object | | | -| params.handleRtd | Function | A passable RTD handler that allows custom adunit and ortb2 logic to be configured. The function signature is (bidConfig, rtd, rtdConfig, pbConfig) => {}. | Optional | -| params.segmentCache | Boolean | This parameter tells the Halo RTD module to attempt reading segments from a local storage cache instead of always requesting them from the Audigent server. | Optional. Defaults to false. | -| params.requestParams | Object | Publisher partner specific configuration options, such as optional publisher id and other segment query related metadata to be submitted to Audigent's backend with each request. Contact prebid@audigent.com for more information. | Optional | -| params.haloIdUrl | String | Parameter to specify alternate haloid endpoint url. | Optional | - -## Publisher Customized RTD Handling - -As indicated above, it is possible to provide your own bid augmentation -functions rather than simply merging supplied data. This is useful if you -want to perform custom bid augmentation and logic with Halo real-time data -prior to the bid request being sent. Simply add your custom logic to the -optional handleRtd parameter and provide your custom RTD handling logic there. - -Please see the following example, which provides a function to modify bids for -a bid adapter called adBuzz and perform custom logic on bidder parameters. - -``` -pbjs.setConfig( - ... - realTimeData: { - auctionDelay: auctionDelay, - dataProviders: [ - { - name: "halo", - waitForIt: true, - params: { - handleRtd: function(bidConfig, rtd, rtdConfig, pbConfig) { - var adUnits = bidConfig.adUnits; - for (var i = 0; i < adUnits.length; i++) { - var adUnit = adUnits[i]; - for (var j = 0; j < adUnit.bids.length; j++) { - var bid = adUnit.bids[j]; - if (bid.bidder == 'adBuzz' && rtd['adBuzz'][0].value != 'excludeSeg') { - bid.params.adBuzzCustomSegments.push(rtd['adBuzz'][0].id); - } - } - } - }, - segmentCache: false, - requestParams: { - publisherId: 1234 - } - } - } - ] - } - ... -} -``` - -The handleRtd function can also be used to configure custom ortb2 data -processing. Please see the examples available in the haloRtdProvider_spec.js -tests and work with your Audigent Prebid integration team (prebid@audigent.com) -on how to best configure your own Halo RTD & Open RTB data handlers. - -## Testing - -To view an example of available segments returned by Audigent's backends: - -`gulp serve --modules=userId,unifiedIdSystem,rtdModule,haloRtdProvider,appnexusBidAdapter` - -and then point your browser at: - -`http://localhost:9999/integrationExamples/gpt/haloRtdProvider_example.html` - - +Audigent Halo has been rebranded as Audigent Hadron. Please review the updated +docs here: +[Audigent Hadron Real-time Data Submodule](/dev-docs/modules/hadronRtdProvider.html) +Please update your Halo references to Hadron before Prebid 7 is released. diff --git a/dev-docs/modules/iabCatagoryTranslation.md b/dev-docs/modules/iabCatagoryTranslation.md deleted file mode 100644 index 7831fbd198..0000000000 --- a/dev-docs/modules/iabCatagoryTranslation.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -layout: page_v2 -page_type: module -title: Module - IAB Category Translation -description: Converts between ad agency brand categories and IAB brand categories. -module_code : CategoryTranslation -display_name : CategoryTranslation -enable_download : true -sidebarType : 1 ---- - -# IAB Category Translation - -{:.no_toc} - -This module converts the IAB sub category to FreeWheel industry group identifiers. The FreeWheel identifiers ensure competitve separation of industries and products. - -Each bid request must return one [IAB subcategory](https://support.aerserv.com/hc/en-us/articles/207148516-List-of-IAB-Categories). - -The module provides the following: - -- Converts IAB subcategories to a FreewWheel industry group identifier. - -## How to use the module: - -1. A Prebid.js package is built that contains this module and the [FreeWheel](/dev-docs/modules/freewheel.html) module. -2. The inclusion of this module causes Prebid to download a mapping file to local storage. The user also has the option to provide their own mapping file. -3. At runtime, brand category translation happens as needed. - - -## Using A Custom Map File -The IAB Category Translation module uses a default mapping file to convert adserver categories to IAB sub categories. If a publisher prefers to use their own mapping file they will need to set the URL location of that file. They can do so by adding the following to their Prebid.js configuration: - -``` -pbjs.setConfig({ - "brandCategoryTranslation": { - "translationFile": "" - } -}); -``` - -This file will be stored locally to expedite the conversion process. If a publisher opts to not provide a conversion mapping file Prebid will use its default conversion mapping file. - -Publishers should ensure that the JSON returned from their custom file is valid for Prebid by adhering to the following structure: - -```JSON -{ - “mapping”: { - ““: { - “id”: ““, - “name”: “” - }, - .... - } -} -``` - -Refer to Prebid Github repository for a [custom file reference](https://github.com/prebid/category-mapping-file). - - -## Further Reading - -[Prebid.js](/dev-docs/getting-started.html) -[Prebid Video](/prebid-video/video-overview.html) -[FreeWheel Module](/dev-docs/modules/freewheel.html) -[Adapter Integration](/dev-docs/bidder-adaptor.html) - - - - - - - diff --git a/dev-docs/modules/iasRtdProvider.md b/dev-docs/modules/iasRtdProvider.md index b1585553a1..99dae5c16a 100644 --- a/dev-docs/modules/iasRtdProvider.md +++ b/dev-docs/modules/iasRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : iasRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/idLibrary.md b/dev-docs/modules/idLibrary.md index 306b877158..5874353f8e 100644 --- a/dev-docs/modules/idLibrary.md +++ b/dev-docs/modules/idLibrary.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: ID Import Library -description: ID Graphing Adapter +description: Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing. module_code : currency display_name : ID Import Library enable_download : true diff --git a/dev-docs/modules/idWardRtdProvider.md b/dev-docs/modules/idWardRtdProvider.md new file mode 100644 index 0000000000..4ac094e210 --- /dev/null +++ b/dev-docs/modules/idWardRtdProvider.md @@ -0,0 +1,61 @@ +--- +layout: page_v2 +title: ID Ward Real Time Data Provider Module +display_name: ID Ward Real Time Data Provider Module +description: ID Ward Real Time Data Provider Module +page_type: module +module_type: rtd +module_code : idWardRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# ID Ward Real Time Data Provider Module + +ID Ward is a data anonymization technology for privacy-preserving advertising. Publishers and advertisers are able to target and retarget custom audience segments covering 100% of consented audiences. +ID Ward’s Real-time Data Provider automatically obtains segment IDs from the ID Ward on-domain script (via `localStorage`) and passes them to the bid-stream. + + +## Publisher Usage + +1) Build the idWardRtd module into the Prebid.js package with: + +``` +gulp build --modules=idWardRtdProvider,... +``` + +2) Use `setConfig` to instruct Prebid.js to initilaize the idWardRtdProvider module, as specified below. + +### Configuration + +``` + pbjs.setConfig({ + realTimeData: { + dataProviders: [ + { + name: "idWard", + waitForIt: true, + params: { + cohortStorageKey: "cohort_ids", + segtax: , + } + } + ] + } + }); +``` + +Please note that idWardRtdProvider should be integrated into the publisher website along with the [ID Ward Pixel](https://publishers-web.id-ward.com/pixel-integration). +Please reach out to Id Ward representative(support@id-ward.com) if you have any questions or need further help to integrate Prebid, idWardRtdProvider, and Id Ward Pixel + + +**Config Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Id Ward Rtd module name | 'idWard' always| +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| cohortStorageKey | String | the `localStorage` key, under which Id Ward Pixel stores the segment IDs | 'cohort_ids' always | +| segtax | Integer | the taxonomy for Id Ward | Getting this value is in progress, once done this will become optional | \ No newline at end of file diff --git a/dev-docs/modules/imRtdProvider.md b/dev-docs/modules/imRtdProvider.md new file mode 100644 index 0000000000..7eee3bc60e --- /dev/null +++ b/dev-docs/modules/imRtdProvider.md @@ -0,0 +1,73 @@ +--- +layout: page_v2 +title: Intimate Merger Real time Data Provider +display_name: Intimate Merger Real-time Data Submodule +description: Intimate Merger Real-time Data Submodule +page_type: module +module_type: rtd +module_code : imRtdProvider +enable_download : true +sidebarType : 1 +--- + +# Intimate Merger Real time Data Provider +{:.no_toc} + +* TOC +{:toc} + +This module reads segments from [Intimate Merger](https://corp.intimatemerger.com/) audience data platform and attaches them as targeting keys to bid requests. + +The audience data platform performs segmentation even in environments where 3rd party cookies are not available, but curretly only available in Japan. + + +## Usage + +Add it to your Prebid.js package with: + +`gulp build --modules=rtdModule,imRtdProvider` + +## Publisher Customized RTD Handling + +The following configuration parameters are available: + +``` +pbjs.setConfig( + ... + realTimeData: { + auctionDelay: 5000, + dataProviders: [ + { + name: "im", + waitForIt: true, + params: { + cid: 5126, // Set your Intimate Merger Customer ID here for production + setGptKeyValues: true + } + } + ] + } + ... +} +``` + +## Parameters + +{: .table .table-bordered .table-striped } +| Param under dataProviders | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module. | `"im"` | +| waitForIt | Optional | Boolean | Required to ensure that the auction is delayed until prefetch is complete. Defaults to false but recommended to true | `true` | +| params | Required | Object | Details of module params. | | +| params.cid | Required | Number | This is the Customer ID value obtained via Intimate Merger. | `5126` | +| params.setGptKeyValues | Optional | Boolean | This is set targeting for GPT/GAM. Default setting is true. | `true` | + +## Testing + +First, make sure to add the Intimate Merger submodule to your Prebid.js package with: + +`gulp serve --modules=rtdModule,imRtdProvider` + +and then point your browser at: + +`http://localhost:9999/integrationExamples/gpt/imRtdProvider_example.html` diff --git a/dev-docs/modules/index.md b/dev-docs/modules/index.md index 7721060433..4b62546f54 100644 --- a/dev-docs/modules/index.md +++ b/dev-docs/modules/index.md @@ -1,6 +1,6 @@ --- layout: page_v2 -title: Prebid Modules +title: Prebid.js Modules description: Module Documentation sidebarType: 1 --- @@ -8,94 +8,89 @@ sidebarType: 1 # Prebid.js Module Overview {:.no_toc} -The core of Prebid.js contains only the foundational code needed for header bidding. Any functionality that could be considered an add-on or that covers a special case is being moved out into modules. Examples of this kind of code include: +The core of Prebid.js contains only the foundational code needed for header bidding. Any functionality that could be considered an add-on is part of a module. These are the major categories: -- Bidder adapters -- Special auction logic -- Ad server API integrations -- Any other extensible functionality - -This section of the site contains user-submitted module documentation. We're hoping that it will grow over time. - -To see all of the modules that are available, see the [`modules` folder in the repo](https://github.com/prebid/Prebid.js/tree/master/modules). - -If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.baseurl}}/dev-docs/bidders.html). +- [Bidder adapters](/dev-docs/bidders.html) +- [Analytics adapters](/overview/analytics.html) +- Any other extensible functionality - documented on this page * TOC {:toc} -## General Modules - -{: .table .table-bordered .table-striped } -| Module | Description | -|---------------------+--------------| -| [**Currency**](/dev-docs/modules/currency.html) | Converts bid currency into ad server currency based on data in a supplied exchange rate file. | -| **ConsentManagement** | Collecting and passing consent information in support of privacy regulations:{::nomarkdown}{:/} See [CMP Best Practices.](/dev-docs/cmp-best-practices.html) | -| [**Google Ad Manager Express**](/dev-docs/modules/dfp_express.html) | A simplified installation mechanism for publishers that have Google Publisher Tag (GPT) ad calls in their pages. | -| [**Supply Chain Object**](/dev-docs/modules/schain.html) | Validates and makes the Supply Object available to bidders | -| [**User ID**](/dev-docs/modules/userId.html) | Sub-modules are available to support a range of identification approaches. | -| [**ID Import Library**](/dev-docs/modules/idLibrary.html) | Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing | -| [**Advanced Size Mapping**](/dev-docs/modules/sizeMappingV2.html) | Display Responsive AdUnits in demanding page environments. | -| [**Price Floors Module**](/dev-docs/modules/floors.html) | Configure and enforce minimum bids. | -| [**GPT Pre-Auction Module**](/dev-docs/modules/gpt-pre-auction.html) | Adds a PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. | -| [**ID Import Library**](/dev-docs/modules/idLibrary.html) | Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing | -| [**First Party Data Enrichment**](/dev-docs/modules/enrichmentFpdModule.html) | Pulls well-known FPD from the environment to form a base of data available to all adapters. | -| [**MASS**](/dev-docs/modules/mass.html) | Enables the MASS protocol for Prebid and custom renderers by DealID | -| [**MultiBid Module**](/dev-docs/modules/multibid.html) | Allows bidders to send multiple bids to the ad server. | -| [**Bid Viewability**](/dev-docs/modules/bidViewable.html) | Triggers an event which can be consumed by analytics and bid adapters. | +{% assign module_pages = site.pages | where: "page_type", "module" %} -## Real-Time Data Providers +## Recommended Modules -All of the modules that fall under the Real-Time Data (RTD) category conform to -a consistent set of publisher controls. The pub can choose to run multiple -RTD modules, define an overall amount of time they're willing to wait for -results, and even flag some of the modules as being more "important" -than others. +Prebid.org highly recommends that publishers utilize the following modules: +
    + + + + + + + + +{% for page in module_pages %}{% if page.recommended == true %} + + + + +{% endif %}{% endfor %} + +
    ModuleDescription
    {{page.display_name}}{{page.description}}
    -See [the realTimeData setConfig](/dev-docs/publisher-api-reference/setConfig.html#setConfig-realTimeData) reference for more details. +## General Modules -{% assign module_pages = site.pages | where: "page_type", "module" | where: "module_type", "rtd" %} +Modules in the Real-Time Data (RTD) category conform to +a consistent set of publisher controls. The publisher can choose to run multiple +RTD modules, define an overall amount of time they're willing to wait for +results, and even flag some of the modules as being higher priority +than others. See [the realTimeData setConfig](/dev-docs/publisher-api-reference/setConfig.html#setConfig-realTimeData) reference for more details. + -{% for page in module_pages %} - {% if page.enable_download == false %}{% continue %}{% endif %} +{% for page in module_pages %}{% if page.recommended == true or page.vendor_specific == true %}{% continue %}{% endif %} - + + {% if page.module_type == "rtd" %}{% else %}{% endif %} {% endfor %}
    Module DescriptionRTD?
    {{page.title}}{{page.display_name}} {{page.description}}yesno
    -## Video Modules - -{: .table .table-bordered .table-striped } -| Module | Description | -|---------------------+--------------| -| [**Ad Pod**](/dev-docs/modules/adpod.html) | Enables developers to add support for a new adserver that handles ad pod (long-form) videos | -| [**Freewheel**](/dev-docs/modules/freewheel.html) | Passes key value targeting to Freewheel SDK | -| [**Google Ad Manager Video**](/dev-docs/modules/dfp_video.html) | Required for serving instream video through Google Ad Manager. | -| [**IAB Category Translation**](/dev-docs/modules/categoryTranslation.html) | Converts IAB sub category to Ad server category for long-form videos. | -| [**Instream Video Ads Tracking**](/dev-docs/modules/instreamTracking.html) | Allow Analytics Adapters and Bid Adapters to track `BID_WON` events for Instream video bids. | -| [**Konduit Accelerate**](/dev-docs/modules/konduit.html) | Provides Real Time Start Rate Performance per Bidder. | - -## Testing and Debug Modules - -{: .table .table-bordered .table-striped } -| Module | Description | -|---------------------+--------------| -| [**Server-to-Server Testing**](/dev-docs/modules/s2sTesting.html) | Adds A/B test support to ease into server-side header bidding. | -| [**First Party Data Validation**](/dev-docs/modules/validationFpdModule.html) | Verify First Party Data ortb2 fields and data types. | +## Vendor-Specific Modules +These modules may require accounts with a service provider. + + + + + + + + + +{% for page in module_pages %}{% if page.recommended == true %}{% continue %}{% endif %}{% if page.vendor_specific == true %} + + + + {% if page.module_type == "rtd" %}{% else %}{% endif %} + +{% endif %}{% endfor %} + +
    ModuleDescriptionRTD?
    {{page.display_name}}{{page.description}}yesno
    ## Further Reading + [Source code of all modules](https://github.com/prebid/Prebid.js/tree/master/modules) -+ [Bidders' Params](/dev-docs/bidders.html) ++ [How to add a Bid Adapter](/dev-docs/bidder-adaptor.html) ++ [How to add an Analytics Adapter](/dev-docs/integrate-with-the-prebid-analytics-api.html) + [How to add a Real Time Data Submodule](/dev-docs/add-rtd-submodule.html) diff --git a/dev-docs/modules/instreamTracking.md b/dev-docs/modules/instreamTracking.md index 4e3d18255e..1e2c16f128 100644 --- a/dev-docs/modules/instreamTracking.md +++ b/dev-docs/modules/instreamTracking.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Instream Video Ads Tracking -description: Allows to track `BID WON` events for instream ad units +description: Allow Analytics Adapters and Bid Adapters to track `BID_WON` events for instream video bids. module_code : instreamTracking display_name : Instream Tracking enable_download : true diff --git a/dev-docs/modules/intersectionRtdProvider.md b/dev-docs/modules/intersectionRtdProvider.md new file mode 100644 index 0000000000..a4381b8e92 --- /dev/null +++ b/dev-docs/modules/intersectionRtdProvider.md @@ -0,0 +1,75 @@ +--- +layout: page_v2 +title: Intersection Module +display_name: Intersection +description: Real Time Intersection +page_type: module +module_type: rtd +module_code : intersectionRtdProvider +enable_download : true +sidebarType : 1 +--- + +# Intersection Module +{:.no_toc} + +* TOC +{:toc} + +## Overview + +The Intersection module provides intersection for ad slots on the page using +[Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). + +Implementation works like this: + + 1) Build the Intersection module into the Prebid.js package with: + +``` +gulp build --modules=intersectionRtdProvider&... +``` + +2) Use `setConfig` to instruct the browser to obtain the intersection data + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` object: + +``` + pbjs.setConfig({ + "realTimeData": { + auctionDelay: 100, + dataProviders:[{ + "name": "intersection", + "waitForIt": true + }] + } + }); +``` + +## Output + +For each bidder, the module adds intersection in a JSON format. +Example: +``` +{ + "intersection":{ + 'boundingClientRect': { + 'left': 10, + 'top': 10, + 'right': 310, + 'bottom': 260, + 'width': 300, + 'height': 250, + 'x': 10, + 'y': 10, + }, + 'intersectionRect': {/* ... */}, + 'rootRect': {/* ... */}, + 'intersectionRatio': 0.5, + 'isIntersecting': false, + 'time': 1636993868145 + } +} +``` + diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 66b4fc3024..75a8b81e1c 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : jwplayerRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- @@ -106,34 +107,53 @@ Each bidRequest for which targeting information was found will conform to the fo ```json { - adUnitCode: 'xyz', - bidId: 'abc', - ..., - rtd: { - jwplayer: { - targeting: { - segments: ['123', '456'], - content: { - id: 'jw_abc123' - } - } - } - } + adUnitCode: 'xyz', + bidId: 'abc', + ..., + ortb2: { + site: { + content: { + id: 'jw_abc123', + data: [ + { + name: 'jwplayer.com', + ext: { + segtax: 502, + cids: ['abc123'] + }, + segment: [ + { + id: '123' + }, + { + id: '456' + } + ] + } + ] + } + } + } } ``` +Each bid for which targeting information was found will have a ortb2 param conforming to the [oRTB v2 object structure](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf). The `ortb2` object will contain our proprietaty targeting segments in a format compliant with the [IAB's segment taxonomy structure](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/segtax.md). -Read the bidRequest.jwTargeting object and pass the values to your endpoint as appropriate. +The content's ID can be obtained in the `bid.ortb2.site.content.id` property path and the targeting segments can be found in `bid.ortb2.site.content.data.segment`. **BidRequest Syntax details:** {: .table .table-bordered .table-striped } | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | -| rtd.jwplayer.targeting | Object | | | -| rtd.jwplayer.targeting.segments | Array of Strings | jwpseg targeting segments | | -| rtd.jwplayer.targeting.content | Object | | | -| rtd.jwplayer.targeting.content.id | String | Unique identifier for the specific media asset | | - +| ortb2.site.content | Object | | | +| ortb2.site.content.id | String | Unique identifier for the specific media asset | | +| ortb2.site.content.data | Array | Contains segment taxonomy objects | | +| ortb2.site.content.data[index].name | String | the `jwplayer.com` string indicating the provider name | | +| ortb2.site.content.data[index].ext.segtax | Integer | the `502` value is the unique identifier for JW Player's proprietary taxonomy | | +| ortb2.site.content.data[index].ext.cids | Array | List of extended content ids as defined in [oRTB's community extensions](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/extended-content-ids.md#example---content-id-and-seller-defined-context). | | +| ortb2.site.content.data[index].segment | Array | Contains the segment taxonomy values as an object | | +| ortb2.site.content.data[index].segment[index].id | String | String representation of the data segment value | | + ## Example To view an example: diff --git a/dev-docs/modules/konduit.md b/dev-docs/modules/konduit.md index 7623ae7aa2..f9bb831eea 100644 --- a/dev-docs/modules/konduit.md +++ b/dev-docs/modules/konduit.md @@ -2,10 +2,11 @@ layout: page_v2 page_type: module title: Module - Konduit Accelerate -description: Applies Konduit video ad acceleration optimization to a provided bid. +description: Applies Konduit video ad acceleration optimization to wining video bid. module_code : konduitWrapper display_name : Konduit Accelerate enable_download : true +vendor_specific: true sidebarType : 1 --- diff --git a/dev-docs/modules/mass.md b/dev-docs/modules/mass.md index d447773ca3..cdacac886a 100644 --- a/dev-docs/modules/mass.md +++ b/dev-docs/modules/mass.md @@ -2,9 +2,9 @@ layout: page_v2 page_type: module title: Module - MASS -description: Enable MASS protocol for Prebid +description: General deal rendering functionality. module_code : mass -display_name : MASS +display_name : Deal Rendering (aka MASS) enable_download : true sidebarType : 1 --- @@ -139,16 +139,46 @@ pbjs.que.push(function() { ## Integration Example +There are two options to view the integration example: + +### Option 1 - Your own development environment To view the integration example: -1) in your cli run: +1) Build Prebid using the following required options + +``` +gulp build --modules=ixBidAdapter,mass +``` + +2) Use a http server with a valid hostname to access its content. It is not advised to run the bid simulation using localhost or 127.0.0.1 ``` -gulp serve --modules=ixBidAdapter,mass +http://hostname/integrationExamples/mass/index.html ``` -2) in your browser, navigate to: +### Option 2 - Hosted online +Mass Platform Limited hosts an official integration and demo page that can be accessed using the following link: https://demo.massplatform.net/ix/prebid/ + +## Testing MASS +Testing requires valid bids to be returned to Prebid. To assist with this process, we recommend you use the MASS Bid Simulation tool found at https://github.com/massplatform/bidsim. Your Exchange partner might be able to assist you with other specialist tools and browser plugins to achieve similar resuls. +The instructions below assume that you have followed the installation instructions for the MASS Bidsim tool found at https://github.com/massplatform/bidsim/blob/master/README.md. + +### Testing using MASS compliant tags +The bidsim tool ships with working DSP example tags that can be found under the bidsim/tags folder. + +A quick way to test the Integration test page in combination with the official bootloader is to use the following command: +``` +node bidsim --inject --bid 2000 --width 300 --height 250 --dealid 'MASS' --tag "tags/inskin-housead-desktop.js" -o https://demo.massplatform.net/ix/prebid ``` -http://localhost:9999/integrationExamples/mass/index.html +### For third-party technology companies +Third-parties that wish to integrate with the official MASS bootloader can get started by running the following command: ``` +node bidsim --inject --bid 2000 --width 300 --height 250 --dealid 'MASS' --tag "tags/test.js" -o https://demo.massplatform.net/ix/prebid +``` + +Explanation: The tags/test.js tag calls a reference endpoint for developers that can be accessed here: https://demo.massplatform.net/reference/endpoint.js. +When running the above command to invoke this reference endpoint, you will see all the params that MASS collected and passed onto your endpoint. This includes inputs, parsed inputs, tag parameters and MASS/Provider specific configurations. + +### Testing on live sites +Any sites that have been MASS configured will work with the Bidsim tool. This is a convenient way to test whether your publisher ad server and slot is correctly configured. diff --git a/dev-docs/modules/medianetRtdProvider.md b/dev-docs/modules/medianetRtdProvider.md new file mode 100644 index 0000000000..fac7f1cf1c --- /dev/null +++ b/dev-docs/modules/medianetRtdProvider.md @@ -0,0 +1,116 @@ +--- +layout: page_v2 +title: Media.net Realtime Module +display_name: Media.net Realtime Module +description: Delivers added functionality based on configurations, i.e. refresh, viewability, etc. +page_type: module +module_type: rtd +module_code : medianetRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Media.net Realtime Module +{:.no_toc} + +* TOC +{:toc} + +## Overview + +The module currently provisions Media.net's Intelligent Refresh configured by the publisher. + +### Intelligent Refresh + +Intelligent Refresh (IR) module lets publisher refresh their ad inventory without affecting page experience of visitors through configured criteria. The module optionally provides tracking of refresh inventory and appropriate targeting in GAM. Publisher configured criteria is fetched via an external JS payload. + +{: .alert.alert-warning :} +Disclosure: This module loads external code that is not open source and has not been reviewed by Prebid.org. + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` object. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------|----------|----------------------------------------|---------------|----------| +| `name ` | required | Real time data module name | `'medianet'` | `string` | +| `params` | required | | | `Object` | +| `params.cid` | required | The customer id is provided by Media.net. | `'8CUX0H51C'` | `string` | + +#### Basic Example + +```javascript +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: 'medianet', + params: { + cid: '8CUX0H51C' + } + }] + } +}); +``` + +## Prebid Adapters module usage + +Prebid bidder and analytics adapters can read `adunit.ortb2Imp.ext.refresh` to know the information passed by Intelligent Refresh Real Time Module. Example AdUnit: + +```javascript +var adUnit = { + "code": "div-gpt-ad-1460505748561-1", + // ... + "ortb2Imp": { + "ext": { + "refresh": { // added by Intelligent Refresh RTD + "mnrf": "1", // mnrf=1 means its a refresh impression + "mnrfc": 2 // mrfc=2 means its the 2nd refresh-ed impression + }, + "data": { "pbadslot": "div-gpt-ad-1460505748561-1" }, + } + } +}; +``` + +## Targeting sent to GAM + +For each prebid adUnit we pass following key values to GAM by default + +```javascript +var targeting = { + "slotA":{ + "mnadc": "slotA", // used to map GPT slot => Prebid AdUnit + "mnrf": "1", // Refresh Impression Flag + "mnrfc": 2 // Refreshed count per slot + } +}; +``` + +## Integration +To install the module, follow these instructions: + +#### Step 1: Prepare the base Prebid file + +- Option 1: Use Prebid [Download](/download.html) page to build the prebid package. Ensure that you do check *Media.net Realtime Module* module + +- Option 2: From the command line, run `gulp build --modules=medianetRtdProvider,...` + +#### Step 2: Set configuration + +Enable Media.net Real Time Module using `pbjs.setConfig` + +```javascript +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: 'medianet', + params: { + cid: '8CUX0H51C' + } + }] + } +}); +``` + diff --git a/dev-docs/modules/multibid.md b/dev-docs/modules/multibid.md index 49f04d8786..e9ae46f0cc 100644 --- a/dev-docs/modules/multibid.md +++ b/dev-docs/modules/multibid.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - MultiBid -description: Allows bidders to return more than one bid response +description: Allows bidders to send multiple bids to the ad server. module_code : multibid display_name : MultiBid enable_download : true diff --git a/dev-docs/modules/optimeraRtdProvider.md b/dev-docs/modules/optimeraRtdProvider.md index ef52f29cf9..351febd353 100644 --- a/dev-docs/modules/optimeraRtdProvider.md +++ b/dev-docs/modules/optimeraRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : optimeraRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- @@ -21,9 +22,11 @@ Optimera Real Time Data Module. Provides targeting for ad requests from data col 1) Compile the Optimera RTD Provider into your Prebid build: ``` -`gulp build --modules=optimeraRtdProvider`... +`gulp build --modules=rtdModule,optimeraRtdProvider`... ``` +Note: You must include rtdModule in the build list. + 2) Use `setConfig` to instruct Prebid.js to initialize the optimera module, as specified below. ## Configuration @@ -49,6 +52,12 @@ Configuration example for using RTD module with the `optimeraRTD` provider: } ``` +## Migration From the Optimera Bidder Adapter + +The Optimera Bidder Adapter is no longer active with Prebid 5.0. Therefore, the bidder settings used for the Optimera Bidder Adapter for < Prebid 5.0 can be removed and replaced with this new Optimera RTD module configuration. + +For the optimeraKeyName setting, the Optimera Bidder Adapter used 'hb_deal_optimera' as the key name, as this is the key that name used in GAM. There is no need to change this key name in GAM, as you can still use this key name with the Optimera RTD Module as indicated above. + Parameters details: Contact Optimera to get assistance with the params. diff --git a/dev-docs/modules/permutiveRtdProvider.md b/dev-docs/modules/permutiveRtdProvider.md new file mode 100644 index 0000000000..0983fe4d8a --- /dev/null +++ b/dev-docs/modules/permutiveRtdProvider.md @@ -0,0 +1,76 @@ +--- +layout: page_v2 +title: Permutive Real Time Data Provider +display_name: Permutive Real Time Data Module +description: Permutive Real Time Data Module +page_type: module +module_type: rtd +module_code : permutiveRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Permutive RTD Provider +{:.no_toc} + +* TOC +{:toc} + +## Overview +This module reads cohorts from Permutive and attaches them as targeting keys to bid requests. + +## Usage +Compile the Permutive RTD module into your Prebid build: +``` +gulp build --modules=rtdModule,permutiveRtdProvider +``` + +> Note that the global RTD module, `rtdModule`, is a prerequisite of the Permutive RTD module. + +You then need to enable the Permutive RTD in your Prebid configuration, using the below format: + +```javascript +pbjs.setConfig({ + ..., + realTimeData: { + auctionDelay: 50, // optional auction delay + dataProviders: [{ + name: 'permutive', + waitForIt: true, // should be true if there's an `auctionDelay` + params: { + acBidders: ['appnexus'] + } + }] + }, + ... +}) +``` + +## Supported Bidders +The Permutive RTD module sets Audience Connector cohorts as bidder-specific `ortb2.user.data` first-party data, following the Prebid `ortb2` convention, for any bidder included in `acBidders`. The module also supports bidder-specific data locations per ad unit (custom parameters) for the below bidders: + +{: .table .table-bordered .table-striped } +| Bidder | ID | Custom Cohorts | Audience Connector | +| ----------- | ---------- | -------------------- | ------------------ | +| Xandr | `appnexus` | Yes | Yes | +| Magnite | `rubicon` | Yes | No | +| Ozone | `ozone` | No | Yes | + +Key-values details for custom parameters: +* **Custom Cohorts:** The module configuration will automatically reflect the SSP integrations (_Activations_) you have enabled in your Permutive dashboard. Any additional bidders you want to pass data to will need to be configured. Permutive cohorts will be sent in the permutive key-value. + +* **Audience Connector:** You'll need to define which bidders should receive Audience Connector cohorts. You need to include the `ID` of any bidder in the `acBidders` array. Audience Connector cohorts will be sent in the `p_standard` key-value. + + +## Parameters + +{: .table .table-bordered .table-striped } +| Name | Type | Description | Default | +| ----------------- | -------------------- | ------------------ | ------------------ | +| name | String | This should always be `permutive` | - | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | +| params | Object | | - | +| params.acBidders | String[] | An array of bidders which should receive Audience Connector cohorts. | `[]` | +| params.maxSegs | Integer | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500` | + diff --git a/dev-docs/modules/prebidServer.md b/dev-docs/modules/prebidServer.md new file mode 100644 index 0000000000..726b354ff9 --- /dev/null +++ b/dev-docs/modules/prebidServer.md @@ -0,0 +1,262 @@ +--- +layout: page_v2 +title: Module - Prebid Server Adapter +display_name: Prebid Server Adapter +description: Server-to-Server header bidding +page_type: module +module_code : prebidServerBidAdapter +enable_download : true +vendor_specific: false +sidebarType : 1 +--- + +# Prebid Server Adapter +{: .no_toc} + +* TOC +{:toc } + +## Overview + +The Prebid Server Adapter is a meta-adapter. It's not an actual bidder, but +rather a way to get a batch of bids from other bidders with one request. +A request for the set of auctions is sent to Prebid Server, which performs +all the auctions server-to-server (S2S), responding in time for Prebid.js to +send the results to the ad server. This lightens the performance load on the user's device. + +## Configuration +Here's an example config enabling the AppNexus Prebid Server: + +```javascript +pbjs.setConfig({ + s2sConfig: { + accountId : '12345', + bidders : ['appnexus','pubmatic', 'rubicon'], + defaultVendor: 'appnexus', + timeout: 300 + } +}); +``` + +To use multiple prebid servers, just define `s2sConfig` as an array. +The same bidder cannot be set in both configs. For example: + +```javascript +pbjs.setConfig({ + s2sConfig: [ + { + accountId: '12345', + bidders: ['appnexus','pubmatic'], + defaultVendor: 'appnexus', + timeout: 300, + }, + { + accountId: '678910', + bidders: ['rubicon'], + defaultVendor: 'rubicon', + timeout: 300, + }, + ], +}); +``` +There are many configuration options for s2sConfig: + +{: .table .table-bordered .table-striped } +| Attribute | Scope | Type | Description | +|------------+---------+---------+---------------------------------------------------------------| +| `accountId` | Required | String | Your Prebid Server account ID. This is obtained from whoever's hosting your Prebid Server. | +| `bidders` | Optional | Array of Strings | Which bidders auctions should take place on the server side | +| `allowUnknownBidderCodes` | Optional | Boolean | Allow Prebid Server to bid on behalf of bidders that are not explicitly listed in the adUnit. See important [note](#allowUnknownBidderCodes) below. Defaults to `false`. | +| `defaultVendor` | Optional | String | Automatically includes all following options in the config with vendor's default values. Individual properties can be overridden by including them in the config along with this setting. See the Additional Notes below for more information. | +| `enabled` | Optional | Boolean | Enables this s2sConfig block - defaults to `false` | +| `timeout` | Required | Integer | Number of milliseconds allowed for the server-side auctions. This should be approximately 200ms-300ms less than your Prebid.js timeout to allow for all bids to be returned in a timely manner. See the Additional Notes below for more information. | +| `adapter` | Required | String | Adapter to use to connect to Prebid Server. Defaults to 'prebidServer' | +| `endpoint` | Required | URL or Object | Defines the auction endpoint for the Prebid Server cluster. See table below for object config properties. | +| `syncEndpoint` | Required | URL or Object | Defines the cookie_sync endpoint for the Prebid Server cluster. See table below for object config properties. | +| `userSyncLimit` | Optional | Integer | Max number of userSync URLs that can be executed by Prebid Server cookie_sync per request. If not defined, PBS will execute all userSync URLs included in the request. | +| `syncTimeout` | Optional | Integer | Maximum number of milliseconds allowed for each server-side userSync to load. Default is 1000. | +| `syncUrlModifier` | Optional | Object | Function to modify a bidder's sync url before the actual call to the sync endpoint. Bidder must be enabled for s2sConfig. | +| `coopSync` | Optional | Boolean | Whether or not PBS is allowed to perform "cooperative syncing" for bidders not on this page. Publishers help each other improve match rates by allowing this. Default is true. | +| `defaultTtl` | Optional | Integer | Configures the default TTL in the Prebid Server adapter to use when Prebid Server does not return a bid TTL - 60 if not set | +| `adapterOptions` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in every impression object at request.imp[].ext.BIDDER. See the example above. | +| `extPrebid` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in request.ext.prebid. See the examples below. | + +If `endpoint` and `syncEndpoint` are objects, these are the supported properties: + +{: .table .table-bordered .table-striped } +| Attribute | Scope | Type | Description | +|------------+---------+---------+---------------------------------------------------------------| +| p1Consent | Required | String | Defines the auction endpoint or the cookie_sync endpoint for the Prebid Server cluster for non-consent requests or users who grant consent. | +| noP1Consent | Required | String | Defines the auction endpoint or the cookie_sync endpoint for the Prebid Server cluster for users who do not grant consent. (This is useful for a server configured to not accept any cookies to ensure compliance regulations.) | + +**Notes on s2sConfig properties** + +- Currently supported vendors are: appnexus, openx, and rubicon +- When using `defaultVendor` option, `accountId` still needs to be defined. +- If `bidders` is omitted, only adUnits that also omit bidders will be sent to Prebid Server. See the [stored impressions](#stored-imp) example below. +- If the `s2sConfig` timeout is greater than the Prebid.js timeout, the `s2sConfig` timeout will be automatically adjusted to 75% of the Prebid.js timeout in order to fit within the auction process. +- When using the `endpoint` or `syncEndpoint` object configs, you should define both properties. If either property is not defined, Prebid Server requests for that type of user will not be made. If you do not need to distinguish endpoints for consent reasons, you can simply define the same URL value in both fields or use the String version of the field (which is configured to use defined URL for all users). +- When `allowUnknownBidderCodes` is `true`, bidders that have not been explicitly requested in [`adUnit.bids`](../adunit-reference.html#adunitbids) may take part in the auction. This can break custom logic that relies on the availability of a bid request object for any given bid. Known scenarios where custom code won't get the request when there's an "unknown bidder": + - There will not be a [`bidRequested`](getEvents.html) event. + - In the [MASS custom renderers](/dev-docs/modules/mass.html#configuration-parameters) module, `payload.bidRequest` will be undefined. + - In the [Price Floors module](/dev-docs/modules/floors.html), custom schema functions will see the bidRequest object as undefined. + + +Additional options for `s2sConfig` may be enabled by including the [Server-to-Server testing module]({{site.baseurl}}/dev-docs/modules/s2sTesting.html). + +**Passing the Referrer to Server Side Adapters** + +* Setting `extPrebid.origreferrer` will be recognized by some server-side adapters as the referring URL for the current page. + +## Bid Params + +Bid params are sourced from the adapter configurations set for client side. These do not need to change for Prebid Server. + +{: .alert.alert-warning :} +**Errors in bidder parameters will cause Prebid Server to reject the +entire request.** The Prebid Server philosophy is to avoid silent failures -- +we assume you will test changes, and that it will be easier to notice a +4xx error coming from the server than a silent failure where it skips just +the bad parameter. + + +## Examples + +### Defining endpoints + +s2sConfig example with the endpoint attributes defined instead of using the 'defaultVendor' approach: +```javascript +pbjs.setConfig({ + s2sConfig: [{ + accountId: '1001', + bidders: ['bidderA', 'bidderB'], + endpoint: 'https://mypbs.example.com/path', + syncEndpoint: 'https://mypbs.example.com/path', + timeout: 300 + }] +}) +``` + +A similar example with the endpoint attributes defined as objects: +```javascript +pbjs.setConfig({ + s2sConfig: [{ + accountId: '1001', + bidders: ['bidderA', 'bidderB'], + endpoint: { + p1Consent: 'https://mypbs.example.com/path', + noP1Consent: 'https://mypbs2.example.com/path' + }, + syncEndpoint: { + p1Consent: 'https://mypbs.example.com/path', + noP1Consent: 'https://mypbs2.example.com/path' + }, + timeout: 300 + }] +}) +``` + +### Server-Side Aliases + +You may want to run a particular bidder on the client for banner, but that same bidder on the +server for video. You would do this by setting a **server-side** alias. For example: + +```javascript +pbjs.setConfig({ + s2sConfig: [{ + accountId: '1', + bidders: ['tripleliftVideo'], + defaultVendor: 'appnexus', + timeout: 500, + extPrebid: { + aliases: { + tripleliftVideo: tripleLift + } + } + }] +}) +``` + +Here's how it works: + +1. Video ad units are coded with the dynamic alias. e.g. tripleliftVideo +1. The s2sConfig.bidders array contains 'tripleliftVideo' telling Prebid.js to direct bids for that code to the server +1. Finally, the extPrebid.aliases line tells Prebid Server to route the 'tripleliftVideo' biddercode to the 'triplelift' server-side adapter. + +### Video via s2sConfig + +Supporting video through the Server-to-Server route can be done by providing a couple of extra arguments on the `extPrebid` object. e.g. + +```javascript +pbjs.setConfig({ + s2sConfig: [{ + accountId: '1001', + bidders: ['rubicon', 'pubmatic'], + defaultVendor: 'rubicon', + timeout: 250, + extPrebid: { + cache: { + vastxml: {returnCreative: false} + }, + targeting: { + pricegranularity: {"ranges": [{"max": 40.00, "increment": 1.00}]} + } + } + }] +}) +``` + + + +### Stored impressions + +Prebid Server stored [requests](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-requests) can be requested through the adUnit `ortb2Imp` property. This is useful to move the list of bidders and parameters from the page to blocks of JSON stored on the server. For these cases, it's not necessary to specify `bids`: + +```javascript +pbjs.addAdUnits([{ + code: 'example-stored-request', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + ortb2Imp: { + ext: { + prebid: { + storedrequest: { + id: 'your-stored-request-id' + } + } + } + } +}]) +``` + +### Stored responses + +For debugging purposes, it can be useful to have a page that retrieves a static value rather than running an actual auction. +For this you can use PBS [stored responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses-pbs-java-only). +Here's an example: + +```javascript +pbjs.addAdUnits([{ + code: 'example-stored-response', + mediaTypes: { + banner: { + sizes: [[300, 250]] + } + }, + ortb2Imp: { + ext: { + prebid: { + storedauctionresponse: { + id: 'your-stored-response-id' + } + } + } + } +}]) +``` + +## Related Reading +- [Prebid Server Overview](/prebid-server/overview/prebid-server-overview.html) diff --git a/dev-docs/modules/pubCommonId.md b/dev-docs/modules/pubCommonId.md index 7e42c44ade..455e89bb38 100644 --- a/dev-docs/modules/pubCommonId.md +++ b/dev-docs/modules/pubCommonId.md @@ -4,7 +4,7 @@ page_type: module title: Module - Publisher Common ID description: User ID persisted in first party domain module_code : pubCommonId -display_name : Publisher Common ID +display_name : Publisher Common ID (deprecated) enable_download : true sidebarType : 1 --- diff --git a/dev-docs/modules/reconciliationRtdProvider.md b/dev-docs/modules/reconciliationRtdProvider.md index da9da39642..47ff52d92e 100644 --- a/dev-docs/modules/reconciliationRtdProvider.md +++ b/dev-docs/modules/reconciliationRtdProvider.md @@ -5,8 +5,9 @@ description: Reconciliation Real Time Data Module page_type: module module_type: rtd module_code: reconciliationRtdProvider -display_name: Reconciliation +display_name: Reconciliation Supply Chain Validation enable_download: true +vendor_specific: true sidebarType: 1 --- diff --git a/dev-docs/modules/schain.md b/dev-docs/modules/schain.md index 77934e227c..4534f4840b 100644 --- a/dev-docs/modules/schain.md +++ b/dev-docs/modules/schain.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Supply Chain Object -description: Validates Supply Chain object and makes it available to bidder +description: Validates the Supply Chain object and makes it available to bidders. module_code : schain display_name : Supply Chain Object enable_download : true diff --git a/dev-docs/modules/sirdataRtdProvider.md b/dev-docs/modules/sirdataRtdProvider.md index 419c8f0876..68a07237f2 100644 --- a/dev-docs/modules/sirdataRtdProvider.md +++ b/dev-docs/modules/sirdataRtdProvider.md @@ -7,6 +7,7 @@ page_type: module module_type: rtd module_code : sirdataRtdProvider enable_download : true +vendor_specific: true sidebarType : 1 --- @@ -195,4 +196,4 @@ To view an example of available segments returned by Sirdata's backends: and then point your browser at: -`http://localhost:9999/integrationExamples/gpt/sirdataRtdProvider_example.html` \ No newline at end of file +`http://localhost:9999/integrationExamples/gpt/sirdataRtdProvider_example.html` diff --git a/dev-docs/modules/sizeMappingV2.md b/dev-docs/modules/sizeMappingV2.md index e51406e929..db922d158f 100644 --- a/dev-docs/modules/sizeMappingV2.md +++ b/dev-docs/modules/sizeMappingV2.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - Size Mapping -description: Display Conditional and Responsive Ad Units +description: Display Responsive AdUnits in demanding page environments. module_code: sizeMappingV2 display_name: Advanced Size Mapping enable_download: true @@ -42,6 +42,8 @@ It's meant for publishers that have complex site designs. You should use this mo If, on the other hand, the AdUnits, bidders, and mediaTypes all change behavior together at the same viewport width, then the built-in [`sizeConfig`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-Responsive-Ads) feature will work. + +Note that the Prebid Server bid adapter does not currently support the scenario where an adUnit has multiple mediaTypes, with different bidders set to different relevantMediaTypes for the same screen size. {% endcapture %} {% include alerts/alert_tip.html content=tip-choosing %} @@ -56,7 +58,7 @@ If you've used [`sizeConfig`](/dev-docs/publisher-api-reference/setConfig.html#s {% highlight js %} mediaTypes: { banner: { - sizeConfig = [ + sizeConfig: [ { minViewPort: [0, 0], sizes: [] }, // deactivate if viewport < 750px { minViewPort: [750, 0], sizes: [[300, 250], [300, 600]] } // activate viewport > 750px ]; diff --git a/dev-docs/modules/timeoutRtdProvider.md b/dev-docs/modules/timeoutRtdProvider.md new file mode 100644 index 0000000000..7830eb7b40 --- /dev/null +++ b/dev-docs/modules/timeoutRtdProvider.md @@ -0,0 +1,159 @@ +--- +layout: page_v2 +title: Timeout Rtd Module +display_name: Timeout RTD +description: Module for managing timeouts in real time +page_type: module +module_type: rtd +module_code : timeoutRtdProvider +enable_download : true +sidebarType : 1 +--- + +## Overview +The timeout RTD module enables publishers to set rules that determine the timeout based on +certain features. It supports rules dynamically retrieved from a timeout provider as well as rules +set directly via configuration. +Build the timeout RTD module into the Prebid.js package with: +``` +gulp build --modules=timeoutRtdProvider,rtdModule... +``` + +## Configuration +The module is configured in the realTimeData.dataProviders object. The module will override +`bidderTimeout` in the pbjs config. + +### Timeout Data Provider interface +The timeout RTD module provides an interface of dynamically fetching timeout rules from +a data provider just before the auction begins. The endpoint url is set in the config just as in +the example below, and the timeout data will be used when making bid requests. + +``` +pbjs.setConfig({ + ... + "realTimeData": { + "dataProviders": [{ + "name": 'timeout', + "params": { + "endpoint": { + "url": "http://{cdn-link}.json" + } + } + } + ]}, + + // This value below will be modified by the timeout RTD module if it successfully + // fetches the timeout data. + "bidderTimeout": 1500, + ... +}); +``` + +Sample Endpoint Response: +``` +{ + "rules": { + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-5": 100, + "6-10": 200, + "11-15": 300 + }, + "deviceType": { + "2": 50, + "4": 100, + "5": 200 + }, + "connectionSpeed": { + "slow": 200, + "medium": 100, + "fast": 50, + "unknown": 10 + }, +} +``` + +### Rule Handling: +The rules retrieved from the endpoint will be used to add time to the `bidderTimeout` based on certain features such as +the user's deviceType, connection speed, etc. These rules can also be configured statically on page via a `rules` object. +Note that the timeout Module will ignore the static rules if an endpoint url is provided. The timeout rules follow the +format: +``` +{ + '': { + '': + } +} +``` +See bottom of page for examples. + +Currently supported features: + +|Name |Description | Keys | Example +| :------------ | :------------ | :------------ |:------------ | +| includesVideo | Adds time to the timeout based on whether there is a video ad unit in the auction or not | 'true'/'false'| { "true": 200, "false": 50 } | +| numAdUnits | Adds time based on the number of ad units. Ranges in the format `'lowerbound-upperbound` are accepted. This range is inclusive | numbers or number ranges | {"1": 50, "2-5": 100, "6-10": 200} | +| deviceType | Adds time based on device type| 2, 4, or 5| {"2": 50, "4": 100} | +| connectionSpeed | Adds time based on connection speed. `connectionSpeed` defaults to 'unknown' if connection speed cannot be determined | slow, medium, fast, or unknown | { "slow": 200} | + +If there are multiple rules set, all of them would be used and any that apply will be added to the base timeout. For example, if the rules object contains: +``` +{ + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-3": 100, + "4-5": 200 + } +} +``` +and there are 3 ad units in the auction, all of which are banner, then the timeout to be added will be 150 milliseconds (50 for `includesVideo[false]` + 100 for `numAdUnits['1-3']`). + +Full example: +``` +pbjs.setConfig({ + ... + "realTimeData": { + "dataProviders": [{ + "name": 'timeout', + "params": { + "rules": { + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-5": 100, + "6-10": 200, + "11-15": 300 + }, + "deviceType": { + "2": 50, + "4": 100, + "5": 200 + }, + "connectionSpeed": { + "slow": 200, + "medium": 100, + "fast": 50, + "unknown": 10 + } + } + } + ]} + } + ... + // The timeout RTD module will add time to `bidderTimeout` based on the rules set above. + "bidderTimeout": 1500, +``` + +## Timeout Providers + +{: .table } +| Partner | Contact | About | +| OpenX | [apollo@openx.com](mailto:apollo@openx.com) | Dynamic timeout optimization and more | \ No newline at end of file diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index dcfc0245a0..3398e3a390 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - User ID -description: Supports multiple cross-vendor user IDs +description: Vendor-specific user ID sub-modules are available to support a range of identification approaches. module_code : userId display_name : User ID enable_download : false @@ -29,6 +29,7 @@ The User ID module supports multiple ways of establishing pseudonymous IDs for u 1. If GDPR applies, the consent signal from the CMP is hashed and stored in a cookie called `_pbjs_userid_consent_data`. This is required so that ID sub-modules may be called to refresh their ID if the user's consent preferences have changed from the previous page, and ensures cached IDs are no longer used if consent is withdrawn. 1. An object containing one or more IDs (`bidRequest.userId`) is made available to Prebid.js adapters and Prebid Server S2S adapters. 1. In addition to `bidRequest.userId`, `bidRequest.userIdAsEids` is made available to Prebid.js adapters and Prebid Server S2S adapters. `bidRequest.userIdAsEids` has userIds in ORTB EIDS format. +1. The page can call [pbjs.getUserIds()](/dev-docs/publisher-api-reference/getUserIds.html), [pbjs.getUserIdsAsEids()](/dev-docs/publisher-api-reference/getUserIdsAsEids.html), or [pbjs.getUserIdsAsync()](/dev-docs/publisher-api-reference/getUserIdsAsync.html). {: .alert.alert-info :} Note that User IDs aren't needed in the mobile app world because device ID is available in those ad serving scenarios. @@ -66,13 +67,23 @@ Publishers that want to do this should design their workflow and then set `_pbjs ## Basic Configuration By including this module and one or more of the sub-modules, a number of new options become available in `setConfig()`, -all of them under the `userSync` object as attributes of the `userIds` array -of sub-objects. The table below has the options that are common across ID systems. See the sections below for specific configuration needed by each system and examples. +under the `userSync` object as attributes of the `userIds` array +of sub-objects. + +Publishers using Google AdManager may want to sync one of the identifiers as their Google PPID for frequency capping or reporting. +The PPID in GAM (which is unrelated to the PPID UserId Submodule) has strict rules; refer to [Google AdManager documentation](https://support.google.com/admanager/answer/2880055?hl=en) for them. Please note, Prebid uses a [GPT command] (https://developers.google.com/publisher-tag/reference#googletag.PubAdsService) to sync identifiers for publisher convenience. It doesn't currently work for instream video requests, as Prebid typically interacts with the player, which in turn may interact with IMA. IMA does has a [similar method] (https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.ImaSdkSettings#setPpid) as GPT, but IMA does not gather this ID from GPT. + +{: .table .table-bordered .table-striped } +| Param under userSync | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| ppid | Optional | String | Must be a source from the [pbjs.getUserIdsAsEids()](#getUserIdsAsEids) array | `"pubcid.org"` | + +The table below has the options that are common across ID systems. See the sections below for specific configuration needed by each system and examples. {: .table .table-bordered .table-striped } | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | May be: `"admixerId"`, `"amxId"`, `"britepoolId"`, `"criteo"`, `"fabrickId"`, `"flocId"`, `"haloId"`, `"id5id"`, `identityLink`, `"idx"`, `"intentIqId"`, `"liveIntentId"`, `"lotamePanoramaId"`, `"merkleId"`, `"mwOpenLinkId"`, `"netId"`, `"novatiqId"`, `"parrableId"`, `"quantcastId"`, `"pubProvidedId"`, `"sharedId"`, `"tapadId"`, `"unifiedId"`,`"uid2"`, `"verizonMediaId"`, `"zeotapIdPlus"` | `"unifiedId"` +| name | Required | String | May be: `"33acrossId"`, `"admixerId"`, `"qid"`, `"adtelligentId"`, `"amxId"`, `"britepoolId"`, `"criteo"`, `"fabrickId"`, `"flocId"`, `"hadronId"`, `"id5id"`, `identityLink`, `"idx"`, `"intentIqId"`, `"justId"`, `"liveIntentId"`, `"lotamePanoramaId"`, `"merkleId"`, `"naveggId"`, `"mwOpenLinkId"`, `"netId"`, `"novatiqId"`, `"parrableId"`, `"quantcastId"`, `"pubProvidedId"`, `"sharedId"`, `"tapadId"`, `"unifiedId"`,`"uid2"`, `"verizonMediaId"`, `"zeotapIdPlus"` | `"unifiedId"` | params | Based on User ID sub-module | Object | | | | bidders | Optional | Array of Strings | An array of bidder codes to which this user ID may be sent. | `['bidderA', 'bidderB']` | | storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be either cookie or HTML5 storage. This is not needed when `value` is specified or the ID system is managing its own storage | | @@ -80,8 +91,7 @@ of sub-objects. The table below has the options that are common across ID system | storage.name | Required | String | The name of the cookie or html5 local storage where the user ID will be stored. | `"_unifiedId"` | | storage.expires | Strongly Recommended | Integer | How long (in days) the user ID information will be stored. If this parameter isn't specified, session cookies are used in cookie-mode, and local storage mode will create new IDs on every page. | `365` | | storage.refreshInSeconds | Optional | Integer | The amount of time (in seconds) the user ID should be cached in storage before calling the provider again to retrieve a potentially updated value for their user ID. If set, this value should equate to a time period less than the number of days defined in `storage.expires`. By default the ID will not be refreshed until it expires. -| value | Optional | Object | Used only if the page has a separate mechanism for storing a User ID. The value is an object containing the values to be sent to the adapters. | `{"tdid": "1111", "pubcid": {2222}, "IDP": "IDP-2233", "id5id": {"uid": "ID5-12345"}}` | - +| value | Optional | Object | Used only if the page has a separate mechanism for storing a User ID. The value is an object containing the values to be sent to the adapters. | `{"tdid": "1111", "IDP": "IDP-2233", "id5id": {"uid": "ID5-12345"}}` | ## Permissions Publishers can control which user ids are shared with the bid adapters they choose to work with by using the bidders array. The bidders array is part of the User id module config, publisher may choose to send an id to some bidders but not all, the default behavior is that each user id go to all bid adapters the publisher is working with. @@ -139,6 +149,53 @@ The Rubicon bid adapter would then receive ## User ID Sub-Modules +### 33Across ID + +The 33Across User ID sub-module is a way for publishers to monetize their cookieless inventory across multiple supply-side platforms via Prebid.JS. The sub-module provides publishers with addressability for their open marketplace cookieless inventory and access to cookieless demand. The 33Across User ID sub-module utilizes Lexicon technology to connect Publishers to Demand partners via proprietary technologies in a probabilistic and privacy-safe manner. Please contact [PrebidUIM@33across.com](mailto:PrebidUIM@33across.com) to get your authorization process started. + +#### 33Across ID Configuration + +Please make sure to add the 33across user ID sub-module to your Prebid.js package with: + +```shell +gulp build --modules=33acrossIdSystem,userId +``` + +The following configuration parameters are available: + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this sub-module | `"33acrossId"` | +| params ||| Details for the sub-module initialization || +| params.pid | Required | String | Partner ID (PID) | Please reach out to [PrebidUIM@33across.com](mailto:PrebidUIM@33across.com) and request your PID | +| storage ||||| +| storage.name | Required | String | The name of the cookie or html5 local storage key | `"33acrossId"` (recommended) | +| storage.type | Required | String | This is where the 33across user ID will be stored | `"html5"` (recommended) or `"cookie"` | +| storage.expires | Strongly Recommended | Number | How long (in days) the user ID information will be stored | `90` (recommended) | +| storage.refreshInSeconds | Strongly Recommended | Number | How many seconds until the ID is refreshed | `8 * 3600` (recommended) | + +#### 33Across ID Example +``` +pbjs.setConfig({ + userSync: { + userIds: [{ + name: "33acrossId", + params: { + pid: "0010b00002GYU4eBAH" // Example ID + }, + storage: { + name: "33acrossId", + type: "html5", + expires: 90, + refreshInSeconds: 8 * 3600 + } + }] + } +}); +``` + + ### AdmixerID Admixer ID, provided by [Admixer] (https://admixer.com/), is a universal ID solution that doesn't rely on 3rd party cookies and helps publishers and advertisers to recognize users across various browsers and environments. Our sub adapter takes deterministic signals like email and phone as input and returns an anonymous id that unlocks access to a wide range of Admixer's demand sources, amplifying audience segmentation, targeting and measurement. @@ -157,7 +214,7 @@ gulp build --modules=admixerIdSystem | --- | --- | --- | --- | --- | | name | Required | String | `"admixerId"` | `"admixerId"` | | params | Required | Object | Details for admixer initialization. | | -| params.pid | Required | String | id provided by admixer | "458frgde-djd7-3ert-gyhu-12fghy76dnmko" | +| params.pid | Optional | String | id provided by admixer | "458frgde-djd7-3ert-gyhu-12fghy76dnmko" | | params.e | Optional | String | The hashed email address of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha256. | "3d400b57e069c993babea0bd9efa79e5dc698e16c042686569faae20391fd7ea" | | params.p | Optional | String | The hashed phone number of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha256. | "05de6c07eb3ea4bce45adca4e0182e771d80fbb99e12401416ca84ddf94c3eb9" | @@ -186,6 +243,123 @@ gulp build --modules=admixerIdSystem }); {% endhighlight %} +### adQuery QiD + +The adQuery QiD is a first-party identifier designed for publishers using the Adquery adapter. For more information please contact [prebid@adquery.io](prebid@adquery.io) + +#### adQuery QiD Configuration + +First, add the adQuery QiD module to your Prebid.js build: + +```shell +gulp build --modules=userId,adqueryIdSystem +``` + +Then configure the qui in your `userSync` configuration: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'qid', + storage: { + name: 'qid', + type: 'html5', + expires: 365, + } + }] + } +}); +``` + +This will add a `userId.qid` property to all bidRequests. This will be read by the Adquery bid adapter, and any other adapters that support EIDs: + +```javascript +{ + qid: 'p9v2dpnuckkzhuc92i' +} +``` + +### Adtelligent + +The [Adtelligent](https://adtelligent.com) ID system is a unique per-session user identifier for providing high quality DMP data for advertisers + +Add it to your Prebid.js package with: + +{: .alert.alert-info :} +gulp build --modules=userId,adtelligentIdSystem + +#### Adtelligent Configuration + +adtelligentIdSystem adapter doesn't require any configuration or storage params. The adapter performs asynchronously and to achieve better performance it is recommended to set the `storage` object `refreshInSeconds` to a short period, such as ten minutes. At the end of the set storage refresh the adapter will refresh its configuration. + +#### Adtelligent Example + +{% highlight javascript %} + pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'adtelligent' + }] + } + }); +{% endhighlight %} + +Example with a short storage for ~10 minutes and refresh in 5 minutes: + +{% highlight javascript %} + pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'adtelligent', + storage: { + type: "html5", + name: "adt_id", + expires:0.003, + refreshInSeconds: 60 * 5 + } + }] + } + }); +{% endhighlight %} + +### AMX RTB ID + +The AMX RTB ID is a first-party identifier designed for publishers using the AMX RTB adapter. For more information please contact [prebid@amxrtb.com](prebid@amxrtb.com) + +#### AMX RTB ID Configuration + +First, add the AMX RTB ID module to your Prebid.js build: + +```shell +gulp build --modules=userId,amxIdSystem +``` + +Then configure the amxId in your `userSync` configuration: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'amxId', + storage: { + name: 'amxId', + type: 'html5', + expires: 14, + } + }] + } +}); +``` + +This will add a `userId.amxId` property to all bidRequests. This will be read by the AMX RTB bid adapter, and any other adapters that support EIDs: + +```javascript +{ + amxId: '3ca11058-ecbc-419f-bda7-b52fe7baf02a' +} +``` + ### BritePool The [BritePool](https://britepool.com) ID is a persistent identifier that enables identity resolution for people-based marketing in the cookieless world. Every BritePool ID is associated with a real identity. As a result, publishers, SSPs and DSPs that integrate with BritePool, or automated @@ -271,6 +445,61 @@ pbjs.setConfig({ }); {% endhighlight %} +### Czech Publisher Exchange ID (CPExID) + +CPExID is provided by [Czech Publisher Exchange](https://www.cpex.cz/), or CPEx. It is a user ID for ad targeting by using first party cookie, or localStorage mechanism. Please contact CPEx before using this ID. + +{: .alert.alert-info :} +gulp build --modules=cpexIdSystem + +#### CPExId Configuration + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module | `"cpexId"` | + +#### CPExId Example + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'cpexId' + }] + } +}); +{% endhighlight %} + +### AudienceOne ID by DAC + +AudienceOne ID, provided by [D.A.Consortium Inc.](https://www.dac.co.jp/), is ID for ad targeting by using 1st party cookie. +Please contact D.A.Consortium Inc. before using this ID. + +Add the AudienceOne ID to your Prebid.js Package with: + +{: .alert.alert-info :} +gulp build --modules=dacIdSystem + +#### AudienceOne ID Configuration + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module | `"dacId"` | + +#### AudienceOne ID Example + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'dacId' + }] + } +}); +{% endhighlight %} + ### Deepintent DPES ID by Deepintent The DeepIntent Healthcare Marketing Platform is the first and only DSP that combines real-world health data, premium partnerships, and custom integrations to reach patients and providers across any device. DeepIntent empowers publishers to maximize their inventory, collaborate and transact directly with advertisers, and grow their business in a safe, controlled, transparent, and privacy-compliant way. Our publisher partners sell inventory on every channel via real-time bidding or conducting one-to-one trading with hundreds of the country’s leading healthcare brands and agencies. @@ -302,7 +531,7 @@ pbjs.setConfig({ name: 'deepintentId', storage: { type: 'cookie', // "html5" is the required storage type option is "html5" - name: '_dpes_id', + name: '_dpes_id', expires: 90 // storage lasts for 90 days, optional if storage type is html5 } }], @@ -329,7 +558,7 @@ pbjs.setConfig({ ### DMD ID by DMD Marketing Corp -DMD is the preeminent supplier of US-based healthcare professional (HCP) identity data to the pharmaceutical, health system and medical publishing industries. DMD is the only data provider that has acquired its deterministic identity data through a fully consented, first-party, opt-in process. DMD’s privacy policy that can be found at [Privacy Policy](https://hcn.health/privacy-policy). +DMD is the preeminent supplier of US-based healthcare professional (HCP) identity data to the pharmaceutical, health system and medical publishing industries. DMD is the only data provider that has acquired its deterministic identity data through a fully consented, first-party, opt-in process. DMD’s privacy policy that can be found at [Privacy Policy](https://hcn.health/privacy-policy). For assistance setting up your module, please contact us at prebid@dmdconnects.com @@ -396,6 +625,11 @@ Please reach out to [FabrickIntegrations@team.neustar](mailto:FabrickIntegration | params.m | | String | This is a mobile advertising ID (IDFA/AAID) used to link a user to their Fabrick ID. | | | params.ia | | String | This is an identifier for advertising (IFA) used to link a user to their Fabrick ID. | | | params.iv | | String | This is an identifier for vendors (IFV) used to link a user to their Fabrick ID. | | +| params.1pd | | String | This is the 1st party user ID (e.g. a Customer ID/CUSTID). Note: This requires separate delivery of identity log files keyed off the 1st party user ID to establish an identity sync. | | +| params.u | | String | This is the page_url - the url which the user is currently browsing. Note: Encoding is required for any character outside of alphabets (A-Z a-z), digits (0-9), hyphen (-), underscore (_) tilde (~), and dot (.). | | +| params.f | | String | This is the referrer_url - the url which the user visited prior to landing on the page_url. Note: Encoding is required for any character outside of alphabets (A-Z a-z), digits (0-9), hyphen (-), underscore (_) tilde (~), and dot (.). | | +| params.ifa_type | | String | This denotes the source of the IFA. Please refer to [IAB IFA Guidelines](https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf) for recommended values and additional details. | | +| params.lmt | | Boolean | Possible values are '0' or '1'. A value of '1' indicates that a user has requested that ad tracking and measurement be disabled. If a value of '1' is being passed, the real IFA must not be sent via the 'ia' parameter – a 'synthetic' or 'session' IFA can be sent. Please refer to [IAB IFA Guidelines](https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf) for recommended values and additional details. | | #### Fabrick Examples @@ -443,9 +677,9 @@ pbjs.setConfig({ ### FLoC ID -The [Federated Learning of Cohorts (FLoC)](https://web.dev/floc/) system provides a privacy-preserving mechanism for interest-based ad selection. As a user moves around the web, their browser uses the FLoC algorithm to work out an "interest cohort", which will be the same for thousands of browsers with a similar recent browsing history. The user's browser is associated with one interest cohort at a time and recalculates its cohort periodically (currently once every seven days during this initial origin trial) on the user's device, without sharing individual browsing data with the browser vendor or anyone else. +The [Federated Learning of Cohorts (FLoC)](https://web.dev/floc/) system provides a privacy-preserving mechanism for interest-based ad selection. As a user moves around the web, their browser uses the FLoC algorithm to work out an "interest cohort", which will be the same for thousands of browsers with a similar recent browsing history. The user's browser is associated with one interest cohort at a time and recalculates its cohort periodically (currently once every seven days during this initial origin trial) on the user's device, without sharing individual browsing data with the browser vendor or anyone else. -There are two important things to note when using the FLoC Userid Sub adapter. +There are two important things to note when using the FLoC Userid Sub adapter. 1. Unlike other user id subadapters FLoC ids cannot be stored in a cookie or Local Storage. FLoC ids change periodically and should always be fetched from the FLoC API @@ -489,76 +723,103 @@ pbjs.setConfig({ }); {% endhighlight %} -### AMX RTB ID +### FTrack ID from Flashtalking By Mediaocean -The AMX RTB ID is a first-party identifier designed for publishers using the AMX RTB adapter. For more information please contact [prebid@amxrtb.com](prebid@amxrtb.com) +The FTrack Identity Framework (["FTrack"](https://www.flashtalking.com/identity-framework#FTrack)) User ID Module allows publishers to take advantage of Flashtalking's FTrack ID during the bidding process. -#### AMX RTB ID Configuration +Flashtalking’s cookieless tracking technology uses probabilistic device recognition to derive a privacy-friendly persistent ID for each device. -First, add the AMX RTB ID module to your Prebid.js build: +Questions? Comments? Bugs? Praise? Please contact FlashTalking's Prebid Support at [prebid-support@flashtalking.com](mailto:prebid-support@flashtalking.com) -```shell -gulp build --modules=userId,amxIdSystem -``` +Complete information available on the Flashtalking [privacy policy page](https://www.flashtalking.com/privacypolicy). -Then configure the amxId in your `userSync` configuration: +#### FTrack ID from Flashtalking By Mediaocean Configuration ```javascript pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'amxId', - storage: { - name: 'amxId', - type: 'html5', - expires: 14, - } - }] - } + userSync: { + userIds: [{ + name: 'FTrack', + params: { + url: 'https://d9.flashtalking.com/d9core', // required, if not populated ftrack will not run + ids: { + 'device id': true, + 'single device id': true, + 'household id': true + } + }, + storage: { + type: 'html5', // "html5" is the required storage type + name: 'FTrackId', // "FTrackId" is the required storage name + expires: 90, // storage lasts for 90 days + refreshInSeconds: 8*3600 // refresh ID every 8 hours to ensure it's fresh + } + }], + auctionDelay: 50 // 50ms maximum auction delay, applies to all userId modules + } }); ``` -This will add a `userId.amxId` property to all bidRequests. This will be read by the AMX RTB bid adapter, and any other adapters that support EIDs: - -```javascript -{ - amxId: '3ca11058-ecbc-419f-bda7-b52fe7baf02a' -} -``` - -### Halo ID from Audigent - -Audigent is a next-generation data management platform and a first-of-a-kind "data agency" containing some of the most exclusive content-consuming audiences across desktop, mobile and social platforms. Our HaloId module allows for user id resolution and Audigent user data segmentation to be retrieved for users across the web. For assistance setting up your module please contact us at [prebid@audigent.com](mailto:prebid@audigent.com). - -#### HaloId Configuration -Add the Halo ID system to your Prebid.js package with: +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| :-- | :-- | :-- | :-- | :-- | +| name | Required | String | The name of this module: `"FTrack"` | `"FTrack"` | +| params | Required | Object | The IDs available, if not populated then the defaults "Device ID" and "Single Device ID" will be returned | | +| params.url | Required | String | The URL for the ftrack library reference. If not populated, ftrack will not run. | 'https://d9.flashtalking.com/d9core' | +| params.ids | Optional | Object | The ftrack IDs available, if not populated then the defaults "Device ID" and "Single Device ID" will be returned | | +| params.ids['device id'] | Optional | Boolean | Should ftrack return "device id". Set to `true` to return it. If set to `undefined` or `false`, ftrack will not return "device id". Default is `false` | `true` | +| params.ids['single device id'] | Optional | Boolean | Should ftrack return "single device id". Set to `true` to return it. If set to `undefined` or `false`, ftrack will not return "single device id". Default is `false` | `true` | +| params.ids['household id'] | Optional; _Requires pairing with either "device id" or "single device id"_ | Boolean | __1.__ Should ftrack return "household id". Set to `true` to attempt to return it. If set to `undefined` or `false`, ftrack will not return "household id". Default is `false`. __2.__ _This will only return "household id" if value of this field is `true` **AND** "household id" is defined on the device._ __3.__ _"household id" requires either "device id" or "single device id" to be also set to `true`, otherwise ftrack will not return "household id"._ | `true` | +| storage | Required | Object | Storage settings for how the User ID module will cache the FTrack ID locally | | +| storage.type | Required | String | This is where the results of the user ID will be stored. FTrack **requires** `"html5"`. | `"html5"` | +| storage.name | Required | String | The name of the local storage where the user ID will be stored. FTrack **requires** `"FTrackId"`. | `"FTrackId"` | +| storage.expires | Optional | Integer | How long (in days) the user ID information will be stored. FTrack recommends `90`. | `90` | +| storage.refreshInSeconds | Optional | Integer | How many seconds until the FTrack ID will be refreshed. FTrack strongly recommends 8 hours between refreshes | `8*3600` | + +### Hadron ID from Audigent + +Audigent is a next-generation data management platform and a first-of-a-kind "data agency" containing some of the most exclusive content-consuming audiences across desktop, mobile and social platforms. Our HadronId module allows for user id resolution and Audigent user data segmentation to be retrieved for users across the web. For assistance setting up your module please contact us at [prebid@audigent.com](mailto:prebid@audigent.com). + +#### HadronId Configuration +Add the Hadron ID system to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=userId,haloIdSystem +gulp build --modules=userId,hadronIdSystem -Add HaloId to the userSync configuration. +Add HadronId to the userSync configuration. ``` pbjs.setConfig({ userSync: { userIds: [{ - name: 'haloId', + name: 'hadronId', storage: { - name: 'haloId', + name: 'hadronId', type: 'html5' + }, + params: { + partnerId: 1234 } }] } }); ``` -The `request.userId.haloId` will contain the Audigent HaloId and associated segments: +The `request.userId.hadronId` will contain the Audigent HadronId: ``` { - "haloId": "user-halo-id", - "auSeg": ["segment1", "segment2"] + "hadronId": "0201chpvai07jv2yg08xizqr0bwpa1w0evvmq014d2ykn0b5oe" } ``` +The following configuration parameters are available: + +{: .table .table-bordered .table-striped } +| Param under usersync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | ID value for the HadronID module - `"hadronId"` | `"hadronId"` | +| params | Optional | Object | Used to store params for the HadronId system | +| params.url | Optional | String | Set an alternate GET url for HadronId with this parameter | +| params.urlArg | Optional | Object | Optional url parameter for params.url | +| params.partnerId | Required | Number | This is the Audigent Partner ID obtained from Audigent. | ### ID+ @@ -594,15 +855,16 @@ pbjs.setConfig({ ### ID5 Universal ID -The ID5 Universal ID is a shared, neutral identifier that publishers and ad tech platforms can use to recognise users even in environments where 3rd party cookies are not available. The ID5 Universal ID is designed to respect users' privacy choices and publishers’ preferences throughout the advertising value chain. For more information about the ID5 Universal ID and detailed integration docs, please visit [our documentation](https://support.id5.io/portal/en/kb/articles/prebid-js-user-id-module). We also recommend that you sign up for our [release notes](https://id5.io/universal-id/release-notes) to stay up-to-date with any changes to the implementation of the ID5 Universal ID in Prebid. +The ID5 ID is a shared, neutral identifier that publishers and ad tech platforms can use to recognise users even in environments where 3rd party cookies are not available. The ID5 ID is designed to respect users' privacy choices and publishers’ preferences throughout the advertising value chain. For more information about the ID5 ID and detailed integration docs, please visit [our documentation](https://support.id5.io/portal/en/kb/articles/prebid-js-user-id-module). -#### ID5 Universal ID Registration -The ID5 Universal ID is free to use, but requires a simple registration with ID5. Please visit [id5.io/universal-id](https://id5.io/universal-id) to sign up and request your ID5 Partner Number to get started. +#### ID5 ID Registration -The ID5 privacy policy is at [https://www.id5.io/platform-privacy-policy](https://www.id5.io/platform-privacy-policy). +The ID5 ID is free to use, but requires a simple registration with ID5. Please visit [our website](https://id5.io/solutions/#publishers) to sign up and request your ID5 Partner Number to get started. -#### ID5 Universal ID Configuration +The ID5 privacy policy is at [https://id5.io/platform-privacy-policy](https://id5.io/platform-privacy-policy). + +#### ID5 ID Configuration First, make sure to add the ID5 submodule to your Prebid.js package with: @@ -615,7 +877,7 @@ The following configuration parameters are available: | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | name | Required | String | The name of this module: `"id5Id"` | `"id5Id"` | -| params | Required | Object | Details for the ID5 Universal ID. | | +| params | Required | Object | Details for the ID5 ID. | | | params.partner | Required | Number | This is the ID5 Partner Number obtained from registering with ID5. | `173` | | params.pd | Optional | String | Partner-supplied data used for linking ID5 IDs across domains. See [our documentation](https://support.id5.io/portal/en/kb/articles/passing-partner-data-to-id5) for details on generating the string. Omit the parameter or leave as an empty string if no data to supply | `"MT1iNTBjY..."` | | params.abTesting | Optional | Object | Allows publishers to easily run an A/B Test. If enabled and the user is in the Control Group, the ID5 ID will NOT be exposed to bid adapters for that request | Disabled by default | @@ -623,7 +885,7 @@ The following configuration parameters are available: | params.abTesting.controlGroupPct | Optional | Number | Must be a number between `0.0` and `1.0` (inclusive) and is used to determine the percentage of requests that fall into the control group (and thus not exposing the ID5 ID). For example, a value of `0.20` will result in 20% of requests without an ID5 ID and 80% with an ID. | `0.1` | {: .alert.alert-info :} -**NOTE:** The ID5 Universal ID that is delivered to Prebid is encrypted by ID5 with a rotating key to enforce privacy requirements and avoid unauthorized usage. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `8` hours (`8*3600` seconds) to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. +**NOTE:** The ID5 ID that is delivered to Prebid will be encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `8` hours (`8*3600` seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. ##### A Note on A/B Testing @@ -636,7 +898,7 @@ To turn on A/B Testing, simply edit the configuration (see above table) to enabl {: .alert.alert-warning :} **ATTENTION:** As of Prebid.js v4.14.0, ID5 requires `storage.type` to be `"html5"` and `storage.name` to be `"id5id"`. Using other values will display a warning today, but in an upcoming release, it will prevent the ID5 module from loading. This change is to ensure the ID5 module in Prebid.js interoperates properly with the [ID5 API](https://github.com/id5io/id5-api.js) and to reduce the size of publishers' first-party cookies that are sent to their web servers. If you have any questions, please reach out to us at [prebid@id5.io](mailto:prebid@id5.io). -Publisher wants to retrieve the ID5 Universal ID through Prebid.js +Publisher wants to retrieve the ID5 ID through Prebid.js {% highlight javascript %} pbjs.setConfig({ @@ -663,109 +925,77 @@ pbjs.setConfig({ }); {% endhighlight %} -### IdentityLink +### IDx + +IDx, a universal ID solution provided by [Retargetly](https://retargetly.com), is the evolution of digital identifiers for the Latin American region. Through a proprietary identity graph, it allows publishers, advertisers, and ad tech platforms to recognize users across domains and devices even where third party cookies aren't available. -IdentityLink, provided by [LiveRamp](https://liveramp.com) is a single person-based identifier which allows marketers, platforms and publishers to perform personalized segmentation, targeting and measurement use cases that require a consistent, cross-channel view of the user in anonymous spaces. +The IDx platform is designed with privacy at its core and allows for nearly every conceivable digital use case including but not limited to audience targeting, retargeting, frequency management, personalization, and total reach reporting. Add it to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=identityLinkIdSystem +gulp build --modules=idxIdSystem -#### IdentityLink Registration +#### IDx Registration -Please reach out to [prebid@liveramp.com](mailto:prebid@liveramp.com) and request your `placementId`. +If you are a publisher or an advertiser, then IDx is free to use but requires a simple registration process. To do this, please send an email to [idx-partners@retargetly.com](mailto:idx-partners@retargetly.com) to request your IDx Partner ID. -The IdentityLink privacy policy is at [https://liveramp.com/privacy/service-privacy-policy/](https://liveramp.com/privacy/service-privacy-policy/). +We may ask for some basic information from you before approving your request. For more information on IDx, please visit [retargetly.com/idx](http://retargetly.com/idx). -#### IdentityLink Configuration +#### IDx Configuration {: .table .table-bordered .table-striped } | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | `"identityLink"` | `"identityLink"` | -| params | Required for Id Link | Object | Details for identityLink initialization. | | -| params.pid | This parameter is required for IdentityLink | String | This is the placementId, value needed for obtaining user’s IdentityLink envelope -| params.notUse3P | This parameter is not required for IdentityLink | Boolean | Property for choosing should 3P Liveramp envelope endpoint be fired or not, in order to get IdentityLink envelope - -#### IdentityLink Examples - -1) Publisher passes a placement ID and elects to store the IdentityLink envelope in a cookie. - - -{% highlight javascript %} -pbjs.setConfig({ - userSync: { - userIds: [{ - name: "identityLink", - params: { - pid: '999', // Set your real identityLink placement ID here - // notUse3P: true/false // If you do not want to use 3P endpoint to retrieve the envelope. If you do not set this property to true, 3P endpoint will be fired. By default this property is undefined and 3P request will be fired. - }, - storage: { - type: "cookie", - name: "idl_env", // create a cookie with this name - expires: 30 // cookie can last for 30 days - } - }], - syncDelay: 3000 // 3 seconds after the first auction - } -}); -{% endhighlight %} +| name | Required | String | `"idx"` | `"idx"` | -2) Publisher passes a placement ID and elects to store the IdentityLink envelope in HTML5 localStorage. +#### IDx Example {% highlight javascript %} pbjs.setConfig({ userSync: { userIds: [{ - name: "identityLink", - params: { - pid: '999', // Set your real identityLink placement ID here - // notUse3P: true/false // If you do not want to use 3P endpoint to retrieve the envelope. If you do not set this property to true, 3P endpoint will be fired. By default this property is undefined and 3P request will be fired. - }, - storage: { - type: "html5", - name: "idl_env", // set localstorage with this name - expires: 30 - } - }], - syncDelay: 3000 + name: "idx" + }] } }); {% endhighlight %} -### IDx - -IDx, a universal ID solution provided by [Retargetly](https://retargetly.com), is the evolution of digital identifiers for the Latin American region. Through a proprietary identity graph, it allows publishers, advertisers, and ad tech platforms to recognize users across domains and devices even where third party cookies aren't available. +### IM-UID by Intimate Merger -The IDx platform is designed with privacy at its core and allows for nearly every conceivable digital use case including but not limited to audience targeting, retargeting, frequency management, personalization, and total reach reporting. +IM-UID, provided by [Intimate Merger](https://corp.intimatemerger.com/), is a universal identifier that designed for publishers, platforms and advertisers to perform segmentation and targeting even in environments where 3rd party cookies are not available. IM-UID is currently only available in Japan. Add it to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=idxIdSystem +gulp build --modules=imuIdSystem -#### IDx Registration +#### IM-UID Registration -If you are a publisher or an advertiser, then IDx is free to use but requires a simple registration process. To do this, please send an email to [idx-partners@retargetly.com](mailto:idx-partners@retargetly.com) to request your IDx Partner ID. +Please visit [https://lp.intimatemerger.com/im-uid](https://lp.intimatemerger.com/im-uid) and request your Customer ID to get started. -We may ask for some basic information from you before approving your request. For more information on IDx, please visit [retargetly.com/idx](http://retargetly.com/idx). +The Intimate Merger privacy policy is at https://corp.intimatemerger.com/privacypolicy/ -#### IDx Configuration +#### IM-UID Configuration {: .table .table-bordered .table-striped } | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | `"idx"` | `"idx"` | +| name | Required | String | The name of this module. | `"imuid"` | +| params | Required | Object | Details of module params. | | +| params.cid | Required | Number | This is the Customer ID value obtained via Intimate Merger. | `5126` | +| params.url | Optional | String | Use this to change the default endpoint URL. | `"https://example.com/some/api"` | -#### IDx Example +#### IM-UID Example {% highlight javascript %} pbjs.setConfig({ userSync: { userIds: [{ - name: "idx" + name: "imuid", + params: { + cid: 5126 // Set your Intimate Merger Customer ID here for production + } }] } }); @@ -884,9 +1114,102 @@ pbjs.setConfig({ }); {% endhighlight %} -### LiveIntent nonID +### Just ID -LiveIntent offers audience resolution by leveraging our next-generation identity solutions. The LiveIntent identity graph is built around a people-based set of data that is authenticated daily through active engagements with email newsletters and media across the web. The LiveIntent nonID is a user identifier tied to an active, encrypted email in our graph and functions in cookie-challenged environments and browsers. +[Justtag Group](https://www.justtag.com/en) is a European, privacy focused DMP and segment provider. Having a leading position in Poland and growing presence in the CEE region, we created Just ID - an alternative ID solution, designed to respect users’ privacy choices which doesn’t rely on 3rd party cookies. Our aim is to help Publishers and Advertisers to recognize users across various environments and enable ad-tech market players with a smooth transition into post 3rd party cookie era. + +#### Just ID Modes + +- **BASIC** - In this mode we rely on Justtag library that already exists on publisher page. Typicaly that library expose global variable called `__atm` + +- **COMBINED** - Just ID generation process may differ between various cases depends on publishers. This mode combines our js library with prebid for ease of integration + +If you have any questions about Just ID, please reach out by emailing [prebid@justtag.com](mailto:prebid@justtag.com). + +#### Just ID Configuration + +{: .table .table-bordered .table-striped } +| Param under usersync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | ID of the module - `'justId'` | `'justId'` | +| params | Optional | Object | Details for Just ID syncing. | | +| params.mode | Optional | String | Mode in which the module works. Available Modes: `'COMBINED'`, `'BASIC'`(default) | `'COMBINED'` | +| params.atmVarName | Optional | String | Name of global object property that point to Justtag ATM Library. Defaults to `'__atm'` | `'__atm'` | +| params.url | Optional | String | API Url, **required** in `COMBINED` mode | `'https://id.nsaudience.pl/getId.js'` | +| params.partner | Optional | String | This is the Justtag Partner Id which may be required in some custom integrations with Justtag | `'some-publisher'` | + +#### Just ID Example + +ex. 1. Mode `COMBINED` + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'justId', + params: { + mode: 'COMBINED', + url: 'https://id.nsaudience.pl/getId.js' + } + }] + } +}); +{% endhighlight %} + +ex. 2. Mode `BASIC` + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'justId' + }] + } +}); +{% endhighlight %} + +#### Just ID Disclosure + +This module in `COMBINED` mode loads external JavaScript to generate optimal quality user ID. It is possible to retrieve user ID, without loading additional script by this module in `BASIC` mode. + +### Kinesso ID + +Kinesso ID solution is a new approach to persistent cross domain authentication. + +#### How it works + +The Kinesso identity solution creates a persistent cross domain authenticated user id that is then used to link users with their interest signals (commonly known as segments). The Kinesso user ID (knsso) is never broadcast into the bid stream. Instead it is sent to a server side data store, merged with accompanying data from the Prebid Id Library and shipped to Kinesso. All data is encrypted at rest and in transit so your identifiers are never stored or transmitted in an insecure manner. + +The Kinesso ID sub adapter sets two cookies, one as a third party cookie and the other as a first party cookie in the publisher's domain. These cookies are merged with the user's hashed email address (when present) server side and sent to Kinesso. The combined output looks like this: + +{: .table .table-bordered .table-striped } +| kpuid | knsso | hid | account_id | created on | +| --- | --- | --- | --- | --- | +| `` | `` | `` | `` | `` | + +Kinesso will then attach these users to deals ids that they will target in the ORTB bid stream by brands and agencies represented by IPG. + +Add it to your Prebid.js package with: + +{: .alert.alert-info :} +gulp build --modules=kinessoIdSystem + +#### Kinesso ID Registration + +You can set up Kinesso ID sub adapter by contacting Kinesso at prebid@kinesso.com + +The Kinesso ID privacy policy is covered under the [Kinesso Privacy Notice](https://kinesso.com/privacy-policy/). Please note, at present the Kinesso ID module is not meant for use inside the EEA. + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module. | `'kpuid'` | +| params | Required | Object | Details for KinessoId initialization | | +| params.accountid | Required | Int | Your SSP Account Id | 123 | + +### LiveIntent nonID + +LiveIntent offers audience resolution by leveraging our next-generation identity solutions. The LiveIntent identity graph is built around a people-based set of data that is authenticated daily through active engagements with email newsletters and media across the web. The LiveIntent nonID is a user identifier tied to an active, encrypted email in our graph and functions in cookie-challenged environments and browsers. There are two ways to build your Prebid.js package to include the LiveIntent nonID: * The standard version which allows publishers to include the module with full functionalities, like hashing email addresses and identity resolution @@ -1028,9 +1351,15 @@ pbjs.setConfig({ ### Lotame Panorama ID -[Lotame Panorama](https://www.lotame.com/panorama/) is a suite of data-enrichment solutions for digital advertising that empowers marketers, agencies, publishers and media companies to transform consumer personas into addressable audiences. At the heart of Lotame Panorama is the [Panorama ID](https://www.lotame.com/panorama/id/), a people-based identifier powered by deterministic and probabilistic data, available across the cookie-challenged web and all browsers. +[Lotame Panorama](https://www.lotame.com/panorama/) is a suite of data-enrichment solutions for digital advertising that empowers marketers, agencies, publishers and media companies to transform consumer personas into addressable audiences. At the heart of Lotame Panorama is the Panorama ID, a people-based identifier powered by deterministic and probabilistic data, available across the cookie-challenged web and all browsers. + +Lotame’s Panorama ID module sends information from the request to its identity graph in order to successfully generate a Panorama ID. For more information on how the Panorama ID works, please visit [https://www.lotame.com/panorama/id/](https://www.lotame.com/panorama/id/). -The Lotame privacy policy is at [https://www.lotame.com/about-lotame/privacy/](https://www.lotame.com/about-lotame/privacy/). If you have any questions about Panorama ID, please reach out by emailing [prebid@lotame.com](mailto:prebid@lotame.com). +**Ease of Implementation**: Deployment of the Lotame Panorama ID module has been optimized for ease by not requiring any registration to utilize. Simply add the generic module to start producing the Panorama ID across your inventory. + +Lotame's privacy policy related to the Panorama ID and the collection of data and how data is used is available at [https://www.lotame.com/about-lotame/privacy/lotames-products-services-privacy-policy/](https://www.lotame.com/about-lotame/privacy/lotames-products-services-privacy-policy/). Consult with your legal counsel to determine the appropriate user disclosures with respect to use of the Lotame Panorama ID module. + +If you have any questions about Panorama ID, please reach out by emailing [PanoramaID@lotame.com](mailto:PanoramaID@lotame.com). Add it to your Prebid.js package with: @@ -1046,6 +1375,11 @@ NOTE: For optimal performance, the Lotame Panorama Id module should be called at #### Lotame Panorama ID Example +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of the module | "lotamePanoramaId" | + {% highlight javascript %} pbjs.setConfig({ userSync: { @@ -1056,6 +1390,49 @@ pbjs.setConfig({ }); {% endhighlight %} +### MediaWallah OpenLinkID + +MediaWallah's openLink is an anonymous person based ID that enables buyers and sellers of media to connect a person and their devices across the web and mobile apps. openLink facilities the buying of media between DSPs, SSPs and publishers. + +Add support for MediaWallah OpenLinkID to your Prebid.js package with: + +{: .alert.alert-info :} +gulp build --modules=userId,mwOpenLinkIdSystem + +#### MediaWallah OpenLinkID Registration + +MediaWallah requires the creation of an accountId a partnerId in order to take advantage of openLink. Please contact your partner resource to get these Ids provisioned. + +#### MediaWallah OpenLinkID Configuration + +
    +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module. | `'mwOpenLinkId'` | +| params | Required | Object | Details for mwOLID syncing. || +| params.accountId | Required | String | The MediaWallah assigned Account Id | `1000` | +| params.partnerId | Required | String | The MediaWallah assign partner Id |`'1001'`| +| params.uid | Optional | String | Your unique Id for the user or browser. Used for matching. | `'u-123xyz'` | +{: .table .table-bordered .table-striped } +
    + +#### MediaWallah OpenLinkID Examples + +``` +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'mwOpenLinkId', + params: { + accountId: '1000', + partnerId: '1001', + uid: 'u-123xyz' + } + }] + } +}) +``` + ### Merkle ID [Merkury by Merkle](https://merkury.merkleinc.com/contact) enables marketers, media owners, and publishers to own, build, and control a cookie-less Private Identity Graph. Merkury uses an organization’s first-party CRM data and valuable interactions such as logins, outbound email campaigns and media reach to create and grow a universe of person-based IDs for cross-channel targeting, personalization, measurement and more. @@ -1070,10 +1447,8 @@ pbjs.setConfig({ userIds: [{ name: 'merkleId', params: { - vendor:'example_vendor', - sv_cid:'example_cid', sv_pubid:'example_pubid', - sv_domain:'example.com' + ssp_ids: ['example_sspid_1', 'example_sspid_2'] }, storage: { type: 'html5', @@ -1085,6 +1460,24 @@ pbjs.setConfig({ }); {% endhighlight %} +### Navegg ID + +[Navegg](https://www.navegg.com) enables publishers, advertisers and agencies to use their own first party data together to activate media in a cookie-less way across several Ad Tech platforms. Navegg has one of the largest data networks in Latin America which also allows the enhancement of data with unique categories. + +#### Navegg ID Examples + +Publisher stores NaveggId in local storage and/or 1st party cookies + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'naveggId' + }] + } +}); +{% endhighlight %} + ### netID The [European netID Foundation (EnID)](https://developerzone.netid.de/index.html) aims to establish with the netID an independent European alternative in the digital market for Demand and Supply side. With the netID Single-Sign-On, the EnID established an open standard for consumer logins for services of Buyers and Brands, that also includes user-centric consent management capabilities that results in a standardized, EU-GDPR compliant, IAB TCF aware, cross-device enabled Advertising Identifier, which can be leveraged by publishers and advertisers (and vendors supporting them) to efficiently deliver targeted advertising through programmatic systems to already more than 38 million Europeans on mobile and desktop devices. @@ -1108,72 +1501,96 @@ pbjs.setConfig({ }); {% endhighlight %} -### NextRoll ID - -NextRoll is an industry-leading marketing technology and data stack that fuels growth for businesses of all kinds. Our technology powers two multi-million dollar high-growth businesses: AdRoll and RollWorks. The NextRoll ID is a cookieless identifier built from NextRoll’s proprietary identity graph. Publishers, ad tech platforms, and NextRoll’s brands (AdRoll and RollWorks) leverage the NextRoll ID to access unique demand in cookieless environments. The NextRoll ID respects user privacy preferences and enables users to opt out through multiple web based mechanisms found in [Section 8 of NextRoll’s Privacy Policy](https://nextroll.com/privacy#service-8). +### Novatiq Hyper ID -#### NextRoll ID Registration +The [Novatiq](https://www.novatiq.com) proprietary dynamic Hyper ID is a unique, non sequential and single use identifier for marketing activation. Our in network solution matches verification requests to telco network IDs safely and securely inside telecom infrastructure. The Novatiq Hyper ID can be used for identity validation and as a secured 1st party data delivery mechanism. -To sign up for a Partner ID please contact your NextRoll representative or send an email to [publishers@nextroll.com](mailto:publishers@nextroll.com). +#### Novatiq Hyper ID Configuration -#### NextRoll ID Configuration - -Add it to your Prebid.js package with: +Enable by adding the Novatiq submodule to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=nextrollIdSystem +gulp build --modules=novatiqIdSystem,userId + -Enable the module in configuration, with your Partner ID: +Module activation and configuration: {% highlight javascript %} pbjs.setConfig({ - userSync: { - userIds: [{ - name: "nextrollId", - params: { - partnerId: 'YOUR_PARTNER_ID' - } - }] - } + userSync: { + userIds: [{ + name: 'novatiq', + params: { + // change to the Partner Number you received from Novatiq + sourceid '1a3' + } + } + }], + // 50ms maximum auction delay, applies to all userId modules + auctionDelay: 50 + } }); {% endhighlight %} -### Novatiq Snowflake ID +#### Parameters for the Novatiq Module + +
    +| Param | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | Module identification: `"novatiq"` | `"novatiq"` | +| params | Required | Object | Configuration specifications for the Novatiq module. | | +| params.sourceid | Required | String | This is the Novatiq Partner Number obtained via Novatiq registration. | `1a3` | +| params.useSharedId | Optional | Boolean | Use the sharedID module if it's activated. | `true` | +| params.sharedIdName | Optional | String | Same as the SharedID "name" parameter
    Defaults to "_pubcid" | `"demo_pubcid"` | +| params.useCallbacks | Optional | Boolean | Use callbacks for custom integrations | `false` | +| params.urlParams | Optional | Object | Sync URl configuration for custom integrations | | +| params.urlParams.novatiqId | Optional | String | The name of the parameter used to indicate the Novatiq ID uuid | `snowflake` | +| params.urlParams.useStandardUuid | Optional | Boolean | Use a standard UUID format, or the Novatiq UUID format | `false` | +| params.urlParams.useSspId | Optional | Boolean | Send the sspid (sourceid) along with the sync request
    Makes the params.sourceid optional if set | `false` | +| params.urlParams.useSspHost | Optional | Boolean | Send the ssphost along with the sync request | `false` | +{: .table .table-bordered .table-striped } +
    + -Novatiq proprietary dynamic snowflake ID is a unique, non sequential and single use identifier for marketing activation. Our in network solution matches verification requests to telco network IDs, safely and securely inside telecom infrastructure. Novatiq snowflake ID can be used for identity validation and as a secured 1st party data delivery mechanism. +### Novatiq Hyper ID with Prebid SharedID support +You can make use of the Prebid.js SharedId module as follows. -#### Novatiq Snowflake ID Configuration +#### Novatiq Hyper ID Configuration -Enable by adding the Novatiq submodule to your Prebid.js package with: +Enable by adding the Novatiq and SharedId submodule to your Prebid.js package with: -``` +{: .alert.alert-info :} gulp build --modules=novatiqIdSystem,userId -``` Module activation and configuration: -```javascript +{% highlight javascript %} pbjs.setConfig({ userSync: { - userIds: [{ + userIds: [ + { name: 'novatiq', params: { - sourceid '1a3', // change to the Partner Number you received from Novatiq + // change to the Partner Number you received from Novatiq + sourceid '1a3', + + // Use the sharedID module + useSharedId: true, + + // optional: will default to _pubcid if left blank. + // If not left blank must match "name" in the the module above + sharedIdName: 'demo_pubcid' } } }], - auctionDelay: 50 // 50ms maximum auction delay, applies to all userId modules + // 50ms maximum auction delay, applies to all userId modules + auctionDelay: 50 } }); -``` +{% endhighlight %} -| Param under userSync.userIds[] | Scope | Type | Description | Example | -| --- | --- | --- | --- | --- | -| name | Required | String | Module identification: `"novatiq"` | `"novatiq"` | -| params | Required | Object | Configuration specifications for the Novatiq module. | | -| params.sourceid | Required | String | This is the Novatiq Partner Number obtained via Novatiq registration. | `1a3` | -If you have any questions, please reach out to us at prebid@novatiq.com. +If you have any questions, please reach out to us at [prebid@novatiq.com](mailto:prebid@novatiq.com) ### Parrable ID @@ -1247,17 +1664,152 @@ pbjs.setConfig({ }); {% endhighlight %} +### Publisher Link +Publisher Link, provided by [Epsilon](https://www.epsilon.com/us), is a cross-device identity solution that activates publisher first-party, authenticated +data to improve audience identification and increase bid opportunities, specifically designed for sites with authenticated +traffic. Publisher first-party authenticated data and a user's unique encrypted ID is linked to an existing people-based +Epsilon CORE ID. By utilizing Publisher Link, publishers are able to reap the benefits of Epsilon's CORE ID. + +#### Publisher Link Registration +Please contact [Epsilon](mailto:PublisherSupport@Epsilon.com) to sign up. + +The Epsilon privacy is covered in the [Epsilon Privacy Policy](https://www.epsilon.com/us/privacy-policy). + +The Publisher Link opt-out is included [here](https://www.epsilon.com/privacy/dms/opt-out/email) + +#### Publisher Link Configuration + +In addition to the parameters documented above in the Basic Configuration section the following Publisher Link specific configuration is available: + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of this module. | `'publinkId'` | +| params | Required | Object | Customized parameters. | | +| params.e | Required | String | Hashed email address of the user. Supports MD5 and SHA256. | `'7D320454942620664D96EF78ED4E3A2A'` | +| params.site_id | Required | String | Site ID provided by Epsilon. | `'123456'` | +| params.api_key | Required | String | API key provided by Epsilon. | `'00000000-0000-0000-0000-00000000000'` + +#### Publisher Link Examples +```javascript + pbjs.setConfig({ + userSync: { + userIds: [{ + name: "publinkId", + storage: { + name: "pbjs_publink", + type: "cookie", + expires: 30 + }, + params: { + e: "7D320454942620664D96EF78ED4E3A2A", // example hashed email (md5) + site_id: "123456", + api_key: "00000000-0000-0000-0000-00000000000" + } + }] + } + }); +``` + +### RampID + +RampID, formerly known as IdentityLink, provided by [LiveRamp](https://liveramp.com) is a single person-based identifier which allows marketers, platforms and publishers to perform personalized segmentation, targeting and measurement use cases that require a consistent, cross-channel view of the user in anonymous spaces. + +Add it to your Prebid.js package with: + +{: .alert.alert-info :} +gulp build --modules=identityLinkIdSystem + +#### RampID Registration + +LiveRamp's RampID is free of charge and only requires a simple registration with Liveramp. Please sign up through our [Console](https://launch.liveramp.com) platform and request a Placement ID, a unique identifier that is used to identify each publisher, to get started. + +The RampID privacy policy is at [https://liveramp.com/privacy/service-privacy-policy/](https://liveramp.com/privacy/service-privacy-policy/). + +#### RampID Configuration + +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of LiveRamp's user ID module. | `"identityLink"` | +| params | Required | Object | Container of all module params. | | +| params.pid | Required | String | This is the Placement ID, a unique identifier that is used to identify each publisher, obtained from registering with LiveRamp. | `999` | +| params.notUse3P | Not required | Boolean | Property for choosing if a cookieable envelope should be set and stored until the user authenticates and a RampID envelope can be created (either `true` or `false`). | `false` | +| storage | Required | Object | This object defines where and for how long the results of the call to get a RampID envelope will be stored. | +| storage.type | Required | String | This parameter defines where the resolved RampID envelope will be stored (either `"cookie"` or `"html5"` localStorage). | `"cookie"` | +| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved RampID envelope will be stored. LiveRamp requires `"idl_env"`. | `"idl_env"` | +| storage.expires | Required | Integer | How long (in days) the RampID envelope information will be stored. To be GDPR and CCPA compliant, we strongly advise to set a 15-day TTL ("Time to Live" / expiration time). If you are not planning to obtain RampID envelopes for EU/EEA or U.S. users, we advise you to change the expiration time to 30 days. | `15` | +| storage.refreshInSeconds | Required | Integer | The amount of time (in seconds) the RampID envelope should be cached in storage before calling LiveRamp again to retrieve a potentially updated value for the RampID envelope. | `1800` + +{: .alert.alert-info :} +**NOTE:** The RampID envelope that is delivered to Prebid will be encrypted by LiveRamp with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to 30 minutes (1800 seconds) to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. + +#### RampID Examples + +1) Publisher passes a Placement ID and elects to store the RampID envelope in a cookie. + +{: .alert.alert-info :} +**NOTE:** Make sure that the expiration time of the cookie is similar to what is set in your ATS configuration. + + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: "identityLink", + params: { + pid: '999', // Set your valid Placement ID here + // notUse3P: true/false // If you do not want to use cookieable envelopes until the user authenticates set this property to true + }, + storage: { + type: "cookie", + name: "idl_env", // "idl_env" is the required storage name + expires: 15, // Cookie can last for 15 days + refreshInSeconds: 1800 + } + }], + syncDelay: 3000 // 3 seconds after the first auction + } +}); +{% endhighlight %} + +2) Publisher passes a Placement ID and elects to store the RampID envelope in HTML5 localStorage. + +{: .alert.alert-info :} +**NOTE:** Make sure that the expiration time of the HTML5 localStorage is similar to what is set in your ATS configuration. + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: "identityLink", + params: { + pid: '999', // Set your valid Placement ID here + // notUse3P: true/false // If you do not want to use cookieable envelopes until the user authenticates set this property to true + }, + storage: { + type: "html5", + name: "idl_env", // "idl_env" is the required storage name + expires: 15, // HTML5 localStorage can last for 15 days + refreshInSeconds: 1800 + } + }], + syncDelay: 3000 // 3 seconds after the first auction + } +}); +{% endhighlight %} + ### SharedID -This module stores an unique user id in the first party domain and makes it accessible to all adapters. Similar to IDFA and AAID, this is a simple UUID that can be utilized to improve user matching, especially for iOS and MacOS browsers, and is compatible with ITP (Intelligent Tracking Prevention). It’s lightweight and self contained. Adapters that support Publisher Common ID will be able to pick up the user ID and return it for additional server-side cross device tracking. +This module stores an unique user id in the first party domain and makes it accessible to all adapters. Similar to IDFA and AAID, this is a simple UUID that can be utilized to improve user matching, especially for iOS and MacOS browsers, and is compatible with ITP (Intelligent Tracking Prevention). It’s lightweight and self contained. Adapters that support SharedId will be able to pick up the user ID and return it for additional server-side cross device tracking. There is no special registration or configuration for SharedID. Each publisher's privacy policy should take -SharedID into account. +SharedID into account. Prebid recommends implementing a method where users can easily opt-out of targeted advertising. Please refer to the User Opt-Out section located at the bottom of this page. For more information check out Prebid's dedicated [identity page](/identity/sharedid.html) Add it to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=pubCommonIdSystem +gulp build --modules=sharedIdSystem #### SharedID ID Configuration @@ -1266,11 +1818,15 @@ In addition to the parameters documented above in the Basic Configuration sectio {: .table .table-bordered .table-striped } | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | The name of this module. | `'pubCommonId'` | +| name | Required | String | The name of this module. | `'sharedId'` | | params | Optional | Object | Customized parameters | | | params.create | Optional | Boolean | For publisher server support only. If true, the publisher's server will create the (pubcid) cookie. Default is true. | `true` | -| params.pixelUrl | Optional | String | For publisher server support only. This is a URL of a pixel for updating cookies' expiration times. Fired after a new ID has been created or an existing ID is being extended. No default. | `'https://example.com/ping'` +| params.pixelUrl | Optional | String | For publisher server support only. Where to call out to for a server cookie -- see [Prebid Identity](/identity/sharedid.html) for more information. | `/wp-json/pubcid/v1/extend/` | params.extend | Optional | Boolean | If true, the expiration time of the stored IDs will be refreshed during each page load. Default is false. | `false` | +| storage | Required | Object | The publisher must specify some kind of local storage in which to store the results of the call to get the user ID. This can be either cookie or HTML5 storage. | +| storage.expires | Integer | Required | How long the user ID information will be stored. | `365` | +| storage.name | String | Required | The name of the cookie or html5 local storage where the user ID will be stored. | `_pubcid` +| storage.type | String | Required | This is where the results of the user ID will be stored. Must be either: Must be either: "cookie" or "html5". For server side implementations, which have the best identifier life and revenue impact, this must be a cookie. | `cookie` #### SharedID Examples @@ -1280,10 +1836,10 @@ In addition to the parameters documented above in the Basic Configuration sectio pbjs.setConfig({ userSync: { userIds: [{ - name: "pubCommonId", + name: "sharedId", storage: { type: "cookie", - name: "_pubcid", // create a cookie with this name + name: "_sharedid", // create a cookie with this name expires: 365 // expires in 1 years } }] @@ -1307,10 +1863,13 @@ pbjs.setConfig({ expires: 60 } },{ - name: "pubCommonId", + name: "sharedId", + params: { + pixelUrl: "/wp-json/pubcid/v1/extend/" + }, storage: { type: "cookie", - name: "_pubcid", // create a cookie with this name + name: "_sharedid", // create a cookie with this name expires: 180 } }], @@ -1319,6 +1878,73 @@ pbjs.setConfig({ }); {% endhighlight %} +3) Publisher supports SharedID and first party domain cookie storage initiated by a first party server + +{% highlight javascript %} +pbjs.setConfig({ + userSync: { + userIds: [{ + name: "sharedId", + params: { + pixelUrl: "/wp-json/pubcid/v1/extend/" //pixelUrl should be specified when the server plugin is used + }, + storage: { + type: "cookie", + name: "_sharedid", // create a cookie with this name + expires: 365 // expires in 1 year + } + }] + } +}); +{% endhighlight %} + +### Trustpid + +Trustpid generates unique tokens, enabling improved efficiency in programmatic advertising while safeguarding transparency and control for end customers via `trustpid.com`. A website visitor’s Trustpid is generated based on network identifiers provided by network operators and requires explicit user consent. + +Trustpid is also the brand name of the service, which is provided by Vodafone Sales and Services Limited (“VSSL”). + +#### Trustpid configuration + +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | The name of the module | `"trustpid"` +| params | Required | Object | Object with configuration parameters for trustpid User Id submodule | - | +| params.maxDelayTime | Required | Integer | Max amount of time (in seconds) before looking into storage for data | 2500 | +| bidders | Required | Array of Strings | An array of bidder codes to which this user ID may be sent. Currently required and supporting AdformOpenRTB | `['adf']` | +| storage | Required | Object | Local storage configuration object | - | +| storage.type | Required | String | Type of the storage that would be used to store user ID. Must be `"html5"` to utilise HTML5 local storage. | `"html5"` | +| storage.name | Required | String | The name of the key in local storage where the user ID will be stored. | `"trustpid"` | +| storage.expires | Required | Integer | How long (in days) the user ID information will be stored. For safety reasons, this information is required.| `1` | + +Configuration example: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [ + { + name: "trustpid", + params: { + maxDelayTime: 2500, + }, + bidders: ["adf"], + storage: { + type: "html5", + name: "trustpid", + expires: 1, + }, + }], + syncDelay: 3000, + auctionDelay: 3000 + } +}); +``` + +#### Truspid onboarding + +If you wish to find out more about Trustpid, please contact onboarding@trustpid.com + ### PubProvided ID The PubProvided Id module allows publishers to set and pass a first party user id into the bid stream. This module has several unique characteristics: @@ -1343,27 +1969,27 @@ Or, the eids values can be passed directly into the `setConfig` call: pbjs.setConfig({ userSync: { userIds: [{ - name: "example.com", + name: "pubProvidedId", params: { eids: [{ source: "domain.com", - uids:[{ - id: "value read from cookie or local storage", - atype: 1, - ext: { - stype: "ppuid" - } - - }] - },{ + uids: [{ + id: "value read from cookie or local storage", + atype: 1, + ext: { + stype: "ppuid" + } + + }] + }, { source: "3rdpartyprovided.com", - uids:[{ - id: "value read from cookie or local storage", - atype: 3, - ext: { - stype: "dmp" - } - }] + uids: [{ + id: "value read from cookie or local storage", + atype: 3, + ext: { + stype: "dmp" + } + }] }] } }] @@ -1388,7 +2014,7 @@ In either case, bid adapters will receive the eid values after consent is valida Add it to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=pubProvidedId +gulp build --modules=pubProvidedIdSystem #### PubProvided Configuration @@ -1404,25 +2030,32 @@ gulp build --modules=pubProvidedId ### Quantcast ID -Quantcast ID enables publishers that use Quantcast Measure tag to uniquely identify -their clients within Quantcast's extensive publisher network without relying on third party -cookies. The Quantcast User ID submodule makes the existing Quantcast first party -cookie available in the bid request. The first party cookie allows Quantcast to correlate -the bid request with Quantcast's Measure dataset. - -Currently, Quantcast ID only works with the presence of Quantcast Measure tag. More information -about Measure can be found in https://www.quantcast.com/measure. - -The Quantcast privacy policy is at https://www.quantcast.com/privacy/. +The Prebid Quantcast ID module stores a Quantcast ID in a first party cookie. The ID is then made available in the bid request. The ID from the cookie added in the bidstream allows Quantcast to more accurately bid on publisher inventories without third party cookies, which can result in better monetization across publisher sites from Quantcast. And, it’s free to use! For easier integration, you can work with one of our SSP partners, like PubMatic, who can facilitate the legal process as well as the software integration for you. Add it to your Prebid.js package with: {: .alert.alert-info :} gulp build --modules=userId,quantcastIdSystem +Quantcast’s privacy policies for the services rendered can be found at + https://www.quantcast.com/privacy/ + +Publishers deploying the module are responsible for ensuring legally required notices and choices for users. + +The Quantcast ID module will only perform any action and return an ID in situations where: +1. the publisher has not set a ‘coppa' flag on the prebid configuration on their site (see [pbjs.setConfig.coppa](https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa)) +2. there is not a IAB us-privacy string indicating the digital property has provided user notice and the user has made a choice to opt out of sale +3. if GDPR applies, an IAB TCF v2 string exists indicating that Quantcast does not have consent for purpose 1 (cookies, device identifiers, or other information can be stored or accessed on your device for the purposes presented to you), or an established legal basis (by default legitimate interest) for purpose 10 (your data can be used to improve existing systems and software, and to develop new products). + #### Quantcast ID Configuration -Quantcast ID module does not require any configuration parameters at this time. +{: .table .table-bordered .table-striped } +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | Required | String | `"quantcastId"` | `"quantcastId"` | +| params | Optional | Object | Details for Quantcast initialization. | | +| params.ClientID | Optional | String | Optional parameter for Quantcast prebid managed service partners. The parameter is not required for websites with Quantcast Measure tag. Reach out to Quantcast for ClientID if you are not an existing Quantcast prebid managed service partner: quantcast-idsupport@quantcast.com | | + #### Quantcast ID Example @@ -1430,13 +2063,14 @@ Quantcast ID module does not require any configuration parameters at this time. pbjs.setConfig({ userSync: { userIds: [{ - name: "quantcastId", + name: "quantcastId" }] } }); {% endhighlight %} + ### Tapad ID Tapad's ID module provides access to a universal identifier that publishers, ad tech platforms and advertisers can use for data collection and collation without reliance on third-party cookies. @@ -1615,100 +2249,87 @@ pbjs.setConfig({ {% endhighlight %} -### Verizon Media ConnectID +### Yahoo ConnectID -Verizon Media ConnectID is a person based ID and does not depend on 3rd party cookies. It enables ad tech platforms to recognize and match users consistently across the open web. Built on top of Verizon Media’s robust and proprietary ID Graph it delivers a higher find rate of audiences on publishers’ sites user targeting that respects privacy. +Yahoo ConnectID is a person based ID and does not depend on 3rd party cookies. It enables ad tech platforms to recognize and match users consistently across the open web. Built on top of Yahoo’s robust and proprietary ID Graph it delivers a higher find rate of audiences on publishers’ sites user targeting that respects privacy. -Verizon Media ConnectID honors privacy choices from the [Verizon Media Privacy Dashboard](https://www.verizonmedia.com/policies/us/en/verizonmedia/privacy/dashboard/index.html) as well as global privacy acts. +Yahoo ConnectID honors privacy choices from the [Yahoo Privacy Dashboard](https://legal.yahoo.com/us/en/yahoo/privacy/dashboard/index.html) as well as global privacy acts. -Add support for Verizon Media ConnectID to your Prebid.js package with: +Add support for Yahoo ConnectID to your Prebid.js package with: {: .alert.alert-info :} -gulp build --modules=userId,verizonMediaIdSystem +gulp build --modules=userId,connectIdSystem -#### Verizon Media ConnectID Registration +#### Yahoo ConnectID Registration -A Verizon Media supplied publisher specific pixel Id is required. Reach out to your account manager for assistance with setup. +A Yahoo supplied publisher specific pixel Id is required. Please reach out to your account manager for assistance with setup. -#### Verizon Media ConnectID Configuration +#### Yahoo ConnectID Configuration
    | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | The name of this module. | `'verizonMediaId'` | +| name | Required | String | The name of this module. | `'connectId'` | | params | Required | Object | Container of all module params. || -| params.pixelId | Required | Number | The Verizon Media supplied publisher specific pixel Id | `8976` | +| params.pixelId | Required | Number | The Yahoo supplied publisher specific pixel Id | `8976` | | params.he | Required | String | The SHA-256 hashed user email address |`'ed8ddbf5a171981db8ef938596ca297d5e3f84bcc280041c5880dba3baf9c1d4'`| | storage | Required | Object | Defines where and for how long the results of the call to get a user ID will be stored. | | | storage.type | Required | String | Defines where the resolved user ID will be stored (either `'cookie'` or `'html5'` localstorage).| `'html5'` | -| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'connectid'` | +| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'connectId'` | | storage.expires | Recommended | Integer | How long (in days) the user ID information will be stored. The recommended value is `15` | `15` | {: .table .table-bordered .table-striped }
    -#### Verizon Media ConnectID Examples +#### Yahoo ConnectID Examples ``` pbjs.setConfig({ userSync: { userIds: [{ - name: "verizonMediaId", + name: "connectId", params: { pixelId: 8976, he: "ed8ddbf5a171981db8ef938596ca297d5e3f84bcc280041c5880dba3baf9c1d4" }, storage: { type: "html5", - name: "connectid", - expires: 1 + name: "connectId", + expires: 15 } }] } }) ``` -### MediaWallah OpenLinkID +### GRAVITO ID by Gravito Ltd. -MediaWallah's openLink is an anonymous person based ID that enables buyers and sellers of media to connect a person and their devices across the web and mobile apps. openLink facilities the buying of media between DSPs, SSPs and publishers. +Gravito ID, provided by [Gravito Ltd.](https://gravito.net), is ID for ad targeting by using 1st party cookie. +Please contact Gravito Ltd. for using this ID. -Add support for MediaWallah OpenLinkID to your Prebid.js package with: +Add the Gravito ID to your Prebid.js Package with: {: .alert.alert-info :} -gulp build --modules=userId,mwOpenLinkIdSystem - -#### MediaWallah OpenLinkID Registration +gulp build --modules=gravitoIdSystem -MediaWallah requires the creation of an accountId a partnerId in order to take advantage of openLink. Please contact your partner resource to get these Ids provisioned. +#### Gravito ID Configuration -#### MediaWallah OpenLinkID Configuration - -
    +{: .table .table-bordered .table-striped } | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | The name of this module. | `'mwOpenLinkId'` | -| params | Required | Object | Details for mwOLID syncing. || -| params.accountId | Required | String | The MediaWallah assigned Account Id | `1000` | -| params.partnerId | Required | String | The MediaWallah assign partner Id |`'1001'`| -| params.uid | Optional | String | Your unique Id for the user or browser. Used for matching. | `'u-123xyz'` | -{: .table .table-bordered .table-striped } -
    +| name | Required | String | The name of this module | `"gravitompId"` | -#### MediaWallah OpenLinkID Examples +#### Gravito ID Example -``` +{% highlight javascript %} pbjs.setConfig({ userSync: { userIds: [{ - name: 'mwOpenLinkId', - params: { - accountId: '1000', - partnerId: '1001', - uid: 'u-123xyz' - } + name: 'gravitompId' }] } -}) -``` +}); +{% endhighlight %} + ## Adapters Supporting the User ID Sub-Modules @@ -1732,34 +2353,41 @@ Bidders that want to support the User ID module in Prebid.js, need to update the {: .table .table-bordered .table-striped } | ID System Name | ID System Host | Prebid.js Attr: bidRequest.userId. | EID Source | Example Value | | --- | --- | --- | --- | --- | --- | --- | +| 33Across ID | 33Across | 33acrossId | 33across.com | "1111" | | Admixer ID | Admixer | admixerId | admixer.net | "1111" | +| adQuery QiD | adQuery | qid | adquery.io | "p9v2dpnuckkzhuc..." | +| Adtelligent ID | Adtelligent | bidRequest.userId.adtelligentId | `"1111"` | | AMX RTB ID | AMX RTB | amxId | amxrtb.com | "3ca11058-..." | | BritePool ID | BritePool | britepoolid | britepool.com | "1111" | +| AudienceOne ID | DAC | dacId | dac.co.jp | {"id": "1111"} | | DeepIntent ID | Deep Intent | deepintentId | deepintent.com | "1111" | | DMD ID | DMD | dmdId | hcn.health | "1111" | +| CpexID | CPEx | cpexId | cpex.cz | "1111" | | CriteoID | Criteo | criteoId | criteo.com | "1111" | | Fabrick ID | Neustar | fabrickId | neustar.biz | "1111" | | FLoC ID | n/a | flocId | | | -| Halo ID | Audigent | haloId | audigent.com | {"haloId":"user-halo-id", "auSeg":["segment1", "segment2"]} | +| Hadron ID | Audigent | hadronId | audigent.com | {"hadronId":"user-hadron-id", "auSeg":["segment1", "segment2"]} | | ID+ | Zeotap | IDP | zeotap.com | "1111" | | ID5 ID | ID5 | id5id | id5-sync.com | {uid: "1111", ext: { linkType: 2, abTestingControlGroup: false } } | | IdentityLink | LiveRamp | idl_env | liveramp.com | "1111" | | Intent IQ ID | Intent IQ | intentiqid | intentiq.com | "1111" | +| Kinesso ID | Kinesso | kpuid | kpuid.com | "1111" | | LiveIntent ID | Live Intent | lipb.lipbid | liveintent.com | "1111" | | Lotame Panorama ID | Lotame | lotamePanoramaId | crwdcntrl.net | "e4b9..." | | MediaWallah OpenLink ID | MediaWallah | mwOpenLinkId | mediawallahscript.com | "1111" | | merkleID | Merkle | merkleId | merkleinc.com | "1111" | +| naveggId | Navegg | naveggId | navegg.com | "1111" | | netID | netID | netId | netid.de | "fH5A..." | -| NextRoll ID | NextRoll | nextrollId | nextroll.com | "bf3Ka.../SjP/zpVGr09voA" | | Novatiq ID | Novatiq | novatiqId | novatiq.com | "1111" | | Parrable ID | Parrable | parrableId | parrable.com | {"eid":"01.15946..."} | +| Publisher Link ID | n/a | publinkId | epsilon.com | | | PubProvided ID | n/a | pubProvidedId | publisher domain | "1111" | | Quantcast ID | n/a | quantcastId | quantcast.com | "1111" | | Tapad ID | Tapad | tapadId | tapad.com | "1111" | | SharedID (PBJS 5.x) | n/a | pubcid | pubcid.org | "1111" | | SharedID (PBJS 4.x)| Prebid | sharedid | sharedid.org | {"id":"01EAJWWN...", "third":"01EAJ..."} | | Unified ID | Trade Desk | tdid | adserver.org | "1111" | -| Verizon Media ConnectID | Verizon Media | connectid | verizonmedia.com | "72d04af6..." | +| ConnectID | Yahoo | connectId | yahoo.com | "72d04af6..." | For example, the adapter code might do something like: @@ -1773,8 +2401,9 @@ For example, the adapter code might do something like: Bidders that want to support the User ID module in Prebid Server, need to update their server-side bid adapter to read the desired OpenRTB 'user.ext.eids.source' object and forward the relevant values to their endpoint. -See the [Prebid.js EIDs javascript source](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.js) for the definitive list of user EID sources. +See the [Prebid.js EIDs javascript source](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.js) for the definitive list of user EID sources. +     ### Exporting User IDs If you need to export the user IDs stored by Prebid User ID module, the `getUserIds()` function will return an object formatted the same as bidRequest.userId. @@ -1783,7 +2412,9 @@ If you need to export the user IDs stored by Prebid User ID module, the `getUser pbjs.getUserIds() // returns object like bidRequest.userId. e.g. {"pubcid":"1111", "tdid":"2222"} ``` -You can use [`getUserIdsAsEids()`](/dev-docs/publisher-api-reference/getUserIds.html) to get the user IDs stored by Prebid User ID module in ORTB Eids format. Refer [eids.md](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format. + + +You can use `getUserIdsAsEids()` to get the user IDs stored by Prebid User ID module in ORTB Eids format. Refer [eids.md](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format. ``` pbjs.getUserIdsAsEids() // returns userIds in ORTB Eids format. e.g. [ @@ -1820,6 +2451,19 @@ pbjs.getUserIdsAsEids() // returns userIds in ORTB Eids format. e.g. ] ``` + + +`pbjs.getUserIds()` and `pbjs.getUserIdsAsEids()` may return only some IDs, or none at all, if they are called before all ID providers have had a chance to initialize - depending on [`auctionDelay` and/or `syncDelay`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-ConfigureUserSyncing-UserSyncProperties), that may need to wait until an auction has completed. +To access the complete set of IDs, you may use `getUserIdsAsync`, which returns a promise that is guaranteed to resolve only once all IDs are available: + +``` +pbjs.getUserIdsAsync().then(function (userIds) { + // all IDs are available here: + pbjs.getUserIds() // same as the `userIds` argument + pbjs.getUserIdsAsEids() +}); +``` + ## ID Providers If you're an ID provider that wants to get on this page: @@ -1828,13 +2472,64 @@ If you're an ID provider that wants to get on this page: - Add your *IdSystem name into the modules/.submodules.json file - Follow all the guidelines in the [contribution page](https://github.com/prebid/Prebid.js/blob/master/CONTRIBUTING.md). - Submit a Pull Request against the [Prebid.js repository](https://github.com/prebid/Prebid.js). -- Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify the /dev-docs/modules/userId.md, and submit a documentation Pull Request as well. +- Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify /dev-docs/modules/userId.md, /download.md, and submit a documentation Pull Request. -## Passing UserIds to Google Ad Manager for targeting +## ESP Configurations + +Google now supports Encrypted Signals for Publishers(ESP), a program that allows publishers can explicitly share encrypted signals on bid requests with third-party bidders. User ID modules now support code which will register the signal sources and encrypted signal are created and is sent to GAM request in a3p parameter. 'encryptedSignal' configuration under userSync Module will help to configure signal sources. + +Please find more details [Share encrypted signals with bidders (Beta)](https://support.google.com/admanager/answer/10488752?hl=en) + +{: .table .table-bordered .table-striped } +| Param under userSync | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| encryptedSignalSources | Optional | Object | Publisher can specify the ESP config by adding encryptedSignal Object under userSync Object | | +| encryptedSignalSources.sources | Required | Object | An array of Object consist of sources list and encryption flag | Check below config as an example | +| encryptedSignalSources.sources.source | Required | Array | An array of sources for which signals needs to be registered | `['sharedid.org','criteo.com']` | +| encryptedSignalSources.sources.encrypt | Required | Boolean | Should be set to false by default. Please find below note | `true` or `false` | +| encryptedSignalSources.sources.customFunc | Required | function | This function will be defined for custom sources only and called which will return the custom data set from the page | Check below config as an example | +| encryptedSignalSources.registerDelay | Optional | Integer | The amount of time (in milliseconds) after which registering of signals will happen. Default value 0 is considered if 'registerDelay' is not provided. | `3000` + +{: .alert.alert-info :} +**NOTE:** +For eids encryption (encryptedSignalSources.encrypt) set to true is not recommended unless downstream is informed of the changes. + +{: .alert.alert-info :} +**NOTE:** +Publishers enabling passing eids/signal through ESP should reach out to SSPs integrated through OB to make sure to take any additional steps needed to ensure impact on 3p cookie based transaction is handled and impact is minimal. + +ESP Configuration Example: -User IDs from Prebid User ID module can be passed to GAM for targeting in Google Ad Manager or could be passed ahead to Google Open Bidding using ```userIdTargeting``` module. Note Google deprecated the ability to pass key values, including identifiers, to OB partners and then later began a closed beta to resume it with details non-public (see https://developers.google.com/authorized-buyers/rtb/request-guide ). More details on the user id module can be found [here](https://github.com/prebid/Prebid.js/blob/master/modules/userIdTargeting.md). In short, you just need to add the optional userIdTargeting sub-module into your `gulp build` command and the additional `userIdTargeting` config becomes available. +``` +pbjs.setConfig({ + userSync: { + ..., + encryptedSignalSources: { + "sources": [{ + source: ['sharedid.org', 'criteo.com', 'id5-sync.com', 'pubcid.org', 'audigent.com'], + encrypt: false + }, { + source: ['pubmatic.com'], + customFunc: () => { + return '{"keywords":["tech","auto"]}'; + }, + encrypt: true + }, { + source: ['segment.com'], + customFunc: () => { + return '[{ "id": "1", "value": "seg1" },{ "id": "2", "value": "seg2" }]'; + }, + encrypt: true + }], + "registerDelay": 3000 + }, + .... + } +}) + +``` ## Further Reading diff --git a/dev-docs/modules/validationFpdModule.md b/dev-docs/modules/validationFpdModule.md index 00c3cae15a..635647034b 100644 --- a/dev-docs/modules/validationFpdModule.md +++ b/dev-docs/modules/validationFpdModule.md @@ -2,7 +2,7 @@ layout: page_v2 page_type: module title: Module - First Party Data Validation -description: Validates First Party Data +description: Verify First Party Data fields and data types. Not recommended for production use. module_code : validationFpdModule display_name : First Party Data Validation enable_download : true @@ -33,7 +33,7 @@ pbjs.setConfig({ ## Validations -This module does its checks only once at the first auction. The checks can be re-run anytime by calling `pbjs.refreshFpd()`. +This module does its checks at the beginning of each auction. When a data field doesn't meet the defined validations, it will be removed. In addition, the module will look for the _pubcid_optout cookie (or local storage), and if it exists, certain fields will be removed. diff --git a/dev-docs/modules/viewability.md b/dev-docs/modules/viewability.md new file mode 100644 index 0000000000..b6d0e21104 --- /dev/null +++ b/dev-docs/modules/viewability.md @@ -0,0 +1,99 @@ +--- +layout: page_v2 +page_type: module +title: Module - Viewability +description: Generic Viewability module, tracks element viewability based on given criteria +module_code: viewability +display_name: Viewability +enable_download: true +sidebarType: 1 +--- + +# Generic Viewability +{:.no_toc} + +* TOC +{:toc} + +## Overview + + +This module will trigger a viewability pixel when a given HTML element becomes viewable according to custom viewability criteria. + +Notes: +- Does not depend on publishers using GAM ad server (does not use GPT's ImpressionViewableEvent). +- Enables custom viewability criteria (timeInView and inViewThreshold). +- Aims to provide (and in some ways extend) functionality of https://github.com/InteractiveAdvertisingBureau/openvv-html , but keeping the size to the bare minimun (openvv-html is ~26kb in size). +- Enables publishers to track viewability through callbacks or img/js pixels. +- Enables buy side to track viewability by posting a message from within the creative iframe (including the postMessage call in the ad markup), thus avoiding custom viewability scripts. + +{: .alert.alert-warning :} +This module does not work on IE (uses IntersectionObserver). + +## Configuration + +Module does not need any configuration, as long as you include it in your PBJS bundle. +Viewability module has only two functions `startMeasurement` and `stopMeasurement` which can be used to enable more complex viewability measurements. Since it allows tracking from within creative (possibly inside a safe frame) this module registers a message listener, for messages with a format that is described bellow. + +`startMeasurement` +This function has 4 parameters when called directly with `pbjs.viewability.startMeasurement()`: + - vid: unique viewability identifier, used to reference particular tracker which can later be used to stop the measurement. It allows for multiple trackers, with different criteria to be registered for a given HTML element, independently. vid is not autogenerated by startMeasurement(), it needs to be provided by caller so that it doesn't have to be posted back to the source iframe (in case viewability is started from within the creative). + - element: reference to an HTML element that needs to be tracked. + - tracker: ViewabilityTracker is an object type with two properties, `method` ('img'|'js'|'callback') and `value` which can be an URL string for 'img' and 'js' trackers, or a function for 'callback' tracker. Example: `{ method: 'img', value: 'http://my.tracker/123' }` + - criteria: ViewabilityCriteria is an object type with two properties, `inViewThreshold` which is a number (0, 1.0] representing a percentage of viewable element we're aiming at, and `timeInView` which is a number of milliseconds that a given element needs to be in view continuously, above a threshold. Example: `{ inViewThreshold: 0.5, timeInView: 1000 }` + +When a tracker needs to be started, without direct access to pbjs, postMessage mechanism can be used to invoke `startMeasurement`, with a following payload: `vid`, `tracker` and `criteria` as described above, but also with `message: 'Prebid Viewability'` and `action: 'startMeasurement'`. Optionally payload can provide `elementId`, if available at that time (for ad servers where name of the iframe is known, or adservers that render outside an iframe). If `elementId` is not provided, viewability module will try to find the iframe that corresponds to the message source. + + +`stopMeasurement`: +This function has only 1 parementer when called directly with `pbjs.viewability.stopMeasurement()`: +- vid: unique viewability identifier, referencing an already started viewability tracker. + +When a tracker needs to be stopped, without direct access to pbjs, postMessage mechanism can be used here as well, to invoke `stopMeasurement`, providing payload with `vid`, `message: 'Prebid Viewability'` and `action: 'stopMeasurement`. + +## Example of starting a viewability measurement, when you have direct access to pbjs +{% highlight js %} + + pbjs.viewability.startMeasurement( + 'ae0f9', + document.getElementById('test_div'), + { method: 'img', value: 'http://my.tracker/123' }, + { inViewThreshold: 0.5, timeInView: 1000 } + ); + +{% endhighlight %} + +## Example of starting a viewability measurement from within a rendered creative +{% highlight js %} + + let viewabilityRecord = { + vid: 'ae0f9', + tracker: { method: 'img', value: 'http://my.tracker/123'}, + criteria: { inViewThreshold: 0.5, timeInView: 1000 }, + message: 'Prebid Viewability', + action: 'startMeasurement' + } + + window.parent.postMessage(JSON.stringify(viewabilityRecord), '*'); + +{% endhighlight %} + +## Example of stopping the viewability measurement, when you have direct access to pbjs +{% highlight js %} + + pbjs.viewability.stopMeasurement('ae0f9'); + +{% endhighlight %} + +## Example of stopping the viewability measurement from within a rendered creative +{% highlight js %} + + let viewabilityRecord = { + vid: 'ae0f9', + message: 'Prebid Viewability', + action: 'stopMeasurement' + } + + window.parent.postMessage(JSON.stringify(viewabilityRecord), '*'); + +{% endhighlight %} diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md new file mode 100644 index 0000000000..ec9752ac35 --- /dev/null +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -0,0 +1,605 @@ +--- +layout: page_v2 +title: Weborama Real Time Data Provider +display_name: Weborama Real-time Segmentation Module +description: Weborama Real-time Segmentation Module +page_type: module +module_type: rtd +module_code : weboramaRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Weborama RTD Segmentation Module +{:.no_toc} + +* TOC +{:toc} + +## Description + +Weborama provides a Real-Time Data Submodule for `Prebid.js`, allowing to easy integrate different products such as: + +* Semantic AI Contextual API that classifies in Real-time a web page seen by a web user within generic and custom topics. It enables publishers to better monetize their inventory and unlock it to programmatic. + +* Weborama Audience Manager (WAM) is a DMP (Data Management Platform) used by over 60 companies in the world. This platform distinguishes itself particularly by a high level interconnexion with the adtech & martech ecosystem and a transparent access to the database intelligence. + +* LiTE by SFBX® (Local inApp Trust Engine) provides “Zero Party Data” given by users, stored and calculated only on the user’s device. Through a unique cohorting system, it enables better monetization in a consent/consentless and identity-less mode. + +Contact prebid-support@weborama.com for more information. + +### Publisher Usage + +Compile the Weborama RTD module into your Prebid build: + +`gulp build --modules=rtdModule,weboramaRtdProvider` + +Add the Weborama RTD provider to your Prebid config, use the configuration template below: + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, // Output debug messages to the web console, *should* be disabled in production + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + /* add weborama rtd submodule configuration here */ + }, + }, + // other modules... + ] + } + }); +}); +``` + +The module configuration has 3 independent sections (`weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf`), each one mapped to a single product (`contextual`, `wam` and `lite`). No section is enabled by default, we must be explicit like in the minimal example below: + +```javascript +pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { // contextual site-centric configuration, *omit if not needed* + token: "<>", // mandatory + }, + weboUserDataConf: { // wam user-centric configuration, *omit if not needed* + enabled: true, + }, + sfbxLiteDataConf: { // sfbx-lite site-centric configuration, *omit if not needed* + enabled: true, + }, + } + }, + // other modules... + ] + } +}); +``` + +Each module can perform two actions: + +* set targeting on [GPT](https://docs.prebid.org/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) / [AST](https://docs.prebid.org/dev-docs/publisher-api-reference/setTargetingForAst.html]) via `prebid.js` + +* send data to other `prebid.js` bidder modules (check the complete list at the end of this page) + +### Parameter Descriptions for the Weborama Configuration Section + +This is the main configuration section + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Mandatory. Always 'Weborama' | +| waitForIt | Boolean | Mandatory. Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true | +| params | Object | | Optional | +| params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | +| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | +| params.weboCtxConf | Object | Weborama Contextual Site-Centric Configuration | Optional | +| params.weboUserDataConf | Object | Weborama WAM User-Centric Configuration | Optional | +| params.sfbxLiteDataConf | Object | Sfbx LiTE Site-Centric Configuration | Optional | +| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | + +#### Contextual Site-Centric Configuration + +To be possible use the integration with Weborama Contextual Service you must be a client with a valid API token. Please contact weborama if you don't have it. + +On this section we will explain the `params.weboCtxConf` subconfiguration: + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| token | String | Security Token provided by Weborama, unique per client | Mandatory | +| targetURL | String | Url to be profiled in the contextual api | Optional. Defaults to `document.URL` | +| setPrebidTargeting|Various|If true, will use the contextual profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Various|If true, will send the contextual profile to all bidders. If an array, will specify the bidders to send data| Optional. Default is `params.sendToBidders` (if any) or `true`.| +| defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | +| onData | Callback | If set, will receive the profile and metadata | Optional. Default is `params.onData` (if any) or log via prebid debug | +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| +| baseURLProfileAPI | String| if present, update the domain of the contextual api| Optional. Default is `ctx.weborama.com` | + +#### WAM User-Centric Configuration + +To be possible use the integration with Weborama Audience Manager (WAM) you must be a client with an account id and you lust include the `wamfactory` script in your pages with `wam2gam` feature activated. +Please contact weborama if you don't have it. + +On this section we will explain the `params.weboUserDataConf` subconfiguration: + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| accountId|Number|WAM account id. If you don't have it, please contact weborama. | Recommended.| +| setPrebidTargeting|Various|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Various|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or `true`.| +| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | +| defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | +| localStorageProfileKey| String | can be used to customize the local storage key | Optional | +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| + +#### Sfbx LiTE Site-Centric Configuration + +To be possible use the integration between Weborama and Sfbx LiTE you should also contact SFBX® to setup this product. + +On this section we will explain the `params.sfbxLiteDataConf` subconfiguration: + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| setPrebidTargeting|Various|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Varios|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or `true`.| +| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | +| defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | +| localStorageProfileKey| String | can be used to customize the local storage key | Optional | +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| + +##### Property setPrebidTargeting supported types + +This property support the following types + +| Type | Description | Example | Notes | +| :------------ | :------------ | :------------ |:------------ | +| Boolean|If true, set prebid targeting for all adunits, or not in case of false| `true` | default value | +| String|Will set prebid targeting only for one adunit | `'adUnitCode1'` | | +| Array of Strings|Will set prebid targeting only for some adunits| `['adUnitCode1','adUnitCode2']` | | +| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(adUnitCode){return adUnitCode == 'adUnitCode';}` | | + +The complete callback function signature is: + +```javascript +setPrebidTargeting: function(adUnitCode, data, metadata){ + return true; // or false, depending on the logic +} +``` + +This callback will be executed with the adUnitCode, profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +It is possible customize the targeting based on the parameters: + +```javascript +setPrebidTargeting: function(adUnitCode, data, metadata){ + // check metadata.source can be omitted if defined in params.weboUserDataConf + if (adUnitCode == 'adUnitCode1' && metadata.source == 'wam'){ + data['foo']=['bar']; // add this section only for adUnitCode1 + delete data['other']; // remove this section + } + return true; +} +``` + +##### Property sendToBidders supported types + +This property support the following types + +| Type | Description | Example | Notes | +| :------------ | :------------ | :------------ |:------------ | +| Boolean|If true, send data to all bidders, or not in case of false| `true` | default value | +| String|Will send data to only one bidder | `'appnexus'` | | +| Array of Strings|Will send data to only some bidders | `['appnexus','pubmatic']` | | +| Object |Will send data to only some bidders and some ad units | `{appnexus: true, pubmatic:['adUnitCode1']}` | | +| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(bid, adUnitCode){return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode';}` | | + +A better look on the `Object` type + +```javascript +sendToBidders: { + appnexus: true, // send profile to appnexus on all ad units + pubmatic: ['adUnitCode1'],// send profile to pubmatic on this ad units +} +``` + +The complete callback function signature is: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + return true; // or false, depending on the logic +} +``` + +This callback will be executed with the bid object (contains a field `bidder` with name), adUnitCode, profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +It is possible customize the targeting based on the parameters: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + if (bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'){ + data['foo']=['bar']; // add this section only for appnexus + adUnitCode1 + delete data['other']; // remove this section + } + return true; +} +``` + +To be possible customize the way we send data to bidders via this callback: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + if (bid.bidder == 'other'){ + /* use bid object to store data based on this specific logic, like in the example below */ + + bid.params = bid.params || {}; + bid.params['some_specific_key'] = data; + + return false; // will prevent the module to follow the pre-defined logic per bidder + } + // others + return true; +} +``` + +In case of using bid _aliases_, we should match the same string used in the adUnit configuration. + +```javascript +pbjs.aliasBidder('appnexus', 'foo'); +pbjs.aliasBidder('criteo', 'bar'); +pbjs.aliasBidder('pubmatic', 'baz'); +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "to-be-defined", // mandatory + sendToBidders: ['foo','bar'], // will share site-centric data with bidders foo and bar + }, + weboUserDataConf: { + accountId: 12345, // recommended, + sendToBidders: ['baz'], // will share user-centric data with only bidder baz + } + } + }] + } +}); +``` + +##### Using onData callback + +We can specify a callback to handle the profile data from site-centric or user-centric data. + +This callback will be executed with the profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +The metadata maybe not useful if we define the callback on site-centric of user-centric configuration, but if defined in the global level: + +```javascript +params: { + onData: function(data, metadata){ + var hasUserCentricData = metadata.user; + var dataSource = metadata.source; + console.log('onData', data, hasUserCentricData, dataSource); + } +} +``` + +an interesting example is to set GAM targeting in global level instead in slot level only for contextual data: + +```javascript +params: { + weboCtxConf: { + token: 'to-be-defined', + setPrebidTargeting: false, + onData: function(data, metadata){ + var googletag = googletag || {}; + googletag.cmd = googletag.cmd || []; + googletag.cmd.push(function () { + for(var key in data){ + googletag.pubads().setTargeting(key, data[key]); + } + }); + }, + } +} +``` + +### More configuration examples + +A more complete example can be found below. We can define default profiles, for each section, to be used in case of no data are found. + +We can control if we will set prebid targeting or send data to bidders in a global level or on each section (`contextual`, `wam` or `lite`). + +By default we try to send the data to all destinations, always. To restrict we can have two choices: + +* Set `setPrebidTargeting` or `sendToBidders` explicity to `true` or `false` on each section; +* Set `setPrebidTargeting` or `sendToBidders` globally to `false` and only enable on the right sections; + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "<>", // mandatory + targetURL: "https://example.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + webo_ctx: [ ... ], // contextual segments + webo_ds: [ ...], // data science segments + }, + enabled: true, + }, + weboUserDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + webo_cs: [...], // wam custom segments + webo_audiences: [...], // wam audiences + }, + enabled: true, + }, + sfbxLiteDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + /* add specific lite segments here */ + }, + enabled: true, + }, + } + }] + } + }); +}); +``` + +Imagine we need to configure the following options using the previous example, we can write the configuration like the one below. + +||contextual|wam|lite| +| :------------ | :------------ | :------------ |:------------ | +|setPrebidTargeting|true|false|true| +|sendToBidders|false|true|true| + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + setPrebidTargeting: false, // optional. set the default value of each section. + sendToBidders: false, // optional. set the default value of each section. + weboCtxConf: { + token: "<>", // mandatory + targetURL: "https://example.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + enabled: true, + }, + weboUserDataConf: { + sendToBidders: true, // override param.sendToBidders. default is true + enabled: true, + }, + sfbxLiteDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + enabled: true, + }, + } + }] + } + }); +}); +``` + +We can also define a list of adunits / bidders that will receive data instead of using boolean values. + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "to-be-defined", // mandatory + setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits + sendToBidders: ['appnexus',...], // overide, send to only some bidders + enabled: true, + }, + weboUserDataConf: { + accountId: 12345, // recommended + setPrebidTargeting: ['adUnitCode2',...], // set target only on certain adunits + sendToBidders: ['rubicon',...], // overide, send to only some bidders + enabled: true, + }, + sfbxLiteDataConf: { + setPrebidTargeting: ['adUnitCode3',...], // set target only on certain adunits + sendToBidders: ['smartadserver',...], // overide, send to only some bidders + enabled: true, + } + } + }] + } + }); +}); +``` + +Finally, we can combine several styles in the same configuration if needed. Including the callback style. + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + setPrebidTargeting: true, // optional + sendToBidders: true, // optional + onData: function(data, meta){ // optional + var userCentricData = meta.user; // maybe undefined + var sourceOfData = meta.source; // contextual, wam or lite + + var isDefault = meta.isDefault; // true if uses default profile + + console.log('onData', data, meta); + }, + weboCtxConf: { + token: "to-be-defined", // mandatory + targetURL: "https://prebid.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting or default true + sendToBidders: ['appnexus',...], // overide, send to only some bidders + defaultProfile: { // optional + webo_ctx: ['moon'], + webo_ds: ['bar'] + }, + enabled: true, + //, onData: function (data, ...) { ...} + }, + weboUserDataConf: { + accountId: 12345, // recommended + setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits + sendToBidders: { // send to only some bidders and adunits + 'appnexus': true, // all adunits for appnexus + 'pubmatic': ['adUnitCode1',...] // some adunits for pubmatic + // other bidders will be ignored + }, + defaultProfile: { // optional + webo_cs: ['Red'], + webo_audiences: ['bam'] + }, + localStorageProfileKey: 'webo_wam2gam_entry', // default + enabled: true, + //, onData: function (data, ...) { ...} + }, + sfbxLiteDataConf: { + setPrebidTargeting: function(adUnitCode){ // specify set target via callback + return adUnitCode == 'adUnitCode1'; + }, + sendToBidders: function(bid, adUnitCode){ // specify sendToBidders via callback + return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'; + } + defaultProfile: { // optional + lite_occupation: ['gérant', 'bénévole'], + lite_hobbies: ['sport', 'cinéma'], + }, + localStorageProfileKey: '_lite', // default + enabled: true, + //, onData: function (data, ...) { ...} + } + } + }] + } + }); +}); +``` + +### Supported Bidders + +We currently support the following bidder adapters: + +* SmartADServer SSP +* PubMatic SSP +* AppNexus SSP +* Rubicon SSP + +We also set the bidder (and global, if no specific bidders are set on `sendToBidders`) ortb2 `site.ext.data` and `user.ext.data` sections (as arbitrary data). The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from [here](https://docs.prebid.org/dev-docs/bidders). + +* Adagio +* AdformOpenRTB +* AdKernel +* AdMixer +* Adnuntius +* Adrelevantis +* adxcg +* AMX RTB +* Avocet +* BeOp +* Criteo +* Etarget +* Inmar +* Index Exchange +* Livewrapped +* Mediakeys +* NoBid +* OpenX +* Opt Out Advertising +* Ozone Project +* Proxistore +* Rise +* Smaato +* Sonobi +* TheMediaGrid +* TripleLift +* TrustX +* Yahoo SSP +* Yieldlab +* Zeta Global Ssp + +### Testing + +To view an example of available segments returned by Weborama's backends: + +`gulp serve --notest --nolint --modules=rtdModule,weboramaRtdProvider,smartadserverBidAdapter,pubmaticBidAdapter,appnexusBidAdapter,rubiconBidAdapter,criteoBidAdapter` + +and then point your browser at: + +`http://localhost:9999/integrationExamples/gpt/weboramaRtdProvider_example.html` diff --git a/dev-docs/modules/yieldmoSyntheticInventoryModule.md b/dev-docs/modules/yieldmoSyntheticInventoryModule.md new file mode 100644 index 0000000000..5b49276bd3 --- /dev/null +++ b/dev-docs/modules/yieldmoSyntheticInventoryModule.md @@ -0,0 +1,80 @@ +--- +layout: page_v2 +page_type: module +title: Yieldmo Synthetic Inventory Module +description: Yieldmo Synthetic Outstream ads +module_code : yieldmoSyntheticInventoryModule +display_name : Synthetic Inventory Module +enable_download : true +sidebarType : 1 +vendor_specific: true +--- + +# Yieldmo Synthetic Inventory Module + +## Overview + +This module enables publishers to set up Yieldmo Synthetic Outstream ads on their pages. + +If publishers will enable this module and provide placementId and Google Ad Manager ad unit path, this module will create a placement on the page and inject Yieldmo SDK into this placement. Publisher will then need to get a placement id from their Yieldmo account manager (accounts email) and setup corresponding ad units on the GAM ad server. + +## Integration + +Build the Yieldmo Synthetic Inventory Module into the Prebid.js package with: + +``` +gulp build --modules=yieldmoSyntheticInventoryModule,... +``` + +## Module Configuration + +```js +pbjs.que.push(function() { + pbjs.setConfig({ + yieldmo_synthetic_inventory: { + placementId: '1234567890', + adUnitPath: '/1234567/ad_unit_name_used_in_gam' + } + }); +}); +``` + +### Configuration Parameters + +|Name |Scope |Description | Example| Type +| :------------ | :------------ | :------------ | :------------ | :------------ | +|placementId | required | Yieldmo placement ID | '1234567890' | string +|adUnitPath | required | Google Ad Manager ad unit path | '/6355419/ad_unit_name_used_in_gam' | string + +### How to get ad unit path + +Ad unit path follows the format /network-code/[parent-ad-unit-code/.../]ad-unit-code, where: + +- network-code is a unique identifier for the Ad Manager network the ad unit belongs to +- parent-ad-unit-code are the codes of all parent ad units (only applies to non-top level ad units) +- ad-unit-code is the code for the ad unit to be displayed + +Note that all ad unit codes included in the ad unit path must adhere to the [formatting rules](https://support.google.com/admanager/answer/1628457#ad-unit-codes) specified by Ad Manager. + +Another and probably the easiest way to get an ad unit path is to get it from the google ad manager ad unit document header generated tag: + +```js +googletag.defineSlot('/1234567/ad_unit_name_used_in_gam', [1, 1], 'ad-container-id').addService(googletag.pubads()); +``` + +### How to get Yieldmo placement id + +Please reach out to your Yieldmo account's person or email to support@yieldmo.com + +### Google Ad Manager setup + +Yieldmo Synthetic Inventory Module is designed to be used along with Google Ad Manager. GAM should be set as usual, but there are a few requirements: + +- Ad unit size should be 1x1 +- Creative should NOT be served into a SafeFrame and also should have 1x1 size +- Synthetic Inventory Universal Tag should be used as 3rd party creative code +### Synthetic Inventory Universal Tag + +```js +
    +``` diff --git a/dev-docs/pb7-notes.md b/dev-docs/pb7-notes.md new file mode 100644 index 0000000000..dc276c25f3 --- /dev/null +++ b/dev-docs/pb7-notes.md @@ -0,0 +1,81 @@ +--- +layout: page_v2 +title: Prebid 7.0 Release Notes & Publisher API Changes +description: Description of the breaking changes included for Prebid 7.0 +sidebarType: 1 +--- + +# Prebid 7.0 Bidder Interface and Publisher API Changes +{:.no_toc} + +This document describes the changes included for Prebid.js version 7.0. + +* TOC +{:toc} + +## Publisher Summary + +1. Be aware that a number of modules have been removed. See below for the list. +2. setConfig of 'publisherDomain' is no longer supported. Use setConfig({pageUrl: "URL"}) instead. +3. setConfig of 'fpd' is no longer supported. Use setConfig({ortb2: ...}) instead. +4. Please ensure your Prebid Server provider is running a relatively recent version of Prebid Server. Prebid.js 7 will not work with PBS-Go before 0.66 or PBS-Java before 1.55. + +Details on all of these below. + +## Removed Modules + +The following modules have been removed from Prebid.js as part of the 7.0 release. Publishers building with one of them will need to point to its replacement or remove the module from their build. + +{: .table .table-bordered .table-striped } + +| Module | Replacement | +|:-----------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AdLive Bid Adapter +| Akamai ID Submodule | rearchitected to use RTD module +| AppNexus Analytics Adapter +| DistrictM DMX Bid Adapter | replaced by Sharethrough +| FLOC ID submodule +| Halo ID & RTD submodules | replaced by Hadron +| NextRoll ID submodule +| OneVideo Bid Adapter | replaced by YahooSSP +| Sortable Adapters +| TrustX Bid Adapter | now an alias of Grid +| UserId Targeting Module + +## Adapter Interface + +Following the precedent of Prebid 5, bidders must read additional values from the ad unit, global config, or the ortb2 object. Bidders may still take these values as parameters, but must also support the Prebid conventions; publishers do not want to set these values multiple times, one for each bid parter. Publishers can now rely on certain parameters no longer needing to be set in bidder configuration, including (a) the instl flag on an ad unit, (b) the position parameter, and (c) the banned categories (bcats). Bidders should consider that if they are accepting any openrtb field in their configuration, they should also check the ortb2 object for that parameter. + +In the Prebid 5 release notes, it was noted that publishers should no longer use publisherDomain as a setConfig parameter, and instead prefer PageURL. Adapters no longer read from this location. Also, the object presented to bidders with the page url and that page's referring page url has been re-implemented. Our goal was that adapters can rely on ortb2.site.page and ortb2.site.ref, with flags for when top is not reached, the canonical link is used, setConfig('pageUrl') is used, or when window.location.href is used for ortb2.site.page. Many bidders had disparate logic for this and the refererInfo.referer had different meanings in different contexts. + +Also, Bid Adapters (not other types of modules) no longer have access to the storage manager unless explicitly allowed by the publisher. We believe bidding functionality should rarely (if ever) need this access and that this extra functionality included in bid adapters must be consented to by the installer in their configuration. The following bid adapters' unit tests were affected by this change: Adagio, Adnuntius, AP Stream, Concert, Conversant, Craft, Criteo, E-Planning, Invibes, Kargo, Quantcast, Trion, Unicorn, and Vidazoo. Adapters simply setting a random identifier in the first party local storage or cookie should consider if the popular shared id user id submodule can fully achieve this functionality for them. See storageAllowed in the [BidderSettings Reference](/dev-docs/publisher-api-reference/bidderSettings.html#2-bidder-setting-attributes) + +Adapters are no longer allowed to return alternate bidder codes unless allowed by the publisher. See allowAlternateBidderCodes in the [BidderSettings Reference](/dev-docs/publisher-api-reference/bidderSettings.html#2-bidder-setting-attributes). + +Finally, adapters known to use HTTP-1 bidding endpoints may now have notices appended to their documentation. + +## Regulatory and Consent Strings + +TCF1 is no longer supported by the Consent Management (GDPR) module. The Consent Management USP module now defaults to framework 'iab' and will work without configuration if installed and a functioning `__uspapi()` exists on the page. + +## First Party Data + +Support has been removed for `setConfig('fpd')`, `config.getLegacyFpd`, `config.convertAdUnitFpd` and related relics of legacy first party data. Publishers should use the methods described in [First Party Data]({{site.baseurl}}/features/firstPartyData.html). + +First party data can also now be set on a specific auction. This is useful for example on infinite scroll pages when contextual segments change, or when the publisher wishes to express the context of an instream video ad but not the display advertising. As part of this change the ortb2 object is now made a part of bid requests, instead of necesitating a getConfig call by an adapter. This has led to slight changes in many dozens of bid adapters and substantial changes to all of the RTD adapters. + +## Prebid Server Adapter + +An undocumented feature "Stored Auction Response" has been deprecated. + +The Prebid Server committee moved the ortb2 location of bidder parameters from `imp[].ext.BIDDER` to `imp[].ext.prebid.bidder.BIDDER`. PBS versions before PBS-Go 0.66 (April 2019) and PBS-Java 1.55 (Feb 2021) are not compatible with Prebid 7+. + +## Build changes + +In later 6.x versions, an improvement in the build process introduced some undesirable behavior for users loading the library twice on the same pageview to the same global library name. If you load Prebid.js twice on a page using the same global, the second load is now prevented. + + +## Further Reading + ++ [Publisher API Reference](/dev-docs/publisher-api-reference.html) ++ [First Party Data](/features/firstPartyData.html) diff --git a/dev-docs/pbs-bidders.md b/dev-docs/pbs-bidders.md index 491c6d70a2..5bf34c26ce 100644 --- a/dev-docs/pbs-bidders.md +++ b/dev-docs/pbs-bidders.md @@ -23,6 +23,9 @@ You can also download the full CSV {% assign bidder_pages = site.pages | where: "layout", "bidder" | where: "pbs", true %} +{: .alert.alert-warning :} +Publishers are advised to check with legal counsel before doing business with any particular bidder. + ## Prebid Server Bidder List -
    -
    +              
    
+                
    
+                  
     var videoAdUnit = [{
   code: 'sample-code',
   sizes: [640,480],
@@ -78,8 +79,9 @@ 
    {{ page.title }}
    
     }
   ]
 }];
-
    
-            
    
+
    +
    +
    @@ -92,15 +94,11 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    - -
    - - - +
    diff --git a/examples/video/outstream/pb-ve-outstream-app.html b/examples/video/outstream/pb-ve-outstream-app.html index 34524e8540..5ec845a426 100644 --- a/examples/video/outstream/pb-ve-outstream-app.html +++ b/examples/video/outstream/pb-ve-outstream-app.html @@ -15,21 +15,21 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    -
    +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    -
    +

    Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

    @@ -38,99 +38,97 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    -<script src="//acdn.adnxs.com/prebid/not-for-prod/prebid.js"></script>
+    
    Place this code in the page header.
    
+    
    
+      
    +<script src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
 <!--AdPlayer.Pro code-->
 <script src="https://static.adplayer.pro/player/demo.js"></script>
-
    
+
    +
    -
    - - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <div id='playerContainerADP'></div>
 <script>
-	/* our app where we run player
+  /* our app where we run player
    our app variables */
-		var pbjs;
-		pbjs = pbjs || {};
-		pbjs.que = pbjs.que || [];
-		var debug = false;
-		if (typeof window.console === 'undefined' || typeof window.console.log === 'undefined' || typeof window.console.dir === 'undefined') {
-		  debug = false;
-		}
-		var videoId = 'video1';
-
-		/* Prebid video ad unit
-		   This is a working example but you must use your own settings/bidders for production
-		   More docs at https://prebid.org/prebid-video/video-overview.html */
-		var adUnits = [{
-		  code: videoId,
-		  mediaTypes: {
-		    video: {
-		      context: 'outstream',
+    var pbjs;
+    pbjs = pbjs || {};
+    pbjs.que = pbjs.que || [];
+    var debug = false;
+    if (typeof window.console === 'undefined' || typeof window.console.log === 'undefined' || typeof window.console.dir === 'undefined') {
+      debug = false;
+    }
+    var videoId = 'video1';
+
+    /* Prebid video ad unit
+       This is a working example but you must use your own settings/bidders for production
+       More docs at https://prebid.org/prebid-video/video-overview.html */
+    var adUnits = [{
+      code: videoId,
+      mediaTypes: {
+        video: {
+          context: 'outstream',
                       playerSize: [640, 480],
                       mimes: ['video/mp4'],
                       protocols: [1, 2, 3, 4, 5, 6, 7, 8],
                       playbackmethod: [2],
                       skip: 1
-		    }
-		  },
-		  bids: [{
-		    bidder: 'appnexus',
-		    params: {
-		      placementId: 13232385
-		    }
-		  }]
-		}];
-
-		pbjs.que.push(function () {
-		  pbjs.addAdUnits(adUnits);
-		  pbjs.requestBids({
-		    timeout: 1000,
-		    bidsBackHandler: function (bids) {
-		      if (debug) {
-		        window.console.dir(bids);
-		      }
-		      // we get the VAST XML from bids adResponse and pass it to our outstream player
    
-		      if (bids && bids[videoId] && bids[videoId].bids && bids[videoId].bids[0] && bids[videoId].bids[0].adResponse) {
-		        var adResponse = bids[videoId].bids[0].adResponse;
-		        if (adResponse.ad && adResponse.ad.video && typeof adResponse.ad.video.content === 'string') {
-		          var vastXml = bids[videoId].bids[0].adResponse.ad.video.content;
-		          if (vastXml !== '') {
-		            if (debug) {
-		              window.console.log(vastXml);
-		            }
-								AdPlayerPro('playerContainerADP').setup({
-									"file": "https://static.adplayer.pro/video/640.mp4",
-									"width": 640,
-									"height": 360,
-									"autoStart": true,
-									"muted": true,
-									"advertising": {
-										"tag": vastXml
-									}
-								});
-		          }
-		        }
-		      }
-		    }
-		  });
-		});
+        }
+      },
+      bids: [{
+        bidder: 'appnexus',
+        params: {
+          placementId: 13232385
+        }
+      }]
+    }];
+
+    pbjs.que.push(function () {
+      pbjs.addAdUnits(adUnits);
+      pbjs.requestBids({
+        timeout: 1000,
+        bidsBackHandler: function (bids) {
+          if (debug) {
+            window.console.dir(bids);
+          }
+          // we get the VAST XML from bids adResponse and pass it to our outstream player
    
+          if (bids && bids[videoId] && bids[videoId].bids && bids[videoId].bids[0] && bids[videoId].bids[0].adResponse) {
+            var adResponse = bids[videoId].bids[0].adResponse;
+            if (adResponse.ad && adResponse.ad.video && typeof adResponse.ad.video.content === 'string') {
+              var vastXml = bids[videoId].bids[0].adResponse.ad.video.content;
+              if (vastXml !== '') {
+                if (debug) {
+                  window.console.log(vastXml);
+                }
+                AdPlayerPro('playerContainerADP').setup({
+                  "file": "https://static.adplayer.pro/video/640.mp4",
+                  "width": 640,
+                  "height": 360,
+                  "autoStart": true,
+                  "muted": true,
+                  "advertising": {
+                    "tag": vastXml
+                  }
+                });
+              }
+            }
+          }
+        }
+      });
+    });
 </script>
-
    
-		
    
-
+
    +
    diff --git a/examples/video/outstream/pb-ve-outstream-dfp.html b/examples/video/outstream/pb-ve-outstream-dfp.html index 0a62332454..1935146169 100644 --- a/examples/video/outstream/pb-ve-outstream-dfp.html +++ b/examples/video/outstream/pb-ve-outstream-dfp.html @@ -17,14 +17,14 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    -
    +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    @@ -38,7 +38,7 @@

    {{ page.title }}

    -
    +

    Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

    @@ -47,14 +47,14 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    +    
    Place this code in the page header.
    
+    
    
+      
     
 <script async src="//www.googletagservices.com/tag/js/gpt.js"></script>
 
@@ -120,14 +120,13 @@ 
    Place this code in the page header.
    
     });
 
 </script>
-
    
-
+
    -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
     
 <div id='video1'>
     <p>Prebid Outstream Video Ad</p>
@@ -139,9 +138,8 @@ 
    Place this code in the page body.
    
     </script>
 </div>
 
-
    
-		
    
-	
+
    +
    diff --git a/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html b/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html new file mode 100644 index 0000000000..ab09e8518f --- /dev/null +++ b/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html @@ -0,0 +1,145 @@ +--- +layout: video_sample +title: Prebid Video | Video Outstream Example with No Ad Server using Specified Renderer +description: An example of an outstream video ad using Prebid.js and no ad server but with a specified renderer. +videoType: pb-os-nas-renderer +isVideo: true +sidebarType: 4 +--- + + + +
    +
    +
    +

    {{ page.title }}

    +

    {{page.description }}

    +
    + + +
    +

    Important: + This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    +
    + +
    +
    +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    +
    + +
    +

    Prebid Outstream Video Ad

    +
    + +
    +

    Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

    +
    +
    + + +
    +

    Warning: + Do not forget to exchange the placementId in the code examples with your own placementId!

    +
    + +

    Place this code in the page header.

    +
    + 
    +
+<script>
+    var pbjs = pbjs || {};
+    pbjs.que = pbjs.que || [];
+
+    function callANRenderer(bid, ad) {
+      const adResponse = {
+          ad: {
+              video: {
+                  content: ad,
+                  player_width: 640,
+                  player_height: 480,
+              }
+          }
+      }
+
+      bid.renderer.push(() => {
+          window.ANOutstreamVideo.renderAd({
+              targetId: bid.adUnitCode,
+              adResponse,
+          });
+      });
+    }
+
+    function render(bid) {
+        let ad = bid.ad || bid.vastXml;
+
+        if (ad) {
+            callANRenderer(bid, ad)
+        } else {
+            if (bid.vastUrl) {
+              (async () => {
+                  ad = await fetch(resp).then(resp => resp.text());
+
+                  if (typeof ad === 'string') {
+                      callANRenderer(bid, ad);
+                  } else {
+                      console.log('Invalid VAST');
+                  }
+              })();
+            } else {
+                console.log('Invalid ad');
+            }
+        }
+    }
+
+    const adUnits = [{
+        code: 'video1',
+        mediaTypes: {
+            video: {
+                context: 'outstream',
+                playerSize: [640, 480],
+                mimes: ['video/mp4'],
+                protocols: [1, 2, 3, 4, 5, 6, 7, 8],
+                playbackmethod: [2],
+                skip: 1,
+                renderer: {
+                    render,
+                    url: "https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js"
+                },
+            }
+        },
+        bids: [{
+            bidder: 'appnexus',
+            params: {
+                placementId: 13232385
+            }
+        }]
+    }];
+
+    pbjs.que.push(function() {
+        pbjs.addAdUnits(adUnits);
+        pbjs.requestBids({
+            timeout: 1000,
+            bidsBackHandler: function(bids) {
+                const highestCpmBids = pbjs.getHighestCpmBids('video1');
+                pbjs.renderAd(document, highestCpmBids[0].adId);
+            }
+        });
+    });
+</script>
+
    +
    + +

    Place this code in the page body.

    +
    + + 
    +
+<div id='video1'>
+  <p>Prebid Outstream Video Ad</p>
+</div>
+
    +
    +
    +
    + + diff --git a/examples/video/outstream/pb-ve-outstream-no-server.html b/examples/video/outstream/pb-ve-outstream-no-server.html index bb78701f5e..4b96f20e91 100644 --- a/examples/video/outstream/pb-ve-outstream-no-server.html +++ b/examples/video/outstream/pb-ve-outstream-no-server.html @@ -17,14 +17,14 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    -
    +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    @@ -33,7 +33,7 @@

    {{ page.title }}

    Prebid Outstream Video Ad

    -
    +

    Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

    @@ -44,14 +44,14 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    +    
    Place this code in the page header.
    
+		
    
+      
     
 <script>
     var pbjs = pbjs || {};
@@ -90,26 +90,24 @@ 
    Place this code in the page header.
    
 
 </script>
 
-
    
+
    +
    -
    - - -

    Place this code in the page body.

    -
    +      
    
+        
+        
     
 <div id='video1'>
-	<p>Prebid Outstream Video Ad</p>
+  <p>Prebid Outstream Video Ad</p>
 </div>
-
    
+
    -
    -
    ; +

    Prebid Outstream Video Ad

    diff --git a/examples/video/outstream/pb-ve-outstream-radiant.html b/examples/video/outstream/pb-ve-outstream-radiant.html index 60315adaa6..ea027595ad 100644 --- a/examples/video/outstream/pb-ve-outstream-radiant.html +++ b/examples/video/outstream/pb-ve-outstream-radiant.html @@ -17,21 +17,21 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    -
    +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    -
    +

    Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

    @@ -40,102 +40,100 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    +    
    Place this code in the page header.
    
+    
    
+      
     
 <!--radiant code-->
 <script src="https://cdn.radiantmediatechs.com/rmp/5.5.6/js/rmp.debug.js"></script>
-
    
+
    +
    -
    - - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <script>
-	/* our app where we run player
+  /* our app where we run player
    our app variables */
-		var pbjs;
-		pbjs = pbjs || {};
-		pbjs.que = pbjs.que || [];
-		var debug = false;
-		if (typeof window.console === 'undefined' || typeof window.console.log === 'undefined' || typeof window.console.dir === 'undefined') {
-		  debug = false;
-		}
-		var videoId = 'video1';
-
-		/* Prebid video ad unit
-		   This is a working example but you must use your own settings/bidders for production
-		   More docs at https://prebid.org/prebid-video/video-overview.html */
-		var adUnits = [{
-		  code: videoId,
-		  mediaTypes: {
-		    video: {
-		      context: 'outstream',
+    var pbjs;
+    pbjs = pbjs || {};
+    pbjs.que = pbjs.que || [];
+    var debug = false;
+    if (typeof window.console === 'undefined' || typeof window.console.log === 'undefined' || typeof window.console.dir === 'undefined') {
+      debug = false;
+    }
+    var videoId = 'video1';
+
+    /* Prebid video ad unit
+       This is a working example but you must use your own settings/bidders for production
+       More docs at https://prebid.org/prebid-video/video-overview.html */
+    var adUnits = [{
+      code: videoId,
+      mediaTypes: {
+        video: {
+          context: 'outstream',
                       playerSize: [640, 480],
                       mimes: ['video/mp4'],
                       protocols: [1, 2, 3, 4, 5, 6, 7, 8],
                       playbackmethod: [2],
                       skip: 1
-		    }
-		  },
-		  bids: [{
-		    bidder: 'appnexus',
-		    params: {
-		      placementId: 13232385
-		    }
-		  }]
-		}];
-
-		pbjs.que.push(function () {
-		  pbjs.addAdUnits(adUnits);
-		  pbjs.requestBids({
-		    timeout: 1000,
-		    bidsBackHandler: function (bids) {
-		      if (debug) {
-		        window.console.dir(bids);
-		      }
-		      // we get the VAST XML from bids adResponse and pass it to our outstream player
-		      if (bids && bids[videoId] && bids[videoId].bids && bids[videoId].bids[0] && bids[videoId].bids[0].adResponse) {
-		        var adResponse = bids[videoId].bids[0].adResponse;
-		        if (adResponse.ad && adResponse.ad.video && typeof adResponse.ad.video.content === 'string') {
-		          var vastXml = bids[videoId].bids[0].adResponse.ad.video.content;
-		          if (vastXml !== '') {
-		            if (debug) {
-		              window.console.log(vastXml);
-		            }
-		            var settings = {
-		              licenseKey: 'Kl8lZ292K3N6MmVvZD9yb201ZGFzaXMzMGRiMEElXyo=',
-		              width: 640,
-		              height: 360,
-		              autoplay: true,
-		              adOutStreamMutedAutoplay: true,
-		              ads: true,
-		              adsResponse: vastXml,
-		              adOutStream: true,
-		              skin: 'outstream'
-		            };
-		            var elementID = 'rmpPlayer';
-		            var rmp = new RadiantMP(elementID);
-		            rmp.init(settings);
-		          }
-		        }
-		      }
-		    }
-		  });
-		});
+        }
+      },
+      bids: [{
+        bidder: 'appnexus',
+        params: {
+          placementId: 13232385
+        }
+      }]
+    }];
+
+    pbjs.que.push(function () {
+      pbjs.addAdUnits(adUnits);
+      pbjs.requestBids({
+        timeout: 1000,
+        bidsBackHandler: function (bids) {
+          if (debug) {
+            window.console.dir(bids);
+          }
+          // we get the VAST XML from bids adResponse and pass it to our outstream player
+          if (bids && bids[videoId] && bids[videoId].bids && bids[videoId].bids[0] && bids[videoId].bids[0].adResponse) {
+            var adResponse = bids[videoId].bids[0].adResponse;
+            if (adResponse.ad && adResponse.ad.video && typeof adResponse.ad.video.content === 'string') {
+              var vastXml = bids[videoId].bids[0].adResponse.ad.video.content;
+              if (vastXml !== '') {
+                if (debug) {
+                  window.console.log(vastXml);
+                }
+                var settings = {
+                  licenseKey: 'Kl8lZ292K3N6MmVvZD9yb201ZGFzaXMzMGRiMEElXyo=',
+                  width: 640,
+                  height: 360,
+                  autoplay: true,
+                  adOutStreamMutedAutoplay: true,
+                  ads: true,
+                  adsResponse: vastXml,
+                  adOutStream: true,
+                  skin: 'outstream'
+                };
+                var elementID = 'rmpPlayer';
+                var rmp = new RadiantMP(elementID);
+                rmp.init(settings);
+              }
+            }
+          }
+        }
+      });
+    });
 </script>
-
    
-		
    
-
+
    +
    diff --git a/examples/video/pb-video-template.html b/examples/video/pb-video-template.html index 1d1f9e5ef8..c5c74be35f 100644 --- a/examples/video/pb-video-template.html +++ b/examples/video/pb-video-template.html @@ -1,7 +1,7 @@ --- layout: video_sample -title: Prebid Video | Video Outstream Example with Google Ad Manager -description: An example of an outstream video with a pre-roll ad using Prebid.js and Google Ad Manager. +title: Prebid Video | Video Outstream Example with Google Ad Manager +description: An example of an outstream video with a pre-roll ad using Prebid.js and Google Ad Manager. videoType: pb-os-dfp isVideo: true sidebarType: 4 @@ -13,27 +13,27 @@

    {{ page.title }}

    {{page.description }}

    - + - +

    {{page.title}}

    - +
    {{page.description}}
    - + - +

    @@ -59,10 +59,10 @@

    {{page.title}}

    googletag.cmd.push(function() { googletag.display('video1'); }); - +
    - +

    Quisque ac luctus nisi, vitae ornare arcu. Proin fermentum sapien vitae odio vestibulum porta. Suspendisse faucibus sapien enim, et faucibus urna tempus et. Integer porttitor justo sed faucibus blandit. Morbi semper lectus vitae semper facilisis. Quisque @@ -159,24 +159,24 @@

    {{page.title}}

    vel tortor. Aenean ultrices libero sed neque fermentum tempor. Morbi tincidunt dui turpis, non mollis est dignissim at. Suspendisse molestie convallis interdum. Donec sit amet fermentum purus.

    - - + + - + - +

    Place this code in the page header.

     	
 	<script async src="//www.googletagservices.com/tag/js/gpt.js"></script>
-		<script async src="//acdn.adnxs.com/prebid/not-for-prod/prebid.js"></script>
+		<script async src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
 		<script type="text/javascript" src="https://ssl.p.jwpcdn.com/player/v/8.0.5/jwplayer.js"></script>
         <script type="text/javascript">
             jwplayer.key = "ssbF6k0i9BPe87xfG/s0ipdp5gwbLoZaDON/GQvuwPU9nVJy"; //Test Key - replace this with your own valid JWPlayer license key
@@ -248,7 +248,7 @@ 
    Place this code in the page header.
    - +

    Place this code in the page body.

    @@ -261,14 +261,14 @@

    Place this code in the page body.

    googletag.display('video1'); }); </script> - </div> + </div>
    - +
    - + - diff --git a/examples/video/server/brid/pbs-ve-brid.html b/examples/video/server/brid/pbs-ve-brid.html index 93b89d953b..0590ef792e 100644 --- a/examples/video/server/brid/pbs-ve-brid.html +++ b/examples/video/server/brid/pbs-ve-brid.html @@ -1,7 +1,7 @@ --- layout: video_sample -title: Prebid Video | Prebid Server Example with Brid player -description: An example of a pre-roll ad using Prebid Server and Brid player. +title: Prebid Video | Prebid Server Example with Brid player +description: An example of a pre-roll ad using Prebid Server and Brid player. videoType: pbs-br isVideo: true sidebarType: 4 @@ -15,29 +15,29 @@

    {{ page.title }}

    {{page.description }}

    - + -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    - +
    - + - + -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    - -
    -

    Place this code in the page header.

    -
    +
+    
    Place this code in the page header.
    
+    
    
+      
     
-<script async src="//acdn.adnxs.com/prebid/not-for-prod/prebid.js"></script>
+<script async src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
 
 <script type="text/javascript" src="//services.brid.tv/player/build/brid.min.js"></script>
 <script>
@@ -128,14 +128,13 @@ 
    Place this code in the page header.
    
 
 </script>
 
-
    
+
    +
    -
    - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
     
 <div id="myDiv" class="brid" style="width:640px; height:360;"></div>
 
@@ -153,15 +152,14 @@ 
    Place this code in the page body.
    
                 "cuepoints": null
             }
         ]
-    }); 
+    });
   }
 </script>
-
    
-		
    
-	
-
    + +
    + - + - + - diff --git a/examples/video/server/jwplayer/pbs-ve-jwplayer-hosted.html b/examples/video/server/jwplayer/pbs-ve-jwplayer-hosted.html index 62e4108e2e..372974066e 100644 --- a/examples/video/server/jwplayer/pbs-ve-jwplayer-hosted.html +++ b/examples/video/server/jwplayer/pbs-ve-jwplayer-hosted.html @@ -1,7 +1,7 @@ --- layout: video_sample -title: Prebid Video | Prebid Server Example with JW Player (Self-Hosted) -description: An example of a pre-roll ad using Prebid Server and JW Player (Hosted). +title: Prebid Video | Prebid Server Example with JW Player (Self-Hosted) +description: An example of a pre-roll ad using Prebid Server and JW Player (Hosted). videoType: pbs-jw02 isVideo: true sidebarType: 4 @@ -14,29 +14,29 @@

    {{ page.title }}

    {{page.description }}

    - + -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    - +
    - + - + -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    - -
    -

    Place this code in the page header.

    -
    -	
-<script async src="//acdn.adnxs.com/prebid/not-for-prod/prebid.js"></script>
+
+    
    Place this code in the page header.
    
+    
    
+      
    +  
+<script async src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
 <script type="text/javascript" src="https://ssl.p.jwpcdn.com/player/v/8.0.5/jwplayer.js"></script>
 <script type="text/javascript">
     jwplayer.key = "YOUR_JW_PLAYER_KEY"; //Test Key - replace this with your own valid JWPlayer license key
    
@@ -131,14 +131,14 @@ 
    Place this code in the page header.
    
 
 </script>
 
-
    
+
    -
    - - -
    -

    Place this code in the page body.

    -
    +
    + +

    Place this code in the page body.

    +
    + + 
     
 <div id="playerContainerJW" style='width:640px; height:480px; border:1px solid black;'></div>
 
@@ -148,7 +148,7 @@ 
    Place this code in the page body.
    
     invokeVideoPlayer = function(url) {
         console.log("starting player with url " + url);
         jwPlayerInstance.setup({
-           
+
            "file": "https://vjs.zencdn.net/v/oceans.mp4",
             "width": 640,
             "height": 480,
@@ -171,12 +171,11 @@ 
    Place this code in the page body.
    
 
 </script>
 
-
    -
    - + +
    - + + } + - diff --git a/examples/video/server/jwplayer/pbs-ve-jwplayer-platform.html b/examples/video/server/jwplayer/pbs-ve-jwplayer-platform.html index f5a15deb27..6456730285 100644 --- a/examples/video/server/jwplayer/pbs-ve-jwplayer-platform.html +++ b/examples/video/server/jwplayer/pbs-ve-jwplayer-platform.html @@ -15,7 +15,7 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    @@ -26,106 +26,105 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    +    
    Place this code in the page header.
    
+    
    
+      
     
       <script>
-	    var pbjs = pbjs || {};
-	    pbjs.que = pbjs.que || [];
-	
-	    /* PRE-DEFINE `invokeVideoPlayer`
-	
-	    Because we have no way of knowing when all the bids will be
-	    returned from Prebid we can't be sure that the browser will
-	    reach the point where `invokeVideoPlayer` is defined before
-	    `bidsBackHandler` fires and tries to call it.
-	
-	    To prevent an "`invokeVideoPlayer` not defined" error, we
-	    pre-define it before we make the call to Prebid, and redefine
-	    it later on with the code to create the player and play the
-	    ad.
-	
-	    In this first version, it simply stores the winning VAST to
-	    use later. */
-	
-	    var tempTag = false;
-	    var invokeVideoPlayer = function(url) {
-	        tempTag = url;
-	    };
-	
-	    var videoAdUnit = {
-	        code: 'video1',
-	        mediaTypes: {
-	            video: {
-			context: 'instream',
-			playerSize: [640, 480],
-			mimes: ['video/mp4'],
-			protocols: [1, 2, 3, 4, 5, 6, 7, 8],
-			playbackmethod: [2],
-			skip: 1
-	            }
-	        },
-	        bids: [{
-	            bidder: 'appnexus',
-	            params: {
-	                placementId: 13232361  // Add your own placement id here.
    
-	            }
-	        }]
-	    };
-	
-	    pbjs.que.push(function() {
-	
-	        // configure prebid to use prebid cache and prebid server 
-	        // make sure to add your own accountId to your s2sConfig object
    
-	        pbjs.setConfig({
-	            cache: {
-	                url: 'https://prebid.adnxs.com/pbc/v1/cache'
-	            },
-	            debug: true,
-	            s2sConfig: {
-	                endpoint: 'https://prebid.adnxs.com/pbs/v1/openrtb2/auction',
-	                enabled: true,
-	                accountId: 'c9d412ee-3cc6-4b66-9326-9f49d528f13e',
-	                bidders: ['appnexus']
-	            }
-	        });
-	
-	        pbjs.addAdUnits(videoAdUnit); // add your ad units to the bid request
    
-	
-	        pbjs.requestBids({
-	            bidsBackHandler: function(bids) {
-	
-	                var videoUrl = pbjs.adServers.dfp.buildVideoUrl({
-	                    adUnit: videoAdUnit,
-	                    params: {
-	                        iu: '/19968336/prebid_cache_video_adunit',
-	                        cust_params: {
-	                            section: 'blog',
-	                            anotherKey: 'anotherValue'
-	                        },
-	                        output: 'vast'
-	                    }
-	                });
-	                invokeVideoPlayer(videoUrl);
-	            }
-	        });
-	    });
-	
-	</script>
-
    
+      var pbjs = pbjs || {};
+      pbjs.que = pbjs.que || [];
 
-		
    
+      /* PRE-DEFINE `invokeVideoPlayer`
+
+      Because we have no way of knowing when all the bids will be
+      returned from Prebid we can't be sure that the browser will
+      reach the point where `invokeVideoPlayer` is defined before
+      `bidsBackHandler` fires and tries to call it.
+
+      To prevent an "`invokeVideoPlayer` not defined" error, we
+      pre-define it before we make the call to Prebid, and redefine
+      it later on with the code to create the player and play the
+      ad.
+
+      In this first version, it simply stores the winning VAST to
+      use later. */
+
+      var tempTag = false;
+      var invokeVideoPlayer = function(url) {
+          tempTag = url;
+      };
+
+      var videoAdUnit = {
+          code: 'video1',
+          mediaTypes: {
+              video: {
+      context: 'instream',
+      playerSize: [640, 480],
+      mimes: ['video/mp4'],
+      protocols: [1, 2, 3, 4, 5, 6, 7, 8],
+      playbackmethod: [2],
+      skip: 1
+              }
+          },
+          bids: [{
+              bidder: 'appnexus',
+              params: {
+                  placementId: 13232361  // Add your own placement id here.
    
+              }
+          }]
+      };
+
+      pbjs.que.push(function() {
+
+          // configure prebid to use prebid cache and prebid server 
+          // make sure to add your own accountId to your s2sConfig object
    
+          pbjs.setConfig({
+              cache: {
+                  url: 'https://prebid.adnxs.com/pbc/v1/cache'
+              },
+              debug: true,
+              s2sConfig: {
+                  endpoint: 'https://prebid.adnxs.com/pbs/v1/openrtb2/auction',
+                  enabled: true,
+                  accountId: 'c9d412ee-3cc6-4b66-9326-9f49d528f13e',
+                  bidders: ['appnexus']
+              }
+          });
+
+          pbjs.addAdUnits(videoAdUnit); // add your ad units to the bid request
    
+
+          pbjs.requestBids({
+              bidsBackHandler: function(bids) {
+
+                  var videoUrl = pbjs.adServers.dfp.buildVideoUrl({
+                      adUnit: videoAdUnit,
+                      params: {
+                          iu: '/19968336/prebid_cache_video_adunit',
+                          cust_params: {
+                              section: 'blog',
+                              anotherKey: 'anotherValue'
+                          },
+                          output: 'vast'
+                      }
+                  });
+                  invokeVideoPlayer(videoUrl);
+              }
+          });
+      });
+
+  </script>
+
    +
    - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <!-- This line loads a player without loading any video content -->
 <!-- Replace this with the correct url for your player -->
@@ -160,10 +159,8 @@ 
    Place this code in the page body.
    
     }
 
 </script>	
-
-
    
+
    -
    diff --git a/examples/video/server/kaltura/pbs-ve-kaltura.html b/examples/video/server/kaltura/pbs-ve-kaltura.html index 5bf385058e..a6eecad0c4 100644 --- a/examples/video/server/kaltura/pbs-ve-kaltura.html +++ b/examples/video/server/kaltura/pbs-ve-kaltura.html @@ -17,7 +17,7 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    @@ -28,16 +28,16 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    -	
-		
+    
    Place this code in the page header.
    
+    
    
+      
    +
+
 <script>
     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
@@ -123,15 +123,13 @@ 
    Place this code in the page header.
    
     });
 
 </script>	
-
-
    
-
-		
    
+
    +
    - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <div id="myPlayer" style="width:640px; height:480px;"></div>
 
@@ -212,10 +210,8 @@ 
    Place this code in the page body.
    
     }
 
 </script>
-
-
    
-		
    
-	
+
    +
    diff --git a/examples/video/server/ooyala/pbs-ve-ooyala.html b/examples/video/server/ooyala/pbs-ve-ooyala.html index 6bbe7c407e..1f2a8b926d 100644 --- a/examples/video/server/ooyala/pbs-ve-ooyala.html +++ b/examples/video/server/ooyala/pbs-ve-ooyala.html @@ -17,7 +17,7 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    @@ -29,16 +29,16 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    -	
-	
+    
    Place this code in the page header.
    
+    
    
+      
    +  
+
 <!-- LOAD OOYALA PLUGINS
 
  Load the Ooyala player scripts you plan to use.
@@ -132,7 +132,7 @@ 
    Place this code in the page header.
    
             }
         });
 
-		// add your ad units to the bid request
    
+    // add your ad units to the bid request
    
         pbjs.addAdUnits(videoAdUnit); 
 
         pbjs.requestBids({
@@ -155,15 +155,13 @@ 
    Place this code in the page header.
    
     });
 
 </script>	
-
-
    
-
-		
    
+
    +
    - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <div id='container' style='width:640px;height:480px;'></div>
 
@@ -263,9 +261,8 @@ 
    Place this code in the page body.
    
 
 </script>
 
-
    
-		
    
-	
+
    +
    diff --git a/examples/video/server/radiant/pbs-ve-radiant.html b/examples/video/server/radiant/pbs-ve-radiant.html index d64d43b0ec..8d89af40b3 100644 --- a/examples/video/server/radiant/pbs-ve-radiant.html +++ b/examples/video/server/radiant/pbs-ve-radiant.html @@ -15,7 +15,7 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    @@ -26,30 +26,28 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    - -
    
+    
    Place this code in the page header.
    
+    
    
+      
     
 <!--production version of prebid.js-->
-<script async src="//acdn.adnxs.com/prebid/not-for-prod/prebid.js"></script>
+<script async src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
 
 <!-- Radiant Media Player core library - debug browser console mode (use rmp.min.js for production) -->
 <script src="https://cdn.radiantmediatechs.com/rmp/5.5.6/js/rmp.debug.js"></script>
-
-
    
+
    +
    - -
    -

    Place this code in the page body.

    -
    +		
    
+      
    Place this code in the page body.
    
+      
+      
     
 /* our app where we run player
    our app variables */
@@ -84,12 +82,12 @@ 
    Place this code in the page body.
    
   code: 'video1',
   mediaTypes: {
     video: {
-	context: 'instream',
-	playerSize: [640, 480],
-	mimes: ['video/mp4'],
-	protocols: [1, 2, 3, 4, 5, 6, 7, 8],
-	playbackmethod: [2],
-	skip: 1
+  context: 'instream',
+  playerSize: [640, 480],
+  mimes: ['video/mp4'],
+  protocols: [1, 2, 3, 4, 5, 6, 7, 8],
+  playbackmethod: [2],
+  skip: 1
     }
   },
   bids: [{
@@ -192,9 +190,8 @@ 
    Place this code in the page body.
    
   }
   pbApp.invokeVideoPlayer(pbApp.fallbackAdTagUrl);
 }, pbApp.playerSetupTimeout);
-
    
-		
    
-
+
    +
    diff --git a/examples/video/server/videojs/pbs-ve-videojs.html b/examples/video/server/videojs/pbs-ve-videojs.html index cb3172c5eb..329ef45b5c 100644 --- a/examples/video/server/videojs/pbs-ve-videojs.html +++ b/examples/video/server/videojs/pbs-ve-videojs.html @@ -17,7 +17,7 @@

    {{ page.title }}

    -
    +

    Important: This example uses a test version of Prebid.js hosted on our CDN that is not recommended for production use. It includes all available adapters. Production implementations should build from source or customize the build using the Download page to make sure only the necessary bidder adapters are included.

    @@ -35,14 +35,14 @@

    {{ page.title }}

    -
    +

    Warning: Do not forget to exchange the placementId in the code examples with your own placementId!

    -
    -

    Place this code in the page header.

    -
    +    
    Place this code in the page header.
    
+    
    
+      
     
 <!-- videojs -->
 <!-- use recent version of videojs to ensure proper functioning with the iOS devices -->
@@ -115,7 +115,7 @@ 
    Place this code in the page header.
    
             }
         });
 
-		// add your ad units to the bid request
    
+    // add your ad units to the bid request
    
         pbjs.addAdUnits(videoAdUnit); 
 
         pbjs.requestBids({
@@ -137,16 +137,13 @@ 
    Place this code in the page header.
    
     });
 
 </script>
-
-
    
-
-
-		
    
+
    +
    - -
    -

    Place this code in the page body.

    -
    +    
    Place this code in the page body.
    
+    
    
+      
+      
     
 <div class="example-video-container">
     <video id="vid1" class="video-js vjs-default-skin vjs-big-play-centered" controls data-setup='{}' width='640' height='480'>
@@ -214,9 +211,8 @@ 
    Place this code in the page body.
    
     }
 
 </script>
-
    
-		
    
-	
+
    +
    diff --git a/faq/prebid-server-faq.md b/faq/prebid-server-faq.md index 897921131b..d9975d5d69 100644 --- a/faq/prebid-server-faq.md +++ b/faq/prebid-server-faq.md @@ -168,3 +168,51 @@ Another way is to [register for our host company mailing list](/prebid-server/ho Prebid Server is not a full-fledged SSP. Any DSP bid adapters should keep this in mind when it comes to assuming SSP functionality like resolving OpenRTB macros. We debated building this functionality into PBS, but realized it would take precious milliseconds away from the overall header bidding auction to scan kilobytes of bidder creatives for the 9 different OpenRTB macros. Since so few bidders require this functionality, it makes sense to have those adapters do it themselves. If an adapter doesn't resolve its own macros, AUCTION_PRICE will eventually get resolved by the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative), but by then the bid price will be in the ad server currency and quantized by the price granularity. This will likely cause reporting discrepancies. + +## Does Prebid Server support region-specific endpoints for bidders? + +Yes. This is handled by the PBS host company in their datacenter config. +Bidders that want to make use of region-specific endpoints will need to work +with each PBS host company: + +- determine which regions the host company supports +- map the regions to the bidder's endpoints +- the host company overrides the bidder's default auction endpoint when they deploy the configuration for each region. + +We recognize that it's inconvenient for bidders to be required to have this +conversation with each host company, but there's really not a better way +in an open source project. Any number of companies may choose to host +PBS and we cannot constrain them into a defined set of regions. + +## Can bidder endpoints differ by publisher? + +You may not use an endpoint domain as a bidder parameter. Prebid Server is not +an open proxy. If absolutely necessary, you may specify a portion of the +domain as a parameter to support geo regions or account specific servers. +However, this is discouraged and may degrade the performance of your adapter +since the server needs to maintain more outgoing connections. Host companies +may choose to disable your adapter if it uses a dynamically configured domain. + +e.g. this config is not allowed because the entire domain name is a variable: + +``` +endpoint: "https://{host}/path" +``` +but this would be ok: +``` +endpoint: "https://{host}.example.com/path" +``` + +## Did the location of the bidder parameters change? + +Why yes, glad you noticed. The original 2017 OpenRTB extension where bidders +and parameters were placed was imp[].ext.BIDDER. Since 2020, the recommended location +is imp[].ext.prebid.bidder.BIDDER. This change was driven by the existence of +other fields in imp[].ext that aren't bidders, like `skadn`, `data`, etc. + +Bidders are copied from imp[].ext to imp[].ext.prebid.bidder, and they will be copied for years to come, but we would ask that new implementations of stored requests +utilize the new location. + +## Does PBS support SSL? + +No, Prebid Server is intended to run behind a load balancer or proxy, so it does not currently support defining a security certificate. diff --git a/features/InterstitialAds.md b/features/InterstitialAds.md index 3eda2187fa..67a68304fe 100644 --- a/features/InterstitialAds.md +++ b/features/InterstitialAds.md @@ -11,24 +11,26 @@ sidebarType: 1 * TOC {:toc} -Interstitails ads are often placed at natural transition points of the user's experince, such as moving from one page to the next. These ads are generally center aligned overlaying user content. +Interstitial ads are often placed at natural transition points of the user's experience, such as moving from one page to the next. These ads are generally center-aligned overlaying user content. This document covers how to setup interstitial ad units. {: .alert.alert-warning :} -Please check with each of your bidders to ensure they're reading the interstitial flag from the standard Prebid location. +Please check with each of this AdUnit's bidders to ensure they're reading the interstitial flag from the standard Prebid location. +If the bidder doesn't specifically support interstitials, results may be unexpected. ## How It Works -The intended flow for publishers is the following: -- Publisher traffics interstitial line item with appropriate size(s) ([GAM example](https://support.google.com/admanager/answer/9840201?hl=en)) +The flow for publishers is the following: +- Publisher traffics an interstitial line item with appropriate size(s) ([GAM example](https://support.google.com/admanager/answer/9840201?hl=en)) - Publisher defines ad server interstitial slot on the page ([GAM Example](https://developers.google.com/publisher-tag/samples/display-web-interstitial-ad)) -- Publisher defines the appropriate interstitial ad sizes within appriate adUnit.mediaType and supplies the adUnit Interstitial flag within the [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#adUnit-interstitial-example) config +- Publisher creates a PBJS AdUnit and defines the appropriate interstitial ad sizes, adUnit.mediaType, and a special interstitial flag +- Publisher adds bidders and parameters that support interstitials to the PBJS AdUnit(s) - Prebid requests bids for interstitial adUnits and invokes the ad server call from the requestBids callback ## Ad Sizes -Publishers are intended to set the desired size in the respective adUnit. +Publishers must set the desired size in the respective adUnit. The below sizes are specials sizes to indicate the ad will be full screen for mobile or tablet devices: - 320x480: Fullscreen mobile phone portrait ad @@ -40,7 +42,6 @@ The below sizes are specials sizes to indicate the ad will be full screen for mo The Prebid Interstitial flag reflects the OpenRTB standard, specifying it at the imp level. - ### Supplying Interstitial Flag If an attribute is specific to an AdUnit, it can be passed this way: @@ -54,9 +55,11 @@ pbjs.addAdUnits({ } }, ortb2Imp: { - intl:1 + instl:1 }, - ... + bids: [ + ... bidders that support interstitials ... + ] }); {% endhighlight %} @@ -64,7 +67,7 @@ pbjs.addAdUnits({ ## How Bid Adapters Should Read Interstitial Flag -To access global data, a Prebid.js bid adapter needs only to retrive the interstitial flag from the adUnit like this: +To access global data, a Prebid.js bid adapter needs only to retrieve the interstitial flag from the adUnit like this: {% highlight js %} utils.deepAccess(bidRequest.ortb2Imp, 'instl') diff --git a/features/adServerKvps.md b/features/adServerKvps.md new file mode 100644 index 0000000000..0db05e0539 --- /dev/null +++ b/features/adServerKvps.md @@ -0,0 +1,243 @@ +--- +layout: page_v2 +title: Prebid.js and Ad Server Key Values +description: Prebid.js and Ad Server Key Values +sidebarType: 1 +--- + +# Prebid.js and Ad Server Key Values +{: .no_toc} + +* TOC +{:toc} + + +The point of header bidding is to supply bids into the regular ad server calls. +Prebid.js provides many ways to do this. This document describes the +controls for obtaining auction results. + +## Overview + +Here's the general way PBJS is integrated into the page: +1. Define AdUnits so they can be linked to existing ad server ad slots in the page +1. Set auction parameters +1. Initiate the auction +1. Gather bid responses to send to the ad server +1. The ad server makes the final decision about which ad to render + +This last step has historically been called "targeting" in Prebid.js, but really what's +sent to the adserver is a set of Key Value Pairs (KVPs) that serve several purposes: +- **Ad server line item targeting**. These values are used to pick out which line items match the request. Generally targets depend on the hb_pb attribute, but could also include hb_deal and hb_format. +- **Display**. Some of these values are needed for rendering the creative properly when the Prebid line item is chosen, including hb_adid, hb_uuid, hb_size, and for AMP/app hb_cache_host. +- **Reporting**. Some publishers rely on ad server key-values for important business reporting. The keys used for reporting could be any of the above, along with hb_source. + +## Decide How The Results Will Be Used + +How a publisher should configure Prebid.js to report auction results +will depend on how the final ad decision will be made. These approaches +need to be in sync. + +There are four main scenarios that follow. + +### Ad Server Line Items are Created Per-Bidder + +In order to have header bidding compete with direct-sold demand, +a publisher can set up placeholder line items in their ad server. + +Prebid.org recommends setting up separate line items +for each bidder. Benefits: +- use ad server reporting to get a view of which bidders are performing well +- control ad decisions with the ad server +- video bids have a fallback available + +There are more details on this scenario in the [Ad Ops section](/adops/before-you-start.html#one-set-of-line-items-for-each-bidder). + +Once implemented in the ad server, setting this up in Prebid.js is +simple, as it is the default [Send All Bids](#send-all-kvps) mode. However +to limit the number of values sent to the ad server, some flavor of +this solution like the [Top Two Bids and Deals](#top-two-bids-and-deals) +may be of interest. + +{: .alert.alert-info :} +Note that `enableSendAllBids` mode can send a lot of keys to your +ad server. Though we recommend this setting, we also recommend that +publishers monitor the key traffic and [control](#controls) as necessary. + +### Only One Set of Ad Server Line Items are Created + +However, there are reasons a publisher may not want to create +separate line items for each bidder: +- some ad servers have a limit on how many line items can be created +- it takes work to set up line items +- the volume of key-value pairs can be a factor + +So the other ad-server based solution is to create one set of line +items that is used by all bidders. + +Setting this mode up in Prebid.js is done by setting [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids) +to false. See the [Bare Minimum solution](#the-bare-minimum-for-display-ads) for reference. + +### Post-Bid + +Sometimes Prebid.js is used as a fallback. This mode is called [PostBid](/overview/what-is-post-bid.html) + +In this scenario, the ad server line item is scheduled as a low-priority 'remnant' and the auction takes place when there's nothing else to serve. +The Prebid.js code is in the ad server creative, which decides the overall winner itself. See the [Post Bid Example](/dev-docs/examples/postbid.html). + +### No Ad Server + +Finally, a publisher may want a particular ad unit to be programmatic-only, which Prebid.js can support. +Please see the [No Ad Server Example](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/noadserver/basic_noadserver.html). + +## Obtaining Auction Results + +### Display and Native + +In early versions of Prebid.js, there were a couple of basic functions +publishers could use to get the auction results: + +- [pbjs.setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) - matches Google Publisher Toolkit ad slots to Prebid.js AdUnits, obtains the auction results for that adunit, and adds "targeting" values using GPT-provided functions. +- [pbjs.getAdserverTargeting](/dev-docs/publisher-api-reference/getAdserverTargeting.html) - a more generic interface for obtaining KVPs + +All of the other functions available in the [publisher API](/dev-docs/publisher-api-reference.html) for obtaining auction bids came later. + +When there are a lot of adunits and bidders on a page, the number of KVPs being sent +to the ad server can grow pretty large, so it quickly became apparent that many options were needed for controlling which KVPs these functions returned. + +Note that in old versions of Prebid.js, native ad components were passed via ad server KVPs. +That approach has been deprecated -- all implementations should now use [one of the recommended approaches for native](/prebid/native-implementation.html). + +### Video + +Video's always been a different implementation than banners because +it's the video player that controls the ad call, not in-page javascript like +the GPT library. So the [Google Ad Manager Video module](/dev-docs/modules/dfp_video.html) includes the [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.html) function. + +Publishers using other ad servers need to integrate on their own +using the [pbjs.getAdserverTargetingForAdUnitCode](/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCode.html) function to build whatever +needed to pass to the video player. + +### Mobile App + +The Prebid SDK does not have a direct way to control what key-value pairs will +be generated by Prebid Server. Instead, the [top-level stored request](/prebid-server/features/pbs-storedreqs.html) stored in Prebid Server defines what should be produced. + +That stored request will contain the 'targeting' options needed to +match the line item setup. See the [Prebid-Server-based +targeting configuration](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#ad-server-targeting), for more detail. The rest of this document is about Prebid.js. + +## Controls + +Over the years, quite a few options have been added to to Prebid.js to adjust the number of bids and the exact set of KVPs sent to the ad server. This is an overlapping-but-powerful set of controls. There are often + +multiple ways to implement the same requirements, and there's no "wrong" +way to do it. + +The list is ordered by those functions that Prebid recommends starting with: + +1. [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids) - the grandaddy of targeting options. If false, only the winning set of KVPs will be sent. We recommend leaving this to the default value of true so that all bidders are represented in the final decision and for detailed reporting in the ad server, but setting it to false (aka "Send Top Bid" mode) is the most dramatic way to minimize what's sent to the ad server. +1. [targetingControls.alwaysIncludeDeals](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - this option makes sure that deals are sent along even if another control would have suppressed it. Publishers running deals should set this value to true. +1. [sendBidsControl.bidLimit](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-Bids-Control) - this option sorts the bids in CPM order and returns the top N, plus any deals if the 'alwaysIncludeDeals' flag is true. +1. [targetingControls.allowTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - this resets the default keys defined by Prebid.js, defining which KVPs are sent for the winning set. (e.g. hb_pb) +1. [targetingControls.allowSendAllBidsTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - similar to allowTargetingKeys but works on the bidder-specific KVPs. (e.g. hb_pb_BIDDER) +1. [bidderSettings.standard.adserverTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - completely redefine what Prebid produces for the winning bid's KVPs. +1. [bidderSettings.standard.sendStandardTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - turn off the sending of the standard winning KVPs +1. [bidderSettings.BIDDER.adserverTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - completely redefine what Prebid produces for the bidder-specific KVPs. +1. [bidderSettings.BIDDER.sendStandardTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - turn off the sending of the standard bidder-specific KVPs +1. [targetingControls.addTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - This is similar to allowTargetingKeys but adds KVPs to the default set rather than replacing them. +1. [targetingControls.auctionKeyMaxChars](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - This limits the number of characters Prebid is allowed to add to the KVPs. The function will count the number of characters used and will limit to the integer number of bids that won't exceed this count. +1. [sendBidsControl.dealPrioritization](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-Bids-Control) - This changes the sort order used by 'bidLimit' to put deals first. It's not useful when alwaysIncludeDeals is specified. + +### Examples + +Here are a few scenarios to give you a sense of the configurability. + +#### Send All KVPs + +If the number of KVPs sent to the ad server is not a concern, then the recommended approach is to Send All Bids and all deals: + +``` +pbjs.setConfig({ + enableSendAllBids: true, + targetingControls: { + alwaysIncludeDeals: true + } +}); +``` + +#### The Bare Minimum for Display Ads + +The opposite approach is to send only the winning set of KVPs directly needed for targeting line items and rendering. + +``` +pbjs.setConfig({ + enableSendAllBids: false, + targetingControls: { + allowTargetingKeys: ['PRICE_BUCKET', 'AD_ID', 'SIZE'] + } +}); +``` + +Note: this example lacks video support, deal support, and doesn't even tell you which bidder won. + +#### Top Two Bids and Deals + +``` +pbjs.setConfig({ + sendBidsControl: { bidLimit: 2 }, + targetingControls: { + alwaysIncludeDeals: true, + allowTargetingKeys: ['BIDDER', 'AD_ID', + 'PRICE_BUCKET', 'SIZE', 'UUID', 'FORMAT', 'DEAL'], + allowSendAllBidsTargetingKeys: ['AD_ID', 'PRICE_BUCKET', 'SIZE', + 'FORMAT', 'DEAL'] + } +}); +``` +Notes: +- this assumes that video creatives are set up refering to HB_UUID rather than bidder-specific UUID values. + +#### Completely Custom KVPs + +Publishers that don't want to use KVPs prefixed with "hb_" can change them with +bidderSettings: + +``` +pbjs.setConfig({ + enableSendAllBids: false +}); +pbjs.bidderSettings={ + standard: { + adserverTargeting: [{ + key: "pb_price", + // note the price granularity assumption below is Medium Granularity + // other options are pbAg (auto), pbCg (custom), pbDg (dense), + // pbHg (high), pbLg (low) + val: function(bidResponse) { return bidResponse.pbMg; } + },{ + key: "pb_size", + val: function(bidResponse) { return bidResponse.size; } + },{ + key: "pb_adid", + val: function(bidResponse) { return bidResponse.adId; } + },{ + key: "pb_uuid", + val: function(bidResponse) { return bidResponse.videoCacheKey; } + },{ + key: "pb_format", + val: function(bidResponse) { return bidResponse.mediaType; } + },{ + key: "pb_bidder", + val: function(bidResponse) { return bidResponse.bidder; } + },{ + key: "pb_deal", + val: function(bidResponse) { return bidResponse.dealId; } + }] + } +}; +``` + +## Related Topics + +- [Prebid.js Publisher API setConfig() routine](/dev-docs/publisher-api-reference/setConfig.html) +- [Ad Ops and Prebid](/adops/before-you-start.html) diff --git a/features/firstPartyData.md b/features/firstPartyData.md index 8d25d5c329..79fb7fdd50 100644 --- a/features/firstPartyData.md +++ b/features/firstPartyData.md @@ -31,9 +31,10 @@ which can be used for more than just First Party Data. Publishers supply First Party Data (FPD) by specifying attributes as configuration or on a Prebid.js AdUnit: -- Global site or user data that applies to all AdUnits and all bidders. Use [`setConfig()`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd) -- AdUnit-specific data that applies to all bidders. Define [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#first-party-data) -- Bidder-specific site or user data that applies to all AdUnits. Use [`setBidderConfig()`](/dev-docs/publisher-api-reference/setBidderConfig.html) +- Global site or user data that applies to all AdUnits, bidders, and auctions. Use [`setConfig()`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd) +- Auction-specific site or user data that applies to all AdUnits and bidders in that auction. Use the `ortb2` parameter of [`requestBids()`](/dev-docs/publisher-api-reference/requestBids.html) +- AdUnit-specific data that applies to all bidders and auctions. Define [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#first-party-data) +- Bidder-specific site or user data that applies to all AdUnits and auctions. Use [`setBidderConfig()`](/dev-docs/publisher-api-reference/setBidderConfig.html) ## In-Page Examples @@ -63,7 +64,10 @@ pbjs.setConfig({ userrating: "4", data: [{ name: "www.dataprovider1.com", - ext: { "segtax": 1 }, + ext: { + segtax: 7, + cids: [ "iris_c73g5jq96mwso4d8" ] + }, segment: [ { id: "687" }, { id: "123" } @@ -83,7 +87,7 @@ pbjs.setConfig({ keywords: "a,b", data: [{ name: "dataprovider.com", - ext: { segtax: 3 }, + ext: { segtax: 4 }, segment: [ { id: "1" } ] @@ -107,6 +111,36 @@ of user data as part of its GDPR or CCPA modules. {: .alert.alert-warning :} If you're using PBJS version 4.29 or before, replace the following in the example above: 'ortb' with 'fpd', 'site' with 'context' and 'site.ext.data' with 'context.data'. +### Supplying Auction-Specific Data + +In some situations the same page may wish to supply different `site` data for some of its sections, +for example in infinite scroll or instream video scenarios where multiple pieces of content that would benefit from different contexts are served together. + +To support this use case, Prebid version 7 and above accepts auction-specific first-party data as a parameter to `requestBids`. For example: + +{% highlight js %} +pbjs.requestBids({ + ortb2: { + site: { + content: { + data: [{ + name: 'www.iris.com', + ext: { + segtax: 500, + cids: ['iris_c73g5jq96mwso4d8'] + }, + segment: [ + {id: '687'}, + {id: '123'} + ] + }] + } + } + } +}); +{% endhighlight %} + + ### Supplying AdUnit-Specific Data If an attribute is specific to an AdUnit, it can be passed this way: @@ -177,6 +211,82 @@ pbjs.setBidderConfig({ // different bidders can receive different data }); {% endhighlight %} +### Supplying App Content Data + +Occasionally, an app which embeds a webview might run Prebid.js. In this case, the app object is often specified for OpenRTB, and the site object would be invalid. When this happens, one should specify app.content.data in place of site.content.data. + +{% highlight js %} +pbjs.setConfig({ + ortb2: { + app: { + name: "myappname", + keywords: "power tools, drills", + content: { + data: [ + { + name: "www.dataprovider1.com", + ext: { + segtax: 6 + }, + segment: [ + { + id: "687" + }, + { + id: "123" + } + ] + }, + { + name: "www.dataprovider1.com", + ext: { + segtax: 7 + }, + segment: [ + { + id: "456" + }, + { + id: "789" + } + ] + } + ] + } + } + } +) + +{% endhighlight %} + +### Supplying OpenRTB Content Data +OpenRTB `content` object describes specific (mostly audio/video) content information, and it is useful for targeting. +For website ad, the content object should be defined in `ortb2.site.content`, for non-browser ad, it should be defined in `ortb2.app.content` + +{% highlight js %} +pbjs.setConfig({ + ortb2: { + site: { + content: { + id: "some_id", + episode: "1", + title: "some title", + series: "some series", + season: "s1", + artist: "John Doe", + genre: "some genre", + isrc: "CC-XXX-YY-NNNNN", + url: "http://foo_url.de", + cat: ["IAB1-1", "IAB1-2", "IAB2-10"], + context: "7", + keywords: ["k1", "k2"], + live: "0" + } + } + } +}); +{% endhighlight %} + ## Segments and Taxonomy The [IAB](https://iab.com) offers standard content and audience taxonomies for categorizing sites and users. Prebid supports defining these values as first party data in `site.content.data` or `user.data` as shown in the examples above. @@ -188,7 +298,7 @@ Segment support is still under development. You can follow the [Prebid.js discus user: { data: [{ name: "dataprovider.com", // who resolved the segments - ext: { segtax: 3 }, // taxonomy used to encode the segments + ext: { segtax: 4 }, // taxonomy used to encode the segments segment: [ { id: "1" } ] @@ -204,20 +314,22 @@ here to their page. For now, here's the beta table defining the segtax values: {: .table .table-bordered .table-striped } | Segtax ID | Taxonomy Type | Version | Description | |-----------+---------------+---------+-------------| -| 1 | Content | 2.1 | [IAB - Content Taxonomy version 2.1](https://iabtechlab.com/wp-content/uploads/2020/07/IABTL-Content-Taxonomy-2.1-Final.xlsx) | -| 2 | Content | 2.2 | [IAB - Content Taxonomy version 2.2](https://iabtechlab.com/wp-content/uploads/2020/12/IABTechLab_Content_Taxonomy_2-2_Final.xlsx) | -| 3 | Audience | 1.1 | [IAB - Audience Taxonomy version 1.1](https://iabtechlab.com/wp-content/uploads/2020/07/IABTL-Audience-Taxonomy-1.1-Final.xlsx) | +| 1 | Content | 1.x | IAB - Content Taxonomy version 1 | +| 2 | Content | 2.x | [IAB - Content Taxonomy version 2](https://iabtechlab.com/wp-content/uploads/2020/12/IABTechLab_Content_Taxonomy_2-2_Final.xlsx) | +| 4 | Audience | 1.1 | [IAB - Audience Taxonomy version 1.1](https://iabtechlab.com/wp-content/uploads/2020/07/IABTL-Audience-Taxonomy-1.1-Final.xlsx) | {: .alert.alert-info :} -Publishers need to check with their SSPs and DSPs to confirm which +The [IAB version of this table](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--category-taxonomies-) is associated with ADCOM. Publishers should check with their SSPs and DSPs to confirm which segment taxonomies they support. ## How Bid Adapters Should Read First Party Data -To access global data, a Prebid.js bid adapter needs only to call [`getConfig()`](/dev-docs/publisher-api-reference/getConfig.html), like this: +Prebid.js bid adapters are supplied global data in the `ortb2` property of [bid requests](/dev-docs/bidder-adaptor.html#building-the-request): {% highlight js %} -config.getConfig('ortb2')) +buildRequests: function(validBidRequests, bidderRequest) { + const firstPartyData = bidderRequest.ortb2; +} {% endhighlight %} AdUnit-specific values must be parsed out of the AdUnit object. diff --git a/features/pbAdSlot.md b/features/pbAdSlot.md index 05478a0f76..8da35d6380 100644 --- a/features/pbAdSlot.md +++ b/features/pbAdSlot.md @@ -1,114 +1,151 @@ --- layout: page_v2 -title: Prebid Ad Slot -description: The Prebid Ad Slot +title: Prebid Ad Slot and GPID +description: Prebid Ad Slot and GPID sidebarType: 1 --- -# Prebid Ad Slot +# The Prebid Ad Slot and the GPID +{:.no_toc} -The Prebid AdUnit 'code' is a mixed attribute that's generally either the GPT slot name or the HTML div ID. The undecided nature of the 'code' makes it harder to utilize for reporting and auction targeting. +* TOC +{:toc} -The `Prebid Ad Slot` is an optional inventory management convention allowing publishers to supply a descriptive and stable label for each ad on the page. This makes it possible to have more granular reporting and better deal targeting. +Prebid Ad Slot and the Global Placement ID (GPID) are overlapping conventions that allow publishers to identify ad inventory on their pages so bidders and reporting systems can better deal with their sites. + +## Background + +It all starts with how publishers decide to label their ad slots: the places on their pages +where ads can be served. In some ad servers like GAM, these things are called "ad units". +Most publishers use unique ad slot names, but some publishers utilize the same name for every ad slot on their page. e.g. "/homepage" might be the name for 5 different slots. + +It's the case of 'same ad slot names' that Prebid Ad Slot and GPID are +meant to address. + +### The Prebid.js AdUnit + +When Prebid.js was developed in 2015, they needed a data structure that would link each ad slot to the bidders and parameters involved in the auction for that slot. Thus was born the Prebid.js [AdUnit](/dev-docs/adunit-reference.html). The AdUnit 'code' is what links this object to the adserver's ad slot. Because some pubs use the same ad slot name everywhere, AdUnit.code is a mixed attribute that can be either the ad slot name **or** the HTML div ID. The undecided nature of AdUnit.code makes it hard to utilize for reporting and auction targeting. + +### The Prebid Ad Slot + +The 'Prebid Ad Slot' was developed in Prebid.js v3 as an optional inventory management convention allowing publishers to supply a descriptive and stable label for each ad on the page. This makes it possible to have more granular reporting and better deal targeting. +However, the PB ad slot is not an industry standard convention, so didn't gain +much traction. + +### The GPID + +The Global Placement ID (GPID) was an initiative in the Fall of 2021 led +by the TradeDesk to solve the problem of inventory identification in an industry-wide way. i.e. Buyers want to be able to identify ad slots in a unique way even +when the publisher uses the same ad slot name multiple times. + +The original suggestion for GPID was to simply append the HTML div element id (aka the 'div-id') to the ad slot name. But some publishers generate div-ids randomly, so the definition of GPID has become: + +``` +imp[].ext.gpid: ADSLOTNAME#UNIQUIFIER +``` +Where ADSLOTNAME is the ad server's slot name (e.g. /1111/homepage) and UNIQUIFIER is something that makes the ADSLOTNAME different from others. Normally it's a +div-id, but if div-ids are random, it can be something else. The "#UNIQUIFIER" is only required if the ADSLOTNAME isn't unique enough on its own. {: .alert.alert-info :} -The Prebid Ad Slot was introduced with Prebid.js 3.x. +The Prebid Ad Slot didn't ever get broad adoption, so it's likely that +someday we'll deprecate it in favor of the more standard GPID. -## A Scenario +## Defining Prebid Ad Slot and GPID -1. The publisher utilizes the same 'slotname' in the page for multiple holes-in-the-page, differentiating in the ad server by size. e.g. -- defineSlot('/1111/homepage', [[300,250]], 'div-293rj893p9wje9we9fj'); -- defineSlot('/1111/homepage', [[728,90]], 'div-j98s9u9usj987665da'); -- defineSlot('/1111/homepage', [[160,600]], 'div-B2q3s4gseshekhsei9sh'); -2. In order to be able to display the right ad in the right hole, the Prebid AdUnit therefore sets the 'code' to the div ID instead of the slotname. -3. The div ID in this case is a random number, not very useful for reporting. -4. Therefore, to get a stable ID that's useful from a business perspective to identify a hole-in-the-page, the publisher -decides to add another identifier... the Prebid Ad Slot. -5. The publisher adds a function to the page that annotates each Prebid AdUnit in the auction with the `pbadslot`. -6. Participating bid adapters read the `pbadslot` and can target deals to them. -7. Participating analytics adapters read the `pbadslot` for more granular reporting. - -Example page function: -{% highlight js %} - -// Use adunit.ortb2Imp.ext.data.pbadslot if it exists. Otherwise, if the -// the adunit.code is a div ID, then look for a data-adslotid attribute, then look a matching slot in GPT -// Otherwise, just use the AdUnit.code -var setPbAdSlot = function setPbAdSlot(adUnits) { - // set pbadslot for all ad units - adUnits.forEach(function (adUnit) { - if (!adUnit.ortb2Imp) { - adUnit.ortb2Imp = {} - } - if (!adUnit.ortb2Imp.ext) { - adUnit.ortb2Imp.ext = {}; - } - if (!adUnit.ortb2Imp.ext.data) { - adUnit.ortb2Imp.ext.data = {}; - } - - // use existing pbadslot if it is already set - if (adUnit.ortb2Imp.ext.data.pbadslot) { - return; - } - - // check if AdUnit.code has a div with a matching id value - const adUnitCodeDiv = document.getElementById(adUnit.code); - if (adUnitCodeDiv) { - // try to retrieve a data element from the div called data-adslotid. - if (adUnitCodeDiv.dataset.adslotid) { - adUnit.ortb2Imp.ext.data.pbadslot = adUnitCodeDiv.dataset.adslotid; - return; - } - // Else if AdUnit.code matched a div and it's a banner mediaType and googletag is present - if (adUnit.mediaTypes && typeof adUnit.mediaTypes === 'object' && adUnit.mediaTypes.banner && adUnit.mediaTypes.banner.sizes && window.googletag && googletag.apiReady) { - var gptSlots = googletag.pubads().getSlots(); - // look up the GPT slot name from the div. - var linkedSlot = gptSlots.find(function (gptSlot) { - return (gptSlot.getSlotElementId() === adUnitCodeDiv.id); - }); - if (linkedSlot) { - adUnit.ortbImp.ext.data.pbadaslot = linkedSlot.getAdUnitPath(); - return; - } - } - } - // Else, just use the AdUnit.code, assuming that it's an ad unit slot - adUnit.ortb2Imp.ext.data.pbadslot = adUnit.code; - }); -}; +There are two ways a publisher can inject these values into the header bidding auctions: -pbjs.onEvent('beforeRequestBids', setPbAdSlot); +1. Supply them manually on the PBJS AdUnits +2. Install the [GPT Pre-Auction module](/dev-docs/modules/gpt-pre-auction.html) -{% endhighlight %} +### Defining them on the PBJS Ad Unit -## How It Works +#### Example 1 - unique ad slot names -The Prebid Ad Slot is just a convention -- it's a form of adunit-specific first party data -stored under `adunit.ortb2Imp.ext.data.pbadslot`. -It can be utilized by any code ready to look for it. +In this example, there's no need for the "UNIQUIFIER" string because every ad slot +on the publisher page is already unique. -It's intended to be specified via Prebid.js in one of two ways: +``` +pbjs.addAdUnits({ + code: '/1111/homepage-leftnav', + ortb2Imp: { + ext: { + gpid: "/1111/homepage-leftnav", + data: { + pbadslot: "/1111/homepage-leftnav" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` + +#### Example 2 - duplicate ad slots + +In this example, the publisher's ad slots all have the same name, but at least + the div-ids are unique. + +``` +pbjs.addAdUnits({ + code: 'div-leftnav', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#div-leftnav", + data: { + pbadslot: "/1111/homepage#div-leftnav" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` -1. Either directly on the AdUnit itself -2. Or defined during the run of a function before the auction +#### Example 3 - duplicate ad slots, random div IDs -The function could determine the pbadslot in any way that produces a stable value useful for targeting and reporting. -Some scenarios that could be supported: +In this example, the publisher utilizes the same 'slotname' in the page for multiple holes-in-the-page, differentiating in the ad server by size. They also use random div-ids. e.g. +- defineSlot('/1111/homepage', [[300,250]], 'div-293rj893p9wje9we9fj'); +- defineSlot('/1111/homepage', [[728,90]], 'div-j98s9u9usj987665da'); -- parse a substring of the ad server's slot name -- use a custom div data element ID, else the AdUnit.code -- use the AdUnit.ortb2Imp.ext.data.pbadslot as a default rather than primary -- support a different ad server +``` +pbjs.addAdUnits({ + code: 'div-293rj893p9wje9we9fj', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#300x250", + data: { + pbadslot: "/1111/homepage#300x250" + } + } + }, + mediaTypes: ... + bids: ... +},{ + code: 'div-j98s9u9usj987665da', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#728x90", + data: { + pbadslot: "/1111/homepage#728x90" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` ## Prebid Server -The OpenRTB location for the Prebid Ad Slot is `imp[].ext.data.pbadslot`: +The Prebid Server Bid Adapter just sends the values to the conventional OpenRTB locations: +- Prebid Ad Slot is `imp[].ext.data.pbadslot` +- GPID is `imp[].ext.gpid` + +Mobile and AMP Stored Requests should place the values there as desired. -- The Prebid SDK will place the value there. -- AMP Stored Requests should place the value there if desired. -- Server-side bid and anlytics adapters may be modified to read the value. +Server-side bid and anlytics adapters may be modified to read the value. ## Further Reading -- The [onEvent()](/dev-docs/publisher-api-reference/onEvent.html) function +- [GPT Pre-Auction Module](/dev-docs/modules/gpt-pre-auction.html) +- [Ad Unit Reference](/dev-docs/adunit-reference.html) diff --git a/features/timeouts.md b/features/timeouts.md index aa07e5ddef..d3d592b91b 100644 --- a/features/timeouts.md +++ b/features/timeouts.md @@ -26,7 +26,7 @@ header bidding activities. Determining this value is a delicate balance: too sho may go down due to delaying the ad server call to the point where users have left the page. Publishers must determine the value that works for them, considering a balance of factors: average user time on page, direct sellthrough, value of different ad channels, and average user network delay. -3. **Timout Buffer** - The JavaScript timer environment is not perfectly accurate +3. **Timeout Buffer** - The JavaScript timer environment is not perfectly accurate because competing JavaScript on the page can delay the header bidding auction or the recognition that auction results have returned. By default, Prebid.js adds a 400ms buffer to the Auction Timeout to account for the noisy environment. Publishers can change this default value with the [`timeoutBuffer`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-timeoutBuffer) configuration. diff --git a/formats/native.md b/formats/native.md index aecf26f0a4..fb60092f1e 100644 --- a/formats/native.md +++ b/formats/native.md @@ -10,10 +10,21 @@ sidebarType: 6 # Prebid Native Ads {:.no_toc} -Native ads are supported by Prebid.js for mobile web. Prebid Server support is coming soon. +## Prebid Server + +At a high level, Prebid Server just passes native parameters through to +bid adapters. See [Prebid Server Native](/prebid-server/features/pbs-native.html) for more information. + +## Prebid SDK + +See the separate pages for +- [iOS](/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.html) +- [Android](/prebid-mobile/pbm-api/android/pbm-nativeadunit-android.html) ## Prebid.js +Native ads are supported by Prebid.js for mobile web. + ### Adops - [Setting up Prebid Native in Google Ad Manager](/adops/gam-native.html) diff --git a/guide.md b/guide.md index f397c5a8d5..d358c4d4cc 100644 --- a/guide.md +++ b/guide.md @@ -9,14 +9,32 @@ sidebarType: 0 # Prebid Website Maintenance Guide -v 1.1 -Sept 7, 2019 +v 1.2 +Sept 24, 2021 *** +## Reviewing Pull Requests and Issues + +Being a reviewer means you're in weekly rotation where you keep an eye on pull requests (PRs) and issues opened in this repo. + +### PR Review Guidelines + +1. Make sure no inappropriate changes are made. This covers obvious things like bad language and content, but we also don't allow overt marketing language on the site. Phrases like "we're the best BLAH" or "number one FOOZIT" need to be toned down. +2. Make sure competitors aren't messing with each other's docs. This can be hard to tell because we don't know which github handles belong to which companies, but in general, if a destructive or suspicious change is being made to a doc, check on the Prebid Slack channel to confirm that the affected company approves the change. +3. Make sure the change doesn't break formatting. It's not always necessary to preview locally, but for large changes, it's worthwhile verifying visually because markdown can be cranky. +4. Help the author with basic readability - if you as a reviewer don't understand a sentence, probably others will have trouble too. Push back and ask questions about what they're really trying to say. +5. We don't generally merge a docs PR until the related code is released. Prebid.js releases happen on Weds or Thurs, and people really like to have their docs PRs merged shortly after the code is released. For Prebid Server, it's ok to merge the docs after the code is merged. +6. Fix broken or out-of-date things you run across. At least flag it in the team slack channel so we can fix it someday. +7. Bid Adapter Guidelines + 1. Check the front-matter: required fields are title and either pbjs or pbs. + 2. Every adapter needs a parameters table that contains exactly 5 columns in this order: Name, Scope, Description, Example, Type. + 3. Discourage full-page HTML examples. Better to have just the bidder-specific logic and a pointer to a standard Prebid.js example. + 4. All headers must be level 3, 4, or 5. + ## Core Technologies -The Prebid website is developed using [Jekyll](https://jekyllrb.com/), a static site generator which uses the following technology to create and style HTML pages. +The Prebid website is developed using [GitHub pages](https://pages.github.com/) and [Jekyll](https://jekyllrb.com/), a static site generator which uses the following technology to create and style HTML pages. See the [main README file](https://github.com/prebid/prebid.github.io/blob/master/README.md) for instructions on how to set this up. **Markdown**: The majority of the content is written in Markdown language. Jekyll transform this into raw HTML. @@ -34,11 +52,18 @@ Learn more about [Liquid](https://help.shopify.com/en/themes/liquid/basics) **CSS**: The site builds on the base Bootstrap template with custom CSS stored in the style.css file. -*** +### Environment + +- prebid.org is built with Wordpress. We call it "the marketing site". We generally use a contracting company to make major updates there so it's pretty. But if you know Wordpress, we may give you permissions to do minor updates there. +- docs.prebid.org is the Github pages site. We call it "the docs site". +- dev.prebid.org is served through Netlify from the 'dev' branch of the repo. It's often out of date and only used for major projects or for sharing major docs for external review. +- stage.prebid.org is also served through Netlify, but from the 'staging' branch. You should assume it's out of date. + +On the rare occasions where we need to use the 'dev' or 'stage' sites, we just check with each other to make sure it's not already being used for something. ## Site Config -The _config.yml file (note underscore prefix) sets the base configuration for the site. Refer to [Jekyll](https://jekyllrb.com/docs/configuration/) documentation on which properties can be set in the _congig.yml file. +The _config.yml file (note underscore prefix) sets the base configuration for the site. Refer to [Jekyll](https://jekyllrb.com/docs/configuration/) documentation on which properties can be set in the _config.yml file. *** @@ -75,7 +100,7 @@ The includes directory contains HTML files that can be included within files, su **_bidders** -The bidders directory is not a standard part of Jekyll; it’s a special use directory specifically for the Prebid.org site. The files in this directory are used to construct the table of partners on the partners/partners.html page. +The bidders directory is not a standard part of Jekyll; it’s a special use directory specifically to construct the table of bidders on dev-docs/bidders.md and dev-docs/pbs-bidders.md **_sites** @@ -236,18 +261,14 @@ The attributes in the Jekyll 'front matter' drive various behaviors and dynamic | ----- | ------ | ------ | ------ | | layout | yes | bidder | Links this file to the bidder.html layout | | title | yes | company name | For display | +| pbjs | sorta | true or false | defines whether this is a Prebid.js bidder | +| pbs | sorta | true or false | defines whether this is a Prebid Server bidder | | description | no | - | Not used | -| hide | no | - | Not used | | biddercode | yes | preferred bidder code | Used as the default ad server targeting suffix and the default download filename | | aliasCode | no | download filename | Overrides the filename used to build the PBJS package on the download page | | prevBiddercode | no | secondary bidder code | Adds a note about an alternate code that may have been used. | -| bidder_supports_deals | no | true or false, whether the adapter supports deals | For display. Defaults to 'true'. | -| s2s_only | no | true or false, whether the adapter is server-to-server only | Adds a note to the display. Defaults to 'false'. | -| gdpr_supported | no | true or false, whether the adapter supports GDPR | For display. Defaults to 'false'. | -| coppa_supported | no | true or false, whether the adapter supports COPPA | For display. Defaults to 'false'. | -| media_types | no | comma-separated list of: banner, video, native | For display. | -| userIds | no | comma-separated list of supported user id modules | For display. | -| prebid_member | no | true or false, whether this company is a prebid.org member | For display. | +| pbjs_version_notes | no | string | Displays on the download page | +| ANYTHING ELSE | no | string | There are many pieces of metadata (e.g. GDPR support, user IDs supported) that bid adapters can disclose. They're displayed on the bidder's parameter page. | The bidderCode, aliasCode, and prevBiddercode parameters bear some description. Some adapters have a longer bidderCode and a shorter bidderCode -- their adapter supports both (with the `alias` feature) but diff --git a/identity/prebid-identity.md b/identity/prebid-identity.md new file mode 100644 index 0000000000..d83d63b126 --- /dev/null +++ b/identity/prebid-identity.md @@ -0,0 +1,63 @@ +--- +layout: page_v2 +title: Prebid User Identity +description: What is Prebid User Identity +sidebarType: 9 +--- + +# Prebid User Identity Overview + +Prebid's aim is to enable the protection of user privacy while still supporting publisher's ability to make revenue, +keeping the Open Web healthy. + +To do this, Prebid offers a number of identity-related products that encourage awareness of privacy regulations such as GDPR, CCPA, and COPPA. The most important projects are: + +- [Prebid.js User Identity Module](/dev-docs/modules/userId.html). This module supports more than 20 different flavors of global IDs with different features that publishers can work with. +- [SharedID](/identity/sharedid.html). This native hosted ID offering from Prebid is simple, free, robust, and privacy-minded. +- **Coming soon:** [Unified ID 2.0](https://prebid.org/blog/prebid-org-to-serve-as-operator-of-unified-id-2-0/) + +## Prebid.js and Identity + +Publishers have several ways to include user identity as part of +the header bidding auction: + +1. Install one or more [User ID modules](/dev-docs/modules/userId.html). These modules obtain +the user's ID from the service and make it available to participating bidders. Publishers +can define [permissions](/dev-docs/modules/userId.html#permissions) to control which bidders receive which IDs. +2. Install the [ID Import Module](/dev-docs/modules/idLibrary.html). This module can be +used to generate a map of identities present on the page. +3. Pass [First Party Data](/features/firstPartyData.html), such as interests, to bidders for more relevant advertising. +4. Include [User Syncing](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) to allow bid adapters to establish IDs. Publishers have control over which bidders may sync, which syncing mechanisms are allowed, and when the syncing occurs. Syncing is subject to privacy controls such as GDPR, CCPA, and COPPA. + +## Prebid Server and Identity + +Prebid Server has user sync functionality, allowing server-side bidders to establish +IDs given appropriate permission from the user for setting cookies. + +Prebid Server can receive extended ID arrays (eids) from Prebid.js and provide them to +participating server-side bid adapters. It also supports permissioning to determine +which eids can be sent to which bidders. + +User IDs are not sent to bid adapters in privacy scenarios such as COPPA and +GDPR requests lacking appropriate consent. For more details see [Prebid Server Privacy](/prebid-server/features/pbs-privacy.html). + +## Prebid SDK and Identity + +In application environments, performance-based advertisers rely on a device’s IDFA to target, +frequency cap, and determine attribution, similar to how cookies are used in desktop +environments. However, IDFAs are persistent to the device. Prebid SDK will read the IDFA from +the device when available. Additionally, Prebid SDK supports third party identity IDs. + +Prebid Server will strip the IDFA and/or third party identity IDs when enforcing regulations such as GDPR and CCPA. + +## AMP, Prebid, and Identity + +Prebid Server supports a user [cookie-sync](/prebid-server/developers/pbs-cookie-sync.html) functionality, including integration with +a consent management platform. This allows server-side bidders to establish IDs given +the appropriate cookie-setting permissions from the user. + +## Further Reading + +- [PBJS User ID module](/dev-docs/modules/userId.html) +- [SharedID](/identity/sharedid.html) +- [Prebid Server Privacy](/prebid-server/features/pbs-privacy.html) diff --git a/identity/sharedid.md b/identity/sharedid.md new file mode 100644 index 0000000000..be8913d04a --- /dev/null +++ b/identity/sharedid.md @@ -0,0 +1,376 @@ +--- +layout: page_v2 +title: SharedID +description: What is SharedID +sidebarType: 9 +--- + +# Prebid SharedID +{: .no_toc} + +* TOC +{:toc} + +{: .alert.alert-warning :} +As of Prebid.js 5.0, PubCommon ID is no longer supported -- it's been merged into SharedId. Also, SharedId no longer syncs to sharedid.org like it did in Prebid.js 4.x. + +## What is it? + +SharedId is a convenient Prebid-owned first party identifier within the [Prebid UserId Module framework](/dev-docs/modules/userId.html). + +There are multiple ways to integrate SharedId on your site. See the table below for a breakout of options, and the rest of this document for detailed integration instructions. + +{: .table .table-bordered .table-striped } +| Implementation | Description | Cookie Lifetime | Safari Cookie Lifetime | Technical Difficulty | Revenue Benefit | +| --- | --- | --- | --- | --- | --- | +| 3rd Party Cookie Only | No first party cookie solution. | Some Blocked | Blocked | None | Low | +| User Id Submodule | Including User Id Module in your Prebid.js installation. | 365 days | 7 days | Basic | Good | +| PubCID Script | Adding the legacy PubCID script; not maintained by Prebid.org. | 365 days | 7 days | High | Varies | +| SharedId First Party Endpoint | Writing a first party cookie from your web server code. | 365 days | 365 days | Intermediate | Best | + +## How does the Prebid UserId Module implementation work? + +The SharedID ID system sets a user id cookie in the publisher’s domain. +Since the cookie is set in the publisher's first party domain it does not fall in scope of browser restrictions on third party cookies. Safari has restrictions on first party cookies set via document.cookie. For this reason we recommend considering a server endpoint installation for maximum effect. See the "Alternate Implementations" section below. + +### Prebid.js 5.x + +The SharedId module reads and/or sets a random ID in +the cookie name defined by the publisher when initializing +the module: + +Example 1: client-side cookie setting +``` +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'sharedId', //"pubCommonId" as a name is supported for backwards compatibility, + storage: { + name: '_sharedID', // name of the 1st party cookie, _pubcid is supported for backwards compatibility + type: 'cookie', + expires: 30 + } + }] + } +}); +``` + +Example 2: setting the cookie with a first party endpoint +``` +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'sharedId', //"pubCommonId" as a name is supported for backwards compatibility, + params: { + pixelUrl: "/wp-json/pubcid/v1/extend/" // this parameter identifies your server-side endpoint that will set a first party cookie' + }, + storage: { + name: '_sharedID', // name of the 1st party cookie, _pubcid is supported for backwards compatibility + type: 'cookie', + expires: 30 + } + }] + } +}); +``` + +The 'source' value transmitted through OpenRTB (user.ext.eids) is pubcid.org. For example: +``` +user: { + ext: { + eids: { + "source":"pubcid.org", + "uids":[ + { + "id":"01EAJWWNEPN3CYMM5N8M5VXY22", + "atype":1 + } + ] + } + } +} +``` + +{: .alert.alert-info :} +The 'pubcid.org' EID source was adopted by more buyers than 'sharedid.org', so +when PubCommon was folded into SharedID, we kept the more commonly recognized +source value. + +### Before Prebid.js 5.0 + +In addition to setting a first party cookie, SharedId in Prebid.js 4.x also sets a third party cookie where possible, syncing the first and third party cookies (subject to browser capability and user opt-out). + +SharedId in Prebid.js 4.x was transmitted through the header-bidding ecosystem on user.ext.eids with a different 'source': +``` +user: { + ext: { + eids: { + "source":"sharedid.org", + "uids":[ + { + "id":"01EAJWWNEPN3CYMM5N8M5VXY22", + "atype":1, + "ext":{ + "third":"01EAJWWNEPN3CYMM5N8M5VXY22" + } + } + ] + } + } +} +``` + +### Detailed Walkthrough + +This diagram summarizes the workflow for SharedId: + +![SharedId](/assets/images/sharedid5.png){: .pb-lg-img :} + +1. The page loads the Prebid.js package, which includes the SharedId module. +2. The page enables one or more user ID modules with pbjs.setConfig({usersync}) per the module documentation. The publisher can control which bidders are allowed to receive each type of ID. +3. If permitted, the SharedId module retrieves and/or sets the designated first party cookie for this user. +4. When a header bidding auction is run, the ID modules are invoked to add their IDs into the bid requests. +5. Bid adapters send the additional IDs to the bidding endpoints, along with other privacy information such as GDPR consent, US Privacy consent, and the Global Privacy Control header. +6. SharedId is used by the bidder for ad targeting, frequency capping, and/or sequential ads. +7. Bids are sent to the publisher's ad server, where the best ad is chosen for rendering. + +{: .alert.alert-info :} +In Prebid.js 4.x, when SharedId performed third-party syncing there +was an extra step in the diagram between steps 3 and 4 where the module would connect to a server on sharedid.org. This step was +removed in Prebid.js 5.0. + +### Privacy Discussion + +There are several privacy scenarios in which a user ID is not created or read: + +1. The User ID module suppresses all cookie reading and setting activity +when the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) is in place and there's no consent for Purpose 1. +2. The User ID module infrastructure supports a first-party opt-out, by setting the `_pbjs_id_optout` cookie or local storage to any value. No other cookies will be set if this one is set. +3. The SharedId module will suppress the ID when the COPPA flag is set. + +For all other privacy-sensitive scenarios, it is encumbent upon bid adapters and endpoints +to be aware of and enforce relevant regulations such as CCPA and Global Privacy Control. + +## Opt-Out + +Prebid recommends that publishers provide their users with information about how IDs are utilized, including targeting, frequency capping, and special ad features like sequential ads. + +If the publisher's legal staff has determined that a user opt-out is necessary beyond existing +mechanisms like GDPR and CCPA, the use of first party cookies requires that opt-out flow be owned +by the publisher. + +Publishers that decide to build a first-party opt-out workflow might follow a process like this: +- User is presented with an option to turn off ad targeting +- If the user opts out, the page can do one of two things: + - set a `_pbjs_id_optout` first party cookie + - avoid calling pbjs.setConfig to initialize the user ID modules + +## Alternative Implementations + +For those not using Prebid's header bidding solution, SharedId can deployed via in inline script reference or from a web server. + +### SharedId Script + +For those interested in implementing SharedId without prebid.js. +1. Clone the [SharedId script repository](https://github.com/prebid/Shared-id-v2) +2. Implement the pubcid.js script on the desired page by following the build instructions in the [readme.md](https://github.com/prebid/Shared-id-v2#readme) + +Prebid also recommends implementing a method where users can easily opt-out of targeted advertising. Please refer to the User Opt-Out section located at the bottom of this page. + +If there are no custom configurations, then just include the script and it'll use the default values. + +``` + +``` + +If custom configurations are needed, define the pubcid_options object before inclusion of the script. Below is an example to switch from using local storage to cookie: + +``` + + +``` + +#### Configuration + +Below are the available configuration options for the PubCID script. + +{: .table .table-bordered .table-striped } +| Parameter Name | Type | Description | | Example | +| --- | --- | --- | --- | --- | +| create | boolean | If true, then an id is created automatically by the script if it's missing. Default is true. If your server has a component that generates the id instead, then this should be set to false | | `true` | +| expInterval | decimal | Expiration interval in minutes. Default is 525600, or 1 year | | `525600` | +| extend | boolean | If true, the the expiration time is automatically extended whenever the script is executed even if the id exists already. Default is true. If false, then the id expires from the time it was initially created. | For publisher server support only. If true, the publisher's server will create the (pubcid) cookie. Default is true. | `true` | +| pixelUrl | string (optional) | For publisher server support only. Where to call out to for a server cookie. | | `/wp-json/pubcid/v1/extend/` +| type | string | Type of storage. It's possible to specify one of the following: 'html5', 'cookie'. Default is 'html5' priority, aka local storage, and fall back to cookie if local storage is unavailable. | If true, the expiration time of the stored IDs will be refreshed during each page load. Default is false. | `cookie` | + +#### Example Configurations + +Always use cookies and create an ID that expires in 30 days after creation. + +``` +{ + type: 'cookie', + extend: false, + expInterval: 43200 +} +``` + +Using a SharedId Endpoint implementation, create the cookie once, which will be allowed to expire before it is created again. + +``` +{ + type: 'cookie', + pixelUrl: '/wp-json/pubcid/v1/extend/', + create: false, + extend: false +} + +``` + +### SharedId First Party Endpoint + +Add server-side support for SharedId to better handle the ever-increasing restrictions on cookies in modern web browsers by having the SharedId first party cookie written and extended by your web server. + +#### CMS + +PubCID/SharedId plugins are available for Wordpress and Drupal. Because the CMS can cache pages to improve scalability, it's impractical to set unique cookies during page generation. Instead these plugins require a dynamic endpoint that serves back a blank pixel along with a unique cookie value. The client side script needs one additional parameter for this URL. Please consult the corresponding plugin documents for default values: + +1. Wordpress : Install directly from the [Wordpress admin page](https://wordpress.org/plugins/publisher-common-id/). Install from [GITHUB](https://github.com/prebid/sharedid-wordpress) +2. Drupal : Install from [Github](https://github.com/prebid/sharedid-drupal). + +#### Endpoint Implementations + +The Wordpress and Drupal plugins require that the host company integrate a new endpoint into their webserver that can receive request from the page and set a unique cookie. +Below are some examples for how to implement this function in various languages or platforms. It is up to the site owner to integrate an appropriate script for their specific scenario. + +##### JAVA +```JAVA +public class PubCid { + private static final String pubcidCookieName = "_pubcid"; + private static final int expireTime = (int) TimeUnit.DAYS.toSeconds(365); //store cookie for 1 year + + /** + * Returns the pubcid cookie found in the user's list of cookies. + * Always update the expire time to another year so that the cookie persists. + * + * @param cookies User's list of cookies + * @return the pubcid cookie if found, null otherwise + */ + public static Cookie getPubcidCookie(Cookie[] cookies) { + + Cookie pubcidCookie = fetchPubcidCookie(cookies); + if (pubcidCookie != null) + pubcidCookie.setMaxAge(expireTime); + + return pubcidCookie; + } + + /** + * Simple function to test if the user has a pubcid cookie + * + * @param cookies User's list of cookies + * @return true if the cookie is found, false otherwise + */ + public static boolean hasPubcidCookie(Cookie[] cookies) { + return fetchPubcidCookie(cookies) != null; + } + + /** + * Local function to find the pubcid cookie within the user's list of cookie + * + * @param cookies User's list of cookies + * @return pubcid cookie if found, null otherwise + */ + private static Cookie fetchPubcidCookie(Cookie[] cookies) { + if (cookies == null) return null; + return Arrays.stream(cookies) + .filter(e -> e.getName().equals(pubcidCookieName)) + .findFirst() + .orElse(null); + } +} +``` +##### PHP +```PHP +$cookie_name = '_pubcid'; +$cookie_path = '/'; +$max_age = 365; + +$value = NULL; + +// See if the cookie exist already + +if (isset($_COOKIE[$cookie_name ])) + $value = $_COOKIE[$cookie_name]; + +// Obtain site domain if defined +if (defined(COOKIE_DOMAIN)) + $cookie_domain = COOKIE_DOMAIN; +else + $cookie_domain = ""; + +// Update the cookie +if (isset($value)) { + setcookie( + $cookie_name, + $value, + time() + $max_age * DAY_IN_SECONDS, + $cookie_path, + $cookie_domain + ); +} +``` +##### Node.js +```Node +const express = require('express'); +const cookieParser = require('cookie-parser'); +const app = express(); +const port = 3000; + +app.use(cookieParser()); + +app.get('/', function(req, res) { + + // Check for existence of _pubcid cookie + let value = req.cookies['_pubcid']; + + // If pubcid exists, then update its expiration time + if (value) { + res.cookie('_pubcid', value, {domain: '.example.com', path: '/', expires: new Date(Date.now() + 1000*60*60*24*365)}); + } + + res.render('index'); +}); + +app.listen(port, ()=>console.log(`App listening on port ${port}`)); +``` +##### Apache +```Apache +# Add to httpd.conf +# Requires mod_headers and mod_env + +# Capture _pubcid cookie value if available +SetEnvIf Cookie "(^|;\ *)_pubcid=([^;\ ]+)" PUBCID_VALUE=$2 +SetEnvIf Cookie "(^|;\ *)_pubcid=([^;\ ]+)" HAVE_PUBCID=1 + +# Add _pubcid cookie if it exists to the response with 1 year expiration time +Header add Set-Cookie "_pubcid=%{PUBCID_VALUE}e;Domain=.example.com;Path=/;Max-Age=31536000" env=HAVE_PUBCID +``` +##### Nginx +```Nginx +# Add to a location directive + + location /example { + set $pubcid_value $cookie__pubcid; + if ($pubcid_value) { + add_header Set-Cookie "_pubcid=$pubcid_value;Domain=.example.com;Path=/;Max-Age=31536000"; + } + } +``` + +## Related Topics + +- [Prebid Identity Overview](/identity/prebid-identity.html) +- [Prebid.js User ID modules](/dev-docs/modules/userId.html) diff --git a/mix-manifest.json b/mix-manifest.json new file mode 100644 index 0000000000..7e2920e36b --- /dev/null +++ b/mix-manifest.json @@ -0,0 +1,4 @@ +{ + "/assets/css/main-bundle.css": "/assets/css/main-bundle.css", + "/_site/assets/css/main-bundle.css": "/_site/assets/css/main-bundle.css" +} diff --git a/overview/ga-analytics.md b/overview/ga-analytics.md index 004a08a5a9..7f21487364 100644 --- a/overview/ga-analytics.md +++ b/overview/ga-analytics.md @@ -80,14 +80,71 @@ Similar query for bidders' bid CPM: ## How does it work? -Prebid.js has a seamless integration with Google Analytics and Google Spreadsheet, as well as [several other Analytics providers]({{site.baseurl}}/overview/analytics.html). +Prebid.js has a seamless integration with Google Analytics and Google Spreadsheet, as well as [several other Analytics providers](/overview/analytics.html). -1. Prebid.js has a built-in plugin for Google Analytics, i.e. zero development work if your site uses Prebid.js. +1. Prebid.js has a module for Google Analytics. 2. All data are sent as Events to Google Analytics. You can build reports and dashboards there just as you do today with web traffic data. 3. We've also built dashboards and data visualization in Spreadsheet (where all the above diagrams come from). You can copy our demo dashboard and link it to your Google Analytics account in a few minutes! 4. The Spreadsheet dashboard can be scheduled to run every morning (or in other intervals). You can get 7 day revenue lookback, latency/CPM distribution analysis and more every morning! +### Building the Prebid.js Package with GA + +You can build the Google Analytics module into your Prebid package in two ways: + +1. The "Easy Button" - use the handy web-based [Prebid.js Download](/download.html) tool, and check the Google Analytics adapter box along with the other modules and adapters desired. +2. From the command line + +``` +gulp build --modules=googleAnalyticsAdapter, OTHER_MODULES, OTHER_ADAPTERS, ... +``` +### Enabling the GA Adapter in Your Page + +1. First, make sure GA is on your page as directed by Google. Get the 'tracking code' from the GA interface. It will look something like: + +``` + + + +``` + +2. Enable the Prebid.js GA module: + +``` +pbjs.que.push(function() { + pbjs.enableAnalytics({ + provider: 'ga', + options: { + sampling: 0.1, + cpmDistribution: myBucketFunction + } + }); +}); + +// takes a CPM value and returns a string price bucket +var myBucketFunction = function(cpm) { + return cpm <= 1 ? '<= 1$' : '> 1$'; +} +``` + +Here are the options available. None of them are required. + +{: .table .table-bordered .table-striped } +| Option | Type | Example | Notes | +|---+---+---+---| +|global | string | ga | Name of the global analytics object. Default is `ga` | +|trackerName | string | "mytracker" | Use another tracker for prebid events. Default is the default tracker. | +|sampling | float | 0.1 | Choose a value from `0` to `1`, where `0` means 0% and `1` means 100% tracked. | +|enableDistribution | boolean | true | Enables additional events that track load time and cpm distribution by creating buckets for load time and cpm. Default is false. | +|cpmDistribution | function | see example | A function that customizes the buckets for cpm distribution. | +|sendFloors | boolean | true | if set, will include floor data in the eventCategory field and include ad unit code in eventAction field. Defaults to false. | + ## Further Reading -- [Analytics for Prebid]({{site.baseurl}}/overview/analytics.html) (Overview and list of analytics providers) -- [Integrate with the Prebid Analytics API]({{site.baseurl}}/dev-docs/integrate-with-the-prebid-analytics-api.html) (For developers) +- [Analytics for Prebid](/overview/analytics.html) (Overview and list of analytics providers) +- [Integrate with the Prebid Analytics API](/dev-docs/integrate-with-the-prebid-analytics-api.html) (For developers) diff --git a/overview/intro.md b/overview/intro.md index 914e35f5d9..23342c615b 100644 --- a/overview/intro.md +++ b/overview/intro.md @@ -31,7 +31,7 @@ Our flagship product, Prebid.js, is sometimes referred to as simply *Prebid*, bu ### What is Header Bidding? -Header bidding is a response to a fragmented and inefficient process for digital ad display. It is an alternative to the "waterfall" method, in which impressions impressions are offered to one sales channel at a time, moving down an inflexible stack of sources. +Header bidding is a response to a fragmented and inefficient process for digital ad display. It is an alternative to the "waterfall" method, in which impressions are offered to one sales channel at a time, moving down an inflexible stack of sources. With header bidding, the publisher creates a short delay in their ad serving to obtain bids from many SSPs and ad exchanges. In this way, publishers can receive high value bids on their inventory that may be unavailable through their primary ad server and exchange. The returned bids are then passed into the ad server so they can compete with direct demand and the primary ad server's exchange on a level playing field. diff --git a/overview/prebid-management-committees.md b/overview/prebid-management-committees.md index daedc6563a..459d6b1a90 100644 --- a/overview/prebid-management-committees.md +++ b/overview/prebid-management-committees.md @@ -8,118 +8,10 @@ sidebarType: 0 # Project Management Committees {: .no_toc} -Project Management Committees are responsible for the active management of one or more GitHub repositories, which are also identified by resolution of the Board. - -The committees meet periodically to: - -- establish and prioritize roadmap items -- review open issues and pull requests -- discuss policies -- create development plans - -The following sections describe the committees. - -* TOC -{:toc} - -## Prebid.js - -{: .table .table-bordered .table-striped } -| **Scope** | Prebid.js and related repositories | -| **Description** | browser-based header bidding | -| **Chair** | Gareth Glaser (Rubicon Project) | -| **Audience** | Product and Engineers | - -GitHub Repositories: - -+ https://github.com/prebid/prebid.js -+ https://github.com/prebid/Prebid.js-packager -+ https://github.com/prebid/prebid-universal-creative -+ https://github.com/prebid/currency-file-generator -+ https://github.com/prebid/prebid-js-build-generator - - -## Prebid Mobile - -{: .table .table-bordered .table-striped } -| **Scope** | Prebid Mobile SDK | -| **Description** | Mobile-app based header bidding | -| **Chair** | Bryan Szekely (Rubicon Project) | -| **Audience** | Product and Engineers | - -GitHub Repositories: - -+ https://github.com/prebid/prebid-mobile-ios -+ https://github.com/prebid/prebid-mobile-android - - -## Prebid Server - -{: .table .table-bordered .table-striped } -| **Scope** | Prebid Server and Prebid Cache | -| **Description** | Server-side header bidding | -| **Chair** | Bret Gorsline (Rubicon Project) | -| **Audience** | Product and Engineers | - -GitHub Repositories: - -+ https://github.com/prebid/prebid-server -+ https://github.com/prebid/prebid-cache -+ https://github.com/prebid/prebid-server-java -+ https://github.com/prebid/prebid-cache-java - - -## Prebid Tools - -{: .table .table-bordered .table-striped } -| **Scope** | Misc. Tools | -| **Description** | Debugging and Operational Support | -| **Chair** | Asaf Shamly (Browsi) | -| **Audience** | Product, Business, and Engineers | - -GitHub Repositories: - -+ https://github.com/prebid/header-bidder-expert - -## Identity - -{: .table .table-bordered .table-striped } -| **Scope** | User Identification | -| **Description** | Chart Prebid's role in the future of identity on the web and coordinate any implementation efforts | -| **Chair** | Stephanie Layser (NewsCorp) | -| **Audience** | Product, Business, and Engineers | - -GitHub Repositories: - -+ TBD - -## Video Taskforce - -{: .table .table-bordered .table-striped } -| **Scope** | Video | -| **Description** | Define the needs for video header bidding | -| **Chair** | Mike Chowla (Pubmatic) | -| **Format Lead** | Joel Korpi (Xandr) | -| **Audience** | Product, Business, and Engineers | - -## Marketing Taskforce - -{: .table .table-bordered .table-striped } -| **Scope** | Prebid.org events and marketing | -| **Description** | Coordinates Prebid events and press releases | -| **Chair** | Joel Fisher (Rubicon Project) | -| **Audience** | Marketing, Business | - -## Publisher Taskforce - -{: .table .table-bordered .table-striped } -| **Scope** | Publisher-related topics | -| **Description** | Header bidding issues, optimization, strategy, best practices | -| **Chair** | Stephanie Layser (NewsCorp) | -| **Audience** | Business | +This page has moved to [https://prebid.org/project-management-committees/](https://prebid.org/project-management-committees/)! ## Further Reading {: .no_toc} * [What is Prebid.org?](/overview/what-is-prebid-org.html) -* [Prebid.org Membership and Partners](/partners/partners.html) +* [Prebid.org Membership](/partners/partners.html) diff --git a/overview/prebid-universal-creative.md b/overview/prebid-universal-creative.md index 77e1a99d17..29e28e06d2 100644 --- a/overview/prebid-universal-creative.md +++ b/overview/prebid-universal-creative.md @@ -11,40 +11,99 @@ nav_section: intro # Prebid Universal Creative {:.no_toc} -The Prebid Universal Creative makes it easier for publishers to configure Prebid in their ad server. The Prebid Universal Creative provides a single creative configuration that can be used across many formats, platforms, devices, and ad servers. +* TOC +{:toc} -Specifically, you need to use the Universal Creative in these scenarios: +## Overview -- AMP and Prebid SDK (these require loading creatives from cache) -- when you need to support safeframes -- when you need to support native +The Prebid Universal Creative (PUC) is a collection of rendering routines +that can pull a particular ad ID from Prebid's cache and do the right +thing to display it. The scripts are generally entered into the ad server for +when a Prebid ad has won the auction. There are a number of use cases: + +{: .table .table-bordered .table-striped } +| Use Case | PUC file | Alternate Approach | +| --- | --- | --- | +| web banner: iframe | creative.js | [Banner and Outstream Video iframes](#banner-and-outstream-video-iframes) | +| web banner: safeframe | creative.js | [Banner Safeframes](#banner-safeframes) | +| web outstream video: iframe | creative.js | [Banner and Outstream Video iframes](#banner-and-outstream-video-iframes) | +| web outstream video: safeframe | n/a | Outstream renderers each choose where to render differently, but none writes to the safeframe. | +| AMP banner: always safeframe | creative.js | n/a | +| native: iframe | native-render.js | n/a | +| native: safeframe | native-render.js | n/a | + +The Prebid Universal Creative is the simplest approach for publishers to configure Prebid in their ad server. The PUC provides a creative configuration that can be used across several formats, platforms, devices, and ad servers. + +Here are the features of the PUC in various scenarios: + +### What the PUC does for Web iframe Banners/Outstream +1. Simply calls the Prebid.js renderAd function + +### What the PUC does for Web Safeframe Banners +1. Calls PostMessage to get the winning ad from Prebid.js +1. Creates an iframe of the appropriate size and displays the winning ad within it + +### What the PUC does for AMP and Mobile Apps +1. Updates the size of the iframe to the size of the winning ad. +1. Retrieves the body of the creative from Prebid Cache based on the UUID +1. If the 'burl' parameter is present, creates a tracking pixel. Includes special support for triggering the viewable billing url for mobile MRAID creatives. +1. If the 'nurl' parameter is present, creates the appropriate HTML to fire the notice URL. +1. If the 'wurl' parameter is present, creates a tracking pixel. This is needed for [Programmatic Guaranteed](/prebid-server/features/pg/pbs-pg-idx.html) support. +1. Resolves any `${AUCTION_PRICE}` macro in the creative body. + +### What the PUC does for Native +1. Retrieves the native attributes from the winning ad. +1. Coordinates the rendering of the native ad using the template method specified by the publisher. + +## Alternate Approaches + +Some publishers prefer to not load the extra creative.js code at render time +due to a tiny but measurable impact on measurement discrepancies. + +While Prebid recommends the use of creative.js because we regularly add +features and fix bugs, publishers may choose to hardcode the functionality +into their ad server creatives. + +They would do this differently for each of the scenarios below. + +### Alternate method for Banner and Outstream Video iframes If you only ever need to display non-safeframed banner and outstream-video creatives, you may use -the original simple approach of just calling the Prebid.js `renderAd` function directly: +the simple approach of just calling the Prebid.js `renderAd` function directly: ``` ``` -## How to Implement +### Alternate Method for Banner Safeframes + +See the example at [https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html) + +This is basically just part of the PUC that's been isolated to be standalone. + +## More Information ### Google Ad Manager -- [Step by Step Guide to Google Ad Manager Setup]({{site.baseurl}}/adops/step-by-step.html) +- [Step by Step Guide to Google Ad Manager Setup](/adops/step-by-step.html) ### AMP -- Adops: [Setting Up Prebid for AMP in Google Ad Manager]({{site.baseurl}}/adops/setting-up-prebid-for-amp-in-dfp.html) -- Developer: [Show Prebid Ads on AMP Pages]({{site.baseurl}}/dev-docs/show-prebid-ads-on-amp-pages.html) +- Adops: [Setting Up Prebid for AMP in Google Ad Manager](/adops/setting-up-prebid-for-amp-in-dfp.html) +- Developer: [Show Prebid Ads on AMP Pages](/dev-docs/show-prebid-ads-on-amp-pages.html) ### Mobile App -- [Step by Step Line Item Setup for Google Ad Manager]({{site.baseurl}}/prebid-mobile/adops-line-item-setup-dfp.html) -- [Step by Step Line Item Setup for MoPub]({{site.baseurl}}/prebid-mobile/adops-line-item-setup-mopub.html) +- [Step by Step Line Item Setup for Google Ad Manager](/prebid-mobile/adops-line-item-setup-dfp.html) +- [Step by Step Line Item Setup for MoPub](/prebid-mobile/adops-line-item-setup-mopub.html) + +### Native + +- [Setting up Prebid Native in GAM](/adops/gam-native.html) ### AppNexus Publisher Adserver -- [Setting up Prebid with the AppNexus Publisher Ad Server]({{site.baseurl}}/adops/setting-up-prebid-with-the-appnexus-ad-server.html) +- [Setting up Prebid with the AppNexus Publisher Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) ### Other -- [Send All Bids to the Ad Server - Ad Ops Setup]({{site.baseurl}}/adops/send-all-bids-adops.html) +- [Send All Bids to the Ad Server - Ad Ops Setup](/adops/send-all-bids-adops.html) diff --git a/overview/what-is-prebid-org.md b/overview/what-is-prebid-org.md index 46ede93b71..ef0dfef76c 100644 --- a/overview/what-is-prebid-org.md +++ b/overview/what-is-prebid-org.md @@ -27,8 +27,7 @@ We focus on providing value-add to publishers and encourage the industry to depl Prebid takes two approaches to accomplish this: ### Wrapper Code of Conduct -Prebid members must agree to support the [Wrapper Code of Conduct](/wrapper_code_of_conduct.html -). This ensures that all wrapper providers are operating within the same principles. +Prebid members must agree to support the [Wrapper Code of Conduct](https://prebid.org/code-of-conduct/). This ensures that all wrapper providers are operating within the same principles. ### Trademark We support wrappers based on Prebid technology with rights to the **Powered by Prebid** brand. diff --git a/package-lock.json b/package-lock.json index 36437ee5ff..13c6d55aa4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1123,7 +1123,6 @@ "merge-source-map": "^1.1.0", "postcss": "^7.0.14", "postcss-selector-parser": "^6.0.2", - "prettier": "^1.18.2", "source-map": "~0.6.1", "vue-template-es2015-compiler": "^1.9.0" }, @@ -2345,7 +2344,6 @@ "dependencies": { "anymatch": "~3.1.1", "braces": "~3.0.2", - "fsevents": "~2.1.2", "glob-parent": "~5.1.0", "is-binary-path": "~2.1.0", "is-glob": "~4.0.1", @@ -2694,21 +2692,26 @@ } }, "node_modules/browserslist": { - "version": "4.14.5", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.14.5.tgz", - "integrity": "sha512-Z+vsCZIvCBvqLoYkBFTwEYH3v5MCQbsAjp50ERycpOjnPmolg1Gjy4+KaWWpm8QOJt9GHkhdqAl14NpCX73CWA==", + "version": "4.19.3", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.19.3.tgz", + "integrity": "sha512-XK3X4xtKJ+Txj8G5c30B4gsm71s69lqXlkYui4s6EkKxuv49qjYlY6oVd+IFJ73d4YymtM3+djvvt/R/iJwwDg==", "dev": true, "dependencies": { - "caniuse-lite": "^1.0.30001135", - "electron-to-chromium": "^1.3.571", - "escalade": "^3.1.0", - "node-releases": "^1.1.61" + "caniuse-lite": "^1.0.30001312", + "electron-to-chromium": "^1.4.71", + "escalade": "^3.1.1", + "node-releases": "^2.0.2", + "picocolors": "^1.0.0" }, "bin": { "browserslist": "cli.js" }, "engines": { "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" } }, "node_modules/bs-recipes": { @@ -2896,10 +2899,14 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001150", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001150.tgz", - "integrity": "sha512-kiNKvihW0m36UhAFnl7bOAv0i1K1f6wpfVtTF5O5O82XzgtBnb05V0XeV3oZ968vfg2sRNChsHw8ASH2hDfoYQ==", - "dev": true + "version": "1.0.30001312", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001312.tgz", + "integrity": "sha512-Wiz1Psk2MEK0pX3rUzWaunLTZzqS2JYZFzNKqAiJGiuxIjRPLgV6+VDPOg6lQOUxmDwhTlh198JsTTi8Hzw6aQ==", + "dev": true, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + } }, "node_modules/chalk": { "version": "2.4.2", @@ -2933,7 +2940,6 @@ "anymatch": "^2.0.0", "async-each": "^1.0.1", "braces": "^2.3.2", - "fsevents": "^1.2.7", "glob-parent": "^3.1.0", "inherits": "^2.0.3", "is-binary-path": "^1.0.0", @@ -3151,9 +3157,9 @@ "dev": true }, "node_modules/color-string": { - "version": "1.5.4", - "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.5.4.tgz", - "integrity": "sha512-57yF5yt8Xa3czSEW1jfQDE79Idk0+AkN/4KWad6tbdxUmAs3MvjxlWSWD4deYytcRfoZ9nhKyFl1kj5tBvidbw==", + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.9.0.tgz", + "integrity": "sha512-9Mrz2AQLefkH1UvASKj6v6hj/7eWgjnT/cVsR8CumieLoT+g900exWeNogqtweI8dxloXN9BDQTYro1oWu/5CQ==", "dev": true, "dependencies": { "color-name": "^1.0.0", @@ -4250,9 +4256,9 @@ "dev": true }, "node_modules/dns-packet": { - "version": "1.3.1", - "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-1.3.1.tgz", - "integrity": "sha512-0UxfQkMhYAUaZI+xrNZOz/as5KgDU0M/fQ9b6SpkyLbk3GEswDi6PADJVaYJradtRVsRIlF1zLyOodbcTCDzUg==", + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-1.3.4.tgz", + "integrity": "sha512-BQ6F4vycLXBvdrJZ6S3gZewt6rcrks9KBgM9vrhW+knGRqc8uEdT7fuCwloc7nny5xNoMJ17HGH0R/6fpo8ECA==", "dev": true, "dependencies": { "ip": "^1.1.0", @@ -4380,9 +4386,9 @@ "dev": true }, "node_modules/electron-to-chromium": { - "version": "1.3.582", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.3.582.tgz", - "integrity": "sha512-0nCJ7cSqnkMC+kUuPs0YgklFHraWGl/xHqtZWWtOeVtyi+YqkoAOMGuZQad43DscXCQI/yizcTa3u6B5r+BLww==", + "version": "1.4.73", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.73.tgz", + "integrity": "sha512-RlCffXkE/LliqfA5m29+dVDPB2r72y2D2egMMfIy3Le8ODrxjuZNVo4NIC2yPL01N4xb4nZQLwzi6Z5tGIGLnA==", "dev": true }, "node_modules/elliptic": { @@ -4822,9 +4828,9 @@ } }, "node_modules/eventsource": { - "version": "1.0.7", - "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-1.0.7.tgz", - "integrity": "sha512-4Ln17+vVT0k8aWq+t/bF5arcS3EpT9gYtW66EPacdj/mAFevznsnyoHLPy2BA8gbIQeIHoPsvwmfBftfcG//BQ==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-1.1.1.tgz", + "integrity": "sha512-qV5ZC0h7jYIAOhArFJgSfdyz6rALJyb270714o7ZtNnw2WSJ+eexhKtE0O8LYPRsHZHf2osHKZBxGPvm3kPkCA==", "dev": true, "dependencies": { "original": "^1.0.0" @@ -7335,9 +7341,9 @@ } }, "node_modules/minimist": { - "version": "1.2.5", - "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz", - "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==", + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.6.tgz", + "integrity": "sha512-Jsjnk4bw3YJqYzbdyBiNsPWHPfO++UGG749Cxs6peCu5Xg4nrena6OVxOYxrQTqww0Jmwt+Ref8rggumkTLz9Q==", "dev": true }, "node_modules/minipass": { @@ -7604,9 +7610,9 @@ } }, "node_modules/node-releases": { - "version": "1.1.64", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.64.tgz", - "integrity": "sha512-Iec8O9166/x2HRMJyLLLWkd0sFFLrFNy+Xf+JQfSQsdBJzPcHpNl3JQ9gD4j+aJxmCa25jNsIbM4bmACtSbkSg==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.2.tgz", + "integrity": "sha512-XxYDdcQ6eKqp/YjI+tb2C5WM2LgjnZrfYg4vgQt49EK268b6gYCHsBLrK2qvJo4FmCtqmKezb0WZFK4fkrZNsg==", "dev": true }, "node_modules/normalize-path": { @@ -8167,9 +8173,9 @@ } }, "node_modules/path-parse": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.6.tgz", - "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==", + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", "dev": true }, "node_modules/path-to-regexp": { @@ -8215,6 +8221,12 @@ "node": ">=0.12" } }, + "node_modules/picocolors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", + "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==", + "dev": true + }, "node_modules/picomatch": { "version": "2.2.2", "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.2.tgz", @@ -10733,9 +10745,9 @@ "dev": true }, "node_modules/ssri": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/ssri/-/ssri-7.1.0.tgz", - "integrity": "sha512-77/WrDZUWocK0mvA5NTRQyveUf+wsrIc6vyrxpS8tVvYBcX215QbafrJR3KtkpskIzoFLqqNuuYQvxaMjXJ/0g==", + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/ssri/-/ssri-7.1.1.tgz", + "integrity": "sha512-w+daCzXN89PseTL99MkA+fxJEcU3wfaE/ah0i0lnOlpG1CYLJ2ZjzEry68YBKfLs4JfoTShrTEsJkAZuNZ/stw==", "dev": true, "dependencies": { "figgy-pudding": "^3.5.1", @@ -11411,10 +11423,20 @@ "dev": true }, "node_modules/ua-parser-js": { - "version": "0.7.22", - "resolved": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.22.tgz", - "integrity": "sha512-YUxzMjJ5T71w6a8WWVcMGM6YWOTX27rCoIQgLXiWaxqXSx9D7DNjiGWn1aJIRSQ5qr0xuhra77bSIh6voR/46Q==", - "dev": true, + "version": "0.7.31", + "resolved": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.31.tgz", + "integrity": "sha512-qLK/Xe9E2uzmYI3qLeOmI0tEOt+TBBQyUIAh4aAgU05FVYzeZrKUdkAZfBNVGRaHVgV0TDkdEngJSw/SyQchkQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/ua-parser-js" + }, + { + "type": "paypal", + "url": "https://paypal.me/faisalman" + } + ], "engines": { "node": "*" } @@ -11664,9 +11686,9 @@ } }, "node_modules/url-parse": { - "version": "1.4.7", - "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.4.7.tgz", - "integrity": "sha512-d3uaVyzDB9tQoSXFvuSUNFibTd9zxd2bkVrDRvF5TmvWWQwqE4lgYJ5m+x1DbecWkw+LK4RNl2CU1hHuOKPVlg==", + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", "dev": true, "dependencies": { "querystringify": "^2.1.1", @@ -11839,10 +11861,8 @@ "integrity": "sha512-aWAgTW4MoSJzZPAicljkO1hsi1oKj/RRq/OJQh2PKI2UKL04c2Bs+MBOB+BBABHTXJpf9mCwHN7ANCvYsvY2sg==", "dev": true, "dependencies": { - "chokidar": "^3.4.1", "graceful-fs": "^4.1.2", - "neo-async": "^2.5.0", - "watchpack-chokidar2": "^2.0.0" + "neo-async": "^2.5.0" }, "optionalDependencies": { "chokidar": "^3.4.1", @@ -12414,9 +12434,9 @@ } }, "node_modules/webpack/node_modules/ssri": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/ssri/-/ssri-6.0.1.tgz", - "integrity": "sha512-3Wge10hNcT1Kur4PDFwEieXSCMCJs/7WvSACcrMYrNp+b8kDL1/0wJch5Ni2WrtwEa2IO8OsVfeKIciKCDx/QA==", + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/ssri/-/ssri-6.0.2.tgz", + "integrity": "sha512-cepbSq/neFK7xB6A50KHN0xHDotYzq58wWCa5LeWqnPrHG8GzfEjO/4O8kpmcGW+oaxkvhEJCWgbgNk4/ZV93Q==", "dev": true, "dependencies": { "figgy-pudding": "^3.5.1" @@ -15256,15 +15276,16 @@ } }, "browserslist": { - "version": "4.14.5", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.14.5.tgz", - "integrity": "sha512-Z+vsCZIvCBvqLoYkBFTwEYH3v5MCQbsAjp50ERycpOjnPmolg1Gjy4+KaWWpm8QOJt9GHkhdqAl14NpCX73CWA==", + "version": "4.19.3", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.19.3.tgz", + "integrity": "sha512-XK3X4xtKJ+Txj8G5c30B4gsm71s69lqXlkYui4s6EkKxuv49qjYlY6oVd+IFJ73d4YymtM3+djvvt/R/iJwwDg==", "dev": true, "requires": { - "caniuse-lite": "^1.0.30001135", - "electron-to-chromium": "^1.3.571", - "escalade": "^3.1.0", - "node-releases": "^1.1.61" + "caniuse-lite": "^1.0.30001312", + "electron-to-chromium": "^1.4.71", + "escalade": "^3.1.1", + "node-releases": "^2.0.2", + "picocolors": "^1.0.0" } }, "bs-recipes": { @@ -15428,9 +15449,9 @@ } }, "caniuse-lite": { - "version": "1.0.30001150", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001150.tgz", - "integrity": "sha512-kiNKvihW0m36UhAFnl7bOAv0i1K1f6wpfVtTF5O5O82XzgtBnb05V0XeV3oZ968vfg2sRNChsHw8ASH2hDfoYQ==", + "version": "1.0.30001312", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001312.tgz", + "integrity": "sha512-Wiz1Psk2MEK0pX3rUzWaunLTZzqS2JYZFzNKqAiJGiuxIjRPLgV6+VDPOg6lQOUxmDwhTlh198JsTTi8Hzw6aQ==", "dev": true }, "chalk": { @@ -15644,9 +15665,9 @@ "dev": true }, "color-string": { - "version": "1.5.4", - "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.5.4.tgz", - "integrity": "sha512-57yF5yt8Xa3czSEW1jfQDE79Idk0+AkN/4KWad6tbdxUmAs3MvjxlWSWD4deYytcRfoZ9nhKyFl1kj5tBvidbw==", + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.9.0.tgz", + "integrity": "sha512-9Mrz2AQLefkH1UvASKj6v6hj/7eWgjnT/cVsR8CumieLoT+g900exWeNogqtweI8dxloXN9BDQTYro1oWu/5CQ==", "dev": true, "requires": { "color-name": "^1.0.0", @@ -16568,9 +16589,9 @@ "dev": true }, "dns-packet": { - "version": "1.3.1", - "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-1.3.1.tgz", - "integrity": "sha512-0UxfQkMhYAUaZI+xrNZOz/as5KgDU0M/fQ9b6SpkyLbk3GEswDi6PADJVaYJradtRVsRIlF1zLyOodbcTCDzUg==", + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-1.3.4.tgz", + "integrity": "sha512-BQ6F4vycLXBvdrJZ6S3gZewt6rcrks9KBgM9vrhW+knGRqc8uEdT7fuCwloc7nny5xNoMJ17HGH0R/6fpo8ECA==", "dev": true, "requires": { "ip": "^1.1.0", @@ -16684,9 +16705,9 @@ "dev": true }, "electron-to-chromium": { - "version": "1.3.582", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.3.582.tgz", - "integrity": "sha512-0nCJ7cSqnkMC+kUuPs0YgklFHraWGl/xHqtZWWtOeVtyi+YqkoAOMGuZQad43DscXCQI/yizcTa3u6B5r+BLww==", + "version": "1.4.73", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.73.tgz", + "integrity": "sha512-RlCffXkE/LliqfA5m29+dVDPB2r72y2D2egMMfIy3Le8ODrxjuZNVo4NIC2yPL01N4xb4nZQLwzi6Z5tGIGLnA==", "dev": true }, "elliptic": { @@ -17075,9 +17096,9 @@ "dev": true }, "eventsource": { - "version": "1.0.7", - "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-1.0.7.tgz", - "integrity": "sha512-4Ln17+vVT0k8aWq+t/bF5arcS3EpT9gYtW66EPacdj/mAFevznsnyoHLPy2BA8gbIQeIHoPsvwmfBftfcG//BQ==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-1.1.1.tgz", + "integrity": "sha512-qV5ZC0h7jYIAOhArFJgSfdyz6rALJyb270714o7ZtNnw2WSJ+eexhKtE0O8LYPRsHZHf2osHKZBxGPvm3kPkCA==", "dev": true, "requires": { "original": "^1.0.0" @@ -18318,9 +18339,9 @@ "dev": true }, "ini": { - "version": "1.3.8", - "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", - "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.5.tgz", + "integrity": "sha512-RZY5huIKCMRWDUqZlEi72f/lmXKMvuszcMBduliQ3nnWbx9X/ZBQO7DijMEYS9EhHBb2qacRUMtC7svLwe0lcw==", "dev": true }, "internal-ip": { @@ -19180,9 +19201,9 @@ } }, "minimist": { - "version": "1.2.5", - "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz", - "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==", + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.6.tgz", + "integrity": "sha512-Jsjnk4bw3YJqYzbdyBiNsPWHPfO++UGG749Cxs6peCu5Xg4nrena6OVxOYxrQTqww0Jmwt+Ref8rggumkTLz9Q==", "dev": true }, "minipass": { @@ -19418,9 +19439,9 @@ } }, "node-releases": { - "version": "1.1.64", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.64.tgz", - "integrity": "sha512-Iec8O9166/x2HRMJyLLLWkd0sFFLrFNy+Xf+JQfSQsdBJzPcHpNl3JQ9gD4j+aJxmCa25jNsIbM4bmACtSbkSg==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.2.tgz", + "integrity": "sha512-XxYDdcQ6eKqp/YjI+tb2C5WM2LgjnZrfYg4vgQt49EK268b6gYCHsBLrK2qvJo4FmCtqmKezb0WZFK4fkrZNsg==", "dev": true }, "normalize-path": { @@ -19879,9 +19900,9 @@ "dev": true }, "path-parse": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.6.tgz", - "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==", + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", "dev": true }, "path-to-regexp": { @@ -19920,6 +19941,12 @@ "sha.js": "^2.4.8" } }, + "picocolors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", + "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==", + "dev": true + }, "picomatch": { "version": "2.2.2", "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.2.tgz", @@ -22145,9 +22172,9 @@ "dev": true }, "ssri": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/ssri/-/ssri-7.1.0.tgz", - "integrity": "sha512-77/WrDZUWocK0mvA5NTRQyveUf+wsrIc6vyrxpS8tVvYBcX215QbafrJR3KtkpskIzoFLqqNuuYQvxaMjXJ/0g==", + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/ssri/-/ssri-7.1.1.tgz", + "integrity": "sha512-w+daCzXN89PseTL99MkA+fxJEcU3wfaE/ah0i0lnOlpG1CYLJ2ZjzEry68YBKfLs4JfoTShrTEsJkAZuNZ/stw==", "dev": true, "requires": { "figgy-pudding": "^3.5.1", @@ -22701,9 +22728,9 @@ "dev": true }, "ua-parser-js": { - "version": "0.7.22", - "resolved": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.22.tgz", - "integrity": "sha512-YUxzMjJ5T71w6a8WWVcMGM6YWOTX27rCoIQgLXiWaxqXSx9D7DNjiGWn1aJIRSQ5qr0xuhra77bSIh6voR/46Q==", + "version": "0.7.31", + "resolved": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.31.tgz", + "integrity": "sha512-qLK/Xe9E2uzmYI3qLeOmI0tEOt+TBBQyUIAh4aAgU05FVYzeZrKUdkAZfBNVGRaHVgV0TDkdEngJSw/SyQchkQ==", "dev": true }, "uglify-js": { @@ -22918,9 +22945,9 @@ } }, "url-parse": { - "version": "1.4.7", - "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.4.7.tgz", - "integrity": "sha512-d3uaVyzDB9tQoSXFvuSUNFibTd9zxd2bkVrDRvF5TmvWWQwqE4lgYJ5m+x1DbecWkw+LK4RNl2CU1hHuOKPVlg==", + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", "dev": true, "requires": { "querystringify": "^2.1.1", @@ -23284,9 +23311,9 @@ "dev": true }, "ssri": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/ssri/-/ssri-6.0.1.tgz", - "integrity": "sha512-3Wge10hNcT1Kur4PDFwEieXSCMCJs/7WvSACcrMYrNp+b8kDL1/0wJch5Ni2WrtwEa2IO8OsVfeKIciKCDx/QA==", + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/ssri/-/ssri-6.0.2.tgz", + "integrity": "sha512-cepbSq/neFK7xB6A50KHN0xHDotYzq58wWCa5LeWqnPrHG8GzfEjO/4O8kpmcGW+oaxkvhEJCWgbgNk4/ZV93Q==", "dev": true, "requires": { "figgy-pudding": "^3.5.1" diff --git a/package.json b/package.json index 27b2226477..320ee697a4 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "test": "echo \"Error: no test specified\" && exit 1", "dev": "npm run development", "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js", - "watch": "npm run development -- --watch", + "watch": "bundle exec jekyll serve", "prod": "npm run production", "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --no-progress --nide-modules --config=node_modules/laravel-mix/setup/webpack.config.js" }, diff --git a/partners/partners.md b/partners/partners.md index 34e9fce27c..71a7cf6417 100644 --- a/partners/partners.md +++ b/partners/partners.md @@ -1,54 +1,15 @@ --- layout: page_v2 -title: Partners | Prebid -description: Partners +title: Membership +description: Membership sidebarType: 0 --- -# Prebid.Org Members +# Prebid.Org Membership -
    -

    Join Now

    -
    +This page has moved to [https://prebid.org/membership/](https://prebid.org/membership/)! -Prebid.org was developed to bring together the oversight, guidance, and development capabilities of the ad tech community to solve the industry’s common technical hurdles. By structuring the organization with a tiered membership system, we can ensure that the organization’s standards are upheld and appropriately funded, and that Prebid solutions continue to be built by and made available to the Prebid community. - -Join your industry peers in helping build and shape the ad tech ecosystem. - -
    - -## Why Join? - -Companies join Prebid.org because they want to take an active role in supporting the growth and evolution of the ad tech ecosystem: -- Network with other members of Prebid.org. -- Support the community by helping fund Prebid services and events. -- Demonstrate thought leadership in the ad tech space. -- Promote Prebid projects for faster market adoption. -- Help define the technologies that shape of the industry by participating in our Slack workspace and joining the [Product Management Committees](/overview/prebid-management-committees.html). - -
    - -## How To Join - -1. Download and review the [Prebid.org Bylaws](https://files.prebid.org/docs/Prebid_org_bylaws_jun_2019.pdf). -2. Complete the [Prebid.org Membership Agreement](https://na3.docusign.net/Member/PowerFormSigning.aspx?PowerFormId=610f838a-3001-4999-aca0-6682cbcac66c&env=na3-eu1&acct=2160069d-b42e-4c0a-9528-3a58d1c58bf9&v=2). -3. Prebid will consider your membership application. - -
    - -## Membership Levels and Pricing - -{: .table .table-bordered .table-striped } -| | Board Seat | PMC Participation | Private Slack Instance | Participate in Prebid.org Events | Prebid.org Email Address | Logo on Prebid.org Website | Annual Fees | -|---------------------|-----------------------------------------------------------------------|-------------------|------------------------|----------------------------------|--------------------------|----------------------------|-------------| -| Leader Members | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | $40,000 | -| Technology Partners | As a Group, Technology members elect a representative to the board | ✓ | ✓ | ✓ | ✓ | ✓ | $25,000 | -| Publishers | As a Group, Publisher members elect a representative to the board | ✓ | ✓ | ✓ | ✓ | ✓ | $5,000 | -| Buyers | As a Group, Buyer members elect a representative to the board | ✓ | ✓ | ✓ | ✓ | ✓ | $5,000 | -| Community | ✖ | ✓ | ✓ | ✓ | ✖ | ✖ | Free | - -Have questions about becoming a member, email us at [membership@prebid.org](mailto:membership@prebid.org). - -
    -
    +## Related Reading +- [Why Prebid](https://prebid.org/why-prebid/) +- [Code of Conduct](https://prebid.org/code-of-conduct/) diff --git a/prebid-mobile/adops-line-item-setup-mopub.md b/prebid-mobile/adops-line-item-setup-mopub.md deleted file mode 100644 index cd5d578c87..0000000000 --- a/prebid-mobile/adops-line-item-setup-mopub.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -layout: page_v2 -title: Setup Line Items for MoPub -description: Setup line items for MoPub -pid: 1 -top_nav_section: prebid-mobile -nav_section: prebid-mobile-adops -sidebarType: 3 ---- - - - - -# Step-by-Step Line Item Setup for MoPub - -* TOC -{:toc } - -This page provides step-by-step instructions to set up Prebid Mobile line items for MoPub to serve ads on app with the Prebid SDK. It is using the Universal Prebid Creative. - -## Step 1. Add a line item - -- Set the **Type & Priority** to **Non-guaranteed** and **12**, respectively, so the line item will compete with all other demand -- Set the **Rate** to the price you want to target, for example $0.50, in the screenshot below - -![MoPub Line Item Setup]({{site.github.url}}/assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub1.png "Example MoPub Line Item"){: .pb-md-img :} - -- In the **Advanced Targeting** section, in **Keywords** target **hb_pb:0.50** - -![MoPub Advanced Targeting Setup]({{site.github.url}}/assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub2.png "Example MoPub Advanced Targeting"){: .pb-md-img :} - -For each level of pricing granularity you need, you will have to set up one line item/creative pair. - -Line items must be set up to target custom keywords that include bid price information. The bid price keywords tell you how much the buyer bid on the impression. - -By default, `Prebid Mobile` will send the highest bid price to Google Ad Manager using the keyword `hb_pb` but will also pass the keys `hb_pb_BIDDERCODE`. You can decide to create one set of line items for all bidders or one set of line items for each bidder. - -## Step 2. Add creatives to your line item - -Banner creatives must be HTML banners with the **Format** set to **Banner** that include the code shown below. - -![MoPub Creative Setup]({{site.github.url}}/assets/images/prebid-mobile/adops-line-item-setup-mopub/mopub3.png "Example MoPub Creative"){: .pb-md-img :} - -The **hb_cache_id** variable stands for the cache id that will load the ad markup from the bid from Prebid Cache. Within each line item, for each ad unit size there should be one creative with this content. - - -{: .alert.alert-success :} -You can always get the latest version of the creative code below from [the Mobile example creative file in our GitHub repo](https://github.com/prebid/prebid-universal-creative/blob/master/template/amp/dfp-creative.html). - -{% highlight javascript %} - - - - -{% endhighlight %} - -## Step 3. Duplicate line items - -Duplicate your line items according to your [price granularity]({{site.github.url}}/prebid-mobile/adops-price-granularity.html) setting. diff --git a/prebid-mobile/adops-setup-full-screen-video-mopub.md b/prebid-mobile/adops-setup-full-screen-video-mopub.md deleted file mode 100644 index 429c0488d3..0000000000 --- a/prebid-mobile/adops-setup-full-screen-video-mopub.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: page_v2 -title: Setup Rewarded Video for MoPub -description: Setup Full Screen Video for MoPub -pid: 1 -top_nav_section: prebid-mobile -nav_section: prebid-mobile-adops -sidebarType: 3 ---- - -# Step-by-Step Line Item Setup for Full-screen Video on MoPub - -* TOC -{:toc } - -This page provides step-by-step instructions to set up full-screen video line items on MoPub to be used with the Prebid Mobile SDK. - -## Step 1. Create full screen adUnit -Under New ad unit, select Fullscreen.   - -## Step 2. Add a line item -In the *Add a Line Item* section: -1. For the *Type and Priority* settings, select *Non-Guaranteed* as the type and set the priority to *12*. This ensures the line item will compete with all other demand. -2. Set the Rate to the price you want to target.  -For the Type and Priority settings, select Non-Guaranteed as the type and set the priority to 12   -3. In the *Advanced Targeting* section, set the target for *Keywords* to `hb_pb:0.50`  -In the Advanced Targeting section, set the target for Keywords to hb_pb:0.50   - -For each level of pricing granularity required, one line item/creative pairing will need to be set up. - -Line items must be set up to target custom keywords that include bid price information. The bid price keywords will contain how much the buyer bid on the impression. - -Prebid Mobile, by default, will send the highest bid price to MoPub using the keyword `hb_pb` but will also submit the key `hb_pb_BIDDERCODE` for each bidder. You can decide to create one set of line items for all bidders or one set of line items for each bidder. - -## Step 3. Add creatives to your line item -Full-screen video creatives must have a *VAST tag* with the *Format* set to *Fullscreen* that includes the code below: -``` - - - - MoPub - - - - - -``` -
    -MoPub VAST tag code   - -The `hb_uuid` variable value is the cache id that will load the ad markup from the bid stored in Prebid Cache. Within each line item, for each ad unit size, there should be one creative with this content. - -The XML can be constructed by providing the VAST tag URL as: -`https://%%KEYWORD:hb_cache_host%%%%KEYWORD:hb_cache_path%%?uuid=%%KEYWORD:hb_uuid%%` - -## Step 4. Duplicate line items -Duplicate your line items according to your [price granularity](/prebid-mobile/adops-price-granularity.html) setting. diff --git a/prebid-mobile/adops-setup-rewarded-video-mopub.md b/prebid-mobile/adops-setup-rewarded-video-mopub.md deleted file mode 100644 index 839a8593e7..0000000000 --- a/prebid-mobile/adops-setup-rewarded-video-mopub.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: page_v2 -title: Setup Rewarded Video for MoPub -description: Setup Rewarded Video for MoPub -pid: 1 -top_nav_section: prebid-mobile -nav_section: prebid-mobile-adops -sidebarType: 3 ---- - -# Step-by-Step Line Item Setup for Rewarded Video on MoPub - -* TOC -{:toc } - -This page provides step-by-step instructions to set up rewarded-video line items on MoPub to be used with the Prebid Mobile SDK. - -## Step 1. Add a line item - - In the *Add a Line Item* section: - 1. For the *Type and Priority* settings, select *Non-Guaranteed* as the type and set the priority to *12*. This ensures the line item will compete with all other demand. - 2. Set the Rate to the price you want to target.  - For the Type and Priority settings, select Non-Guaranteed as the type and set the priority to 12   - 3. In the *Advanced Targeting* section, set the target for *Keywords* to `hb_pb:0.50`  - In the Advanced Targeting section, set the target for Keywords to hb_pb:0.50   - -For each level of pricing granularity required, one line item/creative pairing will need to be set up. - -Line items must be set up to target custom keywords that include bid price information. The bid price keywords will contain how much the buyer bid on the impression. - -Prebid Mobile, by default, will send the highest bid price to MoPub using the keyword `hb_pb` but will also submit the key `hb_pb_BIDDERCODE` for each bidder. You can decide to create one set of line items for all bidders or one set of line items for each bidder. - -## Step 2. Add creatives to your line item -Rewarded video creatives must have a *VAST tag* with the *Format* set to *Rewarded Video* that includes the code below: - -``` - - - - MoPub - - - - -``` - -
    -MoPub VAST tag code   -The `hb_uuid` variable value is the cache id that will load the ad markup from the bid stored in Prebid Cache. Within each line item, for each ad unit size, there should be one creative with this content. - -The XML can be constructed by providing the VAST tag URL as: -`https://%%KEYWORD:hb_cache_host%%%%KEYWORD:hb_cache_path%%?uuid=%%KEYWORD:hb_uuid%%` - -## Step 3. Duplicate line items -Duplicate your line items according to your [price granularity](/prebid-mobile/adops-price-granularity.html) setting. diff --git a/prebid-mobile/modules/modules-overview.md b/prebid-mobile/modules/modules-overview.md new file mode 100644 index 0000000000..6db9db2a90 --- /dev/null +++ b/prebid-mobile/modules/modules-overview.md @@ -0,0 +1,47 @@ +--- + +layout: page_v2 +title: Prebid Modules Overview +description: What is Prebid.js +sidebarType: 2 + +--- + +# Prebid Mobile Modules Overview + +The design of Prebid Mobile is to provide a lightweight SDK with minimal logic, leveraging Prebid Server to handle requests for demand and a much logic as possible as far as auction dynamics go. Keeping with the spirit of this design principle, Prebid Mobile supports a modular architecture to add in new feature sets, that can potentially load the size of Prebid SDK, into components publishers can select to build when assembling their apps. Modularity follows the approach used across the Prebid suite of products (Prebid JS and Prebid Server) to help reduce the overall size of the prebid library/package. + +This page will serve as the central location to link all modular packages, descriptions, and resources for modular links. + +## Benefits and Features + +Some of the benefits to the modular architecture are the following: + +- Allows the ability to customize the Prebid SDK to the developer needs +- Allows for the reduced size of Prebid SDK, adding only modules need +- Allows for the community to add custom and/or 3rd party code without adding code to the core of Prebid SDK +- Reduces the size of Prebid SDK + +## How It Works + +The following diagram describes the overall architecture of modularity prior and after release of 1.12 for both iOS and Android. Both platforms share the same architecture. + +![Modularity](/assets/images/prebid-mobile/modules/modularity.png) + + +Prior to Prebid SDK 1.12 there were two targets(PrebidMobile and PrebidMobileCore) which use the same product name and module name(PrebidMobile). These two modules are the same, they include the same source files. Since no new modules have been created prior to 1.12, new modules can be added and built + +1. Set a unique product name and module name for each product: + * PrebidMobile instead of PrebidMobileCore. It will allows us to seamless migration because it doesn't cause breaking changes. All publishers which now use PrebidMobileCore or PrebidMobile don't need to replace module names in source files + * PrebidMobileFull instead of PrebidMobile. PrebidMobileFull will not include any source files it will be just a name of dependency which will be responsible to add all sub-dependencies +1. Set dependencies between them +1. Edit final distribution binaries(FatFramework, CocoaPods, Carthage, SPM, cross-project dependency) + +Usage: + +```bash +import PrebidMobile +import PrebidMobileRendering +``` + + diff --git a/prebid-mobile/modules/rendering/android-sdk-customization-controls.md b/prebid-mobile/modules/rendering/android-sdk-customization-controls.md new file mode 100644 index 0000000000..6c7e9ade5a --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-customization-controls.md @@ -0,0 +1,76 @@ +--- + +layout: page_v2 +title: Ad Experience Controls +description: Customization of ad expirience +sidebarType: 2 + +--- + +# Ad Experience Controls + +Prebid SDK provides an API way to customize its behaviour. + +> NOTE: In the nearest future the Server Side Configuration will be supported as well. Follow this [feature request](https://github.com/prebid/prebid-server/issues/2186) for the details. + + +## Rendering Controls + +The following properties allow to customize the rendering of Video Interstitial Ads. + +### Max Video Duration + +The `maxVideoDuration` indicates the maximum available playback time in seconds. +If the value in the **Duration** tag is bigger than the given value SDK will fail to load ad, providing a respective error message. + +### Application Muted + +The `isMuted` property indicates whether the ad should run playback with sound or not. +Default value - **false**. + +### Close Button Area + +The `closeButtonArea` property indicates the percent of device screen which the close button should occupy. The possible values are from **0** to **1**. + +### Close Button Position + +The `closeButtonPosition` property indicates the position of the close button on the screen. The possible values are **Position.BOTTOM_LEFT** and **Position.TOP_RIGHT**. The default value is **Position.TOP_RIGHT**. + +The example: + +![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-android-close-button-possition-top-left.png){:width="250px"} + +### Skip Button Area + +The `skipButtonArea` property indicates the percent of device screen which the skip button should occupy. The possible values are from **0** to **1**. + +### Skip Button Position + +The `skipButtonPosition` property indicates the position of the close button on the screen. The possible values are **Position.BOTTOM_LEFT** and **Position.TOP_RIGHT**. The default value is **Position.BOTTOM_LEFT**. + +The example: + +![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-android-skip-button-possition-top-left.png){:width="250px"} + +### Skip Delay + +The `skipDelay` property indicates the number of seconds which should be passed from the start of playback until the skip or close button should be shown. The default value is **10**. + +The code sample: + +``` kotlin +adUnit = MediationInterstitialAdUnit( + activity, + configId, + EnumSet.of(AdUnitFormat.DISPLAY), + mediationUtils +) + +adUnit?.setMaxVideoDuration(30) +adUnit?.setCloseButtonArea(0.1) +adUnit?.setSkipDelay(5) +adUnit?.setSkipButtonArea(0.1) +adUnit?.setSkipButtonPosition(Position.TOP_RIGHT) +adUnit?.setCloseButtonPosition(Position.BOTTOM_LEFT) +``` + diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-admob.md b/prebid-mobile/modules/rendering/android-sdk-integration-admob.md new file mode 100644 index 0000000000..68af32f417 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-admob.md @@ -0,0 +1,411 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering GAM Line Item Setup +description: Prebid Mobile Rendering Modules GAM line item setup +sidebarType: 2 + +--- + +# AdMob Integration + +The integration of Prebid Mobile with Google AdMob assumes that the publisher has an AdMob account and has already integrated the Google Mobile Ads SDK (GMA SDK) into the app. + +See the [Google's integration documentation](https://developers.google.com/admob/android/quick-start) for the AdMob integration details. + +Prebid is integrated into the AdMob monetization via adapters. + +## AdMob Integration Overview + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-admob.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** GMA SDK makes an ad request. AdMob returns the mediation chain with respective ad sources. + +**Step 4** For each prebid's ad source, the GMA SDK sequentially instantiates an adapter. + +**Step 5** The adapter verifies the targeting keywords of the winning bid and the server properties of the given ad source. If they match adapter will render the winning bid. Otherwise, it will fail with "no ad" immediately and the next ad source will instantiate the same adapter but for another set of server params. + +Prebid Mobile supports these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Native + +They can be integrated using these mediation API categories: + +- [**Banner API**](#banner-api) - for *Display Banner* +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* +- [**Native API**](#native-api) - for *Native Ads* + + +## Init Prebid Rendering Module + +To start running bid requests you have to set the Prebid Server **Host** and **Account Id** and then initilize the SDK with application context. The best place for this is the `onCreate()` method of your Application class. + +``` +PrebidMobile.setBidServerHost(HOST) +PrebidMobile.setAccountId(YOUR_ACCOUNT_ID) + +// Init SDK +PrebidMobile.setApplicationContext(this) +``` + +> **NOTE:** The account ID is an identifier of the **Stored Request**. + +### Prebid Adapters + +To integrate Prebid Adapters just add the following lines into your build.gradle files: + +Root build.gradle + +``` +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +App module build.gradle: + +``` +implementation('org.prebid:prebid-mobile-sdk-admob-adapters:x.x.x') +``` + +## Banner API + +Integration example: + + +``` kotlin +// 1. Create AdView and AdRequest +bannerView = AdView(activity) +bannerView?.adSize = AdSize.BANNER +bannerView?.adUnitId = adUnitId + +val extras = Bundle() +val request = AdRequest + .Builder() + .addCustomEventExtrasBundle(PrebidBannerAdapter::class.java, extras) + .build() + +// 2. Create AdMobBannerMediationUtils +val mediationUtils = AdMobBannerMediationUtils(extras, bannerView) + +// 3. Create MediationBannerAdUnit +adUnit = MediationBannerAdUnit( + wrapper.context, + configId, + org.prebid.mobile.rendering.bidding.data.AdSize(width, height), + mediationUtils +) +adUnit?.setRefreshInterval(autoRefreshTime / 1000) + +// 4. Make a bid request +adUnit?.fetchDemand { result -> + Log.d("Prebid", "Fetch demand result: $result") + + // 5. Request the ad + bannerView?.loadAd(request) +} +``` + +#### Step 1: Create AdView and AdRequest + +This step is totally the same as for the original [AdMob integration](https://developers.google.com/admob/android/banner). You don't have to make any modifications here. + + +#### Step 2: Create AdMobMediationBannerUtils + +The `AdMobBannerMediationUtils` is a helper class, wich performs certain utilty work for the `MediationBannerAdUnit`, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationBannerAdUnit + +The `MediationBannerAdUnit` is part of the prebid mediation API. This class is responsible for making the bid request and providing the winning bid and targeting keywords to the mediating SDKs. + +#### Step 4: Make a bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should just make a regular AdMob's ad request. Evetything else will be handled by GMA SDK and prebid adapters. + +## Interstitial API + +Integration example: + +``` kotlin +// 1. Create AdRequest +val extras = Bundle() +val request = AdRequest + .Builder() + .addCustomEventExtrasBundle(PrebidInterstitialAdapter::class.java, extras) + .build() + +// 2. Create AdMobInterstitialMediationUtils +val mediationUtils = AdMobInterstitialMediationUtils(extras) + +// 3. Create MediationInterstitialAdUnit +adUnit = MediationInterstitialAdUnit( + activity, + configId, + AdUnitFormat.DISPLAY, + mediationUtils +) + +// 4. Make a bid request +adUnit?.fetchDemand { result -> + Log.d("Prebid", "Fetch demand result: $result") + + // 5. Make an ad request + InterstitialAd.load(activity, adUnitId, request, object : InterstitialAdLoadCallback() { + override fun onAdLoaded(interstitial: InterstitialAd) { + interstitialAd = interstitial + + // 6. Display the ad + interstitialAd?.show(activity) + } + + override fun onAdFailedToLoad(error: LoadAdError) { + interstitialAd = null + } + }) +} +``` + +#### Step 1: Create AdRequest + +This step is totally the same as for original [AdMob integration](https://developers.google.com/admob/android/interstitial). You don't have to make any modifications here. + +#### Step 2: Create AdMobInterstitialMediationUtils + +The `AdMobInterstitialMediationUtils` is a helper class, wich performs certain utilty work for the `MediationInterstitialAdUnit`, like passing the targeting keywords to adapters. + +#### Step 3: Create MediationInterstitialAdUnit + +The `MediationInterstitialAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing the winning bid and targeting keywords to mediating SDKs. + +The **default** ad format for interstitial is **DISPLAY**. In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter. + +``` +adUnit = MediationInterstitialAdUnit( + activity, + configId, + EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO), + mediationUtils + ) +``` + +#### Step 4: Make a bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an ad reuest + +Now you should just make a regular AdMob's ad request. Evetything else will be handled by GMA SDK and prebid adapters. + +#### Step 6: Display an ad + +Once you receive the ad it will be ready for display. You can show interstitial right in the listener or later according to the app logic. + + +## Rewarded API + +Integration example: + +``` kotlin +// 1. Create AsRequest +val extras = Bundle() +val request = AdRequest + .Builder() + .addNetworkExtrasBundle(PrebidRewardedAdapter::class.java, extras) + .build() + +// 2. Create AdMobRewardedMediationUtils +val mediationUtils = AdMobRewardedMediationUtils(extras) + +// 3. Create MediationRewardedVideoAdUnit +adUnit = MediationRewardedVideoAdUnit(activity, configId, mediationUtils) + +// 4. Make a bid request +adUnit?.fetchDemand { result -> + Log.d("Prebid", "Fetch demand result: $result") + + // 5. Make an ad request + RewardedAd.load(activity, adUnitId, request, object : RewardedAdLoadCallback() { + override fun onAdLoaded(ad: RewardedAd) { + Log.d(TAG, "Ad was loaded.") + rewardedAd = ad + + // 6. Display an ad + rewardedAd?.show(activity) { rewardItem -> + val rewardAmount = rewardItem.amount + val rewardType = rewardItem.type + Log.d(TAG, "User earned the reward ($rewardAmount, $rewardType)") + } + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + Log.e(TAG, adError.message) + rewardedAd = null + } + }) +} +``` + +#### Step 1: Create AdRequest + +This step is totally the same as for the original [AdMob integration](https://developers.google.com/admob/android/rewarded). You don't have to make any modifications here. + +#### Step 2: Create AdMobRewardedMediationUtils + +The `AdMobRewardedMediationUtils ` is a helper class, wich performs certain utilty work for the `MediationInterstitialAdUnit`, like passing the targeting keywords to adapters. + +#### Step 3: Create MediationRewardedVideoAdUnit + +The `MediationRewardedVideoAdUnit` is part of the prebid mediation API. This class is responsible for making bid request and managing the winning bid. + +#### Step 4: Make a bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an ad reuest + +Now you should just make a regular AdMob's ad request. Evetything else will be handled by GMA SDK and prebid adapters. + +#### Step 6: Display an ad + +Once you receive the ad it will be ready for display. You can show interstitial right in the listener or later according to the app logic. + +## Native API + +Integration example: + +``` +// 1. Create AdLoader and AdRequest +val nativeAdOptions = NativeAdOptions + .Builder() + .build() + +val adLoader = AdLoader + .Builder(wrapper.context, adUnitId) + .forNativeAd { ad: NativeAd -> + nativeAd = ad + createCustomView(wrapper, nativeAd!!) + } + .withAdListener(object : AdListener() { + override fun onAdFailedToLoad(adError: LoadAdError) { + Log.e(TAG, "Error: ${adError.message}") + } + }) + .withNativeAdOptions(nativeAdOptions) + .build() + +val extras = Bundle() +val adRequest = AdRequest + .Builder() + .addCustomEventExtrasBundle(PrebidNativeAdapter::class.java, extras) + .build() + +// 2. Create Native AdUnit +val nativeAdUnit = NativeAdUnit(configId) + +// 3. Configure NativeAdUnit +configureNativeAdUnit(nativeAdUnit) + +// 4. Make a bid request +nativeAdUnit.fetchDemand(extras) { resultCode -> + Log.d(TAG, "Fetch demand result: $resultCode") + + // 5. Make an ad request + adLoader.loadAd(adRequest) +} +``` + + +#### Step 1: Create AdRequest + +Prepare the `AdLoader` and `AdRequest` objects before you make the bid request. They are needed for prebid mediation utils. Follow the [AdMob integration instructions](https://developers.google.com/admob/android/native/start) for this step. + +#### Step 2: Create NativeAdUnit + +The `NativeAdUnit` is responsible for making bid requests. Once the bid responce is received you can load an ad from AdMob. + +#### Step 3: Configure NativeAdUnit + +The bid request for native ad should have a descrition of expected assets. The full spec for the Native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the assets array and configuring the `NativeAdUnit`: + +``` kotlin +private fun configureNativeAdUnit(nativeAdUnit: NativeAdUnit) { + + // Configure Ad Unit + nativeAdUnit.setContextType(NativeAdUnit.CONTEXT_TYPE.SOCIAL_CENTRIC) + nativeAdUnit.setPlacementType(NativeAdUnit.PLACEMENTTYPE.CONTENT_FEED) + nativeAdUnit.setContextSubType(NativeAdUnit.CONTEXTSUBTYPE.GENERAL_SOCIAL) + + // Create the list of required assets + val title = NativeTitleAsset() + title.setLength(90) + title.isRequired = true + nativeAdUnit.addAsset(title) + + val icon = NativeImageAsset() + icon.imageType = NativeImageAsset.IMAGE_TYPE.ICON + icon.wMin = 20 + icon.hMin = 20 + icon.isRequired = true + nativeAdUnit.addAsset(icon) + + val image = NativeImageAsset() + image.imageType = NativeImageAsset.IMAGE_TYPE.MAIN + image.hMin = 200 + image.wMin = 200 + image.isRequired = true + nativeAdUnit.addAsset(image) + + val data = NativeDataAsset() + data.len = 90 + data.dataType = NativeDataAsset.DATA_TYPE.SPONSORED + data.isRequired = true + nativeAdUnit.addAsset(data) + + val body = NativeDataAsset() + body.isRequired = true + body.dataType = NativeDataAsset.DATA_TYPE.DESC + nativeAdUnit.addAsset(body) + + val cta = NativeDataAsset() + cta.isRequired = true + cta.dataType = NativeDataAsset.DATA_TYPE.CTATEXT + nativeAdUnit.addAsset(cta) + + // Create the list of required event trackers + val methods: ArrayList = ArrayList() + methods.add(NativeEventTracker.EVENT_TRACKING_METHOD.IMAGE) + methods.add(NativeEventTracker.EVENT_TRACKING_METHOD.JS) + try { + val tracker = NativeEventTracker(NativeEventTracker.EVENT_TYPE.IMPRESSION, methods) + nativeAdUnit.addEventTracker(tracker) + } catch (e: Exception) { + e.printStackTrace() + } +} +``` + +#### Step 4: Make a bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: make an ad request + +Now just load a native ad from AdMob according to the [AdMob instructions](https://developers.google.com/admob/android/native/start). Everything else will be handled by GMA SDK and prebid adapters. diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-gam-native.md b/prebid-mobile/modules/rendering/android-sdk-integration-gam-native.md new file mode 100644 index 0000000000..4bfe7bdc01 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-gam-native.md @@ -0,0 +1,166 @@ +--- + +layout: page_v2 +title: Google Ad Manager Integration - Native +description: Examples of integration native ads with GAM +sidebarType: 2 + +--- + +# GAM: Native Ads Integration + +## Native Ads + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout. +2. Create Native Ad Unit and appropriate GAM ad loader. +3. Configure the Native Ad unit using [NativeAdConfiguration](rendering-native-ad-configuration.html). + * Provide the list of **Native Assets** representing the ad's structure. + * Tune other general properties of the ad. +4. Make a bid request. +5. Prepare publisherAdRequest using `GamUtils.prepare` +6. After receiving response from GAM - check if prebid has won and find native ad using `GamUtils` +7. Bind the winner data from the native ad response with the layout. + +``` kotlin +val builder = AdManagerAdRequest.Builder() +val publisherAdRequest = builder.build() +nativeAdUnit?.fetchDemand { result -> + val fetchDemandResult = result.fetchDemandResult + if (fetchDemandResult != FetchDemandResult.SUCCESS) { + loadGam(publisherAdRequest) + return@fetchDemand + } + + GamUtils.prepare(publisherAdRequest, result) + loadGam(publisherAdRequest) +} +``` + +**NOTE:** `loadGam` method is creating GAM adLoader and executing `loadAd(publisherAdRequest)`. + + +Example of handling NativeAd response (the same applies to Custom): + +``` kotlin +private fun handleNativeAd(nativeAd: NativeAd) { + if (GamUtils.didPrebidWin(nativeAd)) { + GamUtils.findNativeAd(nativeAd) { + inflateViewContentWithPrebid(it) + } + } + else { + inflateViewContentWithNative(nativeAd) + } +} +``` + +## Native Styles + +[See Native Ads Guideline page](rendering-native-guidelines.html) for more details about SDK integration and supported ad types. + +Integration Example: + +``` kotlin +// 1. Create banner custom event handler for GAM ad server. +val eventHandler = GamBannerEventHandler(requireContext(), GAM_AD_UNIT, GAM_AD_SIZE) + +// 2. Create a bannerView instance and provide GAM event handler +bannerView = BannerView(requireContext(), configId, eventHandler) +// (Optional) set an event listener +bannerView?.setBannerListener(this) + +// 3. Provide NativeAdConfiguration +val nativeAdConfiguration = createNativeAdConfiguration() +bannerView?.setNativeAdConfiguration(nativeAdConfiguration) + +// Add bannerView to your viewContainer +viewContainer?.addView(bannerView) + +// 4. Execute ad loading +bannerView?.loadAd() +``` + +#### Step 1: Create Event Handler + +GAM's event handlers are special containers that wrap GAM Ad Views and help to manage collaboration between GAM and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create the event handler you should provide a GAM Ad Unit Id and the list of available sizes for this ad unit. + +**Note:** There is a helper function `convertGamAdSize` in GamBannerEventHandler to help you convert GAM AdSize into Prebid AdSize. + + +#### Step 2: Create Ad View + +**BannerView** - is a view that will display the particular ad. It should be added to the UI. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - the instance of the banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +#### Step 3: Create and provide NativeAdConfiguration + +NativeAdConfiguration creation example: + +``` kotlin +private fun createNativeAdConfiguration(): NativeAdConfiguration { + val nativeAdConfiguration = NativeAdConfiguration() + nativeAdConfiguration.contextType = NativeAdConfiguration.ContextType.SOCIAL_CENTRIC + nativeAdConfiguration.placementType = NativeAdConfiguration.PlacementType.CONTENT_FEED + nativeAdConfiguration.contextSubType = NativeAdConfiguration.ContextSubType.GENERAL_SOCIAL + + val methods = ArrayList() + methods.add(NativeEventTracker.EventTrackingMethod.IMAGE) + methods.add(NativeEventTracker.EventTrackingMethod.JS) + val eventTracker = NativeEventTracker(NativeEventTracker.EventType.IMPRESSION, methods) + nativeAdConfiguration.addTracker(eventTracker) + + val assetTitle = NativeAssetTitle() + assetTitle.len = 90 + assetTitle.isRequired = true + nativeAdConfiguration.addAsset(assetTitle) + + val assetIcon = NativeAssetImage() + assetIcon.type = NativeAssetImage.ImageType.ICON + assetIcon.wMin = 20 + assetIcon.hMin = 20 + assetIcon.isRequired = true + nativeAdConfiguration.addAsset(assetIcon) + + val assetImage = NativeAssetImage() + assetImage.hMin = 20 + assetImage.wMin = 200 + assetImage.isRequired = true + nativeAdConfiguration.addAsset(assetImage) + + val assetData = NativeAssetData() + assetData.len = 90 + assetData.type = NativeAssetData.DataType.SPONSORED + assetData.isRequired = true + nativeAdConfiguration.addAsset(assetData) + + val assetBody = NativeAssetData() + assetBody.isRequired = true + assetBody.type = NativeAssetData.DataType.DESC + nativeAdConfiguration.addAsset(assetBody) + + val assetCta = NativeAssetData() + assetCta.isRequired = true + assetCta.type = NativeAssetData.DataType.CTA_TEXT + nativeAdConfiguration.addAsset(assetCta) + + nativeAdConfiguration.nativeStylesCreative = nativeStylesCreative + + return nativeAdConfiguration +} +``` + +See more NativeAdConfiguration options [here](rendering-native-ad-configuration.html). + +#### Step 4: Load the Ad + +Call the `loadAd()` method to start an In-App Bidding flow. diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-gam.md b/prebid-mobile/modules/rendering/android-sdk-integration-gam.md new file mode 100644 index 0000000000..636fb73f79 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-gam.md @@ -0,0 +1,330 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering GAM Line Item Setup +description: Prebid Mobile Rendering Modules GAM line item setup +sidebarType: 2 + +--- + +# Google Ad Manager Integration + +The integration of Prebid Rendering API with Google Ad Manager (GAM) assumes that publisher has an account on GAM and has already integrated the Google Mobile Ads SDK (GMA SDK) into the app project. + + +If you do not have GAM SDK in the app yet, refer the the [Google Integration Documentation](https://developers.google.com/ad-manager/mobile-ads-sdk/android/quick-start). + +Prebid Rendering API was tested with **GAM SDK 20.4.0**. + + +## GAM Integration Overview + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-GAM.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** Prebid Rendering Module via GAM Event Handler sets up the targeting keywords into the GAM's ad unit. + +**Step 4** GMA SDK makes an ad request. GAM returns the winned line item. + +**Step 5** Basing on the ad response Prebid GAM Event Handler defines which line item has won on the GAM - the Prebid's one or another ad source on GAM. + +**Step 6** The winner is displayed in the app with the respective rendering engine. + +Prebid Rendering API supports these ad formats: + +- Display Banner +- Video Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video + +[//]: # (- Native) +[//]: # (- Native Styles) + +They can be integrated using these API categories. + +- [**Banner API**](#banner-api) - for *Display Banner* and *Outstream Video* +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* + +[//]: # (- [**Native API**](android-sdk-integration-gam-native.html) - for *Native Ads*) + + +## Init Prebid Rendering Module + +To start running bid requests you have to set the Prebid Server **Host** and **Account Id** and then initilize the SDK with application context. The best place for this is the `onCreate()` method of your Application class. + +``` +PrebidMobile.setBidServerHost(HOST) +PrebidMobile.setAccountId(YOUR_ACCOUNT_ID) + +// Init SDK +PrebidMobile.setApplicationContext(this) +``` + +> **NOTE:** The account ID is an identifier of the **Stored Request**. + +### Event Handlers + +GAM Event Handlers is a set of classes that wrap the GAM Ad Units and manage them respectively to the In-App Bidding flow. These classes are provided in the form of library that could be added to the app via Gradle: + +Root build.gradle + +``` +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +App module build.gradle: + +``` +implementation('org.prebid:prebid-mobile-sdk-gam-event-handlers:x.x.x') +``` + + +## Banner API + +To integrate the banner ad you need to implement three easy steps: + + +``` kotlin +// 1. Create banner custom event handler for GAM ad server. +val eventHandler = GamBannerEventHandler(requireContext(), GAM_AD_UNIT, GAM_AD_SIZE) + +// 2. Create a bannerView instance and provide GAM event handler +bannerView = BannerView(requireContext(), configId, eventHandler) +// (Optional) set an event listener +bannerView?.setBannerListener(this) + +// Add bannerView to your viewContainer +viewContainer?.addView(bannerView) + +// 3. Execute ad loading +bannerView?.loadAd() +``` + +#### Step 1: Create Event Handler + +GAM's event handlers are special containers that wrap GAM Ad Views and help to manage collaboration between GAM and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create the event handler you should provide a GAM Ad Unit Id and the list of available sizes for this ad unit. + +#### Step 2: Create Ad View + +**BannerView** - is a view that will display the particular ad. It should be added to the UI. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - the instance of the banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +And assign the listeners for processing ad events. + +#### Step 3: Load the Ad + +Simply call the `loadAd()` method to start [In-App Bidding](../android-in-app-bidding-getting-started.html) flow. The In-App Bidding SDK starts the bidding process right away. + +### Outstream Video + +For **Outstream Video** you also need to specify video placement type of the expected ad: + +``` kotlin +bannerView.videoPlacementType = PlacementType.IN_BANNER // or any other available type +``` + +### Migration from the original API + +GAM setup: +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: +1. Replace the `AdManagerAdView` with `BannerView` in the UI. +3. Implement the interface `BannerViewListener`. +4. Remove usage of `AdManagerAdView`, `AdManagerAdRequest`, and implementation of the `AdListener`. +5. Remove original `BannerAdUnit`. +6. Follow the instructions to integrate [Banner API](#banner-api). + + +## Interstitial API + +To integrate interstitial ad you need to implement four easy steps: + + +``` kotlin +// 1. Create interstitial custom event handler for GAM ad server. +val eventHandler = GamInterstitialEventHandler(requireContext(), gamAdUnit) + +// 2. Create interstitialAdUnit instance and provide GAM event handler +interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, minSizePercentage, eventHandler) +// (Optional) set an event listener +interstitialAdUnit?.setInterstitialAdUnitListener(this) + +// 3. Execute ad load +interstitialAdUnit?.loadAd() + +//.... + +// 4. After ad is loaded you can execute `show` to trigger ad display +interstitialAdUnit?.show() + +``` + +The **default** ad format for interstitial is **DISPLAY**. In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter. + +``` +interstitialAdUnit = InterstitialAdUnit( + requireContext(), + configId, + EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO), + eventHandler) +``` + + +#### Step 1: Create Event Handler + +GAM's event handlers are special containers that wrap the GAM Ad Views and help to manage collaboration between GAM and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a GAM Ad Unit. + +#### Step 2: Create Interstitial Ad Unit + +**InterstitialAdUnit** - is an object that will load and display the particular ad. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **minSizePercentage** - specifies the minimum width and height percent an ad may occupy of a device’s real estate. +- **eventHandler** - the instance of the interstitial event handler + +Also, you can assign the listeners for processing ad events. + +> **NOTE:** minSizePercentage - plays an important role in a bidding process for display ads. If provided space is not enough demand partners won't respond with the bids. + + +#### Step 3: Load the Ad + +Simply call the `loadAd()` method to start [In-App Bidding](../android-in-app-bidding-getting-started.html) flow. The ad unit will load an ad and will wait for explicit instructions to display the Interstitial Ad. + + +#### Step 4: Show the Ad when it is ready + + +The most convenient way to determine if the interstitial ad is ready for displaying is to listen to the particular listener method: + +``` kotlin +override fun onAdLoaded(interstitialAdUnit: InterstitialAdUnit) { +//Ad is ready for display +} +``` + +### Migration from the original API + +GAM setup: +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: +1. Replace the `AdManagerInterstitialAd` with `InterstitialRenderingAdUnit`. +3. Implement the interface `InterstitialEventListener`. +4. Remove usage of `AdManagerInterstitialAd`, `AdManagerAdRequest`. +5. Remove original `InterstitialAdUnit`. +6. Follow the instructions to integrate [Interstitial API](#interstitial-api). + + +## Rewarded API + +To display an Rewarded Ad need to implement four easy steps: + + +``` kotlin +// 1. Create rewarded custom event handler for GAM ad server. +val eventHandler = GamRewardedEventHandler(requireActivity(), gamAdUnitId) + +// 2. Create rewardedAdUnit instance and provide GAM event handler +rewardedAdUnit = RewardedAdUnit(requireContext(), configId, eventHandler) + +// (Optional) set an event listener +rewardedAdUnit?.setRewardedAdUnitListener(this) + +// 3. Execute ad load +rewardedAdUnit?.loadAd() + +//... + +// 4. After ad is loaded you can execute `show` to trigger ad display +rewardedAdUnit?.show() +``` + +The way of displaying the **Rewarded Ad** is totally the same as for the Interstitial Ad. You can customize a kind of ad: + + +To be notified when user earns a reward - implement `RewardedAdUnitListener` interface: + +``` kotlin + fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit) +``` + +The actual reward object is stored in the `RewardedAdUnit`: + +``` kotlin +val reward = rewardedAdUnit.getUserReward() +``` + +#### Step 1: Create Event Handler + +GAM's event handlers are special containers that wrap the GAM Ad Views and help to manage collaboration between GAM and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a GAM Ad Unit. + + +#### Step 2: Create Rewarded Ad Unit + +**RewardedAdUnit** - is an object that will load and display the particular ad. To create it you should provide + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - the instance of rewarded event handler + +Also, you can assign the listener for processing ad events. + + +#### Step 3: Load the Ad + +Simply call the `loadAd()` method to start an In-App Bidding flow. The ad unit will load an ad and will wait for explicit instructions to display the Rewarded Ad. + + +#### Step 4: Show the Ad when it is ready + + +The most convenient way to determine if the ad is ready for displaying is to listen for particular listener method: + +``` kotlin +override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) { +//Ad is ready for display +} +``` + +### Migration from the original API + +GAM setup: +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: +1. Replace the `RewardedAd` with `RewardedAdUnit`. +2. Implement the interface `RewardedAdUnitListener`. +3. Remove original `RewardedVideoAdUnit`. +4. Follow the instructions to integrate [Rewarded API](#rewarded-api). diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-max.md b/prebid-mobile/modules/rendering/android-sdk-integration-max.md new file mode 100644 index 0000000000..612ed65eb6 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-max.md @@ -0,0 +1,347 @@ +--- +layout: page_v2 +title: AppLovin MAX Integration +description: Integration of Prebid Rendering module whith AppLovin MAX +sidebarType: 2 +--- + +# AppLovin MAX Integration + +The integration of Prebid Mobile with AppLovin MAX assumes that publisher has MAX account and has already integrated the AppLovin MAX SDK into the app. + +See the [AppLovin MAX Documentation](https://dash.applovin.com/documentation/mediation/android/getting-started/integration) for the MAX integration details. + +## MAX Integration Overview + +![Rendering with MAX](/assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-max.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** MAX SDK makes an ad request. MAX returns the waterfall with respective placements. + +**Step 4** For each prebid's placement, the MAX SDK sequentially instantiates an adapter. + +**Step 5** The adapter verifies the targeting keywords of the winning bid and the custom properties of the given placement. If they match the adapter will render the winning bid. Otherwise, adpater will fail with "no ad" immediately and the next placement will instantiate the same adapter but for another custom properties. + +Prebid Mobile supports these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Native + +They can be integrated using these API categories: + +- [**Banner API**](#banner-api) - for *Display* Banner +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* +- [**Native API**](#native-ads) - for *Native Ads* + +## Init Prebid Rendering Module + +To start running bid requests you have to set the Prebid Server **Host** and **Account Id** and then initilize the SDK with application context. The best place for this is the `onCreate()` method of your Application class. + +``` +PrebidMobile.setBidServerHost(HOST) +PrebidMobile.setAccountId(YOUR_ACCOUNT_ID) + +// Init SDK +PrebidMobile.setApplicationContext(this) +``` + +> **NOTE:** The account ID is an identifier of the **Stored Request**. + +### Prebid Adapters + +To integrate Prebid Adapters just add the following lines into your build.gradle files: + +Root build.gradle + +``` +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +App module build.gradle: + +``` +implementation('org.prebid:prebid-mobile-sdk-max-adapters:x.x.x') +``` + +## Banner API + +Integration example: + +``` kotlin +// 1. Create MaxAdView +adView = MaxAdView(adUnitId, requireContext()) +adView?.setListener(createListener()) + +// 2. Create MaxMediationBannerUtils +val mediationUtils = MaxMediationBannerUtils(adView) + +// 3. Create MediationBannerAdUnit +adUnit = MediationBannerAdUnit( + requireContext(), + configId, + AdSize(width, height), + mediationUtils +) + +// 4. Make a bid request +adUnit?.fetchDemand { + + // 5. Make an ad request to MAX + adView?.loadAd() +} +``` + +#### Step 1: Create MaxAdView + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/android/getting-started/banners#loading-and-showing-banners-programmatically). You don't have to make any modifications here. + + +#### Step 2: Create MaxMediationBannerUtils + +The `MaxMediationBannerUtils` is a helper class, wich performs certain utilty work for the `MediationBannerAdUnit`, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationBannerAdUnit + +The `MediationBannerAdUnit` is a part of Prebid mediation API. This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by prebid adapters. + +## Interstitial API + +Integration example: + +``` kotlin +// 1. Create MaxInterstitialAd +maxInterstitialAd = MaxInterstitialAd(adUnitId, activity) +maxInterstitialAd?.setListener(createListener()) + +// 2. Create MaxMediationInterstitialUtils +val mediationUtils = MaxMediationInterstitialUtils(maxInterstitialAd) + +// 3. Create MediationInterstitialAdUnit +adUnit = MediationInterstitialAdUnit( + activity, + configId, + EnumSet.of(AdUnitFormat.DISPLAY), + mediationUtils + ) + +// 4. Make a bid request +adUnit?.fetchDemand { + + // 5. Make an ad request to MAX + maxInterstitialAd?.loadAd() +} + +``` + +The **default** ad format for interstitial is **DISPLAY**. In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter. + +``` +adUnit = MediationInterstitialAdUnit( + activity, + configId, + EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO), + mediationUtils + ) +``` + +#### Step 1: Create MaxInterstitialAd + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/android/getting-started/interstitials). You don't have to make any modifications here. + + +#### Step 2: Create MaxMediationInterstitialUtils + +The `MaxMediationInterstitialUtils` is a helper class, wich performs certain utilty work for the `MediationInterstitialAdUnit`, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationInterstitialAdUnit + +The `MediationInterstitialAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid to the mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 6: Display an ad + +Once you receive the ad it will be ready for display. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/android/getting-started/interstitials#showing-an-interstitial-ad) about how to do it. + +## Rewarded API + +Integration example: + +``` swift +// 1. Get an instance of MaxRewardedAd +maxRewardedAd = MaxRewardedAd.getInstance(adUnitId, activity) +maxRewardedAd?.setListener(createListener()) + +// 2. Create MaxMediationRewardedUtils +val mediationUtils = MaxMediationRewardedUtils(maxRewardedAd) + +// 3. Create MediationRewardedVideoAdUnit +adUnit = MediationRewardedVideoAdUnit( + activity, + configId, + mediationUtils + ) + +// 4. Make a bid request +adUnit?.fetchDemand { + + // 5. Make an ad request to MAX + maxRewardedAd?.loadAd() +} +``` + +The way of displaying the rewarded ad is the same as for the Interstitial Ad. + +To be notified when user earns a reward follow the [MAX intructions](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads#accessing-the-amount-and-currency-for-a-rewarded-ad). + +#### Step 1: Get an instance of MaxRewardedAd + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads). You don't have to make any modifications here. + +#### Step 2: Create MaxMediationRewardedUtils + +The `MaxMediationRewardedUtils` is a helper class, wich performs certain utilty work for the `MediationRewardedVideoAdUnit`, like passing the targeting keywords to the adapters. + +#### Step 3: Create MediationRewardedVideoAdUnit + +The `MediationRewardeVideoAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 6: Display an ad + +Once the rewarded ad is recieved you can display it. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads#showing-a-rewarded-ad) for the details. + +## Native Ads + +Integration example: + +``` +// 1. Create MaxNativeAdLoader +nativeAdLoader = MaxNativeAdLoader(adUnitId, requireActivity()) +nativeAdLoader.setNativeAdListener(createNativeAdListener(viewContainer)) +nativeAdLoader.setRevenueListener(createRevenueListener()) + +// 2. Create and configure MediationNativeAdUnit +nativeAdUnit = NativeAdUnit(configId) + +nativeAdUnit.setContextType(NativeAdUnit.CONTEXT_TYPE.SOCIAL_CENTRIC) +nativeAdUnit.setPlacementType(NativeAdUnit.PLACEMENTTYPE.CONTENT_FEED) +nativeAdUnit.setContextSubType(NativeAdUnit.CONTEXTSUBTYPE.GENERAL_SOCIAL) + +// 3. Set up assets for bid request +// See the code below + +// 4. Set up event tracker for bid request +// See the code below + +// 5. Make a bid request +nativeAdUnit.fetchDemand(nativeAdLoader) { +// 6. Make an ad request to MAX + self?.nativeAdLoader?.loadAd(into: self?.createNativeAdView()) +} +``` + +#### Step 1: Create MaxNativeAdLoader + +Prepare the `MaxNativeAdLoader` object before you make a bid request. It will be needed for prebid mediation utils. + +#### Step 2: Create and configure NativeAdUnit + +The `NativeAdUnit` class is responsible for making a bid request and providing a winning bid and targeting keywords. Fot the better targetting you should provide additional properties like `conteaxtType` and `placemantType`. + +#### Step 3: Set up assets for bid request + +The bid request for native ads should have the description of expected assets. The full spec for the native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the assets array: + +``` +val title = NativeTitleAsset() +title.setLength(90) +title.isRequired = true +nativeAdUnit.addAsset(title) + +val icon = NativeImageAsset(20, 20, 20, 20) +icon.imageType = NativeImageAsset.IMAGE_TYPE.ICON +icon.isRequired = true +nativeAdUnit.addAsset(icon) + +val image = NativeImageAsset(200, 200, 200, 200) +image.imageType = NativeImageAsset.IMAGE_TYPE.MAIN +image.isRequired = true +nativeAdUnit.addAsset(image) + +val data = NativeDataAsset() +data.len = 90 +data.dataType = NativeDataAsset.DATA_TYPE.SPONSORED +data.isRequired = true +nativeAdUnit.addAsset(data) + +val body = NativeDataAsset() +body.isRequired = true +body.dataType = NativeDataAsset.DATA_TYPE.DESC +nativeAdUnit.addAsset(body) + +val cta = NativeDataAsset() +cta.isRequired = true +cta.dataType = NativeDataAsset.DATA_TYPE.CTATEXT +nativeAdUnit.addAsset(cta) +``` + +#### Step 4: Set up event tracker for bid request + +The bid request for mative ads may have a descrition of expected event trackers. The full spec for the Native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the event trackers array: + +``` +val methods: ArrayList = ArrayList() +methods.add(NativeEventTracker.EVENT_TRACKING_METHOD.IMAGE) +methods.add(NativeEventTracker.EVENT_TRACKING_METHOD.JS) +try { + val tracker = NativeEventTracker(NativeEventTracker.EVENT_TYPE.IMPRESSION, methods) + nativeAdUnit.addEventTracker(tracker) +} catch (e: Exception) { + e.printStackTrace() +} +``` + +#### Step 5: Make a bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 6: Load Native ad + +Now just load a native ad from MAX according to the [MAX instructions](https://dash.applovin.com/documentation/mediation/android/getting-started/native-manual#load-the-native-ad). diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-pb-native.md b/prebid-mobile/modules/rendering/android-sdk-integration-pb-native.md new file mode 100644 index 0000000000..fe371eb36e --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-pb-native.md @@ -0,0 +1,159 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Pure In-App Bidding Native Ads Integration +description: Integration of native ads for pure In-App Bidding scenario +sidebarType: 2 + +--- + +# Prebid Rendering: Native Ads Integration + +## Native Ads + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout. +2. Create Native Ad Unit. +3. Configure the Native Ad unit using [NativeAdConfiguration](rendering-native-ad-configuration.html). + * Provide the list of **[Native Assets](rendering-native-guidelines.html#components)** representing the ad's structure. + * Tune other general properties of the ad. +4. Make a bid request. +5. Extract NativeAd using `NativeUtils.findNativeAd` +7. Bind the data from the native ad with the layout. + +``` kotlin +nativeAdUnit?.fetchDemand { + if (it.fetchDemandResult != FetchDemandResult.SUCCESS) { + return@fetchDemand + } + NativeUtils.findNativeAd(it) { nativeAd -> + if (nativeAd == null) { + return@findNativeAd + } + inflateViewContentWithPrebid(nativeAd) + } +} +``` + +## Native Styles + +[See Native Ads Guidelines page](rendering-native-guidelines.html) for more details about SDK integration and supported ad types. + +To display an ad using Native Styles you'll need to implement these easy steps: + +``` kotlin +// 1. Create an Ad View +bannerView = BannerView(requireContext(), configId, adSize) +bannerView?.setBannerListener(this) + +// 2. Provide NativeAdConfiguration +val nativeAdConfiguration = createNativeAdConfiguration() +bannerView?.setNativeAdConfiguration(nativeAdConfiguration) + +// Add view to viewContainer +viewContainer?.addView(bannerView) + +// 3. Load ad +bannerView?.loadAd() +``` + +#### Step 1: Create Ad View + +In the Pure In-App Bidding scenario you just need to initialize the Banner Ad View using correct properties: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **size** - the size of the ad unit which will be used in the bid request. + +#### Step 2: Create and provide NativeAdConfiguration + +NativeAdConfiguration creation example: + +``` kotlin +private fun createNativeAdConfiguration(): NativeAdConfiguration { + val nativeAdConfiguration = NativeAdConfiguration() + nativeAdConfiguration.contextType = NativeAdConfiguration.ContextType.SOCIAL_CENTRIC + nativeAdConfiguration.placementType = NativeAdConfiguration.PlacementType.CONTENT_FEED + nativeAdConfiguration.contextSubType = NativeAdConfiguration.ContextSubType.GENERAL_SOCIAL + + val methods = ArrayList() + methods.add(NativeEventTracker.EventTrackingMethod.IMAGE) + methods.add(NativeEventTracker.EventTrackingMethod.JS) + val eventTracker = NativeEventTracker(NativeEventTracker.EventType.IMPRESSION, methods) + nativeAdConfiguration.addTracker(eventTracker) + + val assetTitle = NativeAssetTitle() + assetTitle.len = 90 + assetTitle.isRequired = true + nativeAdConfiguration.addAsset(assetTitle) + + val assetIcon = NativeAssetImage() + assetIcon.type = NativeAssetImage.ImageType.ICON + assetIcon.wMin = 20 + assetIcon.hMin = 20 + assetIcon.isRequired = true + nativeAdConfiguration.addAsset(assetIcon) + + val assetImage = NativeAssetImage() + assetImage.hMin = 20 + assetImage.wMin = 200 + assetImage.isRequired = true + nativeAdConfiguration.addAsset(assetImage) + + val assetData = NativeAssetData() + assetData.len = 90 + assetData.type = NativeAssetData.DataType.SPONSORED + assetData.isRequired = true + nativeAdConfiguration.addAsset(assetData) + + val assetBody = NativeAssetData() + assetBody.isRequired = true + assetBody.type = NativeAssetData.DataType.DESC + nativeAdConfiguration.addAsset(assetBody) + + val assetCta = NativeAssetData() + assetCta.isRequired = true + assetCta.type = NativeAssetData.DataType.CTA_TEXT + nativeAdConfiguration.addAsset(assetCta) + + nativeAdConfiguration.nativeStylesCreative = nativeStylesCreative + + return nativeAdConfiguration +} +``` + +Native Styles creative example: + +``` html + + + +``` + +See more NativeAdConfiguration options [here](rendering-native-ad-configuration.html). + +**IMPORTANT:** + +You should add HTML and CSS to define your native ad template with universal creative and provide it via NativeAdConfiguration. + +#### Step 3: Load the Ad + +Call `loadAd()` and SDK will: + +- make bid request to Prebid server +- render the winning bid on display diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-pb.md b/prebid-mobile/modules/rendering/android-sdk-integration-pb.md new file mode 100644 index 0000000000..ad10e372a0 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-pb.md @@ -0,0 +1,186 @@ +--- + +layout: page_v2 +title: Custom or No mediation +description: Integration of Prebid SDK withou primaty Ad Server +sidebarType: 2 + +--- + +# Custom Integration + +## Table of Contents + +- [Overview of Rendering API](#mobile-api) +- [Banner](#banner-api) +- [Interstitial](#interstitial-api) +- [Rewarded](#rewarded-api) + +[//]: # (- [Native](android-sdk-integration-pb-native.html)) + +## Overview of Rendering API + +The integration and usage of the Rendering API are similar to any other Ad SDK. It sends the bid requests to the Prebid Server and renders the winning bid. + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-Pure-Prebid.png) + +Prebid's Rendering API provides the ability to integrate these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Outstream Video + +[//]: # (- [Native](android-sdk-integration-pb-native.html)) + +The Rendering API ad formats are accessible through the following API classes: + +- **Banner API** - for **Display** and **Video** Banners +- **Interstitial API** - for **Display** and **Video** Interstitials +- **Rewarded API** - for **Rewarded Video** + +### Init Prebid Rendering Module + +To start running bid requests you have to set the Prebid Server **Host** and **Account Id** and then initilize the SDK with application context. The best place for this is the `onCreate()` method of your Application class. + +``` +PrebidMobile.setBidServerHost(HOST) +PrebidMobile.setAccountId(YOUR_ACCOUNT_ID) + +// Init SDK +PrebidMobile.setApplicationContext(this) +``` + +> **NOTE:** The account ID is an identifier of the **Stored Request**. + +### Banner API + +Integration example: + + +``` kotlin +// 1. Create an Ad View +bannerView = BannerView(requireContext(), configId, adSize) +bannerView?.setBannerListener(this) + +// Add view to viewContainer +viewContainer?.addView(bannerView) + +// 2. Load ad +bannerView?.loadAd() +``` + +#### Step 1: Create Ad View + +Initialize the `BannerAdView` with properties: + +- `configId` - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- `size` - the size of the ad unit which will be used in the bid request. + +#### Step 2: Load the Ad + +Call `loadAd()` and SDK will: + +- make bid request to Prebid +- render the winning bid on display + +#### Outstream Video + +For **Banner Video** you will also need to specify the `bannerView.videoPlacementType`: + +``` kotlin +bannerView.videoPlacementType = PlacementType.IN_BANNER // or any other available type +``` + +### Interstitial API + +Integration example: + +``` kotlin +// 1. Create an Interstitial Ad Unit +interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, minSizePercentage) +interstitialAdUnit?.setInterstitialAdUnitListener(this) + +// 2. Load Ad +interstitialAdUnit?.loadAd() +// ..... + +// 3. Show the ad +interstitialAdUnit?.show() +``` + +The **default** ad format for interstitial is **DISPLAY**. In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter. + +``` +interstitialAdUnit = InterstitialAdUnit( + requireContext(), + configId, + EnumSet.of(AdUnitFormat.DISPLAY, AdUnitFormat.VIDEO)) +``` + +#### Step 1: Create an Ad Unit + +Initialize the `InterstitialAdUnit ` with properties: + +- `configId` - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- `minSizePercentage` - specifies the minimum width and height percent an ad may occupy of a device’s real estate. + +You can also assign the listener for processing ad events. + +> **NOTE:** the `minSizePercentage` - plays an important role in a bidding process for display ads. If provided space is not enough demand partners won't respond with the bids. + +#### Step 2: Load the Ad + +Call the `loadAd()` method which will make a request to Prebid server. + + +#### Step 3: Show the Ad when it is ready + +Wait until the ad is loaded and present it to the user in any suitable time. + +``` kotlin +override fun onAdLoaded(interstitialAdUnit: InterstitialAdUnit) { + //Ad is ready for display +} +``` + +### Rewarded API + +Integration example: + +``` kotlin +// 1. Create an Ad Unit +rewardedAdUnit = RewardedAdUnit(requireContext(), configId) +rewardedAdUnit?.setRewardedAdUnitListener(this) + +// 2. Execute ad load +rewardedAdUnit?.loadAd() + +/// ....... + +// After ad is loaded you can execute `show` to trigger ad display +rewardedAdUnit?.show() +``` + +#### Step 1: Create Rewarded Ad Unit + +Create the `RewardedAdUnit` object with parameters: + +- `adUnitId` - an ID of Stored Impression on the Prebid server. + +#### Step 2: Load the Ad + +Call the `loadAd()` method which will make a request to Prebid server. + + +#### Step 3: Show the Ad when it is ready + + +Wait until the ad is loaded and present it to the user in any suitable time. + +``` kotlin +override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) { +//Ad is ready for display +} +``` diff --git a/prebid-mobile/modules/rendering/android-sdk-integration.md b/prebid-mobile/modules/rendering/android-sdk-integration.md new file mode 100644 index 0000000000..bc0573ad96 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration.md @@ -0,0 +1,81 @@ +--- + +layout: page_v2 +title: Integrating the Android SDK +description: Prebid Android Rendering SDK Integration +sidebarType: 2 + +--- + +# Integrating the Android SDK with your project + +## Gradle Integration + + +To add the dependency, open your project and update the app module’s build.gradle to have the following repositories and dependencies: + +``` +allprojects { + repositories { + ... + google() + mavenCentral() + ... + } +} + +// ... + +dependencies { + ... + implementation('org.prebid:prebid-mobile-sdk:2.0.0') + ... +} +``` + +## Updating your Android manifest + + +Before you start, you need to integrate the SDK by updating your Android manifest. + +1. Open your AndroidManifest.xml and add the following permissions and activity declarations according to the bundle you are integrating. + +``` xml + + + + + +``` + + **Notes:** + + - `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` will + automatically allow the device to send user location for + targeting, which can help increase revenue by increasing the + value of impressions to buyers. + - `WRITE_EXTERNAL_STORAGE` is optional and only required for MRAID + 2.0 storePicture ads. + +2. For *banner and interstitial ads only*, include the following custom activities (even though you won't instantiate them directly). This is not necessary for video interstitial ads. + + Custom Activities: + +``` xml + +``` + +**NOTE** +>Interstitial ads are implemented in a dialog. For proper interstitial workflow it is recommended to use a separate Activity with `configChanges` attribute specified to avoid any issues which may occur on orientation change. +> See above example with `configChanges` attribute. + +3. Add this tag to your `` to use Google Play Services: + + ``` xml + +``` diff --git a/prebid-mobile/modules/rendering/android-sdk-parameters.md b/prebid-mobile/modules/rendering/android-sdk-parameters.md new file mode 100644 index 0000000000..c32c11e1f6 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-parameters.md @@ -0,0 +1,81 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# Parameters + +The tables below list the methods and properties that the Prebid Rendering API allows to customize. +The more actual info about the user, the app, and the device you provide the more chances to win an impression. + +Please strictly follow the recommendations in the below tables and provide all ❗ **Required** and **Highly Recommended** values. + + +1. [Targeting](#targeting) +2. [PrebidRenderingSettings](#prebidrenderingsettings) + +## Targeting + +{: .table .table-bordered .table-striped } + +| **Parameter** | **Method** | Description | Required?| +| -------------------------- | ------------------------- | ------------------------------------------------------------ | -------- | +| age | `setUserAge` | Age of the user in years. For example: `35` | ❗ Highly Recommended | +| buyerid | `setBuyerId` | Buyer-specific ID for the user as mapped by the exchange for the buyer. | Optional | +| crr | `setCarrier` | Mobile carrier - Defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: -. For example: `"310-410"` | Optional | +| customdata | `setUserCustomData` | Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional | +| dma | `setDma` | A designated market are. For US locations, indicates the end-user's Designated Market Area. For example: dma=803. | Optional | +| ext | `setUserExt` | Placeholder for exchange-specific extensions to OpenRTB. | Optional | +| gen | `setUserGender` | The gender of the user (Male, Female, Other, Unknown). For example: `Gender.FEMALE` | ❗ Highly Recommended | +| inc | `setUserAnnualIncomeInUs` | Annual income of the user in US dollars. For example: `55000`| ❗ Highly Recommended | +| ip | `setDeviceIpAddress` | The IP address of the carrier gateway. If this is not present, Prebid Rendering retrieves it from the request header. For example: `"192.168.0.1"` | ❗ Highly Recommended | +| keywords | `setUserKeywords` | Comma separated list of keywords, interests, or intent. | Optional | +| lat, lon | `setUserLatLng` | Location of the user’s home base defined by a provided longitude and latitude. It's highly recommended to provide Geo data to improve the request.| Optional | +| publisher | `setPublisherName` | Publisher name (may be aliased at the publisher’s request).| Recommended if available | +| url/storeurl | `setAppStoreMarketUrl` | The URL for the mobile application in Google Play. That field is required in the request.
    **For example:**` https://play.google.com/store/apps/details?id=com.outfit7.talkingtom`. | ❗ Required | +| xid | `setUserId` | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended | + +## How to set user parameters + +You can use `Targeting` to pass ad call request parameters. + +``` java +// Set user parameters to enrich ad request data. +// Please see Targeting for the userKeys and the APIs available. +Targeting.setUserKeywords("socialNetworking"); +Targeting.setUserAge(18); +Targeting.setUserAnnualIncomeInUs(50000); + +// Set parameters. +// Targeting.setCustomParameters(Hashtable params) +// Targeting.setParameters(Hashtable params) +// clear parameters +// Targeting.clearParameters() +// Targeting.clearParameter(String key) +``` + +## Custom key-value parameters + +You can submit values through `Targeting` for the extended (`c.xxx`) ad-call +parameters. + +{: .table .table-bordered .table-striped } + +| **Parameter** | **Method** | **Description** | +| ----------------------- | ------------------- | ------------------------------------------------------------ | +| custom
    parameter | setCustomParameter | A custom user parameter auto-prepended with c..
    You should provide the plain name of the parameter, such as xxx, which will be changed to c.xxx when sent. | +| custom
    parameters | setCustomParameters | Custom user parameters, which consist of a dictionary of name-value parameter pairs, where each param name will be automatically prepended with c.. | + +## PrebidRenderingSettings + +{: .table .table-bordered .table-striped } + +| **Field** | **Description** | **Default** | +| ----------------------- | ------------------------------------------------------------ | ----------- | +| defaultAutoRefreshDelay | Controls the initial value of `autoRefreshDelay` for all newly created BannerAdViews in seconds. | 60 | +| logLevel | Controls the type of messages of the internal logger. Options are:
    - DEBUG - this is the noisiest level.
    - ERROR
    - WARN
    - NONE | NONE | +| sendMRAIDSupportParams | If `true`, the SDK sends "`af=3,5`", indicating support for MRAID. | true | diff --git a/prebid-mobile/modules/rendering/ios-sdk-Integration.md b/prebid-mobile/modules/rendering/ios-sdk-Integration.md new file mode 100644 index 0000000000..eb7083258d --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-Integration.md @@ -0,0 +1,57 @@ +--- + +layout: page_v2 +title: Integrating the Android SDK +description: Prebid Android Rendering SDK Integration +sidebarType: 2 + +--- + +# Code Integration for iOS + + +## CocoaPods integration + +Starting with v2.0.0 the Rendering API is a part of Prebid Mobile SDK. Add the following item into your podfile to integrate it: + +``` +pod 'PrebidMobile' +``` + +If you need to integrate Prebid with GAM, AdMob or AppLovin MAX add these pods respectively + +``` +# + Google Ad Manager (optional) +pod 'PrebidMobileGAMEventHandlers' + +# + AdMob (optional) +pod 'PrebidMobileAdMobAdapters' + +# + MAX (optional) +pod 'PrebidMobileMAXAdapters' +``` + + +## Init Prebid Rendering + +The best place for initialization is the `application:didFinishLaunchingWithOptions` method. Import the SDK first: + +``` +import PrebidMobile +``` + +Then set the predefined or costom Prebid Server **host** and provide the **Prebid Account ID**. + +``` +Prebid.shared.prebidServerHost = HOST +Prebid.shared.prebidServerAccountId = YOUR_ACCOUNT_ID +``` + +And initialize the SDK: + +``` +Prebid.initializeSDK() +``` + + + diff --git a/prebid-mobile/modules/rendering/ios-sdk-customization-controls.md b/prebid-mobile/modules/rendering/ios-sdk-customization-controls.md new file mode 100644 index 0000000000..4a3e951d8d --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-customization-controls.md @@ -0,0 +1,72 @@ +--- + +layout: page_v2 +title: Ad Experience Controls +description: Approaches for changing the ad expirience +sidebarType: 2 + +--- + +# Ad Experience Controls + +Prebid SDK provides an API way to customize its behaviour. + +> NOTE: In the nearest future the Server Side Configuration will be supported as well. Follow this [feature request](https://github.com/prebid/prebid-server/issues/2186) for the details. + + +## Rendering Controls + +The following properties allow to customize the rendering of Video Interstitial Ads. + +### Max Video Duration + +The `videoParameters.maxDuration` indicates the maximum available playback time in seconds. +If the value in the **Duration** tag is bigger than the given value SDK will fail to load ad, providing a respective error message. + +### Application Muted + +The `isMuted` property indicates whether the ad should run playback with sound or not. +Default value - **false**. + +### Close Button Area + +The `closeButtonArea` property indicates the percent of device screen which the close button should occupy. The possible values are from **0** to **1**. + +### Close Button Position + +The `closeButtonPosition` property indicates the position of the close button on the screen. The possible values are **TopLeft** and **TopRight**. The default value is **TopRight**. + +The example: + +![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-ios-close-button-possition-top-left.png){:width="250px"} + +### Skip Button Area + +The `skipButtonArea` property indicates the percent of device screen which the skip button should occupy. The possible values are from **0** to **1**. + +### Skip Button Position + +The `skipButtonPosition` property indicates the position of the close button on the screen. The possible values are **TopLeft** and **TopRight**. The default value is **TopLeft**. + +The example: + +![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-ios-skip-button-possition-top-left.png){:width="250px"} + +### Skip Delay + +The `skipDelay` property indicates the number of seconds which should be passed from the start of playback until the skip or close button should be shown. The default value is **10**. + +The code sample: + +``` swift +interstitialController = InterstitialRenderingAdUnit(configID: prebidConfigId, + minSizePercentage: CGSize(width: 30, height: 30)) +interstitialController?.delegate = self +interstitialController?.videoParameters.maxDuration = SingleContainerInt(integerLiteral: 30) +interstitialController?.closeButtonArea = 0.1 +interstitialController?.skipDelay = 5 +interstitialController?.skipButtonArea = 0.1 +interstitialController?.skipButtonPosition = .topRight +interstitialController?.closeButtonPosition = .topRight +``` + diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-admob.md b/prebid-mobile/modules/rendering/ios-sdk-integration-admob.md new file mode 100644 index 0000000000..e9b233a256 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-admob.md @@ -0,0 +1,428 @@ +--- +layout: page_v2 +title: Google Ad Manager Integration +description: Integration of Prebid Rendering module whith Google Ad Manager +sidebarType: 2 +--- + +# AdMob Integration + +The integration of Prebid Mobile with Google AdMob assumes that publisher has an AdMob account and has already integrated the Google Mobile Ads SDK (GMA SDK) into the app. + +See the [Google Integration Documentation](https://developers.google.com/admob/ios/quick-start) for the AdMob integration details. + + +{: .alert.alert-warning :} +**Warning:** The `GADMobileAds.sharedInstance().start()` should be called in the adapters bundle, otherwise, GMA SDK won't load the ads with error: `adView:didFailToReceiveAdWithError: SDK tried to perform a networking task before being initialized.` + +To avoid the error add the following line to your app right after initialization of GMA SDK: + +``` +GAMUtils.shared.initializeGAM() +``` + +Prebid is integrated into the AdMob monetization via adapters. + +## AdMob Integration Overview + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-admob.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** GMA SDK makes an ad request. AdMob returns the mediation chain with respective ad sources. + +**Step 4** For each prebid's ad source, the GMA SDK sequentially instantiates an adapter. + +**Step 5** The adapter verifies the targeting keywords of the winning bid and the server properties of the given ad source. If they match adapter will render the winning bid. Otherwise, it will fail with "no ad" immediately and the next ad source will instantiate the same adapter but for another set of server parpams. + +Prebid Mobile supports these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Native + +They can be integrated using these API categories: + +- [**Banner API**](#banner-api) - for *Display* Banner +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* +- [**Native API**](#native-ads) - for *Native Ads* + + +## Banner API + +Integration example: + +``` swift +// 1. Create GADRequest and GADBannerView +gadRequest = GADRequest() + +gadBanner = GADBannerView(adSize: size) +gadBanner.delegate = self +gadBanner.rootViewController = self + +gadBanner.adUnitID = adUnitId + +// 2. Create AdMobMediationBannerUtils +mediationDelegate = AdMobMediationBannerUtils(gadRequest: gadRequest, + bannerView: gadBanner) + +// 3. Create MediationBannerAdUnit +prebidAdMobMediaitonAdUnit = MediationBannerAdUnit(configID: configID, + size: CGSize(width: 320, height: 50), + mediationDelegate: mediationDelegate) + +// 4. Make a bid request +prebidAdMobMediaitonAdUnit.fetchDemand { [weak self] result in + + // 5. Store the winning bid in the GADRequest extras + // You must provide a winning bid via extras to the GADRequest here. + // Prebid SDK can't do it internally. + // Otherwise, the Prebid adapter won't be able to retrieve and render the winning bid. + let extras = GADCustomEventExtras() + extras.setExtras(self?.mediationDelegate.getEventExtras(), + forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + + self?.gadRequest.register(extras) + + // 6. Make an ad request to AdMob + self?.gadBanner.load(self?.gadRequest) +} +``` + +#### Step 1: Create GADRequest and GADBannerView + +This step is totally the same as for original [AdMob integration](https://developers.google.com/admob/ios/banner). You don't have to make any modifications here. + + +#### Step 2: Create AdMobMediationBannerUtils + +The `AdMobMediationBannerUtils` is a helper class, wich performs certain utilty work for the `MediationBannerAdUnit`, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationBannerAdUnit + +The `MediationBannerAdUnit` is part of Prebid mediation API. This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Store the winning bid in the GADRequest extras + +GMA SDK doesn't provide extras to the adapter which were set not in the app scope. + +That is why you must add the code for dispatching the winning bid to the adapters. In the most cases you will just need to copy and paste the following lines inside the completion closure of the `fetchDemand()` method: + +``` +let extras = GADCustomEventExtras() + +extras.setExtras(self?.mediationDelegate.getEventExtras(), + forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + +self?.gadRequest.register(extras) +``` +Everything +Make sure that you use the proper label for extras - `AdMobConstants.PrebidAdMobEventExtrasLabel`. Prebid adapters will extract the winnig bid by this key. + +#### Step 6: Make an Ad Reuest + +Now you should make a regular AdMob's ad request. Everything else will be handled by prebid adapters. + +## Interstitial API + +Integration example: + +``` swift +// 1. Create GADRequest +gadRequest = GADRequest() + +// 2. Create AdMobMediationInterstitialUtils +mediationDelegate = AdMobMediationInterstitialUtils(gadRequest: self.gadRequest) + +// 3. Create MediationInterstitialAdUnit +admobAdUnit = MediationInterstitialAdUnit(configId: configID, + mediationDelegate: mediationDelegate!) + +// 4. Make a bid request +admobAdUnit?.fetchDemand(completion: { [weak self]result in + + // 5. Store the winning bid in the GADRequest extras + // You must provide a winning bid via extras to the GADRequest here. + // Prebid SDK can't do it internally. + // Otherwise, the Prebid adapter won't be able to retrieve and render the winning bid. + let extras = GADCustomEventExtras() + let prebidExtras = self?.mediationDelegate!.getEventExtras() + extras.setExtras(prebidExtras, forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + + self?.gadRequest.register(extras) + + // 6. Make an ad request to AdMob + GADInterstitialAd.load(withAdUnitID: adUnitID, request: self?.gadRequest) { [weak self] ad, error in + guard let self = self else { return } + if let error = error { + PBMLog.error(error.localizedDescription) + return + } + + // 7. Present the interstitial ad + self.interstitial = ad + self.interstitial?.fullScreenContentDelegate = self + self.interstitial?.present(fromRootViewController: self) + } +}) +``` + +The **default** ad format for interstitial is **.display**. In order to make a `multiformat bid request`, set the respective values into the `adFormats` property. + +``` swift +// Make bid request for video ad +adUnit?.adFormats = [.video] + +// Make bid request for both video amd disply ads +adUnit?.adFormats = [.video, .display] + +// Make bid request for disply ad (default behaviour) +adUnit?.adFormats = [.display] + +``` + + +#### Step 1: Create GADRequest + +This step is totally the same as for original [AdMob integration](https://developers.google.com/admob/ios/interstitial#swift). You don't have to make any modifications here. + + +#### Step 2: Create AdMobMediationInterstitialUtils + +The `AdMobMediationInterstitialUtils` is a helper class, wich performs certain utilty work for the `MediationInterstitialAdUnit`, like passing the targeting keywords to adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationInterstitialAdUnit + +The `MediationInterstitialAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid to the mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Store the winning bid in the GADRequest extras + +GMA SDK doesn't provide extras to the adapter which were set not in the app scope. + +That is why you must add the code for dispatching the winning bid to the adapters. In the most cases you will just need to copy and paste the following lines inside the completion closure of the `fetchDemand()` method: + + +``` +let extras = GADCustomEventExtras() +let prebidExtras = self?.mediationDelegate!.getEventExtras() +extras.setExtras(prebidExtras, forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + +self?.gadRequest.register(extras) +``` + +Make sure that you use the proper label for extras - `AdMobConstants.PrebidAdMobEventExtrasLabel`. Prebid adapters will extract the winnig bid by this key. + +#### Step 6: Make an Ad Reuest + +Now you should make a regular AdMob's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 7: Display an ad + +Once you receive the ad it will be ready for display. Folow the [AdMob instructions](https://developers.google.com/admob/ios/interstitial#swift) about how to do it. + +## Rewarded API + +Integration example: + +``` swift +// 1. Create GADRequest +let request = GADRequest() + +// 2. Create AdMobMediationInterstitialUtils +let mediationDelegate = AdMobMediationRewardedUtils(gadRequest: request) + +// 3. Create MediationInterstitialAdUnit +admobRewardedAdUnit = MediationRewardedAdUnit(configId: "12f58bc2-b664-4672-8d19-638bcc96fd5c", mediationDelegate: mediationDelegate) + +// 4. Make a bid request +admobRewardedAdUnit.fetchDemand { [weak self] result in + guard let self = self else { return } + + // 5. Make an ad request to AdMob + GADRewardedAd.load(withAdUnitID: self.admobPrebidAdUnitId, request: request) { [weak self] ad, error in + guard let self = self else { return } + if let error = error { + PBMLog.error(error.localizedDescription) + return + } + + // 6. Present the interstitial ad + self.gadRewardedAd = ad + self.gadRewardedAd?.fullScreenContentDelegate = self + DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(3)) { + self.gadRewardedAd?.present(fromRootViewController: self, userDidEarnRewardHandler: { + print("Reward user") + }) + } + } +} +``` + +The way of displaying the rewarded ad is totally the same as for the Interstitial Ad. + +To be notified when user earns a reward follow the [AdMob intructions](https://developers.google.com/admob/ios/rewarded#show_the_ad). + +#### Step 1: Create GADRequest + +This step is totally the same as for original [AdMob integration](https://developers.google.com/admob/ios/rewarded). You don't have to make any modifications here. + + +#### Step 2: Create MediationRewardedAdUnit + +The `AdMobMediationRewardedUtils` is a helper class, wich performs certain utilty work for the `MediationRewardedAdUnit`, like passing the targeting keywords to the adapters. + +#### Step 3: Create MediationInterstitialAdUnit + +The `MediationRewardedAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular AdMob's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 6: Display an ad + +Once the rewarded ad is recieved you can display it. Folow the [AdMob instructions](https://developers.google.com/admob/ios/rewarded#swift) for the details. + +## Native Ads + +{: .alert.alert-warning :} +**Warning:** If you use Native Ads you **must** integrate AdMob Adapters via the source files instead of cocoapods integration or standalone framework. The integration using framework leads to [runtime errors](https://github.com/prebid/prebid-mobile-ios/issues/516) related to the type casting. + +In order to integrate AdMob adapters just add the adapters' source files to your app project. + +Integration example: + +``` swift +// 1. Create GAD Request +gadRequest = GADRequest() + +// 2. Create AdMobMediationNativeUtils +mediationDelegate = AdMobMediationNativeUtils(gadRequest: gadRequest) + +// 3. Create and configure MediationNativeAdUnit +nativeAdUnit = MediationNativeAdUnit(configId: prebidConfigId, + mediationDelegate: mediationDelegate!) + +nativeAdUnit.setContextType(ContextType.Social) +nativeAdUnit.setPlacementType(PlacementType.FeedContent) +nativeAdUnit.setContextSubType(ContextSubType.Social) + +// 4. Set up assets for bid request +nativeAdUnit.addNativeAssets(nativeAssets) + +// 5. Set up event tracker for bid request +nativeAdUnit.addEventTracker(eventTrackers) + +// 5. Make a bid request +nativeAdUnit.fetchDemand { [weak self] result in + guard let self = self else { return } + + // 6. Store the winning bid in the GADRequest extras + // You must provide a winning bid via extras to the GADRequest here. + // Prebid SDK can't do it internally. + // Otherwise, the Prebid adapter won't be able to retrieve and render the winning bid + let extras = GADCustomEventExtras() + let prebidExtras = self.mediationDelegate?.getEventExtras() + extras.setExtras(prebidExtras, forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + self.gadRequest.register(extras) + + // 7. Load AdMob Native ad + self.adLoader = GADAdLoader(adUnitID: self.adMobAdUnitId!, + rootViewController: self.rootController, + adTypes: [ .native ], + options: nil) + + self.adLoader?.delegate = self + + // 8. Make an ad request + self.adLoader?.load(self.gadRequest) +} +``` + +#### Step 1: Create GAD Request + +Prepare the `GADRequest` object before you make a bid request. It will be needed for prebid mediation utils. + +#### Step 2: Create AdMobMediationNativeUtils + +The `AdMobMediationNativeUtils` is a helper class, wich performs certain utilty work for `MediationNativeAdUnit`, like passing the targeting keywords to adapters and checking the visibility of the ad view. + +#### Step 3: Create and configure MediationNativeAdUnit + +The `MediationNativeAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters. Fot the better targetting you should provide additional properties like `conteaxtType` and `placemantType`. + +#### Step 4: Set up assets for bid request + +The bid request for native ads should have the description of expected assets. The full spec for the native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the assets array: + +``` +let image = NativeAssetImage(minimumWidth: 200, minimumHeight: 50, required: true) +image.type = ImageAsset.Main + +let icon = NativeAssetImage(minimumWidth: 20, minimumHeight: 20, required: true) +icon.type = ImageAsset.Icon + +let title = NativeAssetTitle(length: 90, required: true) + +let body = NativeAssetData(type: DataAsset.description, required: true) + +let cta = NativeAssetData(type: DataAsset.ctatext, required: true) + +let sponsored = NativeAssetData(type: DataAsset.sponsored, required: true) + +return [icon, title, image, body, cta, sponsored] +``` + +#### Step 5: Set up event tracker for bid request + +The bid request for mative ads may have a descrition of expected event trackers. The full spec for the Native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the event trackers array: + +``` +let eventTrackers = [ + NativeEventTracker(event: EventType.Impression, + methods: [EventTracking.Image,EventTracking.js]) +] +``` + +#### Step 6: Make a bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 7: Store the winning bid in the GADRequest extras + +GMA SDK doesn't provide extras to the adapter if they were set not in the app scope. + +That is why you must add the code for dispatching the winning bid to the adapters. In the most cases you will just need to copy and paste the following lines inside the completion closure of the `fetchDemand()` method: + +``` +let extras = GADCustomEventExtras() +let prebidExtras = self?.mediationDelegate!.getEventExtras() +extras.setExtras(prebidExtras, forLabel: AdMobConstants.PrebidAdMobEventExtrasLabel) + +self?.gadRequest.register(extras) +``` + +Make sure that you use the proper label for extras - `AdMobConstants.PrebidAdMobEventExtrasLabel`. Prebid adapters will extract the winnig bid by this key. + +#### Step 8: Load AdMob Native ad + +Now just load a native ad from AdMob according to the [AdMob instructions](https://developers.google.com/admob/ios/native/start). diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-gam-native.md b/prebid-mobile/modules/rendering/ios-sdk-integration-gam-native.md new file mode 100644 index 0000000000..c8a8a53402 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-gam-native.md @@ -0,0 +1,180 @@ +--- + +layout: page_v2 +title: Native Ads Integration +description: Integration of Prebid Rendering module whith Google Ad Manager for Native Ads +sidebarType: 2 +--- + +# GAM: Native Ads Integration + +## Unified Native Ads + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout. +2. Create Native Ad Unit and appropriate GAM ad loader. +3. Configure the Native Ad unit using [NativeAdConfiguration](rendering-native-ad-configuration.md). + * Provide the list of [Native Assets](../../info-modules/rendering-native-guidelines#components) representing the ad's structure. + * Tune other general properties of the ad. +4. Make a bid request. +5. Prepare publisherAdRequest using `GAMUtils.shared.prepareRequest` +6. After receiving response from GAM - check if prebid has won and find native ad using `GAMUtils` +7. Bind the winner data from the native ad response with the layout. + +``` swift +func loadAd() { + guard let nativeAdConfig = nativeAdConfig else { + return + } + adUnit = NativeAdUnit(configID: prebidconfigID, nativeAdConfiguration: nativeAdConfig) + + adUnit?.fetchDemand { [weak self] demandResponseInfo in + guard let self = self else { + return + } + + let dfpRequest = GAMRequest() + GAMUtils.shared.prepareRequest(dfpRequest, demandResponseInfo: demandResponseInfo) + + self.adLoader = GADAdLoader(adUnitID: self.gamAdUnitId, + rootViewController: self.rootController, + adTypes: self.adTypes, + options: []) + + self.adLoader?.delegate = self + self.adLoader?.load(dfpRequest) + } +} +``` + +Example of handling NativeAd response (the same applies to Custom Native Ads): + +``` swift +func adLoader(_ adLoader: GADAdLoader, didReceive nativeAd: GADNativeAd) { + unifiedAdRequestSuccessful.isEnabled = true + customTemplateAd = nil + + let nativeAdDetectionListener = NativeAdDetectionListener { [weak self] prebidNativeAd in + guard let self = self else { + return + } + self.nativeAdLoadedButton.isEnabled = true + self.nativeAdViewBox.renderNativeAd(prebidNativeAd) + self.nativeAdViewBox.registerViews(prebidNativeAd) + self.theNativeAd = prebidNativeAd // Note: RETAIN! or the tracking will not occur! + prebidNativeAd.trackingDelegate = self + prebidNativeAd.uiDelegate = self + } onPrimaryAdWin: { [weak self] in + guard let self = self else { + return + } + self.unifiedAdWinButton.isEnabled = true + + self.nativeAdView?.removeFromSuperview() + + guard + let nibObjects = Bundle.main.loadNibNamed("UnifiedNativeAdView", owner: nil, options: nil), + let adView = nibObjects.first as? UnifiedNativeAdView + else { + assert(false, "Could not load nib file for adView") + } + + self.setAdView(adView) + + adView.renderUnifiedNativeAd(nativeAd) + } onNativeAdInvalid: { [weak self] error in + self?.nativeAdInvalidButton.isEnabled = true + } + + GAMUtils.shared.findNativeAd(for: nativeAd, + nativeAdDetectionListener:nativeAdDetectionListener) +} +``` + +## Native Styles + +The Native Styles ads are integrated with Baner API. + +Integration Example: + +``` swift +// 1. Create an Event Handler +let eventHandler = BannerEventHandler(adUnitID: GAM_AD_UNIT_ID, + validGADAdSizes: [NSValueFromGADAdSize(adSize)]) + +// 2. Create a Banner View +let banner = BannerView(configID: CONFIG_ID, + eventHandler: eventHandler) +banner.delegate = self + +// 3. Setup Native Ad Configuration +banner.nativeAdConfig = NativeAdConfiguration(testConfigWithAssets: assets) + +// 4. Load an Ad +banner.loadAd() +``` + +#### Step 1: Create Event Handler + +To create the event handler you should provide a GAM Ad Unit Id and the list of available sizes for this ad unit. + +#### Step 2: Create Ad View + +**BannerView** - is a view that will display the particular ad. It should be added to the UI. To create it you should provide: + +- **configID** - an ID of Stored Impression on the Prebid server +- **eventHandler** - the instance of the banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +#### Step 3: Create and provide Native Assets + +To make a proper bid request publishers should provide the needed assets to the NativeAdConfiguration class. Each asset describes the UI element of the ad according to the [OpenRTB standarts](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +``` swift +let assets = [ + { + let title = NativeAssetTitle(length: 90) + title.required = true + return title + }(), + { + let icon = NativeAssetImage() + icon.widthMin = 50 + icon.heightMin = 50 + icon.required = true + icon.imageType = NSNumber(value: PBMImageAssetType.icon.rawValue) + return icon + }(), + { + let image = NativeAssetImage() + image.widthMin = 150 + image.heightMin = 50 + image.required = true + image.imageType = NSNumber(value: PBMImageAssetType.main.rawValue) + return image + }(), + { + let desc = NativeAssetData(dataType: .desc) + desc.required = true + return desc + }(), + { + let cta = NativeAssetData(dataType: .ctaText) + cta.required = true + return cta + }(), + { + let sponsored = NativeAssetData(dataType: .sponsored) + sponsored.required = true + return sponsored + }(), +] +``` + +See the full description of NativeAdConfiguration options [here](rendering-native-ad-configuration.md). + +#### Step 4: Load the Ad + +Call the `loadAd()` method in order to make bid request and render the winning bid. \ No newline at end of file diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md b/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md new file mode 100644 index 0000000000..92d3840d45 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md @@ -0,0 +1,305 @@ +--- +layout: page_v2 +title: Google Ad Manager Integration +description: Integration of Prebid Rendering module whith Google Ad Manager +sidebarType: 2 +--- + +# Google Ad Manager Integration + +The integration of Prebid Rendering API with Google Ad Manager (GAM) assumes that publisher has an account on GAM and has already integrated the Google Mobile Ads SDK (GMA SDK) into the app project. + +If you do not have GMA SDK in the app yet, refer the the [Google Integration Documentation](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/quick-start). + +{: .alert.alert-warning :} +**Warning:** GMA SDK is a closed library that sometimes works in an unexpected way. The `GADMobileAds.sharedInstance().start()` should be called in all bundles where it is used. Otherwise, GMA SDK won't load the ads with error: `adView:didFailToReceiveAdWithError: SDK tried to perform a networking task before being initialized.` + +To avoid the error add the following line to your app right after initialization of GMA SDK: + +``` +GAMUtils.shared.initializeGAM() +``` + + +## GAM Integration Overview + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-GAM.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** Prebid SDK using Prebid GAM Event Handler sets up the targeting keywords into the GAM's ad unit. + +**Step 4** GMA SDK makes an ad request. GAM returns the winner of the waterfall. + +**Step 5** Basing on the ad response Prebid GAM Event Handler decides who has won on the GAM - the Prebid bid or another ad source on GAM. + +**Step 6** The winner is displayed in the App with the respective rendering engine. The winning bid will be renderd by Prebid SDK. An other ad will be rendered by GMA SDK. The GAM Event Handler manages this process. + +Prebid Rendering API supports these ad formats: + +- Display Banner +- Video Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video + +[//]: # (- Native) +[//]: # (- Native Styles) + +They can be integrated using these API categories: + +- [**Banner API**](#banner-api) - for *Display* and *Video* Banner +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* + +[//]: # (- [**Native API**](android-sdk-integration-gam-native.html) - for *Native Ads*) + + +## Banner API + +Integration example: + +``` swift +// 1. Create an Event Handler +let eventHandler = GAMBannerEventHandler(adUnitID: GAM_AD_UNIT_ID, + validGADAdSizes: [NSValueFromGADAdSize(adSize)]) + +// 2. Create a Banner View +let banner = BannerView(configID: CONFIG_ID, + eventHandler: eventHandler) + +banner.delegate = self + +addBannerToUI(banner: banner) + +// 3. Load an Ad +banner.loadAd() +``` + +#### Step 1: Create Event Handler + +To create the `GAMBannerEventHandler ` you should provide: + +- a **GAM Ad Unit Id** +- the list of available **sizes** for this ad unit. + + +#### Step 2: Create Ad View + +`BannerView` - is a view that will display the particular ad. It should be added to the UI. To create it you should provide: + +- `configID` - an ID of Stored Impression on the Prebid server +- `eventHandler` - the instance of the banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +#### Step 3: Load the Ad + +Call the method `loadAd()` which will: + +- make a bid request to Prebid Server. +- render the winning bid on display. + +### Banner Video + +For **Banner Video** you also need to specify the ad format: + +``` swift +banner.adFormat = .video +``` + +And all the rest code will be the same as for integration of Display Banner. + +### Migration from the original API + +GAM setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `GAMBannerView` with `BannerView` in the UI. +2. Implement the protocol `BannerViewDelegate` in the View Controller. +3. Remove usage of `GAMBannerView`, `GAMRequest`, and implementation of the `GADBannerViewDelegate`. +4. Remove original `BannerAdUnit`. +5. Follow the instructions to integrate [Banner API](#banner-api). + +## Interstitial API + +Integration example: + +``` swift +// 1. Create Event Handler +let eventHandler = GAMInterstitialEventHandler(adUnitID: GAM_AD_UNIT_ID) + +// 2. Create Interstitial Ad Unit +interstitial = InterstitialRenderingAdUnit (configID: CONFIG_ID, + minSizePercentage: CGSize(width: 30, height: 30), + eventHandler: eventHandler) + +interstitial.delegate = self + +// 3. Load an Ad +interstitial.loadAd() + +/// ....... + +// 4. Show Ad +if interstitial.isReady { + interstitial.show(from: self) +} + +``` + +The **default** ad format for interstitial is **.display**. In order to make a `multiformat bid request`, set the respective values into the `adFormats` property. + +``` swift +// Make bid request for video ad +adUnit?.adFormats = [.video] + +// Make bid request for both video amd disply ads +adUnit?.adFormats = [.video, .display] + +// Make bid request for disply ad (default behaviour) +adUnit?.adFormats = [.display] + +``` + + +#### Step 1: Create Event Handler + +To create an event handler you should provide a **GAM Ad Unit**. + +#### Step 2: Create Interstitial Ad Unit + +Initialize the `InterstitialRenderingAdUnit` with properties: + +- `configID` - an ID of Stored Impression on the Prebid server +- `minSizePercentage` - specifies the minimum width and height percent an ad may occupy of a device’s real estate. +- `eventHandler` - the instance of the interstitial event handler + +> **NOTE:** the `minSizePercentage` - plays an important role in a bidding process for display ads. If provided space is not enough demand partners won't respond with the bids. + + +#### Step 3: Load the Ad + +Call the method `loadAd()` which will make a bid request to Prebid Server. + +#### Step 4: Show the Ad when it is ready + +Wait for the ad to and show it to the user in any suitable time. + + +``` swift +// MARK: InterstitialRenderingAdUnitDelegate + +func interstitialDidReceiveAd(_ interstitial: InterstitialAdUnit) { + // Now the ad is ready for display +} +``` + +### Migration from the original API + +GAM setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `GAMInterstitialAd` with `InterstitialRenderingAdUnit` in the View Controller. +2. Implement the protocol `InterstitialAdUnitDelegate` in the View Controller. +3. Remove usage of `GAMInterstitialAd`, `GAMRequest`. +4. Remove original `InterstitialAdUnit`. +5. Follow the instructions to integrate [Interstitial API](#interstitial-api). + + +## Rewarded API + +Integration example: + +``` swift + // 1. Create an Event Handler +let eventHandler = GAMRewardedEventHandler(adUnitID: GAM_AD_UNIT_ID) + +// 2. Create an Ad Unit +rewardedAd = RewardedAdUnit(configID: CONFIG_ID, + eventHandler: eventHandler) + +rewardedAd.delegate = self + +// 3. Load an Ad +rewardedAd.loadAd() + +/// ....... + +// 4. Display Ad +if rewardedAd.isReady { + rewardedAd.show(from: self) +} + +``` + +The way of displaying the Rewarded Ad is totally the same as for the Interstitial Ad. + +To be notified when user earns a reward - implement the method of `RewardedAdUnitDelegate`: + +``` swift +- (void)rewardedAdUserDidEarnReward:(RewardedAdUnit *)rewardedAd; +``` + +The actual reward object is stored in the `RewardedAdUnit`: + +``` +if let reward = rewardedAd.reward as? GADAdReward { + // ... +} +``` + +#### Step 1: Create Event Handler + +To create an event handler you should provide a **GAM Ad Unit ID**. + +#### Step 2: Create Rewarded Ad Unit + +Create the `RewardedAdUnit` object with parameters: + +- `configID` - an ID of Stored Impression on the Prebid server +- `eventHandler` - the instance of rewarded event handler + +#### Step 3: Load the Ad + +Call the `loadAd()` method which will make a bid request to Prebid server. + +#### Step 4: Show the Ad when it is ready + +Wait for the ad to load and show it to the user in any suitable time. + + +``` swift +// MARK: RewardedAdUnitDelegate + +func rewardedAdDidReceiveAd(_ rewardedAd: RewardedAdUnit) { + // Now the ad is ready for display +} +``` + +### Migration from the original API + +GAM setup: + +1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. +2. Create new GAM ad unit. +3. Setup new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `GADRewardedAd` with `RewardedAdUnit` in the View Controller. +2. Implement the protocol `RewardedAdUnitDelegate` in the View Controller. +3. Remove usage of `GAMRequest`. +4. Remove original `RewardedVideoAdUnit`. +5. Follow the instructions to integrate [Rewarded API](#rewarded-api). +ß \ No newline at end of file diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-max.md b/prebid-mobile/modules/rendering/ios-sdk-integration-max.md new file mode 100644 index 0000000000..f7f7ffe155 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-max.md @@ -0,0 +1,300 @@ +--- +layout: page_v2 +title: AppLovin MAX Integration +description: Integration of Prebid Rendering module whith AppLovin MAX +sidebarType: 2 +--- + +# AppLovin MAX Integration + +The integration of Prebid Mobile with AppLovin MAX assumes that publisher has MAX account and has already integrated the AppLovin MAX SDK into the app. + +See the [AppLovin MAX Documentation](https://dash.applovin.com/documentation/mediation/ios/getting-started/integration) for the MAX integration details. + +## MAX Integration Overview + +![Rendering with AppLovin MAX as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/prebid-in-app-bidding-overview-max.png) + +**Steps 1-2** Prebid SDK makes a bid request. Prebid server runs an auction and returns the winning bid. + +**Step 3** MAX SDK makes an ad request. MAX returns the waterfall with respective placements. + +**Step 4** For each prebid's placement, the MAX SDK sequentially instantiates an adapter. + +**Step 5** The adapter verifies the targeting keywords of the winning bid and the custom properties of the given placement. If they match the adapter will render the winning bid. Otherwise, adpater will fail with "no ad" immediately and the next placement will instantiate the same adapter but for another custom properties. + +Prebid Mobile supports these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Native + +They can be integrated using these API categories: + +- [**Banner API**](#banner-api) - for *Display* Banner +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* +- [**Native API**](#native-ads) - for *Native Ads* + + +## Banner API + +Integration example: + +``` swift +// 1. Create MAAdView +adBannerView = MAAdView(adUnitIdentifier: maxAdUnitId) +adBannerView?.delegate = self + +// 2. Create MAXMediationBannerUtils +mediationDelegate = MAXMediationBannerUtils(adView: adBannerView!) + +// 3. Create MediationBannerAdUnit +adUnit = MediationBannerAdUnit(configID: prebidConfigId, + size: adUnitSize, + mediationDelegate: mediationDelegate!) + +// 4. Make a bid request +adUnit?.fetchDemand { [weak self] result in + + // 5. Make an ad request to MAX + self?.adBannerView.loadAd() +} +``` + +#### Step 1: Create MAAdView + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/ios/getting-started/banners#loading-a-banner). You don't have to make any modifications here. + + +#### Step 2: Create MAXMediationBannerUtils + +The `MAXMediationBannerUtils ` is a helper class, wich performs certain utilty work for the `MediationBannerAdUnit`, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationBannerAdUnit + +The `MediationBannerAdUnit` is a part of Prebid mediation API. This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by prebid adapters. + +## Interstitial API + +Integration example: + +``` swift +// 1. Create MAInterstitialAd +interstitial = MAInterstitialAd(adUnitIdentifier: maxAdUnitId) +interstitial.delegate = self + +// 2. Create MAXMediationInterstitialUtils +mediationDelegate = MAXMediationInterstitialUtils(interstitialAd: interstitial!) + +// 3. Create MediationInterstitialAdUnit +adUnit = MediationInterstitialAdUnit(configId: prebidConfigId, + minSizePercentage: CGSize(width: 30, height: 30), + mediationDelegate: mediationDelegate!) + +// 4. Make a bid request +adUnit?.fetchDemand { [weak self] result in + guard let self = self else { return } + + guard result == .prebidDemandFetchSuccess else { + self.fetchDemandFailedButton.isEnabled = true + return + } + + // 5. Make an ad request to MAX + self.interstitial?.load() +}) +``` + +The **default** ad format for interstitial is **.display**. In order to make a `multiformat bid request`, set the respective values into the `adFormats` property. + +``` swift +// Make bid request for video ad +adUnit?.adFormats = [.video] + +// Make bid request for both video amd disply ads +adUnit?.adFormats = [.video, .display] + +// Make bid request for disply ad (default behaviour) +adUnit?.adFormats = [.display] + +``` + +#### Step 1: Create MAInterstitialAd + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/ios/getting-started/interstitials). You don't have to make any modifications here. + + +#### Step 2: Create MAXMediationInterstitialUtils + +The `MAXMediationInterstitialUtils` is a helper class, wich performs certain utilty work for the `MediationInterstitialAdUnit `, like passing the targeting keywords to the adapters and checking the visibility of the ad view. + +#### Step 3: Create MediationInterstitialAdUnit + +The `MediationInterstitialAdUnit` is a part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid to the mediating SDKs. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 6: Display an ad + +Once you receive the ad it will be ready for display. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/ios/getting-started/interstitials#showing-an-interstitial-ad) about how to do it. + +## Rewarded API + +Integration example: + +``` swift +// 1. Get an instance of MARewardedAd +rewarded = MARewardedAd.shared(withAdUnitIdentifier: maxAdUnitId) +rewarded.delegate = self + +// 2. Create MAXMediationRewardedUtils +mediationDelegate = MAXMediationRewardedUtils(rewardedAd: rewarded!) + +// 3. Create MediationRewardedAdUnit +adUnit = MediationRewardedAdUnit(configId: prebidConfigId, mediationDelegate: mediationDelegate!) + +// 4. Make a bid request +adUnit?.fetchDemand { [weak self] result in + guard let self = self else { return } + + // 5. Make an ad request to MAX + self.rewarded?.load() +} +``` + +The way of displaying the rewarded ad is totally the same as for the Interstitial Ad. + +To be notified when user earns a reward follow the [MAX intructions](https://dash.applovin.com/documentation/mediation/ios/getting-started/rewarded-ads#loading-a-rewarded-ad). + +#### Step 1: Get an instance of MARewardedAd + +This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/ios/getting-started/rewarded-ads). You don't have to make any modifications here. + + +#### Step 2: Create MAXMediationRewardedUtils + +The `MAXMediationRewardedUtils` is a helper class, wich performs certain utilty work for the `MediationRewardedAdUnit`, like passing the targeting keywords to the adapters. + +#### Step 3: Create MediationRewardedAdUnit + +The `MediationRewardedAdUnit` is a part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters. + +#### Step 4: Make bid request + +The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler. + +#### Step 5: Make an Ad Reuest + +Now you should make a regular MAX's ad request. Everything else will be handled by GMA SDK and prebid adapters. + +#### Steps 6: Display an ad + +Once the rewarded ad is recieved you can display it. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/ios/getting-started/rewarded-ads#showing-a-rewarded-ad) for the details. + +## Native Ads + +Integration example: + +``` swift +// 1. Create MANativeAdLoader +nativeAdLoader = MANativeAdLoader(adUnitIdentifier: maxAdUnitId) +nativeAdLoader?.nativeAdDelegate = self + +// 2. Create MAXMediationNativeUtils +mediationDelegate = MAXMediationNativeUtils(nativeAdLoader: nativeAdLoader!) + +// 3. Create and configure MediationNativeAdUnit +nativeAdUnit = MediationNativeAdUnit(configId: prebidConfigId, + mediationDelegate: mediationDelegate!) + +nativeAdUnit.setContextType(ContextType.Social) +nativeAdUnit.setPlacementType(PlacementType.FeedContent) +nativeAdUnit.setContextSubType(ContextSubType.Social) + +// 4. Set up assets for bid request +nativeAdUnit.addNativeAssets(nativeAssets) + +// 5. Set up event tracker for bid request +nativeAdUnit.addEventTracker(eventTrackers) + +// 6. Make a bid request +nativeAdUnit.fetchDemand { [weak self] result in + + // 7. Make an ad request to MAX + self?.nativeAdLoader?.loadAd(into: self?.createNativeAdView()) +} +``` + +#### Step 1: Create MANativeAdLoader + +Prepare the `MANativeAdLoader` object before you make a bid request. It will be needed for prebid mediation utils. + +#### Step 2: Create MAXMediationNativeUtils + +The `MAXMediationNativeUtils` is a helper class, wich performs certain utilty work for `MediationNativeAdUnit`, like passing the targeting keywords to adapters and checking the visibility of the ad view. + +#### Step 3: Create and configure MediationNativeAdUnit + +The `MediationNativeAdUnit` is a part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters. Fot the better targetting you should provide additional properties like `conteaxtType` and `placemantType`. + +#### Step 4: Set up assets for bid request + +The bid request for native ads should have the description of expected assets. The full spec for the native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the assets array: + +``` +let image = NativeAssetImage(minimumWidth: 200, minimumHeight: 50, required: true) +image.type = ImageAsset.Main + +let icon = NativeAssetImage(minimumWidth: 20, minimumHeight: 20, required: true) +icon.type = ImageAsset.Icon + +let title = NativeAssetTitle(length: 90, required: true) + +let body = NativeAssetData(type: DataAsset.description, required: true) + +let cta = NativeAssetData(type: DataAsset.ctatext, required: true) + +let sponsored = NativeAssetData(type: DataAsset.sponsored, required: true) + +return [icon, title, image, body, cta, sponsored] +``` + +#### Step 5: Set up event tracker for bid request + +The bid request for mative ads may have a descrition of expected event trackers. The full spec for the Native template you can find in the [Native Ad Specification from IAB](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +The example of creating the event trackers array: + +``` +let eventTrackers = [ + NativeEventTracker(event: EventType.Impression, + methods: [EventTracking.Image,EventTracking.js]) +] +``` + +#### Step 6: Make a bid request + +The `fetchDemand` method makes a bid request to prebid server and provides a result in a completion handler. + +#### Step 7: Load Native ad + +Now just load a native ad from MAX according to the [MAX instructions](https://dash.applovin.com/documentation/mediation/ios/getting-started/native-manual#load-the-native-ad). diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-pb-native.md b/prebid-mobile/modules/rendering/ios-sdk-integration-pb-native.md new file mode 100644 index 0000000000..1e21555af7 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-pb-native.md @@ -0,0 +1,174 @@ +--- + +layout: page_v2 +title: Native Ads Integration +description: Integration of Prebid SDK without Primary Ad Server SDK +sidebarType: 2 + +--- + +# Native Ads Integration + +## Unified Native Ads + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout. +2. Create Native Ad Unit. +3. Configure the Native Ad unit using [NativeAdConfiguration](rendering-native-ad-configuration.html). + * Provide the list of [Native Assets](rendering-native-guidelines.html#components) representing the ad's structure. + * Tune other general properties of the ad. +4. Make a bid request. +5. Extract NativeAd using `NativeUtils.findNativeAd` +7. Bind the data from the native ad with the layout. + + +``` swift +func loadAd() { + guard let nativeAdConfig = nativeAdConfig else { + return + } + adUnit = NativeAdUnit(configID: prebidConfigId, nativeAdConfiguration: nativeAdConfig) + + adUnit?.fetchDemand { [weak self] demandResponseInfo in + guard let self = self, + demandResponseInfo.fetchDemandResult == .ok else { + return + } + + demandResponseInfo.getNativeAd { [weak self] nativeAd in + guard let self = self, + let nativeAd = nativeAd else { + return + } + + self?.renderNativeAd(nativeAd) + + self.theNativeAd = nativeAd // Note: RETAIN! or the tracking will not occur! + nativeAd.trackingDelegate = self + nativeAd.uiDelegate = self + + if let _ = nativeAd.videoAd?.mediaData { + self.nativeAdViewBox?.mediaViewDelegate = self + self.setupMediaPlaybackTrackers(isVisible: true) + } + } + } +} +``` + +## Native Styles + +[See Native Ads Guidelines page](rendering-native-guidelines.html) for more details about SDK integration and supported ad types. + +To display an ad using Native Styles you'll need to implement these easy steps: + +``` swift +// 1. Create an Ad View +let banner = BannerView(configId: CONFIG_ID, + adSize: adSize) + +banner.delegate = self + +// 2. Set the Native Ad Configurations +let nativeAdConfig = NativeAdConfiguration(testConfigWithAssets: assets) +nativeAdConfig.nativeStylesCreative = nativeStylesCreative + +banner.nativeStylesCreative = nativeAdConfig + +// 3. Load an Ad +banner.loadAd() +``` + +#### Step 1: Create Ad View + +In the Pure In-App Bidding scenario you just need to initialize the Banner Ad View using correct properties: + +- **configID** - an ID of Stored Impression on the Apollo server. +- **size** - the size of the ad unit which will be used in the bid request. + + +{% capture warning_note %} +You should add HTML and CSS to define your native ad template with universal creative and provide it via the nativeStylesCreative property of NativeAdConfiguration. +{% endcapture %} +{% include /alerts/alert_important.html content=warning_note %} + +#### Step 2: Create and provide Native Assets + +To make a proper bid request publishers should provide the needed assets to the NativeAdConfiguration class. Each asset describes the UI element of the ad according to the [OpenRTB standarts](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf). + +``` swift +let assets = [ + { + let title = NativeAssetTitle(length: 90) + title.required = true + return title + }(), + { + let icon = NativeAssetImage() + icon.widthMin = 50 + icon.heightMin = 50 + icon.required = true + icon.imageType = NSNumber(value: ImageAssetType.icon.rawValue) + return icon + }(), + { + let image = NativeAssetImage() + image.widthMin = 150 + image.heightMin = 50 + image.required = true + image.imageType = NSNumber(value: ImageAssetType.main.rawValue) + return image + }(), + { + let desc = NativeAssetData(dataType: .desc) + desc.required = true + return desc + }(), + { + let cta = NativeAssetData(dataType: .ctaText) + cta.required = true + return cta + }(), + { + let sponsored = NativeAssetData(dataType: .sponsored) + sponsored.required = true + return sponsored + }(), +] +``` + +Native Styles creative example: + +``` html + + + +``` + + +See the full description of NativeAdConfiguration options [here](rendering-native-ad-configuration.html). + +#### Step 3: Load the Ad + +Call `loadAd()` and SDK will: + +- make a bid request to Prebid server +- render the winning bid on display + + diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-pb.md b/prebid-mobile/modules/rendering/ios-sdk-integration-pb.md new file mode 100644 index 0000000000..dbed9cf9e1 --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-pb.md @@ -0,0 +1,187 @@ +--- + +layout: page_v2 +title: Custom or No mediation +description: Integration of Prebid SDK without Primary Ad Server SDK +sidebarType: 2 + +--- + +# Custom Bidding Integration + +## Table of Contents + +- [Mobile API](#mobile-api) +- [Banner](#banner-api) +- [Interstitial](#interstitial-api) +- [Rewarded](#rewarded-api) + +## Mobile API + +The integration and usage of the Rendering API are similar to any other Ad SDK. It sends the bid requests to the Prebid Server and renders the winning bid. + +![In-App Bidding with Prebid](/assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-Pure-Prebid.png) + +Prebid supports rendering of these ad formats: + +- Display Banner +- Display Interstitial +- Video Interstitial +- Rewarded Video +- Outstream Video + +[//]: # (- Native) + +They can be integrated using these API categories: + +- [**Banner API**](#banner-api) - for *Display* and *Video* Banners +- [**Interstitial API**](#interstitial-api) - for *Display* and *Video* Interstitials +- [**Rewarded API**](#rewarded-api) - for *Rewarded Video* + +[//]: # (- [**Native API**](ios-sdk-integration-pb-native.html) - for *Native Ads*) + +### Banner API + +Integration example: + +``` swift +// 1. Create an Ad View +let banner = BannerView(frame: CGRect(origin: .zero, size: adSize), + configID: CONFIG_ID, + adSize: adSize) + +banner.delegate = self + +// 2. Load an Ad +banner.loadAd() +``` + +#### Step 1: Create Ad View + +Initialize the `BannerAdView` with properties: + +- `frame` - the frame rectangle for the view +- `configID` - an ID of the Stored Impression on the Prebid Server +- `size` - the size of the ad unit which will be used in the bid request. + +#### Step 2: Load the Ad + +Call the method `loadAd()` which will: + +- make a bid request to the Prebid Server. +- render the winning bid on display. + +#### Outstream Video + +For **Banner Video** you also need to specify the ad format: + +``` swift +banner.adFormat = .video +``` + +### Interstitial API + +Integration example: + +``` swift +// 1. Create an Interstitial Ad Unit +interstitial = InterstitialRenderingAdUnit(configID: CONFIG_ID, + minSizePercentage: CGSize(width: 30, height: 30)) + +interstitial.delegate = self + +// 2. Load an Ad +interstitial.loadAd() + +// ..... + +// 3. Show An Ad +if interstitial.isReady { + interstitial.show(from: self) +} + +``` + +The **default** ad format for interstitial is **.display**. In order to make a `multiformat bid request`, set the respective values into the `adFormats` property. + +``` swift +// Make bid request for video ad +adUnit?.adFormats = [.video] + +// Make bid request for both video amd disply ads +adUnit?.adFormats = [.video, .display] + +// Make bid request for disply ad (default behaviour) +adUnit?.adFormats = [.display] + +``` + +#### Step 1: Create an Ad Unit + + +Initialize the Interstitial Ad Unit with properties: + +- `configID` - an ID of Stored Impression on the Prebid Server +- `minSizePercentage` - specifies the minimum width and height percent an ad may occupy of a device’s real estate. + +> **NOTE:** minSizePercentage - plays an important role in a bidding process for display ads. If provided space is not enough demand partners won't respond with the bids. + +#### Step 2: Load the Ad + +Call the method `loadAd()` which will make a bid request to Prebid server. + + +#### Step 3: Show the Ad when it is ready + +Wait until the ad will be loaded and present it to the user in any suitable time. + +``` swift +// MARK: InterstitialRenderingAdUnitDelegate + +func interstitialDidReceiveAd(_ interstitial: InterstitialRenderingAdUnit) { + // Now the ad is ready for display +} +``` + +### Rewarded API + +Integration example: + +``` swift +// 1. Create an Ad Unit +rewardedAd = RewardedAdUnit(configID: CONFIG_ID) +rewardedAd.delegate = self + +// 2. Load an Ad +rewardedAd.loadAd() + +/// ....... + +// 3. Display the Ad +if rewardedAd.isReady { + rewardedAd.show(from: self) +} +``` + + +#### Step 1: Create Rewarded Ad Unit + +Create the `RewardedAdUnit` object with parameter: + +- **configID** - an ID of Stored Impression on the Prebid Server + +#### Step 2: Load the Ad + +Call the `loadAd()` method which will make a bid request to Prebid server. + +#### Step 3: Show the Ad when it is ready + +Wait until the ad will be loaded and present it to the user in any suitable time. + +``` swift +// MARK: RewardedAdUnitDelegate + +func rewardedAdDidReceiveAd(_ rewardedAd: RewardedAdUnit) { + // Now the ad is ready for display +} +``` \ No newline at end of file diff --git a/prebid-mobile/modules/rendering/ios-sdk-parameters.md b/prebid-mobile/modules/rendering/ios-sdk-parameters.md new file mode 100644 index 0000000000..a4c6f0e0fe --- /dev/null +++ b/prebid-mobile/modules/rendering/ios-sdk-parameters.md @@ -0,0 +1,88 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# Request parameters + +The tables below list methods and properties that the Rendering Module allows to customize in order to enrich the bid requests with actual data. The more info is provided about the user, the app, and the device the more chances to win a bid. + +Please strictly follow the recommendations in the below tables and provide all ❗ **Required** and **Highly Recommended** values. + + +1. [PrebidRenderingTargeting Properties](#prebidrenderingtargeting-variables) +1. [PrebidRenderingTargeting Methods](#prebidrenderingtargeting-methods) +1. [PrebidRenderingConfig](#prebidrenderingconfig) + +## PrebidRenderingTargeting proeprties + +{: .table .table-bordered .table-striped } + +| **Variable** | **Description** | **Required?** | +| -------------------- | ---------------- | ------------------------------------------------------------ | ------------------------ | +| appStoreMarketURL | Stores URL for the mobile application. For example: `"https://itunes.apple.com/us/app/your-app/id123456789"` | ❗ Required | +|contentUrl | This is the deep-link URL for the app screen that is displaying the ad. This can be an iOS universal link. | ❗ Highly Recommended | +|publisherName| App's publisher's name. | ❗ Highly Recommended | +| userAge | User's age in years. For example: `35` | ❗ Highly Recommended | +| coppa | Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes | ❗ Highly Recommended | +| userAnnualIncomeInUS | User's annual income in US dollars. For example: `55000` | ❗ Highly Recommended | +| userGender | User's gender (Male, Female, Other, Unknown). For example: `GenderFemale` | ❗ Highly Recommended | +|userGenderDescription| String representation of the user's gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown) | | +| userID | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended | +| buyerUID | Buyer-specific ID for the user as mapped by the exchange for the buyer. | ❗ Highly Recommended | +| userEthnicity | User's ethnicity (African American, Asian, Hispanic, White, Other). For example: `EthnicityAsian` | Recommended if available | +| userMaritalStatus | User's marital status (Single, Married, Divorced, Unknown). For example: `MaritalStatusDivorced` | Recommended if available | +| networkType | Network connection type of the user (offline, wifi, or cell).For example: `NetworkTypeWifi` | ❗ Required | +| IP | The IP address of the carrier gateway. If this is not present, Prebid retrieves it from the request header. For example: `"192.168.0.1"` | ❗ Highly Recommended | +| carrier | Mobile carrier - Defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: -. For example: `"310-410"` | Optional | +| DMA | For US locations, indicates the user's Designated Market Area. For example: `"803"` | Optional | +| keywords | Comma separated list of keywords, interests, or intent | Optional | +| userCustomData| Optional feature to pass bidder the data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional | +|userExt| Placeholder for exchange-specific extensions to OpenRTB. | Optional | + +The code sample: + +``` swift +let targeting = PrebidRenderingTargeting.shared +targeting.userGender = .male +targeting.userAge = 99 +targeting.userAnnualIncomeInUS = 9999 +targeting.setLatitude(123.0, longitude: 456.0) +``` + + +## PrebidRenderingTargeting methods + +{: .table .table-bordered .table-striped } + +| **Method** | **Description** | +| ---------------------------------------- | ------------------------------------------------------------ | +| addCustomParam:@"val1" withName:@"key1" | Adds the custom parameters. The name will be auto-prepended with `c.` to avoid collisions. Example: `addCustomParam:@"73" withName:@"temperature"` | +| setCustomParams:@["key1":@"val1"] | Adds a dictionary of name-value parameter pairs, where each parameter name will be prepended with `c.` to avoid name collisions. Example: `setCustomParams:@["key1":@"val1"]` | +| addParam:@"val1" withName:@"key1" | Adds a new `param` by name and sets its value. If an ad call parameter doesn't exist in this SDK, you can set it manually using this method.
    Example: `addParam:@"73" withName:@"temperature"` | +| setLatitude:latitude longitude:longitude | Sets the latitude and longitude of a geographic location.
    Latitude from -90.0 to +90.0, where negative is south.
    Longitude from -180.0 to +180.0, where negative is west. | +| resetUserAge; | Sets the User Age to 0 | +| resetUserAnnualIncomeInUS; | Sets the userAnnualIncomeInUS to 0 | + +## PrebidRenderingConfig + +{: .table .table-bordered .table-striped } + +| **Method** | **Description** | **Default** | +| -------------------------------------- | ------------------------------------------------------------ | ----------- | +| creativeFactoryTimeout | Controls how long in seconds each creative has to load before it is considered a failure. | 3 | +| creativeFactoryTimeoutPreRenderContent | Controls how long (in seconds) the video and display interstitial creative has to completely pre-render before it is considered a failure. | 30 | +| useInternalClickthroughBrowser | Controls whether to use in-app browser or the Safari app for displaying ad click-through content. | true | +| logLevel | Controls the verbosity of PrebidRenderingModule's internal logger. Options are (from most to least noisy):
    - .info
    - .warn
    - .error
    - .none | .info | +| debugLogFileEnabled | If `true`, the output of PrebidRenderingModule's internal logger is written to a text file. This can be helpful for debugging. | false | + +The code sample: + +``` swift +PrebidRenderingConfig.shared.creativeFactoryTimeout = 5.0 +``` + diff --git a/prebid-mobile/modules/rendering/modules-rendering.md b/prebid-mobile/modules/rendering/modules-rendering.md new file mode 100644 index 0000000000..c3bab7685a --- /dev/null +++ b/prebid-mobile/modules/rendering/modules-rendering.md @@ -0,0 +1,120 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# Prebid Mobile Rendering + +Prebid Mobile has added a rendering module (currently in open beta) which provides an API for rendering display and video media types independently of the current core feature set and interfaces. The API enables Prebid Mobile to have full ownership of the Web view selected for rendering and will pass any associated ad markup to the controlled view. This new functionality enables publishers to have improved control of features such as Open Measurement, MRAID, SKAdNetwork. This same functionality is available for rendering video (VAST) creatives through an internal video player. + +The **rendering API** is available on iOS and Android starting with the `1.13.0-beta1` version. + +Starting with `1.14.0-beta1` Prebid mobile supports integration with **AdMob**. + +Starting with `2.0.0` Prebid mobile supports integration with **AppLovin MAX**. + +## Benefits + +Prebid SDK rendering offers the following benefits: + +- **Monetization without an Ad Server**: Publishers who do not have a direct sales force or have no need for an ad server can still access Prebid's mobile demand stack. Publishers will be able to render ads directly without relying on any 3rd party SDKs. +- **Reduced ad delivery latency**: The rendering module enables Prebid SDK to render ads immediately when demand is returned from Prebid Server or when receiving the render signal from an ad server. The render process should vastly reduce ad delivery speeds. +- **Less infrastructure**: The rendering API does not rely on Prebid Server's Cache server, reducing the cost and utility of Prebid Server Cache. +- **Less discrepancy**: Having control of the rendering process provides the potential to reduce discrepancy by having ads instantly available (less http calls, less infrastructure, less setup). This control enables the publisher to follow open and transparent industry standards or even potentially custom requirements from buyers. +- **Framework support**: Full support of SKAdNetworks and similar frameworks +- **MRAID 3.0 support** +- **Flexible Ad Measurement**: Controlling the rendering and Open Measurement process allows publishers to potentially configure any measurement provider in a transparent and open source process. Prebid SDK will eventually be IAB Open Measurement certified. +- **Community driven**: Being a part of Prebid, there is the ability to add features not readily or easily available either through the Ad Server or other SDKs + +## Potential Features + +This set of features are not supported in the current release but are designated for future implementation. + +- **Multiformat Ad Unit**: The rendering module will enable Prebid SDK to display any bid format in the given inventory regardless of Primary Ad Server capabilities. +- **Support of Custom Ad Servers**: The rendering module will work with any ad server not just GAM and MoPub. +- **Rendering Delegation**: The module will potentially delegate rendering of the winning bid to the Demand Partner SDK if it is required for special creatives. + +## How It Works + +Rendering API supports two integration scenarios: + +* **Custom or No mediation** when no Primay Ad Server is used. The SDK renders the winning bid immediately when it is available. +* **Using a Primary Ad Server** Prebid SDK detects when a Prebid line item wins on the ad server and renders the cached bid in the owned Web view or Video view. + +In both scenarios, Prebid SDK leverages Prebid Server for demand. Below are the processes for both In-App and Primary Ad Server modes: + +### Custom In-App Bidding + +![In-App Rendering](/assets/images/prebid-mobile/modules/rendering/Prebid-In-App-Bidding-Overview-Pure-Prebid.png) + +1. The Prebid SDK sends the bid request to the Prebid Server +1. Prebid Server runs the header bidding auction among preconfigured demand partners +1. Prebid Server responses with the winning bid +1. The rendering module renders the winning bid + +### Prebid Rendering Module with Primary Ad Server + +![Rendering with Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/In-App-Bidding-Integration.png) + +1. The rendering module sends the bid request to the Prebid server. +1. Prebid server runs the header bidding auction among preconfigured demand partners. +1. Prebid Server responds with the winning bid that contains targeting keywords. +1. The rendering module sets up the targeting keywords of the winning bid into the ad unit of the primary ad server SDK. +1. The primary ad server SDK sends the ad request to the primary ad server. +1. The primary ad server responds with an ad or mediation chain. +1. The winning ad meta information is passed to the rendering module. +1. Depending on the ad response, the rendering module renders the winning bid or allows the primary ad server SDK to show its own winning ad. + +## Supported Ad Formats + +Prebid Mobile rendering supports the following ad formats: + +* Display Banner +* Video Banner +* Display Interstitial +* Video Interstitial +* Rewarded Video + +## Integration Scenarios + +### Android + +Follow these steps to integrate the rendering API: + +1. If integrating into an ad server, create line items specific for rendering (line items for rendering API are unique and do not coincide with the standard Prebid SDK line items): + * [GAM](rendering-gam-line-item-setup.html) + * [AdMob](rendering-admob-line-item-setup.html) + * [MAX](rendering-max-line-item-setup.html) +1. [Integrate Prebid SDK](android-sdk-integration.html) into your project. +1. Add prebid's ad units to your app respectively to the monetization scenario: + * [Custom in-app bidding](android-sdk-integration-pb.html) integration without primary ad server. + * In-app bidding using [Google Ad Manager (GAM)](android-sdk-integration-gam.html) as a primary ad server + * In-app bidding using [AdMob](android-sdk-integration-admob) as a primary ad server. + * In-app bidding using [AppLovin MAX](android-sdk-integration-max.html) as a primary ad server. + +1. Actualize the [integration and targeting](android-sdk-parameters.html) properties. + +### iOS + +Follow these steps to integrate the rendering API: + +1. If integrating into an ad server, create line items specific for rendering (line items are uniqe for the Rendering Module and do not cooicide with the standard Prebid SDK line items): + * [GAM](rendering-gam-line-item-setup.html) + * [AdMob](rendering-admob-line-item-setup.html) + * [MAX](rendering-max-line-item-setup.html) +1. [Integrate Prebid SDK](ios-sdk-integration.html). +1. Add prebid's ad units to your app respectively to the monetization scenario: + * [Custom in-app bidding](ios-sdk-integration-pb.html) integration without a primary ad server. + * In-app bidding using [Google Ad Manager (GAM)](ios-sdk-integration-gam.html) as a primary ad server. + * In-app bidding using [AdMob](ios-sdk-integration-gam.html) as a primary ad server. + * In-app bidding using [AppLovin MAX](ios-sdk-integration-max.html) as a primary ad server. + 1. Actualize the [integration and targeting](ios-sdk-parameters.html) properties. + +## Additional refences + +- [Deep Links Support](rendering-deeplinkplus.html) +- [Impression Tracking](rendering-impression-tracking.html) diff --git a/prebid-mobile/modules/rendering/rendering-admob-line-item-setup.md b/prebid-mobile/modules/rendering/rendering-admob-line-item-setup.md new file mode 100644 index 0000000000..6f4ee870df --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-admob-line-item-setup.md @@ -0,0 +1,94 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# AdMob Setup + + +## Mediation Group Setup + +### Step 1: Create Mediation Group + +In your AdMob account go to `Mediation` and click on `Create Mediation Group`: + + Pipeline Screenshot + +Choose one of the ad formats: + +- Banner +- Interstitial +- Native Advanced +- Rewarded interstitial + +Choose a platform - iOS or Android. + +Press `CONTINUE`. Then set the name for the mediation group and other properties: + +Pipeline Screenshot + +Press `ADD AD UNITS` and select the target items in the modal dialog: + +Pipeline Screenshot + +Press `DONE`. And move to the next step. + + +### Step 2: Add Custom Events + +Pipeline Screenshot + + +Now you have to add custom events for possible bid prices. Follow the [price granularity](https://docs.prebid.org/prebid-mobile/adops-price-granularity.html#prebid-mobile-price-granularity) guide to determine how many entries you need. + +Press `ADD CUSTOM EVENT`: + +Pipeline Screenshot + +Set the `Label` and `eCPM` for the custom event. Press `CONTINUE`. + +Pipeline Screenshot + +The fields in this dialog are critical for the proper integration: + +- `Class Name` is a name of respective adapter. + - Banner: + - iOS: `PrebidAdMobBannerAdapter` + - Android: `org.prebid.mobile.admob.PrebidBannerAdapter` + - Interstitial Display: + - iOS: `PrebidAdMobInterstitialAdapter` + - Android: `org.prebid.mobile.admob.PrebidInterstitialAdapter` + - Interstitial Video: + - iOS: `PrebidAdMobVideoInterstitialAdapter` + - Android: `org.prebid.mobile.admob.PrebidInterstitialAdapter` + - Rewarded: + - iOS: `PrebidAdMobRewardedVideoAdapter ` + - Android: `org.prebid.mobile.admob.PrebidRewardedAdapter` + - Native: + - iOS: `PrebidAdMobNativeAdapter ` + - Android: `org.prebid.mobile.admob.PrebidNativeAdapter` +- `Parameter` is a keywords for the current ad source. **Important**: make sure that the price of the ad source is the same as the price in this keyword. For example: + +``` +{"hb_pb":"0.10"} +``` + +Prebid SDK will compare the keywords in the winning bids with keywords provided in the `Parameter` fields. + +{: .alert.alert-warning :} +The adapter will render the winning bid only if the bid's targeting keywords contain `all` keywords from the Parameter field. + + +Press `DONE` and repeat the adding of the custom events for all needed prices. + +Pipeline Screenshot + +Once you add all needed custom events - press `DONE`. The Mediation Group is ready to serve the prebid demand to your app. + + + + diff --git a/prebid-mobile/modules/rendering/rendering-deeplinkplus.md b/prebid-mobile/modules/rendering/rendering-deeplinkplus.md new file mode 100644 index 0000000000..0a95c02cb3 --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-deeplinkplus.md @@ -0,0 +1,76 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# Deep Link+ + +Prebid Rendering Module supports the premium standard for retargeting campaigns - [DeepLink+](https://developers.mopub.com/dsps/ad-formats/deep-linking/) + +## Advantages over traditional mobile deep-linking functionality + +Technology has traditionally failed in providing the ideal user experience — as processing traditional deep-links requires opening up blank browser windows, redirecting users multiple times, and sometimes breaking down completely. Additionally, buyers would lack analytics around when primary URLs worked versus when fallback URLs were required. + +Deep Link+ provides a premium user experience while letting advertisers scale retargeting campaigns with accurate analytics. + +The new deeplinking format enables buyers to submit: + + * primary URL + * fallback URL + * primary tracking URL + * fallback tracking URL + +And since Deep Link+ is built into the SDK, there is no need to pop up browser windows and re-directs that deteriorate the user experience. + +## Support + +The schema is supported for both kinds of ads - video and display. + +The JSTag integration is not supported yet. + + +## How it works + + +DSPs should rely on the SDK version in the bid request: +``` +"displaymanagerver": "4.11.0" +``` + +Starting with version 4.11.0 Android SDK supports deeplink+ + +To leverage the retargeting campaigns buyers use a specific scheme as click URL in the ad response. That URL describes the deep-linking and failover logic: + +``` +deeplink+://navigate? + primaryUrl=PRIMARY_DEEPLINK& + primaryTrackingUrl=PRIMARY_TRACKER& + fallbackUrl=FALLBACK_URL + &fallbackTrackingUrl=FALLBACK_TRACKER +``` + +The only required parameter is `primaryUrl` and if there are no other parameters, the deeplink+ would be handled as standard deeplink URL: doing nothing if the app is missing. + +The `fallbackUrl` can be any supported URI type (e.g., http, traditional deeplink) except for another Deep Link+ URL. To specify multiple tracker URLs (primary or fallback), buyers simply need to repeat the tracker key with any desired tracker URLs. The `primaryTrackingURL` is triggered if the deeplink is successful (which occurs after the user clicks). + +For example, below is a Deep Link+ URL whose primary target is the Twitter app, with two (2) primary tracker URLs, a fallback URL directing the user to Twitter’s mobile website if the primary deeplink fails and zero (0) fallback tracker URLs: + +``` +deeplink+://navigate? + primaryUrl=twitter%3A%2F%2Ftimeline& + primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fclicktracking& + primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fmopubtracking& + fallbackUrl=http%3A%2F%2Fmobile.twitter.com +``` + +The SDK will process this scheme regarding to the standard. + +## Integration tips + +**Publishers**: No action required for full-featured support of the ads with DeepLink+ schema. All work is performed by the SDK. + +**Buyers**: Must insert the deeplink+ scheme into creative or provide it via redirect for the regular clickthrough URL. diff --git a/prebid-mobile/modules/rendering/rendering-gam-line-item-setup.md b/prebid-mobile/modules/rendering/rendering-gam-line-item-setup.md new file mode 100644 index 0000000000..8d076a3502 --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-gam-line-item-setup.md @@ -0,0 +1,206 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering GAM Line Item Setup +description: Prebid Mobile Rendering Modules GAM line item setup +sidebarType: 2 + +--- + +# Google Ad Manager Setup + +## Step 1: Create New Order + + Pipeline Screenshot + + +## Step 2: Create Line Item + +To integrate the Prebid demand you have to create a Line Items with a specific price and targeting keywords. + +> Even though a Line Item can be named in any way, we strongly recommend to use the price or targeting keyword in the name. It will help to navigate through hundreds of them. + +### Select Type + +Create a Line Item depending on the type of expected creative kind: + +* **Display** - for the Banner, HTML Interstitial +* **Video and Audio** - for the Video Interstitial, Rewarded Video, and Outstream Video ads. + +Pipeline Screenshot + +Set sizes respectively to expected creatives. + +### Select Price + +The Line Item price should be chosen according to the price granularity policy. + +Pipeline Screenshot + +### Set Targeting Keywords + +The **Custom targeting** property should contain a special keyword with the price of winning bid. The same as a Rate of the Line Item. + +Pipeline Screenshot + +## Step 3: Prepare Prebid Creative + +### Display Banner, Video Banner, Display Interstitial, Video Interstitial. + +The Prebid SDK integrates with GAM basing on [App Events](https://developers.google.com/ad-manager/mobile-ads-sdk/android/banner#app_events) feature, almost for all ad formats. That means that creative should contain a special tag that will be processed by Prebid's GAM Event Handlers. + +If GAM Event Handler receives the `PrebidAppEvent` event it will render the winning bid. Otherwise the control will be passed to the GAM Ad View and it will render the received creative. + +``` html + + +``` + +Pipeline Screenshot + +### Rewarded Video + +Prebid rendering for Rewarded video ads is based on the [OnAdMetadataChangedListener](https://developers.google.com/android/reference/com/google/android/gms/ads/rewarded/OnAdMetadataChangedListener). So you need to set up a special VAST tag in the creative. + +``` js +https://cdn.jsdelivr.net/npm/prebid-universal-creative/dist/prebid-mobile-rewarded-vast.xml +``` + +Pipeline Screenshot + +If GAM Event Handler receives the tag's info it will render the winning bid. Otherwise the control will be passed to the GAM Ad View and it will render the received creative. + + \ No newline at end of file diff --git a/prebid-mobile/modules/rendering/rendering-impression-tracking.md b/prebid-mobile/modules/rendering/rendering-impression-tracking.md new file mode 100644 index 0000000000..868bf3c075 --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-impression-tracking.md @@ -0,0 +1,58 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# Impression Tracking + +## Responsibilities + +The impression tracking depends on a certain integration approach. + +In case of GAM or MoPub integration when the Ad Server ad wins - the impression will be tracked according to the policy of the certain Primary Ad Server SDK that will handle the rendering. + +If Prebid ad wins on the Primary Ad Server Auction, the impression tracking will depend on particular integration kind: + +* **GAM** impression will be tracked only for banner ads since it allows [manual impression counting](https://developers.google.com/ad-manager/mobile-ads-sdk/android/banner#manual_impression_counting). Rendering Module is not able to track impressions for GAM Interstitial or Rewarded ads. +* **MoPub** impression will be tracked as stated in the MoPub policies since the rendering part is performed according to the Mediation feature. +* **Pure In-App Bidding** impression pixels for Open Measurement and VAST will be tracked according to the [In-App Bidding Impression](#in-app-bidding-impression) policies of the SDK. + + +## In-App Bidding Impression + +Prebid Rendering Module tracks the impression pixel as stated in a definition of **render impression** from [Mobile Application Advertising Measurement Guidelines](http://mediaratingcouncil.org/Mobile%20In-App%20Measurement%20Guidelines%20(MMTF%20Final%20v1.1).pdf): + + +> **Ad Impression**: A measurement of responses from an ad delivery system to an ad request from the user's device, which is filtered for invalid traffic and is recorded at a point as late as possible in the process of delivery of the creative material to the user's device. The ad must be loaded and at minimum begin to render in order to count it as a valid ad impression. Measurement of begin to render should include logical components necessary to display the ad, but does not necessarily include logical elements that are not essential (such as other tracking elements). +> +> In the context of the guidance above, “loaded” means the logical creative file has been transmitted and received at the client-side (user device) and “render” refers to the process of painting the creative file or adding it to any portion of the Document Object Model. + +The impression pixel is triggered when at least 1 pixel of the creative appears on the screen. +This rule is applied to all tracking pixels display, video, Open Measurement. + +## MRAID + +### MRAID 2.0 Creative + +SDK broadcasts the `mraid.viewableChange()` event when the ad becomes rendered. It means that for proper impression tracking with MRAID the creative's code for tracking impression must depend on `mraid.isViewable()`. For example: + + +``` javascript +if ( mraid.viewableChangeEventWasDetected() ) + if( mraid.isViewable() == true) + fireMyImpressionTrackers(); + else if ( mraid.isViewable() == false) + doNothing(); +``` + +Otherwise the impression tracking would be inconsistent with Prebid Rendering SDK approach. + +### MRAID 3.0 Creative + +For the ads that support the MRAID 3, the impression tracking code should be rather dependent on `exposureChange()` function. Since it provides much more information about the viewability of an Ad Container, the impression tracking could be much more accurate and correspond to the MRC and IAB guidelines. + +However, the IAB strongly recommends not to use the MRAID facilities to track impressions. The best practice is to use the **Open Measurement** framework which is supported by SDK as well. \ No newline at end of file diff --git a/prebid-mobile/modules/rendering/rendering-max-line-item-setup.md b/prebid-mobile/modules/rendering/rendering-max-line-item-setup.md new file mode 100644 index 0000000000..7b9780fa1d --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-max-line-item-setup.md @@ -0,0 +1,51 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Modules +description: Prebid Mobile Rendering Modules architecture +sidebarType: 2 + +--- + +# AppLovin MAX Setup + +## Custom Network Setup + +In your MAX account go to `Mediation` -> `Manage` -> `Networks` and click `Click here to add a Custom Network`. Then create an **SDK** custom network with the following adapter names: + +Pipeline Screenshot + + + +iOS adapter: +``` +PrebidMAXMediationAdapter +``` + +Android Adapter: +``` +com.applovin.mediation.adapters.PrebidMaxMediationAdapter +``` + + +## Add Placements + + +Now you have to add placements for Prebid Custom Network into the respective ad unit's waterfall. + +Create or choose an existing Ad Unit. Go the the `Custom Networks & Deals` section. Chose the Prebid's custom network that you created at the previous step. Change the status to active and add placements following the [price granularity](https://docs.prebid.org/prebid-mobile/adops-price-granularity.html#prebid-mobile-price-granularity) guide to determine how many entries you need. + +Pipeline Screenshot + + +Make sure that the `Custom Parameters` field contain expecting targetting keywords of the winning bid: + +``` +{"hb_pb":"0.10"} +``` + +{: .alert.alert-warning :} +The adapter will render the winning bid only if the bid's targeting keywords contain `all` keywords from the `Custom Parameters` field. + + + diff --git a/prebid-mobile/modules/rendering/rendering-native-ad-configuration.md b/prebid-mobile/modules/rendering/rendering-native-ad-configuration.md new file mode 100644 index 0000000000..b75d9e1a91 --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-native-ad-configuration.md @@ -0,0 +1,122 @@ +--- + +layout: page_v2 +title: Native Ad Configuration +description: Properties and structure of native ads +sidebarType: 2 + +--- + +# Native Ad Configuration + + +The `NativeAdConfiguration` class provides an ability to set *assets*, *event trackers* and other *OpenRTB parameters* required for Native Ads. + +## Parameters + +{: .table .table-bordered .table-striped } + +| Property | Default | Required | Description | +|:---------------|:--------|:------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| context | Undefined | recommended | The context in which the ad appears | +| contextsubtype | Undefined | optional | A more detailed context in which the ad appears | +| plcmttype | Undefined | recommended | The design/format/layout of the ad unit being offered | +| seq | - | optional | 0 for the first ad, 1 for the second ad, and so on. Note this would generally NOT be used in combination with plcmtcnt - either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1) | +| assets | - | required | An array of Asset Objects. | +| eventtrackers | - | optional | Specifies what type of event tracking is supported | +| privacy | false | recommended | Set to 1 when the native ad supports buyer-specific privacy notice. Set to 0 when the native ad doesn’t support custom privacy links or if support is unknown | +| ext | - | optional | This object is a placeholder that may contain custom JSON | + +> **Note:** `plcmtcnt`, `aurlsupport` and `durlsupport` OpenRTB fields are not supported + +## Event Trackers + +`NativeEventTracker` class is used to set up the `eventtrackers` field for the Native bid request respectively to the OpenRTB docs. + +The event tracker object specifies the kinds of events the bidder can request to be tracked in the bid response, and which types of tracking are available for each event type. + +### Event Trackers Properties + +{: .table .table-bordered .table-striped } + +| Name | Description | +|:---------------------|:-------------------------------------------------------------| +| eventType | Type of event available for tracking | +| eventTrackingMethods | Array of the types of tracking available for the given event | +| ext | The custom extension available to the publisher | + + +### Event Trackers Enums + +#### NativeEventType + +{: .table .table-bordered .table-striped } + +| Name | ID | Description | +|:-----------------|:-----|:-------------------------------------------------------------------------------| +| Impression | 1 | Impression | +| MRC50 | 2 | Visible impression using MRC definition at 50% in view for 1second | +| MRC100 | 3 | 100% in view for 1 second (ie GroupM standard) | +| Video50 | 4 | Visible impression for video using MRC definition at 50% in view for 2 seconds | +| ExchangeSpecific | 500+ | Exchange specific | + +#### NativeEventTrackingMethod + +{: .table .table-bordered .table-striped } + +| Name | ID | Description | +|:-------|:-----|:------------------------------------------------------------------------------------------------------------------------------------------| +| Image | 1 | Image-pixel tracking - URL provided will be inserted as a 1x1 pixel at the time of the event | +| JS | 2 | Javascript-based tracking - URL provided will be inserted as a js tag at the time of the event | +| ExchangeSpecific | 500+ | Could include custom measurement companies such as moat, double verify, IAS, etc - in this case additional elements will often be passed | + + +## Enums + +### NativeContextType + +{: .table .table-bordered .table-striped } + +| Name | ID | Description | +|:----------------|:-----|:---------------------------------------------------------------------------------------------| +| Undefined | 0 | Unset | +| ContentCentric | 1 | Content-centric context such as news feed, article, image gallery, video gallery, or similar | +| SocialCentric | 2 | Social-centric context such as social network feed, email, chat, or similar | +| Product | 3 | Product context such as product listings, details, recommendations, reviews, or similar | +| ExchangeSpecific| 500+ | To be defined by the exchange | + +### NativeContextSubtype + +> **NOTE**: SubType should only be combined with the primary context type as indicated (ie for a context type of 1, only context subtypes that start with 1 are valid). + +{: .table .table-bordered .table-striped } + +| Name | ID | Description | +|:---------------------|:-----|:---------------------------------------------------------------------------------------------| +| Undefined | 0 | Unset| +| GeneralOrMixed | 10 | General or mixed content | +| Article | 11 | Primarily article content (which of course could include images, etc as part of the article) | +| Video | 12 | Primarily video content | +| Audio | 13 | Primarily audio content | +| Image | 14 | Primarily image content | +| UserGenerated | 15 | User-generated content - forums, comments, etc | +| Social | 20 | General social content such as a general social network | +| Email | 21 | Primarily email content | +| Chat | 22 | Primarily chat/IM content | +| SellingProducts | 30 | Content focused on selling products, whether digital or physical | +| ApplicationStore | 31 | Application store/marketplace | +| ProductReview | 32 | Product reviews site primarily (which may sell product secondarily) | +| ExchangeSpecific | 500+ | To be defined by the exchange | + +### NativePlacementType + +{: .table .table-bordered .table-striped } + +| Name | ID | Description | +|:----------------------|:-----|:-------------------------------------------------------------------------------------------------------------------------------| +| Undefined | 0 || +| FeedGridListing | 1 | In the feed of content - for example as an item inside the organic feed/grid/listing/carousel | +| AtomicUnit | 2 | In the atomic unit of the content - IE in the article page or single image page | +| OutsideCoreContent | 3 | Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc | +| RecommendationWidget | 4 | Recommendation widget, most commonly presented below the article content | +| ExchangeSpecific | 500+ | To be defined by the exchange | diff --git a/prebid-mobile/modules/rendering/rendering-native-guidelines.md b/prebid-mobile/modules/rendering/rendering-native-guidelines.md new file mode 100644 index 0000000000..4c589e694d --- /dev/null +++ b/prebid-mobile/modules/rendering/rendering-native-guidelines.md @@ -0,0 +1,74 @@ +--- + +layout: page_v2 +title: Native Ads Guidelines +description: The best practices for implementing native ads +sidebarType: 2 + +--- + +# Native Ads Guidelines + +## Getting Started + +The Prebid Rendering Module implements the [OpenRTB Specification](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) for the native ads. + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout: + * HTML and CSS for the Native Styles format. + * Native components for the Unified Ads format. +1. Configure the Native Ad using [NativeAdConfiguration](rendering-native-ad-configuration.html). + * Provide the list of [Native Assets](#components) representing the ad's structure. + * Tune other general properties of the ad. +1. Make a bid request. +1. **OPTIONAL** Bind the data from the bid response with the layout, if it is needed for the particular integration. + +### Unified Native Ads + +The general integration scenario requires these steps from publishers: + +1. Prepare the ad layout using the native components in the codebase of the app. +2. Create Native Ad Unit. +3. Configure the Native Ad unit using [NativeAdConfiguration](rendering-native-ad-configuration.html). + * Provide the list of [Native Assets](#components) representing the ad's structure. + * Tune other general properties of the ad. +4. Make a bid request. +5. Find the winning native ad using `GAMUtils.shared.findNativeAd` or `MoPubUtils.findNativeAd`. +6. Bind the data from the native ad response with the layout. + +### Native Styles + +The Prebid Rendering Module supports the original prebid's approach for rendering [native ads](https://docs.prebid.org/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.html). It is similar to the Google's Native Styles ad format. In this case publisher should preare the layout of the ad using HTML and CSS and add the universal creative to the ad code. + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/Native-Styles-Primary-Ad-Server.png) + +1. Prebid Rendering Module sends the bid request. +2. Prebid server runs the header bidding auction among preconfigured demand partners. +3. In-App Bidding SDK sets up the targeting keywords of the winning bid to the ad unit of Primary Ad Server SDK. +4. Primary Ad Server SDK sends the ad request to the Ad Server. If Prebid's line item wins the ad response will contain **Prebid Universal Creative** and **Ad Layout**. +5. The received creative will be rendered in the Web View of Primary Ad Server SDK. + +The ad will be rendered in the web view. The rendering engine will be the prebid's universal creative. It will load the winning bid from the prebid cache and substitute assets into the ad markup. For the more detailed info visit the Prebid's instructions about [How Native Ads Work](https://docs.prebid.org/dev-docs/show-native-ads.html#how-native-ads-work). + +In order to prepare the valid layout folow the instructions in the Prebid docs for [Mobile in general](https://docs.prebid.org/prebid-mobile/adops-native-setup.html) and for [Google Ad Manager](https://docs.prebid.org/adops/setting-up-prebid-native-in-dfp.html). + +In the case of integration of Native Styles ads without Primary Ad Server publishers should provide the Ad Layout to the SDK. And the winning bid will be rendered right after receiving it from Prebid. + +![Rendering with GAM as the Primary Ad Server](/assets/images/prebid-mobile/modules/rendering/Native-Styles-Prebid.png) + +1. Setup layout for the Native Styles ad. +2. Prebid Rendering Module sends the bid request. +3. Prebid server runs the header bidding auction among preconfigured demand partners. +3. The received creative will be rendered in the Web View of Prebid Rendering Module. + +## Components + +The Prebid Rendering Module supports all Native Ad components proclaimed by the OpenRTB specification: **title**, **image**, **video**, **data**. + +We strongly recommend to follow the industry best practices and requirements, especially in the case of integration with Primary Ad Server: + +* [OpenRTB Specification](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) +* [The Native Advertizing Playbook](https://www.iab.com/wp-content/uploads/2015/06/IAB-Native-Advertising-Playbook2.pdf) +* [Google Guidelines](https://support.google.com/admanager/answer/6075370) +* [MoPub Guidelines](https://developers.mopub.com/publishers/best-practices/native-ads/) diff --git a/prebid-mobile/pbm-api/android/code-integration-android.md b/prebid-mobile/pbm-api/android/code-integration-android.md index cae4ee0f81..b61db1d2d6 100644 --- a/prebid-mobile/pbm-api/android/code-integration-android.md +++ b/prebid-mobile/pbm-api/android/code-integration-android.md @@ -10,24 +10,29 @@ sidebarType: 2 # Code Integration for Android -Get started with Prebid Mobile by creating a [Prebid Server account]({{site.github.url}}/prebid-mobile/prebid-mobile-pbs.html). Once your account is set up include the Prebid Mobile SDK in your app by either using Maven or by [cloning the repo](https://github.com/prebid/prebid-mobile-android) and using our included script to build the SDK. +Get started with Prebid Mobile by getting access to a [Prebid Server](/prebid-mobile/prebid-mobile-pbs.html). Once your account is set up include the Prebid Mobile SDK in your app by either using Maven or by [cloning the repo](https://github.com/prebid/prebid-mobile-android) and using our included script to build the SDK. ### Include with Maven If you are not familar with using Maven for build management visit the [Maven website](https://maven.apache.org/index.html). -To include the Prebid Mobile SDK simply add this line to your gradle dependencies: +To include the Prebid Mobile SDK simply add this line to your gradle dependencies to get the lastest stable release: ``` -implementation 'org.prebid:prebid-mobile-sdk:[1,2)' +implementation 'org.prebid:prebid-mobile-sdk:1.12.2' ``` -If you wish to explicitly state the lastest stable release, please use the following: +{% capture warning_note %} +Prebid is going to release beta versions of SDK from time to time. So if you don't want to update to beta versions - avoid Maven's range notation for the dependency versions. +If you still use the range notation like this: ``` -implementation 'org.prebid:prebid-mobile-sdk:1.3' +implementation 'org.prebid:prebid-mobile-sdk:[1,2)' ``` +please change it to the strict version. {% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + ### Build framework from source @@ -67,6 +72,20 @@ For details on creating the specific ad units and additional parameters and meth [Banner Ad Unit](/prebid-mobile/pbm-api/android/pbm-banneradunit-android.html) [Interstitial Ad Unit](/prebid-mobile/pbm-api/android/pbm-bannerinterstitialadunit-android.html) +#### Using Asset Ids with In-App Native Ad Units + +Setting this option to `true`, in your instance of Prebid Mobile, enables you to add an id for each asset in the assets array. The default setting is `false` + +**Kotlin** +``` +PrebidMobile.assignNativeAssetID(true) +``` + +**Java** +``` +PrebidMobile.assignNativeAssetID(true); +``` + ### Resize ad slot Prebid recommends app developers to resize ads slots to the Prebid rendering ad size using native code due to an unresolved bug in the Google Mobile Ads SDK (described [here](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!category-topic/google-admob-ads-sdk/ios/648jzAP2EQY)) where render failures can occur with 3rd party creatives (such as Prebid Universal Creative) using size overrides. diff --git a/prebid-mobile/pbm-api/android/pbm-adunit-android.md b/prebid-mobile/pbm-api/android/pbm-adunit-android.md index 121b7e7761..216ec73a8b 100755 --- a/prebid-mobile/pbm-api/android/pbm-adunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-adunit-android.md @@ -23,12 +23,12 @@ The `AdUnit` object is an abstract object that cannot be instantiated. Use the [ **Parameters** -- `configId`: String containing the Prebid Server configuration ID. +- `configId`: String containing the Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). - `adType`: `BANNER` or `INTERSITIAL`. This value will be set by the object based on which type of ad unit object you create. **Properties** -- `configId`: Prebid Server configuration ID. +- `configId`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). - `adType`: `BANNER` or `INTERSITIAL`. - `periodMillis`: Integer defining the refresh time in milliseconds. Default = 0, meaning no auto refresh. - `keywords`: ArrayList containing keys and values. @@ -104,7 +104,9 @@ private void loadMPRewardedVideo() { } ``` +### setAppContent +Provides targeting information for the `app.content` field of the bid request. Parameter is an `ContentObject` wich provides all respective fields. ### setAutoRefreshPeriodMillis @@ -255,6 +257,42 @@ Clear all key-value combinations from the Prebid Mobile ad unit. none +### UserData + +The following methods enable adding `user.data[]` objects into the bid request: + +``` +public void addUserData(DataObject dataObject) +``` + +``` +public ArrayList getUserData() +``` + +``` +public void clearUserData() +``` + +### App Content Data + +In order to set the `app.contnent.data[]` objects use the `getAppContent()` first and then one of the respective methods of the `ContentObject` class: + +``` +public void addData(@NonNull DataObject dataObject) +``` + +``` +public ArrayList getDataList() +``` + +``` +public void setDataList(@NonNull ArrayList dataObjects) +``` + +``` +public void clearDataList() +``` + ## Example ``` diff --git a/prebid-mobile/pbm-api/android/pbm-banneradunit-android.md b/prebid-mobile/pbm-api/android/pbm-banneradunit-android.md index e48b1378aa..6c2199e327 100755 --- a/prebid-mobile/pbm-api/android/pbm-banneradunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-banneradunit-android.md @@ -19,11 +19,11 @@ Use the `BannerAdUnit` object to create and configure a banner ad unit in your a ### BannerAdUnit -Create a new Banner Ad Unit associated with a Prebid Server configuration ID and a banner size. +Create a new Banner Ad Unit associated with a Prebid Server 'configuration ID' and a banner size. **Parameters** -- `configId`: String; Prebid Server configuration ID. +- `configId`: String; Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). - `width`: Integer; Width of the ad unit. - `height`: Integer; Height of the ad unit. diff --git a/prebid-mobile/pbm-api/android/pbm-bannerinterstitialadunit-android.md b/prebid-mobile/pbm-api/android/pbm-bannerinterstitialadunit-android.md index 35bbb34ff7..05e7f978b1 100755 --- a/prebid-mobile/pbm-api/android/pbm-bannerinterstitialadunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-bannerinterstitialadunit-android.md @@ -29,7 +29,7 @@ Prebid Server will send the eligible size list to each bidder to solicit a bid. **Parameters** -`configId`: Prebid Server configuration ID. +`configId`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occuy of a device's real estate. Support in SDK version 1.2+ diff --git a/prebid-mobile/pbm-api/android/pbm-native-inapp-android.md b/prebid-mobile/pbm-api/android/pbm-native-inapp-android.md index 73313bb13f..cae9002fa8 100644 --- a/prebid-mobile/pbm-api/android/pbm-native-inapp-android.md +++ b/prebid-mobile/pbm-api/android/pbm-native-inapp-android.md @@ -28,6 +28,10 @@ The cached assets might expire. If this occurs the publisher will receive a noti {% include alerts/alert_important.html content=importantNote %} +{% capture importantNote %} +Starting with the `1.14.0-beta1` version the converting of the native ad template to the ad objects is changed to match the IAB specs. See this [issue](https://github.com/prebid/prebid-mobile-ios/issues/494) for the details. If you update SDK from the previous version - verify the native ads integration before the release. +{% endcapture %} + ## Ad Ops Setup These instructions will enable you to create a creative template in either Google Ad Manager or MoPub that can then be applied to native ads in your app. @@ -110,7 +114,7 @@ The `PrebidNativeAdListener` interface provides three methods to handle the disp **onPrebidNativeNotFound** - Use this method when a Prebid Native is not found in the server returned response. The ad should be displayed as a regular AdUnit type. + Use this method when a Prebid Native ad is not found in the server returned response. The ad should be displayed as a regular AdUnit type. **onPrebidNativeNotValid** @@ -122,6 +126,20 @@ The `PrebidNativeAdListener` interface provides three methods to handle the disp An object representing the `PrebidNativeAd` to be displayed. +#### Using Asset Ids with In-App Native Ad Units + +Setting this option to `true`, in your instance of Prebid Mobile, enables you to add an id for each asset in the assets array. The default setting is `false` + +**Kotlin** +``` +PrebidMobile.assignNativeAssetID(true) +``` + +**Java** +``` +PrebidMobile.assignNativeAssetID(true); +``` + ##### Methods *registerView* diff --git a/prebid-mobile/pbm-api/android/pbm-nativeadunit-android.md b/prebid-mobile/pbm-api/android/pbm-nativeadunit-android.md index f73d087b18..71c9f9939f 100644 --- a/prebid-mobile/pbm-api/android/pbm-nativeadunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-nativeadunit-android.md @@ -23,7 +23,7 @@ See [AdUnit](/prebid-mobile/pbm-api/android/pbm-adunit-android.html) for additio **Parameters** -`configId (String)`: Prebid Server configuration ID. +`configId (String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). ## Examples diff --git a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md index cd857e9ad4..6a25b808c5 100755 --- a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md +++ b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md @@ -114,9 +114,9 @@ TargetingParams.setStoreUrl(storeUrl); ``` -### Open Measurment SDK (OMSDK) +### Open Measurement SDK (OMSDK) -OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is elligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. +OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. There three components to signaling support for OMSDK: * Partner Name @@ -168,9 +168,10 @@ Example: BannerAdUnit bannerAdUnit = new BannerAdUnit("PREBID_SERVER_CONFIGURATION_ID", 300, 250); bannerAdUnit.setUserKeyword("my_key", "my_value"); BannerBaseAdUnit.Parameters parameters = new BannerBaseAdUnit.Parameters(); -parameters.setApi(Arrays.asList(new Signals.Api(6, 7))); +parameters.setApi(Arrays.asList(new Signals.Api(7))); ``` +Note that the OMID value for imp.banner/video/native.api field should be 7, as defined by the IAB in the [OMSDK v1.2 document](https://s3-us-west-2.amazonaws.com/omsdk-files/docs/Open+Measurement+SDK+Onboarding_version_1.2.pdf). ### Inventory (Context) Keywords @@ -212,7 +213,7 @@ Data is broken up into two different data types: * Global scope * Ad Unit grain - The below first party user and inventory context will apply to all ad units. For ad unit level first party data, refer to [First Partay Data section in the Ad Unit](pbm-adunit-android#first-party-data) page. + The below first party user and inventory context will apply to all ad units. For ad unit level first party data, refer to [First Party Data section in the Ad Unit](pbm-adunit-android#first-party-data) page. ### First Party User Data User specic data is passed in the global scope (i.e. applicable to all ad units). diff --git a/prebid-mobile/pbm-api/android/pbm-video-instream-android.md b/prebid-mobile/pbm-api/android/pbm-video-instream-android.md index 60d0c8e655..6cf32ad0a5 100644 --- a/prebid-mobile/pbm-api/android/pbm-video-instream-android.md +++ b/prebid-mobile/pbm-api/android/pbm-video-instream-android.md @@ -29,7 +29,7 @@ VideoAdUnit("configID", width, height, VideoAdUnit.PlacementType.placement); ``` **Parameters** -* `configId`: String; Prebid Server configuration ID. +* `configId`: String; Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). * `width`: Integer; Width of the video player. * `height`: Integer; Height of the video player. * `placement` (DEPRECATED FIELD) Enumeration. Possible values: diff --git a/prebid-mobile/pbm-api/android/pbm-video-rewarded-adunit-android.md b/prebid-mobile/pbm-api/android/pbm-video-rewarded-adunit-android.md index dd08df289a..6428c3fa89 100755 --- a/prebid-mobile/pbm-api/android/pbm-video-rewarded-adunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-video-rewarded-adunit-android.md @@ -30,7 +30,7 @@ RewardedVideoAdUnit("configId"); **Parameters** -`configId`: String; Prebid Server configuration ID. +`configId`: String; Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). ### Paramaters diff --git a/prebid-mobile/pbm-api/android/pbm-videointerstitialadunit-android.md b/prebid-mobile/pbm-api/android/pbm-videointerstitialadunit-android.md index 47378cdcdb..d44eb8b16d 100755 --- a/prebid-mobile/pbm-api/android/pbm-videointerstitialadunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-videointerstitialadunit-android.md @@ -32,7 +32,7 @@ VideoInterstitialAdUnit("configId"); **Parameters** -`configId`: String; Prebid Server configuration ID. +`configId`: String; Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). ### Paramaters diff --git a/prebid-mobile/pbm-api/android/pbm-videooutstreamadunit-android.md b/prebid-mobile/pbm-api/android/pbm-videooutstreamadunit-android.md index 28b47e6f70..634e8feb22 100755 --- a/prebid-mobile/pbm-api/android/pbm-videooutstreamadunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-videooutstreamadunit-android.md @@ -30,7 +30,7 @@ VideoAdUnit("configID", width, height, VideoAdUnit.PlacementType.placement); //p **Parameters** -* `configId`: String; Prebid Server configuration ID. +* `configId`: String; Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). * `width`: Integer; Width of the video player. * `height`: Integer; Height of the video player. * `placement` (DEPRECATED FIELD) Enumeration. Possible values: diff --git a/prebid-mobile/pbm-api/android/prebidmobile-object-android.md b/prebid-mobile/pbm-api/android/prebidmobile-object-android.md index 97bd8bc04a..751850a1a7 100755 --- a/prebid-mobile/pbm-api/android/prebidmobile-object-android.md +++ b/prebid-mobile/pbm-api/android/prebidmobile-object-android.md @@ -131,6 +131,19 @@ none boolean isShareGeoLocation() ``` +### setCustomHeaders + +The following methods enable the customization of the HTTP call to the Prebid server: + +``` +public static void setCustomHeaders(HashMap customHeaders) +``` + +You can also inspect the current custon headers using: + +``` +public static HashMap getCustomHeaders() +``` ### setApplicationContext diff --git a/prebid-mobile/pbm-api/ios/code-integration-ios.md b/prebid-mobile/pbm-api/ios/code-integration-ios.md index a817247d97..dca08a5f04 100644 --- a/prebid-mobile/pbm-api/ios/code-integration-ios.md +++ b/prebid-mobile/pbm-api/ios/code-integration-ios.md @@ -16,7 +16,9 @@ Get started with Prebid Mobile by creating a [Prebid Server account]({{site.gith - TOC {:toc} -### Include with Cocoapods +## Package Managers + +### Cocoapods If you are not familar with using Cocoapods for dependency management visit their [getting started page](https://guides.cocoapods.org/using/getting-started.html). Once you have your `podfile` setup, include the following: @@ -28,54 +30,61 @@ target 'MyAmazingApp' do end ``` -### Include with Carthage +Run the following commands: + +1. Install CocoaPods +1. Run `pod install` +1. Add Prebid pod into `Podfile`, specify version if nedded +1. Run `pod update` +1. Use the `.xcworkspace` file which was generated by CocoaPods + +### Carthage If you are not familiar with the Carthage package builder, please refere to the project [github page](https://github.com/Carthage/Carthage) for more details. -Since Prebid SDK architecture supports a multi-module feature for future enhancements, that currently use the same module name for every schema, please use CarthageBuild.sh script to build a necessary binary. +1. Install Carthage +2. Add `github prebid/prebid-mobile-ios` to your `Cartfile`. +3. Run `carthage update`. +4. Drag <[module_name]({{site.baseurl}}/prebid-mobile/modules/modules-overview.html)>.framework from `Carthage/Build` to `General -> Linked Frameworks and Libraries` -There are two shared schemes available ([issue #239](https://github.com/prebid/prebid-mobile-ios/issues/239)): -- PrebidMobile -- PrebidMobileCore -Follow the next steps: +### XCFramework -1. Add PrebidSDK dependency into Cartfile. Release notes -``` -github "prebid/prebid-mobile-ios" == 1.5 -``` -2. Update Carthage -``` -carthage update -``` +1. Clone the project and run buildPrebidMobile.sh script from `scripts` folder +2. Drag XC<[module_name]({{site.baseurl}}/prebid-mobile/modules/modules-overview.html)>.xcframework(e.g. XCPrebidMobile.xcframework) from `generated/output` directory into your project. Make sure Copy items if needed is selected. +3. Go to your Xcode project’s `General -> Frameworks, Libraries, and Embedded Content` settings. Use `Embed & Sign` for dynamic and `Do Not Embed` for static linking + + +### Swift PM +If you are not familiar with the Swift Package Manager, please refere to the project [github page](https://github.com/apple/swift-package-manager) for more details. + +1. Add Prebid dependency `File -> Swift Packages -> Add Package Dependency...` +2. Select desired version, branch or commit +3. Select Prebid [module]({{site.baseurl}}/prebid-mobile/modules/modules-overview.html) 3. Build the specific schema `CarthageBuild.sh` - + **Variant 1** - + - Run CarthageBuild.sh script from Cartfile folder. The path should be: `.../Carthage/Checkouts/prebid-mobile-ios/scripts/CarthageBuild.sh` - + - Enter Schema name (PrebidMobile or PrebidMobileCore) - If you run CarthageBuild.sh and see Permission denied use: `chmod +x ` - + **Variant 2** - + - Open `PrebidMobile.xcodeproj` at `.../Carthage/Checkouts/prebid-mobile-ios/PrebidMobile.xcodeproj` using Xcode - + - Manage Schemes -> Check Shared checkbox for a necessary schema - + - run `carthage build prebid-mobile-ios` 4. Integrate the binary into your project - - You can find the schema name in the build PrebidSDK framework inside Info.plist with `PrebidMobileName` key - - ### Build framework from source Build Prebid Mobile from source code. After [cloning the repo](https://github.com/prebid/prebid-mobile-ios), use Terminal or another command line tool, change to the root directory and run: @@ -85,15 +94,12 @@ Build Prebid Mobile from source code. After [cloning the repo](https://github.co ``` This will output the PrebidMobile.framework. -### Setup Prebid Server Account - -In order to conduct header bidding within your app you will need a Prebid Server hosted account. There are two options available for publishers: - -1. The simplest option is to sign up for a hosted solution. Several [Prebid.org members](https://prebid.org/product-suite/managed-services/) provide hosting packages. +### Setup Prebid Server -2. Implement your own Prebid Server solution. You will need to [download](https://github.com/prebid/prebid-server) the source code from Github. The repository has [full instructions](https://github.com/prebid/prebid-server/tree/master/docs/developers) for configuring, deploying, and testing your implementation. +In order to conduct header bidding within your app you will need a Prebid Server hosted account. There are two options available for publishers described at [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-pbs.html). -Once you have a Prebid Server account, you will need to add your account credentials to the app. +Once you have a Prebid Server, you will add 'account' info to the app. For +example, if you're using the AppNexus Prebid Server: ``` @@ -101,6 +107,15 @@ Prebid.shared.prebidServerAccountId = @"YOUR_ACCOUNT_ID"; Prebid.shared.prebidServerHost = PrebidHostAppnexus; ``` +{: .alert.alert-info :} +Note that in actuality, the "account ID" is just the name of the "top-level" +stored request as described on the [Prebid Server Stored Request](/prebid-server/features/pbs-storedreqs.html) page. By convention, most Prebid Server host companies define the top level stored request ID as the +account ID they assign to the publisher. This is a convenient convention since +publishers generally set the same timeout and price granularity across all +apps. But it may not be the case for your +Prebid Server host company, so please check with them. If you're hosting your own +Prebid Server, this value can be whatever value you wish, not necessarily an account ID. + If you have opted to host your own Prebid Server solution you will need to store the url to the server in your app. @@ -141,6 +156,20 @@ For details on creating the specific ad units and additional parameters and meth [Banner Ad Unit](/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.html) [Interstitial Ad Unit](/prebid-mobile/pbm-api/ios/pbm-bannerinterstitialadunit-ios.html) +#### Using Asset Ids with In-App Native Ad Units + +Setting this option to `true`, in your instance of Prebid Mobile, enables you to add an id for each asset in the assets array. The default setting is `false` + +**Swift** +``` +Prebid.shared.shouldAssignNativeAssetID = true +``` + +**Objective C** +``` +[Prebid shared].shouldAssignNativeAssetID = YES; +``` + ### Resize ad slot Prebid recommends app developers to resize ads slots to the Prebid rendering ad size using native code due to an unresolved bug in the Google Mobile Ads SDK (described [here](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!category-topic/google-admob-ads-sdk/ios/648jzAP2EQY)) where render failures can occur with 3rd party creatives (such as Prebid Universal Creative) using size overrides. @@ -149,7 +178,8 @@ Prebid recommends app developers to resize ads slots to the Prebid rendering ad Failure to resize rendering Prebid ads can cause revenue loss under certain conditions. For this reason, we advise using the below resize function in all scenarios. {% endcapture %} {% include /alerts/alert_warning.html content=warning_note %} -*SWIFT* +**Swift** + ```swift func adViewDidReceiveAd(_ bannerView: GADBannerView) { @@ -168,12 +198,11 @@ func adViewDidReceiveAd(_ bannerView: GADBannerView) { }) } +``` +**Objective-C** - ``` - -*Objective C* - ```objective_c +```objective_c -(void) adViewDidReceiveAd:(GADBannerView *)bannerView { NSLog(@"Ad received"); [AdViewUtils findPrebidCreativeSize:bannerView @@ -187,7 +216,7 @@ func adViewDidReceiveAd(_ bannerView: GADBannerView) { NSLog(@"error: %@", error); }]; } - ``` +``` ## Further Reading diff --git a/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md index 3c688d4fb5..92513cc1a1 100755 --- a/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md @@ -27,7 +27,7 @@ Create a new Banner Ad Unit or Interstitial Ad Unit with a Prebid Server configu **Parameters** -`configId`: String containing the Prebid Server configuration ID. +`configId`: String containing the Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `size:`: CGSize conatining width and height of the AdUnit. @@ -193,12 +193,60 @@ func removeContextKeyword(_ element: String) func clearContextKeywords() ``` +### App Content +The `ContentObject` alows you to provide more details about content whithin the app. All proeprties provided to the `ContentObject` will be sent in the `app.content` field of the bid request. +``` +func setAppContent(_ appContent: ContentObject) +``` + +``` +func getAppContent() -> ContentObject? +``` + +``` +func clearAppContent() +``` + +### App Content Data + +Using the following methods you can add `app.content.data` objects to the bid requests. + +``` +func addAppContentData(_ dataObjects: [ContentDataObject]) +``` + +``` +func removeAppContentData(_ dataObject: ContentDataObject) +``` + +``` +func clearAppContentData() +``` + +### User Data + +Using the following methods you can add `user.data` objects to the bid requests. + +``` +func getUserData() -> [PBMORTBContentData]? +``` +``` +func addUserData(_ userDataObjects: [PBMORTBContentData]) +``` + +``` +func removeUserData(_ userDataObject: PBMORTBContentData) +``` + +``` +func clearUserData() +``` ### Data Object -The Data object is free form data (also known as First Party Data)supplied by the publisher to provide additional targeting of the user or inventory context, used primarily for striking PMP (Private MarketPlace) deals with Advertisers. Data supplied in the data parameters are typically not sent to DSPs whereas information sent in non-data objects (i.e. `setYearOfBirth`, `setGender`, etc.) will be. Access to FPD can be limited to a supplied set of Prebid bidders via an access control list. +The Data object is free form data (also known as First Party Data) supplied by the publisher to provide additional targeting of the user or inventory context, used primarily for striking PMP (Private MarketPlace) deals with Advertisers. Data supplied in the data parameters are typically not sent to DSPs whereas information sent in non-data objects (i.e. `setYearOfBirth`, `setGender`, etc.) will be. Access to FPD can be limited to a supplied set of Prebid bidders via an access control list. Data is broken up into two different data types: * User @@ -207,7 +255,7 @@ Data is broken up into two different data types: * Global scope * Ad Unit grain - The below first party inventory context will apply to the specic ad unit the data object is applied to. For global user or inventory context level first party data, refer to [first party data section of the Targeting](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data) page. +The first party inventory context below will apply to the specic ad unit the data object is applied to. For global user or inventory context level first party data, refer to [first party data section of the Targeting](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data) page. #### addContextData ``` diff --git a/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.md index 5f64545276..e537596409 100755 --- a/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.md @@ -25,7 +25,7 @@ See [AdUnit]({{site.baseurl}}/prebid-mobile/pbm-api/ios/pbm-adunit-ios.html) for **Parameters** -`configId (String)`: Prebid Server configuration ID. +`configId (String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `size (CGSize)`: Width and height of the banner. @@ -70,7 +70,7 @@ let bannerUnit = BannerAdUnit(configId: "6ace8c7d-88c0-4623-8117-75bc3f0a2e45", **Add additional ad sizes** ``` -bannerUnit.addAdditionalSizes(sizes: CGSize(width: 320, height: 50)) +bannerUnit.addAdditionalSize(sizes: [CGSize(width: 320, height: 50), CGSize(width: 300, height: 250)]) ``` Once a BannerAdUnit is created use Google Mobile Ads or MoPub to retrieve and display creatives. diff --git a/prebid-mobile/pbm-api/ios/pbm-bannerinterstitialadunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-bannerinterstitialadunit-ios.md index 428d549eec..3e891d2b8d 100755 --- a/prebid-mobile/pbm-api/ios/pbm-bannerinterstitialadunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-bannerinterstitialadunit-ios.md @@ -30,7 +30,7 @@ BannerInterstitialAdUnit(configId: String, minWidthPerc: Int, minHeightPerc: Int **Parameters** -`configId`: Prebid Server configuration ID. +`configId`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occuy of a device's real estate. Support in SDK version 1.2+ diff --git a/prebid-mobile/pbm-api/ios/pbm-code-integration-ios.md b/prebid-mobile/pbm-api/ios/pbm-code-integration-ios.md index 6de803a46e..a103962e7f 100644 --- a/prebid-mobile/pbm-api/ios/pbm-code-integration-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-code-integration-ios.md @@ -187,7 +187,7 @@ Create the ad units and add sizes for banner ad units. Replace `PREBID-SERVER- Prebid.shared.prebidServerAccountId = "`PREBID-SERVER-ACCOUNT-ID" Prebid.shared.shareGeoLocation = true -let bannerUnit = BannerAdUnit(configId: "PREBID-SERVER-CONFIGURATION-ID", size: CGSize(width: 300, height: 250)) +let bannerUnit = BannerAdUnit(configId: "PREBID-SERVER-IMPLEVEL-STOREDREQUEST-ID", size: CGSize(width: 300, height: 250)) bannerUnit.setAutoRefreshMillis(time: 35000) ``` **Google Ad Manager Example** diff --git a/prebid-mobile/pbm-api/ios/pbm-native-inapp-ios.md b/prebid-mobile/pbm-api/ios/pbm-native-inapp-ios.md index ac8e593117..51a8673e37 100644 --- a/prebid-mobile/pbm-api/ios/pbm-native-inapp-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-native-inapp-ios.md @@ -28,6 +28,12 @@ The cached assets might expire. If this occurs the publisher will receive a noti {% include alerts/alert_important.html content=importantNote %} +{% capture importantNote %} +Starting with the `1.14.0-beta1` version converting the native ad template to the ad objects is changed to match the IAB specs. See this [issue](https://github.com/prebid/prebid-mobile-ios/issues/494) for the details. If you update SDK from the previous version - verify the native ads integration before the release. +{% endcapture %} + +{% include alerts/alert_important.html content=importantNote %} + ## Ad Ops Setup These instructions will enable you to create a creative template in either Google Ad Manager or MoPub that can then be applied to native ads in your app. @@ -58,7 +64,7 @@ These instructions will enable you to create a creative template in either Googl | isPrebid | 1 | | hb_cache_id_local | %%PATTERN:hb_cache_id_local%% | -9. Now create Prebid line items with price priority and a display ad type that are targeting `hb_pb key-values`. Associate the creative you added in steps 4 thru 8 (making sure to choose your native format as expected creatives on the line item) to the ad unit you created in the second step. +9. Create Prebid line items with price priority and a display ad type that is targeting `hb_pb key-values`. Associate the creative you added in steps 4 thru 8 (making sure to choose your native format as expected creatives on the line item) to the ad unit you created in the second step. ### MoPub @@ -122,6 +128,19 @@ The `NativeAdDelegate` protocol provides three methods to handle the display and An object representing the `NativeAd` to be displayed. +#### Using Asset Ids with In-App Native Ad Units + +Setting this option to `true`, in your instance of Prebid Mobile, enables you to add an id for each asset in the assets array. The default setting is `false` + +**Swift** +``` +Prebid.shared.shouldAssignNativeAssetID = true +``` + +**Objective C** +``` +[Prebid shared].shouldAssignNativeAssetID = YES; +``` ##### Methods *registerViews* diff --git a/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.md index 4b56d569cd..3d69e27686 100644 --- a/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-nativeadunit-ios.md @@ -23,7 +23,7 @@ See [AdUnit](/prebid-mobile/pbm-api/ios/pbm-adunit-ios.html) for additional para **Parameters** -`configId (String)`: Prebid Server configuration ID. +`configId (String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). ## Examples diff --git a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md index 414d830d01..6fbb28f752 100644 --- a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md @@ -151,9 +151,9 @@ Targeting.shared.itunesID Targeting.shared.itunesID = itunesID ``` -### Open Measurment SDK (OMSDK) +### Open Measurement SDK (OMSDK) -OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is elligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. +OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. There three components to signaling support for OMSDK: * Partner Name @@ -219,7 +219,7 @@ parameters.api = [Signals.Api(7)] adUnit.setParameters(parameters); ``` - +Note that the OMID value for imp.banner/video/native.api field should be 7, as defined by the IAB in the [OMSDK v1.2 document](https://s3-us-west-2.amazonaws.com/omsdk-files/docs/Open+Measurement+SDK+Onboarding_version_1.2.pdf). ## Inventory (Context) Keywords @@ -278,7 +278,7 @@ Data is broken up into two different data types: * Global scope * Ad Unit grain - The below first party user and inventory context will apply to all ad units. For ad unit level first party data, refer to [First Partay Data section in the Ad Unit](pbm-adunit-ios#first-party-data) page. + The below first party user and inventory context will apply to all ad units. For ad unit level first party data, refer to [First Party Data section in the Ad Unit](pbm-adunit-ios#first-party-data) page. ### First Party User Data diff --git a/prebid-mobile/pbm-api/ios/pbm-video-instream-ios.md b/prebid-mobile/pbm-api/ios/pbm-video-instream-ios.md index c2591172de..239fb9cbf4 100644 --- a/prebid-mobile/pbm-api/ios/pbm-video-instream-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-video-instream-ios.md @@ -30,7 +30,7 @@ Video instream is only supported with Google Ad Manager. **Parameters** - `configId(String)`: Prebid Server configuration ID. + `configId(String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `size(CGSize)`: Width and height of the video ad unit. diff --git a/prebid-mobile/pbm-api/ios/pbm-video-rewarded-adunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-video-rewarded-adunit-ios.md index d1be426cc1..c7572a5431 100755 --- a/prebid-mobile/pbm-api/ios/pbm-video-rewarded-adunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-video-rewarded-adunit-ios.md @@ -17,11 +17,11 @@ Create a new Video Rewarded Ad Unit associated with a Prebid Server configuratio **Parameters** -`configId(String)`: Prebid Server configuration ID. +`configId(String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). -# Paramaters +# Parameters Parameters is a sub class of RewardedVideoAdUnit.Create new Parameters class to define the parameters of the video ad unit. Parameters contain the OpenRTB video attributes. diff --git a/prebid-mobile/pbm-api/ios/pbm-videointerstitialadunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-videointerstitialadunit-ios.md index 385bac77d3..fd0f201ee9 100755 --- a/prebid-mobile/pbm-api/ios/pbm-videointerstitialadunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-videointerstitialadunit-ios.md @@ -17,10 +17,10 @@ Video Insterstital is only supported with Google Ad Manager. **Parameters** -`configId(String)`: Prebid Server configuration ID. +`configId(String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). -# Paramaters +# Parameters Parameters is a sub class of VideoInterstitialAdUnit.Create new Parameters class to define the parameters of the video ad unit. Parameters contain the OpenRTB video attributes. diff --git a/prebid-mobile/pbm-api/ios/pbm-videooutstreamadunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-videooutstreamadunit-ios.md index f5379e6be3..bd673ce00b 100755 --- a/prebid-mobile/pbm-api/ios/pbm-videooutstreamadunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-videooutstreamadunit-ios.md @@ -30,7 +30,7 @@ See [AdUnit]({{site.baseurl}}/prebid-mobile/pbm-api/ios/pbm-adunit-ios.html) for **Parameters** -`configId(String)`: Prebid Server configuration ID. +`configId(String)`: Prebid Server configuration ID. Note: this is a Prebid Server [impression-level stored request ID](/prebid-server/features/pbs-storedreqs.html). `size(CGSize)`: Width and height of the video ad unit. @@ -61,7 +61,7 @@ OpenRTB Placement Type represented as an enumeration of values: * inFeed is transformed into OpenRTB value 4 to bid adapters -### Paramaters +### Parameters Parameters is a sub class of videoAdUnit. Create new Parameters class to define the parameters of the video ad unit. Parameters contain the OpenRTB video attributes. diff --git a/prebid-mobile/pbm-api/ios/prebidmobile-object-ios.md b/prebid-mobile/pbm-api/ios/prebidmobile-object-ios.md index a00812968f..58d76b786d 100644 --- a/prebid-mobile/pbm-api/ios/prebidmobile-object-ios.md +++ b/prebid-mobile/pbm-api/ios/prebidmobile-object-ios.md @@ -8,6 +8,7 @@ sidebarType: 2 --- # Prebid: NSObject + {: .notoc} The Prebid class is a singleton that enables the user to apply global settings. @@ -17,11 +18,7 @@ The Prebid class is a singleton that enables the user to apply global settings. --- -## Object - -### Prebid - -**Properties** +## Properties `prebidServerAccountId`: String containing the Prebid Server account ID. @@ -72,6 +69,10 @@ var timeoutMillis: Int var storedAuctionResponse: String ``` +## Methods + +### Stored Response + `addStoredBidResponse`: Function containing two properties: * `bidder`: Bidder name as defined by Prebid Server bid adapter of type string. @@ -94,8 +95,19 @@ func clearStoredBidResponses() pbsDebug = BOOL ``` +### Custom headers -## Examples +The following methods enables the customization of the HTTP call to the prebid server: + +``` +func addCustomHeader(name: String, value: String) +``` + +``` +func clearCustomHeaders() +``` + +# Examples *SWIFT* ```swift @@ -166,8 +178,7 @@ Prebid.shared.pbsDebug = true; ``` - -## Related Topics +# Related Topics - [Prebid Mobile API - iOS]({{site.baseurl}}/prebid-mobile/pbm-api/ios/pbm-api-ios.html) - [Banner Ad Unit](/prebid-mobile/pbm-api/ios/pbm-banneradunit-ios.html) diff --git a/prebid-mobile/prebid-mobile-pbs.md b/prebid-mobile/prebid-mobile-pbs.md index 64cf7dd104..c80971c8cf 100644 --- a/prebid-mobile/prebid-mobile-pbs.md +++ b/prebid-mobile/prebid-mobile-pbs.md @@ -31,13 +31,24 @@ Before you begin using Prebid Mobile in your apps, you need to prepare your end- ### Implement Your Own Prebid Server Host -Prebid Server is an open source project. This allows you to host your own implementation of Prebid Server, though it's not as easy as downloading Prebid.js, because it needs to be hosted. The source code is available under the [Prebid organization on GitHub](https://github.com/prebid/prebid-server). There's also a [Java version of Prebid Server](https://github.com/prebid/prebid-server-java). +Prebid Server is an open source project. This allows you to host your own implementation of Prebid Server, though it's not as easy as downloading Prebid.js, because it needs to be hosted. The source code is available for [Prebid-Server GoLang](https://github.com/prebid/prebid-server) and [Prebid Server-Java](https://github.com/prebid/prebid-server-java). -See the [Prebid Server docs on GitHub](https://github.com/prebid/prebid-server/tree/master/docs/developers) for more information on setting up your own server host. +See the [Prebid Server documentation](/prebid-server/overview/prebid-server-overview.html) for more information on [setting up your own server host](/prebid-server/hosting/pbs-hosting.html). + +### A Note on 'Accounts' + +Several pages and examples in the mobile documentation refer to entering +your "Prebid Server Account ID". + +In actuality, an “account ID” is just the name of the “top-level” stored request as described on the [Prebid Server Stored Request page](/prebid-server/features/pbs-storedreqs.html). +By convention, most Prebid Server host companies define the top level stored request ID as the account ID they assign to the publisher. +This is a convenient convention since publishers generally set the same timeout and price granularity across all apps. +But it may not be the case for your Prebid Server host company, so please check with them. +If you’re hosting your own Prebid Server, this value can be whatever value you wish, not necessarily an account ID. ## Configure Prebid Server -After you've registered with your chosen Prebid Server host, you need to create at least one Prebid Server bidder configuration. Each configuration contains a list of bidders and their parameters. The configuration will be in the form of a JSON structure, similar to this: +After you've registered with your chosen Prebid Server host, you need to create at least one Prebid Server bidder configuration in a [stored request](/prebid-server/features/pbs-storedreqs.html). Each stored request configuration contains a list of bidders and their parameters. The configuration will be in the form of a JSON structure, similar to this: ``` [ @@ -50,7 +61,10 @@ After you've registered with your chosen Prebid Server host, you need to create ] ``` -The preceding is an example structure using AppNexus as the bidder. The parameters you need to set differ for each bidder. See [Bidder Parameters]({{site.github.url}}/prebid-server/developers/add-new-bidder-go.html) for a full list of parameters for available Prebid Server bidders. +The preceding is an example "impression-level stored request" using AppNexus as the bidder. The parameters you need to set differ for each bidder. See [Bidder Parameters](/prebid-server/developers/add-new-bidder-go.html) for a full list of parameters for available Prebid Server bidders. + +Each block of JSON like this is called a "stored request" and gets an ID called a "stored request ID". This ID is then programmed into an adslot using the iOS or Android SDKs. Doing it this way allows the publisher to change bidders and parameters without +having to change the app. ## Developers - Using the SDK @@ -66,7 +80,6 @@ After you have the SDK installed, register ad units with the Prebid Mobile frame Ad ops users configure the primary ad server with Prebid Mobile line items targeted to key/values. - [Set Up Line Items for Google Ad Manager]({{site.github.url}}/prebid-mobile/adops-line-item-setup-dfp.html) -- [Set Up Line Items for MoPub]({{site.github.url}}/prebid-mobile/adops-line-item-setup-mopub.html) ## Additional Information diff --git a/prebid-server/developers/add-a-module-java.md b/prebid-server/developers/add-a-module-java.md new file mode 100644 index 0000000000..a021a96ca4 --- /dev/null +++ b/prebid-server/developers/add-a-module-java.md @@ -0,0 +1,229 @@ +--- +layout: page_v2 +sidebarType: 5 +title: Prebid Server | Developers | Adding a Java Module + +--- + +# Prebid Server - Adding a Java Module +{: .no_toc} + +* TOC +{:toc } + +## Overview + +This document details how to make a module for PBS-Java. + +You will want to be familiar with the following background information: + +- the [module overview](/prebid-server/developers/add-a-module.html) +- the [PBS-Java Modularity Tech Spec](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.oklyk2bogkx4) + +### Coding standards + +The module’s code style should correspond to the [PBS-Java project code style](https://github.com/prebid/prebid-server-java/blob/master/docs/code-style.md). + +## Module Directory Layout + +The Prebid Server repository contains a maven submodule called `all-modules` located in the `extra/modules` folder. It includes all available PBS modules. So, in order to add a new module, fork the repository and create a folder with the desired name inside the modules folder with the following structure: + +``` ++- prebid-server-java/ + +- extra/ + +- modules/ + +- YOUR_MODULE_NAME/ + +- pom.xml <- POM of your module + +- pom.xml <- POM of all included modules +``` + +A benefit of open sourcing your module in this way is that it can use the parent `all-modules` as a maven dependency. It simplifies management of the PBS-Core and other commonly used dependencies and you will be confident that it works well with the current version of Prebid Server. + +### Your module's build file + +Here's a partial example of your module-specific `pom.xml` file: + +``` + + + + org.prebid.server.hooks.modules + all-modules + PREBID_SERVER_VERSION + + + YOUR_MODULE_ARTIFACT_ID + + YOUR_MODULE_TEXTUAL_NAME + YOUR_MODULE_DESCRIPTION + +``` + +where: +- PREBID_SERVER_VERSION is the current version of Prebid Server. The release team will update this value for all modules with each release, but you need to set it to the version of PBS that you're developing with. +- YOUR_MODULE_ARTIFACT_ID is the name of your module JAR file without version and extension. e.g. ortb2-blocking +- YOUR_MODULE_TEXTUAL_NAME is unique within the space of all other modules. e.g. instead of naming a module "blocking", a better name would be "ortb2blocking". + +### Add your module to the add-modules build file + +Add your module within `extra/modules/pom.xml` in the "modules" section: + +``` + + ... + YOUR_MODULE_ARTIFACT_ID + +``` + +### Your directory layout + +The structure of your module source code inside the modules directory must have a standard maven-compatible structure: + +``` ++- src/ + +- main/ + +- java/ <- source code + +- org.prebid.server.* <- The package path needs to include "org.prebid.server" + +- resources/ <- required resources + +- test/ + +- java/ <- tests + +- resources/ <- required test resources ++- pom.xml <- POM of your module ++- README.md <- documentation +``` + +## Module Code + +The quick start is to take a look in two places: +- the [ortb2-blocking module](https://github.com/prebid/prebid-server-java/tree/master/extra/modules/ortb2-blocking) +- the [module test cases](https://github.com/prebid/prebid-server-java/tree/master/src/test/java/org/prebid/server/it/hooks) + +### Adding module documentation +It is required to add a "README.md" file to the root of your module folder. Recommended this file contains the description of what the implemented module does, links to external documentation and includes maintainer contact info (email, slack, etc). + +The documentation must also live on the docs.prebid.org site. Please add a markdown file to https://github.com/prebid/prebid.github.io/tree/master/prebid-server/pbs-modules + +### Hook Interfaces + +The Prebid server processing workflow is divided into serveal 'stages' where module authors can code agaist a specific function signature called a 'hook'. + +The Prebid Server host company will define which modules to run in which order by setting up a configuration defining which hooks run, and which can run in parallel. + +The supported stages are described in the [general module overview](/prebid-server/developers/add-a-module.html#2-understand-the-endpoints-and-stages) and in PBS-Core source code at the "org.prebid.server.hooks" package. + +These are the available hooks that can be implemented in a module: + +- org.prebid.server.hooks.v1.entrypoint.EntrypointHook +- org.prebid.server.hooks.v1.auction.RawAuctionRequestHook +- org.prebid.server.hooks.v1.auction.ProcessedAuctionRequestHook +- org.prebid.server.hooks.v1.bidder.BidderRequestHook +- org.prebid.server.hooks.v1.bidder.RawBidderResponseHook +- org.prebid.server.hooks.v1.bidder.ProcessedBidderResponseHook +- org.prebid.server.hooks.v1.auction.AuctionResponseHook + +In a module it is not necessary to implement all mentioned interfaces but only one (or several) required by your functionality. + +Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic interface with methods should be implemented: +- `code()` - returns module code. +- `call(...)` - returns result of hook invocation. + +### Examples + +1) To **update** the request in the `RawAuctionRequestHook` you would return: +``` +Future.succeededFuture( + InvocationResultImpl.builder() + .status(InvocationStatus.success) + .action(InvocationAction.update) + .payloadUpdate(payload -> + AuctionRequestPayloadImpl.of(payload.bidRequest().toBuilder() + .id("updated request ID") + .build())) + .build() +); +``` + +Please note that the `InvocationStatus` is only considered when the status is set to `InvocationStatus.success`. That means the `payloadUpdate` is only applied with `InvocationStatus.success` **and** `InvocationAction.update` + +2) To **reject** the request in the `RawAuctionRequestHook` you would return: +``` +Future.succeededFuture( + InvocationResultImpl.rejected(“The rejection reason”) +); +``` + +3) To supply [analytics tags](/prebid-server/developers/module-atags.html) in the `RawAuctionRequestHook` you would return: +``` +Future.succeededFuture( + InvocationResultImpl.builder() + ... + .analyticsTags(TagsImpl.of( + Collections.singletonList(ActivityImpl.of( + "device-id", + "success", + Collections.singletonList(ResultImpl.of( + "success", + mapper.mapper().createObjectNode() + .put("some-field", "some-value"), + AppliedToImpl.builder() + .impIds(Collections.singletonList("impId1")) + .request(true) + .build())))))) + ... + .build() +); +``` + +More test implementations for each hook can be found in unit-tests at https://github.com/prebid/prebid-server-java/tree/master/src/test/java/org/prebid/server/it/hooks folder. + +### Applying results asynchronously + +Please note method call() returns a Future object. This means it won’t apply changes immediately but rather when PBS-Core executes it in org.prebid.server.hooks.execution.GroupExecutor#executeHook method. + +### Do not block the main thread + +Prebid Server Java uses Vert.x in its core, so developers need to keep an eye on blocking the main thread. See the [Vert.x documentation](https://vertx.io/docs/vertx-core/java/#_dont_block_me). + +Thus, for any kind of blocking operations it is recommended to use a Vert.x built-in (for example, io.vertx.core.http.HttpClient) or even better - PBS wrapper components (for example, org.prebid.server.vertx.http.HttpClient). + +To see how to proceed with async operations, please see similar PBS-Core functionality, for example Currency Conversion Service implementation (class “org.prebid.server.currency.CurrencyConversionService”). + +### Configuration + +It's possible to define default module configuration which can be read by the module at PBS startup. Please see the [Configuration](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.mh3urph3k1mk) section of the technical specification. + +### Testing + +Unit tests are required. Each implemented hook must be at least 90% covered by unit tests. + +### How to build and install a module + +Read about the bunding of modules with PBS in the [bundling section](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.o8dv0neoq4xm) of the technical specification. + +## Analytics Adapters and Modules + +Each module can inject analytics tags into the request as described in the analytics tags section. + +Analytics adapters can receive these tags in a parameter that's been added to the Auction/AMP endpoints. The org.prebid.server.analytics.model.AuctionEvent event object which includes AuctionContext with HookExecutionContext inside. + +To get analytics tag you need to go into: + +``` +AuctionEvent + -> AuctionContext + -> HookExecutionContext + -> stageOutcomes (select stage) + -> groups (iterate through groups) + -> hooks (go through hooks and find interested one) + -> analyticsTags +``` + +The AnalyticsTags object has activities with collection of org.prebid.server.hooks.v1.analytics.Result objects inside. Each Result has the values() method which returns com.fasterxml.jackson.databind.node.ObjectNode. + +It depends on the particular module implementation how to parse their analytics tags, since the internal structure is custom and depends on the module. Therefore, analytics modules that want to report on specific behavior need to be coded to know about that module. See the ortb2blocking module for an example of what analytics tags may be available. + + +## Further Reading + +- [PBS Module Overview](/prebid-server/developers/add-a-module.html) +- [PBS Module Analytics Tags Conventions](/prebid-server/developers/module-atags.html) diff --git a/prebid-server/developers/add-a-module.md b/prebid-server/developers/add-a-module.md new file mode 100644 index 0000000000..502adf870e --- /dev/null +++ b/prebid-server/developers/add-a-module.md @@ -0,0 +1,190 @@ +--- +layout: page_v2 +sidebarType: 5 +title: Prebid Server | Developers | Adding a Module + +--- + +# Prebid Server - Adding a Module +{: .no_toc} + +This document guides you through the process of developing a module for host companies to plug into their instance of Prebid Server. +We encourage you to look at existing modules for working examples. You can also ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). + +{: .alert.alert-info :} +Modules are currently only supported in [PBS-Java](https://github.com/prebid/prebid-server-java). + + +* TOC +{:toc } + +## Overview + +The ability to add optional modules in [Prebid.js](/prebid/prebidjs.html) has been widely used, +with dozens of interesting features forming a healthy ecosystem of vendor choice that's good for publishers and the industry. + +Prebid Server (Java) supports a rich module interface that +allows anyone to contribute functionality at predefined places +along the request pipeline. Here's the general development process: + +1. The module writer designs the feature, then optionally posts it as an [issue](https://github.com/prebid/prebid-server/issues) for community feedback. +1. They then code the module and unit tests and write user documentation. +1. Code, tests, and documentation are submitted to the Prebid Server team for review. +1. Once accepted, Prebid Server Host companies may choose to activate the new module for their publishers. +1. Publishers can utilize the feature, doing any required account setup described in the module documentation. + +The first module written was the ORTB2 Blocking module. Example ideas for future modules include creative validation and traffic quality. +If you have an idea for a module that's not feasible (e.g. a new endpoint), open [an issue](https://github.com/prebid/prebid-server/issues) with a detailed description of what you're looking to do. + +### Terminology + +- **PBS**: short for **P**re**b**id **S**erver +- **PBS-core**: The inner workings of Prebid Server -- not part of a module, bid adpater, or analytics adapter +- **PBS-Java**: the Java version of Prebid Server +- **PBS-Go**: the Go-Lang version of Prebid Server +- **Host Company**: the entity running the PBS cluster, e.g. one of the ones on [this list](https://prebid.org/product-suite/managed-services/). +- **Module**: a coherent feature set that plugs into Prebid Server with its own configuration. +- **Stage**: a place in the Prebid Server process flow from which a module can be invoked. +- **Hook**: a function in the module code that executes at a given stage with a particular function signature. +- **Endpoint**: an externally-visible service that responds to web requests. e.g. /openrtb2/auction, /cookie-sync. +- **Analytics Tags**: a mechanism for a module to inform other modules of what it has encountered or changed. + +## Planning Your Module + +### 1. Review the Module Rules + +There are a number of things modules are not allowed to do +without disclosing prominently on their documentation. Please review +the [Module Rules](/dev-docs/module-rules.html) page. Here are some highlights: + +- a module can't add pixels to the creative without disclosure +- every module must obey privacy regulations: GDPR, CCPA, COPPA +- modules cannot create new bids. That is reserved for bid adapters. +- modules must be configurable to make data available to all bidders. i.e. you can't make a module that works always and forever with just one bidder without prominent disclosure. + +### 2. Understand the Endpoints and Stages + +Here's a description of the Stages of a PBS request that modules can tap into for each supported endpoint: + +{: .table .table-bordered .table-striped } +| Stage | Description | Endpoints | Example Use Cases | +|-------------+-------------+-------+-----| +| Entrypoint | Hook functions can see the raw request before PBS has processed or validated anything | auction, amp, video | A/B testing of account parameters, Alternate account validation, AMP pre-processing | +| Raw Auction Request | Validations have been done, but no enrichments | auction, amp, video | A/B testing of StoredRequests, Advanced device detection, Traffic Quality | +| Processed Auction Request | Any stored requests have been merged in and all PBS enrichments are done | auction, amp, video | Inject First Party Data, Channel determination, Bid floors, Bidder optimization | +| Bidder Request | The request has been customized for a particular bidder in the auction | auction, amp, video | Bidder-specific bcat/badv, Bidder-specific deals | +| Raw Bidder Response | Hook functions can get access to the unprocessed bidder response | auction, amp, video | Response validations | +| Processed Bidder Response | PBS has done its own validations on an individual bidder's response | auction, amp, video | Advanced CPM adjustments, Custom VAST macros | +| Auction Response | Last step before the response goes back to the client | auction, amp, video | Inject ad server targeting, alternate auction winner logic | + +### 3. Figure out which Stages You're going to Hook Into + +A module may be comprised of: + +- init and hook functions that are called by Prebid Server +- internal functions and state +- optional external connections to data sources or other services + +Some modules may plug into only one endpoint and one stage of processing. Others may coordinate activity across multiple stages. For example, +this diagram illustrates the design of a module that's configured to plug into two stages of +the processing workflow: + +![Prebid Server Modularity Architecture](/assets/images/prebid-server/module-example.png){:class="pb-xlg-img"} + +### 4. Module Hook Actions: Read, Change and/or Reject + +There are a few basic ways a module's hook function can respond to PBS-core: + +- inspect the request/response +- change the request by adding a new field to the request/response or updating an existing field +- instruct PBS-core to reject the request or response entirely + +The amount of time your module takes to perform its actions will be limited +by PBS-core. For example, if a creative validation module needs to 'phone home' +to analyze the bid creative, it will have a tight window of a few milliseconds +to get the response and apply it. Your documentation can request how long +the module needs, but keep in mind that PBS host companies may not use your +module if it leads to an increased rate in header bidding timeouts. + +### 5. Determine what Should be Configurable + +There are two sources of configuration for each module: + +#### 5.1. Initialization Config + +When Prebid Server starts up, it can be configured to initialize +modules supported by the Host Company. This start up config should contain +values that are constant across requests. e.g.: + +- URLs for external services +- host-company specific settings like cache sizes, installation ID, global timeout, other defaults + +Values in this config can only change with a bounce of Prebid Server. + +#### 5.2. Runtime Config + +For each user request, modules can have account-specific +configuration stored in the account-config data source. This configuration +is used to store parameters that could vary for different publishers +utilizing this PBS instance. e.g.: + +- publisher account ID +- application config (e.g. 'blocked advertisers') +- publisher timeout override + +### 6. Consider Storage Needs + +If your module will require state of some sort beyond configurtaion, you'll have to provide instructions +to the PBS host company. Examples: + +- a module could require a No-SQL endpoint that's populated at init and refreshed periodically +- modules may require a local SQL DB populated with application data +- some modules may require access to local disk to read a security certificate + +### 7. Think about Analytics Tags + +Analytics Tags (aka 'ATags') are a log mechanism provided by PBS-core to inform downstream +modules about what's happened in the request so far. Use of the Analytics Tag structure +is completely optional, but there may be application or reporting reasons for sharing +the results. Examples: + +- The [ORTB2 Blocking module](/prebid-server/pbs-modules/ortb2-blocking.html) creates ATags informing analytics adapters that +a bid response was inspected and/or blocked for violating a publisher-defined +rule like advertiser domains. This data can be used to alert the analytics users +that a given bidder is losing bid opportunities by not adhering to the auction parameters. +- A bid optimization module could inform analytics how many times it dropped a bidder from an auction for various reasons. e.g. "dropped this bidder X% of the time due to geographic reasons, Y% of the time due to session length. + +See the [Module Analytics Tag Conventions](/prebid-server/developers/module-atags.html) for more specific details +about how to format ATags. + +### 8. Write the Code, Config, and Unit Tests + +The details of the implementation depend on the platform. + +- PBS-Java: see [Adding a PBS-Java module](/prebid-server/developers/add-a-module-java.html) +- PBS-Go: TBD + +Other rules for open source PBS pull request: + +- Unit test coverage must exceed 90%. +- A maintainer email address must be provided and be a group, not an individual. e.g. "support@example.com rather than jsmith@example.com + +### 9. Write the Module Documentation + +Fork the [documentation repo](https://github.com/prebid/prebid.github.io) and +create a file in /prebid-server/pbs-modules. You can start by copying one of the existing files. It should contain: + +- A description of the module functionality: why people might be interested in using it. +- Prerequisites: any necessary account activation, other required modules, etc. +- Configuration: both init and runtime +- Analytics Tag support +- Privacy Support: disclose whether the module has user privacy implications and support for GDPR, CCPA, etc. + +### 10. Submit the Pull Requests + +When everthing checks out on your dev environment, submit the PRs for review. + +## Further Reading + +- [Prebid Server Module List](/prebid-server/pbs-modules/index.html) +- [PBS Module Analytics Tags Conventions](/prebid-server/developers/module-atags.html) diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md index 7cfc39e2f7..0f21de1090 100644 --- a/prebid-server/developers/add-new-bidder-go.md +++ b/prebid-server/developers/add-new-bidder-go.md @@ -13,7 +13,7 @@ Thank you for contributing a bid adapter to the open source Prebid Server projec This document guides you through the process of developing a new bid adapter for your bidding server. We encourage you to look at [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance. You can also ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). {: .alert.alert-info :} -**NOTE:** There are two implementations of Prebid Server, [PBS-Go](https://github.com/prebid/prebid-server) and [PBS-Java](https://github.com/prebid/prebid-server-java). We recommend you build new adapters for PBS-Go and allow us to port it to PBS-Java within a couple of months. If you'd like to build both yourself, please also follow these [instructions for building an adapter in PBS-Java](/prebid-server/developers/add-new-bidder-java.html). +There are two implementations of Prebid Server, [PBS-Go](https://github.com/prebid/prebid-server) and [PBS-Java](https://github.com/prebid/prebid-server-java). We recommend you build new adapters for PBS-Go and allow us to port it to PBS-Java within a couple of months. If you'd like to build both yourself, please also follow these [instructions for building an adapter in PBS-Java](/prebid-server/developers/add-new-bidder-java.html). * TOC @@ -29,15 +29,15 @@ An OpenRTB 2.5 Bid Request contains one or more Impressions, each representing a ### Choose A Name -You will need to choose a unique name for your bid adapter. Names should be written in lower case and may not contain special characters or emoji. If you already have a Prebid.js bid adapter, we encourage you to use the same name with the same bidder parameters. You may not name your adapter `all`, `context`, `data`, `general`, `prebid`, or `skadn` as those have special meaning in various contexts. Existing bid adapter names are [maintained here](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders.go#L37). +You will need to choose a unique name for your bid adapter. Names should be written in lower case and may not contain special characters or emoji. If you already have a Prebid.js bid adapter, we encourage you to use the same name with the same bidder parameters. You may not name your adapter `all`, `context`, `data`, `general`, `prebid`, `skadn` or `tid` as those have special meaning in various contexts. Existing bid adapter names are [maintained here](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders.go#L37). -We ask that the first 6 letters of the name you choose be unique among the existing bid adapters. This consideration helps with generating targeting keys for use by some ad exchanges, such as Google Ad Manager. There's no need to manually check, as this constraint is enforced by the [`TestBidderUniquenessGatekeeping`](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders_test.go#L61) test. +We ask that the first 6 letters of the name you choose be unique among the existing bid adapters. This consideration helps with generating targeting keys for use by some ad exchanges, such as Google Ad Manager. There's no need to manually check, as this constraint is enforced by the [`TestBidderUniquenessGatekeeping`](https://github.com/prebid/prebid-server/blob/master/openrtb_ext/bidders_validate_test.go#L45) test. Throughout the rest of this document, substitute `{bidder}` with the name you've chosen. ### Respect The Rules -We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://docs.prebid.org/wrapper_code_of_conduct.html) and [module rules](https://docs.prebid.org/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions. +We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://prebid.org/code-of-conduct/) and [module rules](/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions. **Please take the time to read our rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter: - Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another. @@ -48,9 +48,9 @@ We are proud to run the Prebid Server project as a transparent and trustworthy h - Adapters must annotate the bid response with the proper media type, ideally based on the response from the bidding server. {: .alert.alert-warning :} -Failure to follow the rules will lead to delays in approving your adapter for inclusion in Prebid Server. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). +Failure to follow the rules will lead to delays in approving your adapter. If you'd like to discuss an exception to a rule, please make your request by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). -### Ongoing Support and Maintenance +### Support and Maintenance You are expected to provide support and maintenance for the code you contribute to Prebid Server as part of your bid adapter. We ask that you proactively update your adapter when your bidding server introduces new features or breaking changes. @@ -60,18 +60,18 @@ Please be attentive in reading and responding to emails and [GitHub issues](http ## Create Your Adapter -Prebid Server bid adapters consist of several components: bidder info, bidder parameters, adapter code, user sync code, registration with the core framework, and default configuration values. This chapter will guide you though each component. +Prebid Server bid adapters consist of several components: bidder info, bidder parameters, adapter code, registration with the core framework, and default configuration values. This document will guide you though each component. -Please refer to [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance, but understand that our adapter interfaces and coding style evolve over time. Please prefer the examples in this document over differences you may find in code. +Please refer to [existing bid adapters](https://github.com/prebid/prebid-server/tree/master/adapters) for working examples and practical guidance, but understand that our adapter interfaces and coding style evolve over time. The examples in this document have precedence over differences you may find in an existing bid adapter. Our project is written in the [Go programming language](https://golang.org/). We understand not everyone has prior experience writing Go code. Please try your best and we'll respectfully steer you in the right direction during the review process. {: .alert.alert-info :} -Please do not ignore errors from method calls made in your bid adapter code. Even if it's seemingly impossible for an error to occur, such as from `json.Marshal`, it's still possible under the high throughput multi-threaded nature of Prebid Server. +**Please do not ignore errors from method calls made in your bid adapter code.** Even if it's seemingly impossible for an error to occur, such as from `json.Marshal`, it's still possible under the high throughput multi-threaded nature of Prebid Server. ### Bidder Info -Let's begin with your adapter's bidder information YAML file. This file is required and contains your maintainer email address, your [GDPR Global Vendor List (GVL) id](https://iabeurope.eu/vendor-list-tcf-v2-0/), specifies the ad formats your adapter will accept, and allows you to opt-out of video impression tracking. +Let's begin with your adapter's bidder information YAML file. This file is required and contains your bid adapter's maintainer email address, [GDPR Global Vendor List (GVL) ID](https://iabeurope.eu/vendor-list-tcf-v2-0/), supported ad formats, user sync endpoints, and allows you to opt-out of video impression tracking. Create a file with the path `static/bidder-info/{bidder}.yaml` and begin with the following template: @@ -93,6 +93,10 @@ capabilities: - video - audio - native +userSync: + redirect: + url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID ``` Modify this template for your bid adapter: @@ -100,6 +104,7 @@ Modify this template for your bid adapter: - Change the `gvlVendorID` from the sample value of `42` to the id of your bidding server as registered with the [GDPR Global Vendor List (GVL)](https://iabeurope.eu/vendor-list-tcf-v2-0/), or remove this line entirely if your bidding server is not registered with IAB Europe. - Change the `modifyingVastXmlAllowed` value to `false` if you'd like to opt-out of [video impression tracking](https://github.com/prebid/prebid-server/issues/1015), or remove this line entirely if your adapter doesn't support VAST video ads. - Remove the `capabilities` (app/site) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support. +- Follow the [User Sync Configuration](#user-sync-configuration) documentation below to configure the endpoints for your bid adapter, or remove the `userSync` section if not supported.
    Example: Website with banner ads only. @@ -112,6 +117,10 @@ capabilities: site: mediaTypes: - banner +userSync: + redirect: + url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID ```
    @@ -125,6 +134,10 @@ capabilities: site: mediaTypes: - banner +userSync: + redirect: + url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID ``` @@ -145,22 +158,71 @@ capabilities: mediaTypes: - banner - video +userSync: + redirect: + url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID ```

    +#### User Sync Configuration + +Prebid Server offers a federated [user sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) process to store user ids from multiple bidders in a single cookie under the host's domain. You may add support for your bid adapter by configuring iframe and/or redirect endpoints. + +The Bidder Info template above demonstrates configuration of a `redirect` user sync. The `url` points to an endpoint on your bidding server which will honor the privacy policies, replace the `userMacro` in the redirect url with the user's tracking id, and respond with an HTTP 302 redirect to that url. You may also specify an `iframe` endpoint which will return an HTML document to be rendered in an `iframe` on the user's device and use JavaScript to perform the redirect. You may omit the `{%raw%}{{.GDPR}}{%endraw%}`, `{%raw%}{{.GDPRConsent}}{%endraw%}`, and/or `{%raw%}{{.USPrivacy}}{%endraw%}` macros if they are not applicable to your legal situation. + +If both `iframe` and `redirect` endpoints are provided, the `iframe` endpoint will be used by default. + +```yaml +userSync: + iframe: + url: https://foo.com/iframe/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID + redirect: + url: https://foo.com/redirect/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID +``` + +If your bid adapter supports user sync and doesn't have a good default endpoint, you may optionally specify a `supports` array with the items `iframe` and/or `redirect` to inform Prebid Server hosts. Hosts will receive a warning on startup if a bid adapter supports user sync and isn't configured. Expect hosts to contact you at the maintainer email address for instructions. + +```yaml +userSync: + # foo supports user syncing, but requires configuration by the host. contact this + # bidder directly at the email address in this file to ask about enabling user sync. + supports: + - iframe + - redirect +``` + +Each user sync is assigned a case-sensitive `key`, defaulting to your bidder name. You may use a different `key` value, but we discourage doing so except for when multiple bidders share the same bidding server. You might encounter this use case for built-in aliases or for multiple bidders implementing different protocols for the same bidding server. Only one bid adapter may specify endpoints when using a shared key, or Prebid Server will fail to startup due to the ambiguity. + +```yaml +foo.yaml +-------- +userSync: + redirect: + url: https://foo.com/sync?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: $UID + +bar.yaml +-------- +userSync: + key: foo +``` + ### Bidder Parameters -Your bid adapter might require extra information from the publisher to form a request to your bidding server. The bidder parameters JSON Schema codifies this information to allow Prebid Server to verify requests and to provide an API for third party configuration systems. +Your bid adapter might require extra information from the publisher to form a request to your bidding server. The bidder parameters JSON Schema codifies this information to allow Prebid Server to verify requests and to provide an API for configuration systems. Publishers will provide extra information using an OpenRTB 2.5 Bid Request Extension, preferably at `request.imp[].ext.prebid.bidder.{bidder}` but also supported at `request.imp[].ext.{bidder}`. Prebid Server will validate the publisher information based on your schema and relocate the data to `request.imp[].ext.bidder`, regardless of your bidder name or the publisher's chosen location. -We request that you do not duplicate information that is already present in the [OpenRTB 2.5 Bid Request specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=13) or is already part of an established Prebid convention. For example, your bidder parameters should not include first party data, bid floors, schain, video parameters, referrer information, or privacy consent including COPPA, CCPA, and GDPR TCF. For video parameters in particular, you must prefer the OpenRTB 2.5 Bid Request standard of `request.imp[].video`. +We request you do not duplicate information already present in the [OpenRTB 2.5 Bid Request specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=13) or already part of an established Prebid convention. For example, your bidder parameters should not include first party data, bid floors, schain, video parameters, referrer information, or privacy consent including COPPA, CCPA, and GDPR TCF. For video parameters in particular, you must prefer the OpenRTB 2.5 Bid Request standard of `request.imp[].video`. {: .alert.alert-warning :} -**ENDPOINT NOTE:** You may not use an endpoint domain as a bidder parameter. Prebid Server is not an open proxy. If absolutely necessary, you may specify a portion of the domain as a parameter to support geo regions or account specific servers. However, this is discouraged and may degrade the performance of your adapter since the server needs to maintain more outgoing connections. Host companies may choose to disable your adapter if it uses a dynamically configured domain. +You may not use an endpoint domain as a bidder parameter. Prebid Server is not an open proxy. If absolutely necessary, you may specify a portion of the domain as a parameter to support geo regions or account specific servers. However, this is discouraged and may degrade the performance of your adapter since the server needs to maintain more outgoing connections. Host companies may choose to disable your adapter if it uses a dynamically configured domain. -Create a file with the path `static/bidder-params/{bidder}.json` using [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to define your bidder parameters. Prebid Server requires this file for every adapter, even if yours doesn't require bidder parameters (see the 'no parameters' example at the end of this section). +Create a file with the path `static/bidder-params/{bidder}.json` and use [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to define your bidder parameters. Prebid Server requires this file for every adapter, even if yours doesn't require bidder parameters (see the 'no parameters' example at the end of this section). Let's start with this example which defines one required `placementId` string parameter: @@ -183,7 +245,9 @@ Let's start with this example which defines one required `placementId` string pa ``` We encourage you to utilize the full features of [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) to narrowly define your bidder parameter data types. If you copy and paste these examples, please remember to change the `title` and `description` to refer to your bidder name instead of our fictional Foo example. -When choosing your parameter names, please consider aligning with the OpenRTB 2.5 standard by using lower case letters without camel casing or special characters. +When choosing your parameter names, please consider aligning with the OpenRTB 2.5 standard by using lower case letters without camel casing or special characters. + +Properties in [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) are case sensitive. If you choose to specify multiple properties differing only by case for compatibility, we ask that you include the word 'preferred' in one of the descriptions to give a hint to third party configuration systems. In addition to the examples listed below, please refer to [existing bidder parameter files](https://github.com/prebid/prebid-server/tree/master/static/bidder-params) for guidance. @@ -234,7 +298,7 @@ In addition to the examples listed below, please refer to [existing bidder param "title": "Foo Adapter Params", "description": "A schema which validates params accepted by the Foo adapter", "type": "object", - + "properties": { "token": { "type": "string", @@ -280,18 +344,47 @@ In addition to the examples listed below, please refer to [existing bidder param } ``` + +
    + Example: Multiple properties differing only by case. + +```json +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "title": "Foo Adapter Params", + "description": "A schema which validates params accepted by the Foo adapter", + "type": "object", + + "properties": { + "partnerid": { + "type": "string", + "description": "Partner ID, preferred." + }, + "partnerID": { + "secret": "string", + "description": "Partner ID" + } + }, + + "oneOf": [ + { "required": ["partnerid"] }, + { "required": ["partnerID"] } + ] +} +``` +

    ### Bidder Parameters Code {: .alert.alert-info :} -You can skip this step if your adapter has no bidder parameters. +You can skip this section if your adapter has no bidder parameters. -If you've defined bidder parameters for your adapter, you also need to represent your bidder parameters in code. The core framework uses the JSON Schema file for validation, but your adapter code needs a data structure to support JSON unmarshalling / deserialization. These data structures are organized in a shared path using a standard naming convention, which also serves as documentation of all adapter parameters. +If you defined bidder parameters for your adapter, you also need to represent your bidder parameters in code. The core framework uses the JSON Schema file for validation, but your adapter code needs a data structure to support JSON unmarshalling / deserialization. These data structures are organized in a shared path using a standard naming convention, which also serves as documentation of all adapter parameters. Create a file with the path `openrtb_ext/imp_{bidder}.go` containing an exported (must start with an upper case letter) data structure named `ImpExt{Bidder}`. All required and optional bidder parameters from the JSON Schema should be represented as fields. -For example, this is what the bidder parameter code looks like for the example we used in the previous section: +For example, this is what the bidder parameter code looks like for the Foo example we used in the previous section: ```go package openrtb_ext @@ -301,7 +394,7 @@ type ImpExtFoo struct { } ``` -Please follow [Go's standard naming convention](https://golang.org/doc/effective_go.html) for the field names (particularly for acronyms) and use `` `json:...` `` attributes to specify the JSON name, matching exactly what you defined in the bidder parameters JSON Schema. Please keep in mind that JSON is case sensitive. +Please follow [Go's standard naming convention](https://golang.org/doc/effective_go.html) for the field names (particularly for acronyms) and use `` `json:...` `` attributes to specify the JSON name, matching exactly what you defined in the bidder parameters JSON Schema. ### Adapter Code @@ -326,7 +419,7 @@ import ( "fmt" "net/http" - "github.com/mxmCherry/openrtb" + "github.com/mxmCherry/openrtb/v15/openrtb2" "github.com/prebid/prebid-server/adapters" "github.com/prebid/prebid-server/config" "github.com/prebid/prebid-server/errortypes" @@ -345,7 +438,7 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters return bidder, nil } -func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapters.ExtraRequestInfo) ([]*adapters.RequestData, []error) { +func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) ([]*adapters.RequestData, []error) { requestJSON, err := json.Marshal(request) if err != nil { return nil, []error{err} @@ -356,15 +449,15 @@ func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapter Uri: a.endpoint, Body: requestJSON, } - + return []*adapters.RequestData{requestData}, nil } -func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) { +func (a *adapter) MakeBids(request *openrtb2.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) { if responseData.StatusCode == http.StatusNoContent { return nil, nil } - + if responseData.StatusCode == http.StatusBadRequest { err := &errortypes.BadInput{ Message: "Unexpected status code: 400. Bad request from publisher. Run with request.debug = 1 for more info.", @@ -379,18 +472,17 @@ func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.Re return nil, []error{err} } - var response openrtb.BidResponse + var response openrtb2.BidResponse if err := json.Unmarshal(responseData.Body, &response); err != nil { return nil, []error{err} } - + bidResponse := adapters.NewBidderResponseWithBidsCapacity(len(request.Imp)) bidResponse.Currency = response.Cur for _, seatBid := range response.SeatBid { - for _, bid := range seatBid.Bid { - bid := bid // pin https://github.com/kyoh86/scopelint#whats-this + for i, bid := range seatBid.Bid { b := &adapters.TypedBid{ - Bid: &bid, + Bid: &seatBid.Bid[i], BidType: getMediaTypeForBid(bid), } bidResponse.Bids = append(bidResponse.Bids, b) @@ -408,17 +500,17 @@ This method may be called multiple times if the host has configured aliases of y The first argument, `bidderName`, is the name of the bidder being built. This may be the bidder name you've chosen or it may be an alias. Most adapters don't make use of the `bidderName`, but its provided by the core framework for situations where the adapter might need to do something special for aliases. The second argument, `config`, is all the configuration values set for your adapter. However, not all of this information is intended for use by the `Builder` method. The only two fields relevant here are `config.Endpoint` and `config.ExtraAdapterInfo`: -- `config.Endpoint` is the base url of your bidding server and may be interpreted as either a literal address or as a templated macro to support dynamic domains or dynamic paths. -- `config.ExtraAdapterInfo` may be used for any other values your adapter may need, such as an application token or publisher allow/deny list. You may interpret this string however you like, although JSON is a common choice. +- `config.Endpoint` is the base url of your bidding server and may be interpreted as either a literal address or as a templated macro to support dynamic paths. +- `config.ExtraAdapterInfo` is an optional setting may be used for any other values your adapter may need, such as an application token or publisher allow/deny list. You may interpret this string however you like, although JSON is a common choice. -The `Builder` method is expected to return an error if either the `config.Endpoint` or the `config.ExtraAdapterInfo` values are invalid or cannot be parsed. Errors will be surfaced to the host during application startup as a fatal error. +The `Builder` method is expected to return an error if either the `config.Endpoint` or the `config.ExtraAdapterInfo` values are invalid or cannot be parsed. Errors will be surfaced to the host during application startup as a fatal error.
    Example: Builder using endpoint macros. ```go type adapter struct { - endpointTemplate template.Template + endpointTemplate *template.Template } // Builder builds a new instance of the Foo adapter for the given bidder with the given config. @@ -427,9 +519,9 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters if err != nil { return nil, fmt.Errorf("unable to parse endpoint url template: %v", err) } - + bidder := &adapter{ - endpointTemplate: *template, + endpointTemplate: template, } return bidder, nil } @@ -450,7 +542,7 @@ func Builder(bidderName openrtb_ext.BidderName, config config.Adapter) (adapters if err != nil { return nil, err } - + bidder := &adapter{ endpoint: config.Endpoint, token: info.token, @@ -484,9 +576,9 @@ func buildDefaultExtraInfo() extraInfo { The `MakeRequests` method is responsible for returning none, one, or many HTTP requests to be sent to your bidding server. Bid adapters are forbidden from directly initiating any form of network communication and must entirely rely upon the core framework. This allows the core framework to optimize outgoing connections using a managed pool and record networking metrics. The return type `adapters.RequestData` allows your adapter to specify the HTTP method, url, body, and headers. -This method is called once by the core framework for bid requests which have at least one valid Impression for your adapter. Impressions not configured for your adapter will be removed and are not accessible. +This method is called once by the core framework for bid requests which have at least one valid Impression for your adapter. Impressions not configured for your adapter are not accessible. -The first argument, `request`, is the OpenRTB 2.5 Bid Request object. Extension information is stored as `json.RawMessage` byte arrays and must be unmarshalled and/or marshalled to be read and/or mutated. It is *critical* to understand that the `request` object contains pointers to shared memory. If your adapter needs to alter any data referenced by a pointer then you *must* first make a shallow copy. The only exception is for `request.Imp` and its elements, as these are already shallow copies. The exact same instance of the `request` object is also passed to the `MakeBids` method, so please be careful when mutating. It's safe to assume that `request.Imp[]` always contains at least one element and that the `request.Imp[].ext.bidder` was successfully validated by your bidder parameter JSON Schema. +The first argument, `request`, is the OpenRTB 2.5 Bid Request object. Extension information is stored as `json.RawMessage` byte arrays and must be unmarshalled and/or marshalled to be read and/or mutated. It is *critical* to understand that the `request` object contains pointers to shared memory. If your adapter needs to alter any data referenced by a pointer then you *must* first make a shallow copy. The only exception is for `request.Imp` and its elements, as these are already shallow copies. The exact same instance of the `request` object is also passed to the `MakeBids` method, so please be careful when mutating. It's safe to assume that `request.Imp[]` always contains at least one element and that the `request.Imp[].ext.bidder` was successfully validated per your bidder parameter JSON Schema.
    Example: Mutating banner shared memory (make a copy). @@ -504,33 +596,37 @@ if request.Imp[i].W == nil && request.Imp[i].H == nil && len(request.Imp[i].Form

    -The second argument, `requestInfo`, is for extra information and helper methods provided by the core framework. For now, this just includes `requestInfo.PbsEntryPoint` which is commonly used to determine if the request is for AMP or Long Form Video Ad Pods. This object will be expanded in the future to also include currency conversion and extension unmarshalling helper methods. +The second argument, `requestInfo`, is for extra information and helper methods provided by the core framework. This includes: + +- `requestInfo.PbsEntryPoint` to access the entry point of the bid request, commonly used to determine if the request is for AMP or for a [Long Form Video Ad Pod](/dev-docs/modules/adpod.html). +- `requestInfo.GlobalPrivacyControlHeader` to read the value of the `Sec-GPC` Global Privacy Control (GPC) header of the bid request. +- `requestInfo.ConvertCurrency` a method to perform currency conversions. -The `MakeRequests` method is expected to return a slice (similar to a C# `List` or a Java `ArrayList`) of `adapters.RequestData` objects representing the HTTP calls to be sent to your bidding server and a slice of type `error` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please return `nil` for both return values. Neither slices may contain `nil` elements. + +The `MakeRequests` method is expected to return a slice (similar to a C# `List` or a Java `ArrayList`) of `adapters.RequestData` objects representing the HTTP calls to be sent to your bidding server and a slice of type `error` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please return `nil` for both return values. Please do not add `nil` items in the slices. {: .alert.alert-info :} HTTP calls to your bidding server will automatically prefer GZIP compression. You should not specify it yourself using headers. You don't have to worry about decompressing the response in `MakeBids` either, as that will be taken care of automatically. -An Impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the Impression into multiple calls and merge the responses. +##### Impression Splitting -
    - Example: Impression splitting. +An Impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the Impression into multiple calls and merge the responses. ```go -func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) { +func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) { var requests []*adapters.RequestData var errors []error - + requestCopy := *request for _, imp := range request.Imp { - requestCopy.Imp = []openrtb.Imp{imp} + requestCopy.Imp = []openrtb2.Imp{imp} requestJSON, err := json.Marshal(request) if err != nil { errors = append(errors, err) continue } - + requestData := &adapters.RequestData{ Method: "POST", Uri: a.endpoint, @@ -541,12 +637,58 @@ func (a *adapter) MakeRequests(request *openrtb.BidRequest, requestInfo *adapter return requests, errors } ``` + +##### Currency + +Prebid Server is a global product that is currency agnostic. Publishers may ask for bids in any currency. It's totally fine if your bidding endpoint only supports a single currency, but your adapter needs to deal with it. This section will describe how to do so. + +Here are 3 key points to consider: + +1. If your endpoint only bids in a particular currency, then your adapter must not blindly forward the openrtb to your endpoint. You should instead set $.cur to your server's required currency. +2. Your adapter must label bid responses properly with the response currency. i.e. if you only bid in USD, then your adapter must set USD as the response currency. PBS will convert to the publisher's requested currency as needed. See the [currency feature](/prebid-server/features/pbs-currency.html) for more info. +3. You should be aware that floors can be defined in any currency. If your bidding service supports floors, but only in a particular currency, then you must read use the `requestInfo.ConvertCurrency` function before sending $.imp[].bidfloor and $.imp[].bidfloorcur to your endpoint. + +
    + Example: Currency conversion needed for bid floor values in impressions. + +```go +func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) (*adapters.RequestData, []error) { + + for _, imp := range request.Imp { + // Check if imp comes with bid floor amount defined in a foreign currency + if imp.BidFloor > 0 && imp.BidFloorCur != "" && strings.ToUpper(imp.BidFloorCur) != "USD" { + + // Convert to US dollars + convertedValue, err := reqInfo.ConvertCurrency(imp.BidFloor, imp.BidFloorCur, "USD") + if err != nil { + return nil, []error{err} + } + + // Update after conversion. All imp elements inside request.Imp are shallow copies + // therefore, their non-pointer values are not shared memory and are safe to modify. + imp.BidFloorCur = "USD" + imp.BidFloor = convertedValue + } + } + + requestJSON, err := json.Marshal(request) + if err != nil { + return nil, []error{err} + } + + requestData := &adapters.RequestData{ + Method: "POST", + Uri: a.endpoint, + Body: requestJSON, + } + + return []*adapters.RequestData{requestData}, nil +} +```

    -If your bidding server supports multiple currencies, please be sure to pass through the `request.cur` field. If your bidding server only bids in a single currency, such as USD or EUR, that's fine. Prebid Server will convert your bid to the request currency if you include it in the bid response, otherwise we assume USD and conversion will not occur. - -Please ensure you forward the bid floor (`request.imp[].bidfloor`) and bid floor currency (`request.imp[].bidfloorcur`) values to your bidding server for enforcement. You'll soon have access to currency conversion helper methods if your endpoint only supports floors in a single currency. +##### Common Data There are a several values of a bid that publishers expect to be populated. Some are defined by the OpenRTB 2.5 specification and some are defined by Prebid conventions. @@ -557,9 +699,10 @@ There are a several values of a bid that publishers expect to be populated. Some | COPPA | OpenRTB | `request.regs.ext.us_privacy`
    The publisher is specifying the Children's Online Privacy Protection flag. | Currency | OpenRTB |`request.cur`
    The publisher is specifying the desired bid currency. The Prebid Server default is USD. | [Debug](https://github.com/prebid/prebid-server/issues/745) | Prebid | `request.ext.prebid.debug`
    The publisher is requesting verbose debugging information from Prebid Server. +| [Request-Defined currency conversion rates](https://docs.prebid.org/prebid-server/features/pbs-currency.html) | Prebid | `request.ext.prebid.currency`
    The publisher decides to prioritize its own custom currency conversion rates over Prebid Server's currency conversion rates. If a currency rate is not found in `request.ext.prebid.currency`, Prebid Server's rates will be used unless `usepbsrates` is set to `false`. If missing, `usepbsrates` defaults to true. | [First Party Data (FPD)](https://docs.prebid.org/prebid-server/features/pbs-fpd.html)| Prebid | `request.imp[].ext.context.data.*`, `request.app.ext.data.*`, `request.site.ext.data.*`, `request.user.ext.data.*`
    The publisher may provide first party data (e.g. keywords). | GDPR | OpenRTB | `request.regs.ext.gdpr`, `request.user.ext.consent`
    The publisher is specifying the European General Data Protection Regulation flag and TCF consent string. -| Site or App | OpenRTB | `request.site`, `request.app`
    The publisher will provide either the site or app, but not both, representing the client's device. +| Site or App | OpenRTB | `request.site`, `request.app`
    The publisher will provide either the site or app, but not both, representing the client's device. | Supply Chain | OpenRTB | `request.source.ext.schain`
    The publisher's declaration of all parties who are selling or reselling the bid request. | Test | OpenRTB | `request.test`
    The publisher is sending non-production traffic which also enables verbose debugging information from Prebid Server. | Video | OpenRTB | `request.imp[].video`
    The publisher is specifying video ad requirements or preferences. @@ -571,18 +714,20 @@ For simplicity, adapters are expected to make net-price bids (e.g. "If this ad w The `MakeBids` method is responsible for parsing the bidding server's response and mapping it to the [OpenRTB 2.5 Bid Response object model](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=32). -This method is called for each response received from your bidding server within the bidding window (`request.tmax`). If there are no requests or if all requests time out, the `MakeBids` method will not be called. +This method is called for each response received from your bidding server within the bidding time window (`request.tmax`). If there are no requests or if all requests time out, the `MakeBids` method will not be called. -{: .alert.alert-info :} +{: .alert.alert-warning :} It's *imperative* to include all required information in the response for your bid to be accepted. Please avoid common mistakes, such as not specifying the bid currency and not properly detecting the media type from the bidding server response. The first argument, `request`, is the exact same OpenRTB 2.5 Bid Request object provided to (and potentially mutated by) the `MakeRequests` method. The information in the `request` may be useful when detecting the media type. The second argument, `requestData`, is the exact same `adapters.RequestData` object returned by the `MakeRequests` method. It's rare for adapters to make use of this information, but it's provided for potential edge cases. -The third argument, `responseData`, is the HTTP response received from your bidding server and contains the status code, body, and headers. If your bidding server replies with a GZIP encoded body, it will be automatically decompressed. +The third argument, `responseData`, is the HTTP response received from your bidding server and contains the status code, body, and headers. If your bidding server replies with a GZIP encoded body, it will be automatically decompressed. -The `MakeBids` method is expected to return an `adapters.BidderResponse` object with one or more bids mapped from your bidding server's response. This may be as simple as decorating an OpenRTB 2.5 Bid Response with a some Prebid Server metadata (such as the media type) or more complicated mapping logic depending on your server's response format. +The `MakeBids` method is expected to return an `adapters.BidderResponse` object with one or more bids mapped from your bidding server's response. This may be as simple as decorating an OpenRTB 2.5 Bid Response with some Prebid Server metadata (such as the media type) or more complicated mapping logic depending on your server's response format. + +##### Object Model Please review the entire [OpenRTB 2.5 Bid Response](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=32) documentation to fully understand the response object model and expectations. We've summarized some common fields below. Data which is listed as required is enforced by the core framework and cannot be omitted. @@ -591,12 +736,12 @@ Please review the entire [OpenRTB 2.5 Bid Response](https://www.iab.com/wp-conte | - | - | - | `.Currency` | Required | [3-letter ISO 4217 code](https://www.iso.org/iso-4217-currency-codes.html) defining the currency of the bid. The Prebid Server default is USD. | `.Bids[].BidType` | Required | Prebid Server defined value identifying the media type as `banner`, `video`, `audio`, or `native`. Should be mapped from the bidding server response. -| `.Bids[].Bid.ADomain` | Optional | Advertiser domain for block list checking. -| `.Bids[].Bid.AdM` | Optional | Ad markup to serve if the bid wins. May be HTML, Native, or VAST/VMAP formats. You should resolve any AUCTION_PRICE macros. | `.Bids[].Bid.CrID` | Required | Unique id of the creative. | `.Bids[].Bid.ID` | Required | Bidder generated id to assist with logging and tracking. | `.Bids[].Bid.ImpID` | Required | ID of the corresponding bid request Impression. Prebid Server validates the id is actually found in the bid request. | `.Bids[].Bid.Price` | Required | Net price CPM of the bid, not gross price. Publishers can correct for gross price bids by setting Bid Adjustments to account for fees. We recommend the most granular price a bidder can provide. +| `.Bids[].Bid.ADomain` | Optional | Advertiser domain for block list checking. +| `.Bids[].Bid.AdM` | Optional | Ad markup to serve if the bid wins. May be HTML, Native, or VAST/VMAP formats. You should resolve any AUCTION_PRICE macros. | `.Bids[].Bid.W` | Optional | Width of the creative in pixels. | `.Bids[].Bid.H` | Optional | Height of the creative in pixels. | `.Bids[].Bid.Ext` | Optional | Embedded JSON containing Prebid metadata (see below) or custom information. @@ -604,22 +749,25 @@ Please review the entire [OpenRTB 2.5 Bid Response](https://www.iab.com/wp-conte {: .alert.alert-info :} We recommend resolving creative OpenRTB macros in your adapter. Otherwise, AUCTION_PRICE will eventually get resolved by the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative), but by then the bid price will be in the ad server currency and quantized by the price granularity. -If you'd like to support Long Form Video Ad Pods, then you'll need to provide the followings information: +If you'd like to support [Long Form Video Ad Pods](/dev-docs/modules/adpod.html)s, then you'll need to provide the followings information: {: .table .table-bordered .table-striped } | BidderResponse Path | Description | - | - -| `.Bids[].BidVideo.PrimaryCategory` | Category for the bid. Should be able to be translated to the primary ad server format. -| `.Bids[].Bid.Cat` | Category for the bid. Should be able to be translated to the primary ad server format. +| `.Bids[].BidVideo.PrimaryCategory` | Category for the bid in the taxonomy used by the ad server. Will be passed through without translation. +| `.Bids[].Bid.Cat` | IAB category for the bid which may be translated to the taxonomy used by the ad server. | `.Bids[].BidVideo.Duration` | Length of the video in integer seconds. | `.Bids[].DealPriority` | Deal tier integer value. Defaults to 0. {: .alert.alert-info :} Either `.Bids[].BidVideo.PrimaryCategory` or `.Bids[].Bid.Cat` should be provided. -Prebid has historically struggled with sharing granular bid response data with publishers, analytics, and reporting systems. To address this, we've introduced a standard object model. We encourage adapters to provide as much information as possible in the bid response. + +##### Metadata + +Prebid has introduced a standard object model for sharing granular bid response data with publishers, analytics, and reporting systems. We encourage adapters to provide as much information as possible in the bid response. {: .alert.alert-danger :} -Bid metadata will be *required* in Prebid.js 5.X+ release, specifically for AdvertiserDomains and MediaType. We recommend making sure your adapter sets these values or Prebid.js may throw out the bid. +Bid metadata will be *required* in Prebid.js 5.X+ release, specifically for bid.ADomain and MediaType. We recommend making sure your adapter sets these values or Prebid.js may throw out the bid. {: .table .table-bordered .table-striped } | Path | Description @@ -630,13 +778,13 @@ Bid metadata will be *required* in Prebid.js 5.X+ release, specifically for Adve | `.AgencyName` | Bidder-specific agency name. | `.AdvertiserID` | Bidder-specific advertiser id. | `.AdvertiserName` | Bidder-specific advertiser name. -| `.AdvertiserDomains` | Advertiser domains for the landing page(s). Should match `.Bids[].Bid.ADomain`. | `.BrandID` | Bidder-specific brand id for advertisers with multiple brands. | `.BrandName` | Bidder-specific brand name. -| `.dchain` | Demand Chain Object. +| `.DemandSource` | Bidder-specific demand source. Some adapters may functionally serve multiple SSPs or exchanges, and this specifies which. +| `.DChain` | Demand chain object. | `.PrimaryCategoryID` | Primary IAB category id. | `.SecondaryCategoryIDs` | Secondary IAB category ids. -| `.MediaType` | Either `banner`, `audio`, `video`, or `native`. Should match `.Bids[].BidType`. +| `.MediaType` | Either `banner`, `audio`, `video`, or `native`. This is used in the scenario where a bidder responds with a mediatype different than the stated type. e.g. native when the impression is for a banner. One use case is to help publishers determine whether the creative should be wrapped in a safeframe.

    @@ -644,83 +792,46 @@ Bid metadata will be *required* in Prebid.js 5.X+ release, specifically for Adve Example: Setting metadata. ```go -func (a *adapter) MakeBids(request *openrtb.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) { +func (a *adapter) MakeBids(request *openrtb2.BidRequest, requestData *adapters.RequestData, responseData *adapters.ResponseData) (*adapters.BidderResponse, []error) { ... for _, seatBid := range response.SeatBid { - for _, bid := range seatBid.Bid { - bid := bid // pin https://github.com/kyoh86/scopelint#whats-this + for i, bid := range seatBid.Bid { b := &adapters.TypedBid{ - Bid: &bid, + Bid: &seatBid.Bid[i], BidType: getMediaTypeForBid(bid), - } - - if meta, err := buildMeta(b); err != nil { - errs = append(errs, metaErr) - } else { - b.Bid.Ext = meta - bidResponse.Bids = append(bidResponse.Bids, b) + BidMeta: getBidMeta(bid), } } ... } -func buildMeta(bid *adapters.TypedBid) (json.RawMessage, error) { - metaExt := openrtb_ext.ExtBidPrebid { - Meta: &openrtb_ext.ExtBidPrebidMeta { - NetworkID: 1, - NetworkName: "Some Network Name", - AgencyID: 2, - AgencyName: "Some Agency Name", - AdvertiserID: 3, - AdvertiserName: "Some Advertiser Name", - AdvertiserDomains: bid.ADomain, - dchain: bid.ext.dchain, - BrandID: 4, - BrandName: "Some Brand Name", - PrimaryCategoryID: "IAB-1", - SecondaryCategoryIDs: []string{"IAB-2", "IAB-3"}, - MediaType: b.BidType, - } +func getBidMeta(bid *adapters.TypedBid) *openrtb_ext.ExtBidPrebidMeta { + // Not all fields are required. This example includes all fields for + // demonstration purposes. + return &openrtb_ext.ExtBidPrebidMeta { + NetworkID: 1, + NetworkName: "Some Network Name", + AgencyID: 2, + AgencyName: "Some Agency Name", + AdvertiserID: 3, + AdvertiserName: "Some Advertiser Name", + AdvertiserDomains: []string{"Some Domain"}, + DemandSource: "Some Demand Source", + DChain: json.RawMessage(`{Some Demand Chain JSON}`), + BrandID: 4, + BrandName: "Some Brand Name", + PrimaryCategoryID: "IAB-1", + SecondaryCategoryIDs: []string{"IAB-2", "IAB-3"}, + MediaType: "banner", } - return json.Marshal(meta) } ```

    -### Create A User Syncer (Optional) - -Prebid Server offers a federated [user sync solution](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) to store user ids in a single cookie under the host's domain. You may add support with a relatively small amount of code if your bidding server supports this protocol. - -Create a file with the path `adatpers/{bidder}/usersync.go` using the following template: - -```go -package {bidder} - -import ( - "text/template" - - "github.com/prebid/prebid-server/adapters" - "github.com/prebid/prebid-server/usersync" -) - -func NewSyncer(template *template.Template) usersync.Usersyncer { - return adapters.NewSyncer("{bidder}", template, adapters.SyncTypeRedirect) -} -``` - -The heavy lifting is handled by the `adapters.NewSyncer` method. You just need to provide a few arguments: - -{: .table .table-bordered .table-striped } -| Argument | Description -| - | - -| `familyName` | Name used for storing your user sync id within the federated cookie. Please keep this the same as your bidder name. -| `urlTemplate` | Pass through the `template` argument. -| `syncType` | Type of user sync supported by your bidding server. The valid options are `SyncTypeRedirect` and `SyncTypeIframe`. - ### Register With The Core -Prebid Server does not use reflection or any other automagic technology to recognize your new bid adapter. You must manually register it with the core framework. +Prebid Server does not use reflection or any other automated technology to recognize your new bid adapter. You must manually register it with the core framework. {: .alert.alert-info :} You will need to add an `import` statement for your bid adapter package in these files. Modern code editors such as Visual Studio Code and JetBrain's GoLand will automatically do that for you. @@ -745,7 +856,7 @@ const ( func CoreBidderNames() []BidderName { return []BidderName{ ... - Bidder{Bidder}, + Bidder{Bidder}, ... } } @@ -763,20 +874,9 @@ func newAdapterBuilders() map[openrtb_ext.BidderName]adapters.Builder { } ``` -If you have a user syncer, edit the file `usersync/usersyncers/syncer.go` to include it in the syncer map. - -```go -func NewSyncerMap(cfg *config.Configuration) map[openrtb_ext.BidderName]usersync.Usersyncer { - syncers := make(map[openrtb_ext.BidderName]usersync.Usersyncer, len(cfg.Adapters)) - ... - insertIntoMap(cfg, syncers, openrtb_ext.Bidder{Bidder}, {bidder}.NewSyncer) - ... -} -``` - ### Set Adapter Defaults -Lastly, you need to provide default settings for your bid adapter. You can decide if you'd like your bid adapter to be enabled out of the box, and if so, you'll need to provide a default endpoint and default extra adapter info if applicable. If your bid adapter requires host specific information to function properly, such as a security token or host account, then it's best to leave the adapter disabled. +You need to provide default settings for your bid adapter. You can decide if you'd like your bid adapter to be enabled out of the box, and if so, you'll need to provide a default endpoint and default extra adapter info (if applicable). If your bid adapter requires host specific information to function properly, such as a security token or host account, then it's best to leave the adapter disabled. {: .alert.alert-warning :} **HOST SPECIFIC INFO:** The default endpoint must not be specific to any particular host, such as Xandr/AppNexus. We may ask you about suspicious looking ids during the review process. Please reach out to individual hosts if you need to set specialized configuration. @@ -789,7 +889,7 @@ Edit the file `config/config.go` to register your default endpoint within the `S func SetupViper(v *viper.Viper, filename string) { ... v.SetDefault("adapters.{bidder}.endpoint", "https://your.url/any/path") - v.SetDefault("adapters.{bidder}.extra_info", `{"your": "extra info"}`) + v.SetDefault("adapters.{bidder}.extra_info", `{"your": "extra info"}`) ... } ``` @@ -806,76 +906,9 @@ func SetupViper(v *viper.Viper, filename string) { } ``` -### Set User Syncer Defaults - -If you implemented a user syncer, you'll need to provide a default endpoint. Edit the file `config/config.go` to alphabetically register your user syncer in the `setDerivedDefaults` method: - -```go -func (cfg *Configuration) setDerivedDefaults() { - ... - setDefaultUsersync(cfg.Adapters, openrtb_ext.Bidder{Bidder}, "https://your.url/sync?r="+url.QueryEscape(externalURL)+"%2Fsetuid%3Fbidder%3D{bidder}%26gdpr%3D{%raw%}{{.GDPR}}%26gdpr_consent%3D{{.GDPRConsent}}{%endraw%}%26uid%3D%5BUUID%5D") - ... -} -``` - -If you don't have a good default, please add a comment instead. - -```go -func (cfg *Configuration) setDerivedDefaults() { - ... - // openrtb_ext.Bidder{Bidder} doesn't have a good default. - ... -} -``` - - -Yes, you're right. That url value is quite complicated. You can find further details in our [user sync documentation](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html). - -The user sync endpoint is composed of two main parts, the url of your user syncer and a redirect back to Prebid Server. The url of your user syncer is responsible for reading the user id from the client's cookie and redirecting to Prebid Server with a user id macro resolved. - -The url of your user syncer can make use of the following privacy policy macros which will be resolved by Prebid Server before sending the url to your server: -- `{%raw%}{{.USPrivacy}}{%endraw%}`: Client's CCPA consent string. -- `{%raw%}{{.GDPR}}{%endraw%}`: Client's GDPR TCF enforcement flag. -- `{%raw%}{{.GDPRConsent}}{%endraw%}`: Client's GDPR TCF consent string. - -
    - Example: Bidding server url with no macros. - -```go -"https://your.url/sync?r=" -``` -
    - -
    - Example: Bidding server url with CCPA privacy consent. - -```go -"https://your.url/sync?usp={%raw%}{{.USPrivacy}}{%endraw%}&r=" -``` -
    -

    - -The redirect url for Prebid Server must follow this format: -``` -{host}/setuid?bidder={bidder}&gdpr={%raw%}{{.GDPR}}&gdpr_consent={{.GDPRConsent}}{%endraw%}&uid=[UUID] -``` - -{: .table .table-bordered .table-striped } -| Token | Description -| - | - -| `{host}` | Placeholder for the Prebid Server host url. In code, you would substitute it with `url.QueryEscape(externalURL)`. -| `{bidder}` | Placeholder for the name of your bid adapter. -| `[UUID]` | Macro defined by your user sync server which will be replaced with the user's id. - -The final value of the redirect url is encoded for safe use within a query string: - -``` -{host}%2Fsetuid%3Fbidder%3D{bidder}%26gdpr%3D{%raw%}{{.GDPR}}%26gdpr_consent%3D{{.GDPRConsent}}{%endraw%}%26uid%3D%5BUUID%5D -``` - ## Test Your Adapter -This chapter will guide you through the creation of automated unit tests to cover your bid adapter code, bidder parameters JSON Schema, and user sync code. We use GitHub Action Workflows to ensure the code you submit passes validation. You can run the same validation locally with this command: +This section will guide you through the creation of automated unit tests to cover your bid adapter code and bidder parameters JSON Schema. We use GitHub Action Workflows to ensure the code you submit passes validation. You can run the same validation locally with this command: ```bash ./validate.sh --nofmt --cov --race 10 @@ -883,7 +916,7 @@ This chapter will guide you through the creation of automated unit tests to cove ### Adapter Code Tests -Bid requests and server responses can be quite verbose. To avoid large blobs of text embedded within test code, we've created a framework for bid adapters which use a JSON body and/or a url. If your bidding server uses another payload format, such as XML, you're on your own. +Bid requests and server responses can be quite verbose. To avoid large blobs of text embedded within test code, we've created a framework for bid adapters which use a JSON body and/or a url to send a bid request. We require the use of our test framework as it includes checks to ensure no changes are made to shared memory. We strive for as much test coverage as possible, but recognize that some code paths are impractical to simulate and rarely occur. You do not need to test the error conditions for `json.Marshal` calls, for template parse errors within `MakeRequests` or `MakeBids`, or for `url.Parse` calls. Following this guidance usually results in a coverage rate of around 90% - 95%, although we don't enforce a specific threshold. @@ -894,7 +927,7 @@ package {bidder} import ( "testing" - + "github.com/prebid/prebid-server/adapters/adapterstest" "github.com/prebid/prebid-server/config" "github.com/prebid/prebid-server/openrtb_ext" @@ -903,11 +936,11 @@ import ( func TestJsonSamples(t *testing.T) { bidder, buildErr := Builder(openrtb_ext.Bidder{Bidder}, config.Adapter{ Endpoint: "http://whatever.url"}) - + if buildErr != nil { t.Fatalf("Builder returned unexpected error %v", buildErr) } - + adapterstest.RunJSONBidderTest(t, "{bidder}test", bidder) } ``` @@ -962,7 +995,7 @@ The format of a JSON test is as follows: The `mockBidRequest`, `httpCalls`, and `expectedBidResponses` fields are required. The `expectedMakeRequestsErrors` and `expectedMakeBidsErrors` may be omitted if there are no expected errors. We provide a `literal` and `regex` mode for testing error values. We often use the `regex` mode to handle error messages produced by the core Go framework which changed between recent releases. -To make everyone's life easier, please use a JSON 'prettifier' to apply standard formatting to your test files. We recommend the use of Visual Studio Code's [Beautify](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify) extension. +Please use a JSON 'prettifier' to apply standard formatting to your test files. We recommend the use of Visual Studio Code's [Beautify](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify) extension. ### Builder Tests @@ -974,7 +1007,7 @@ If your adapter supports template parsing, we recommend adding this failure test func TestEndpointTemplateMalformed(t *testing.T) { _, buildErr := Builder(openrtb_ext.Bidder{Bidder}, config.Adapter{ Endpoint: "{%raw%}{{Malformed}}{%endraw%}"}) - + assert.Error(t, buildErr) } ``` @@ -987,7 +1020,7 @@ func TestBadConfig(t *testing.T) { Endpoint: `http://it.doesnt.matter/bid`, ExtraAdapterInfo: `{foo:42}`, }) - + assert.Error(t, buildErr) } @@ -996,27 +1029,14 @@ func TestEmptyConfig(t *testing.T) { Endpoint: `http://it.doesnt.matter/bid`, ExtraAdapterInfo: ``, }) - + bidder{Bidder} := bidder.(*adapter) - + assert.NoError(t, buildErr) assert.Empty(t, bidder{Bidder}.extraInfo.SomeInfo) } ``` -### Adapter Race Condition Tests - -You must define race condition tests for each media type supported by your bid adapter. We don't expect bid adapters to run concurrent code. Rather, these tests attempt to verify your bid adapter doesn't modify shared memory. We use Go's [race detector](https://golang.org/doc/articles/race_detector.html) which is a great line of defense, but it may produce false negatives. It will not produce false positives, so please investigate further if these tests ever fail. - -Create a file with the path `adapters/{bidder}/{bidder}test/params/race/{mediaType}.json` for each `banner`, `video`, `audio`, and `native` media type supported by your adapter. Include all required and optional bidder parameters defined by your JSON Schema. - -Here's an example file using the same example JSON Schema from other chapters: -```json -{ - "placementId": "Some Placement" -} -``` - ### Bidder Parameter Tests The bidder parameter JSON Schema files are considered a form of code and must be tested. Create a file with the path `adapters/{bidder}/params_test.go` using the following template: @@ -1027,7 +1047,7 @@ package {bidder} import ( "encoding/json" "testing" - + "github.com/prebid/prebid-server/openrtb_ext" ) @@ -1036,7 +1056,7 @@ func TestValidParams(t *testing.T) { if err != nil { t.Fatalf("Failed to fetch the json schema. %v", err) } - + for _, p := range validParams { if err := validator.Validate(openrtb_ext.Bidder{Bidder}, json.RawMessage(p)); err != nil { t.Errorf("Schema rejected valid params: %s", p) @@ -1049,7 +1069,7 @@ func TestInvalidParams(t *testing.T) { if err != nil { t.Fatalf("Failed to fetch the json schema. %v", err) } - + for _, p := range invalidParams { if err := validator.Validate(openrtb_ext.Bidder{Bidder}, json.RawMessage(p)); err == nil { t.Errorf("Schema allowed invalid params: %s", p) @@ -1068,66 +1088,11 @@ var invalidParams = []string{ ``` Please include tests for required fields, optional fields, conditional fields such as `oneOf`, regex filters, and data type mismatches. For example, if the field is defined as a string please include one invalid case for the wrong data type such as an integer in this example. -You don't have to go crazy with combinatorials. We're looking for just enough test cases to build confidence. - -### User Syncer Tests - -{: .alert.alert-info :} -Please skip to the end of this section if your adapter doesn't define a user syncer. - -We ask that you include a user syncer test to verify the basic mechanics of macro substitution. The `syncURL` should be the same value used in the `setDefaultUsersync` call with the `url.QueryEscape(externalURL)` code replaced with a simple hardcoded value such as `"host"`. Please keep the privacy policy values simple, as we're only testing substitution. - -Create a file with the path `adapters/{bidder}/usersync_test.go` using the following template: - -```go -package {bidder} - -import ( - "testing" - "text/template" - - "github.com/prebid/prebid-server/privacy" - "github.com/prebid/prebid-server/privacy/ccpa" - "github.com/prebid/prebid-server/privacy/gdpr" - "github.com/stretchr/testify/assert" -) - -func TestSyncer(t *testing.T) { - syncURL := "" - syncURLTemplate := template.Must( - template.New("sync-template").Parse(syncURL), - ) - - syncer := NewSyncer(syncURLTemplate) - syncInfo, err := syncer.GetUsersyncInfo(privacy.Policies{ - GDPR: gdpr.Policy{ - Signal: "A", - Consent: "B", - }, - CCPA: ccpa.Policy{ - Consent: "C", - }, - }) - - assert.NoError(t, err) - assert.Equal(t, "", syncInfo.URL) - assert.Equal(t, "redirect", syncInfo.Type) -} -``` - -If you *DON'T* have a user syncer, edit the file `usersync/usersyncers/syncer_test.go` to exclude your bid adapter from user sync tests: - -```go -adaptersWithoutSyncers := map[openrtb_ext.BidderName]bool{ - ... - openrtb_ext.Bidder{Bidder}: true, - ... -} -``` +There is no need to provide a combinatorial for every edge case possibility. We're looking for just enough test cases to build confidence. ### Manual End To End Tests -We'll verify your adapter works correctly on a technical level during the code review, but you'll need to perform separate end-to-end testing: +We'll verify your adapter works correctly on a technical level during the code review, but you'll need to perform manual end-to-end testing: 1. Build the project and start your server: ```bash @@ -1171,20 +1136,22 @@ We'll verify your adapter works correctly on a technical level during the code r }' ``` -If your bid adapters defines a user syncer, please perform end-to-end testing of the user sync process: +### User Sync Testing + +If your bid adapter defines one or more user sync endpoints, you'll need to perform manual end-to-end testing of each endpoint using the following process: -1. [Save a User ID](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-setuid.html) using the `familyName` of your user syncer. This is likely the same as your bidder name. +1. [Save a User ID](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-setuid.html) using the `key` of your user sync endpoint. This should default to your bidder name and is case sensitive. 1. Run a test auction (see the curl example above) and verify in the debug response that the outgoing `request.ext.debug.httpcalls` calls includes the User ID you saved in step 1. -It may be a bit tricky to track down the root cause of user sync errors. If you get stuck, please [submit a GitHub issue](https://github.com/prebid/prebid-server/issues/new) and we'll provide guidance. +If you are having issues finding the root cause of user sync errors, please [submit a GitHub issue](https://github.com/prebid/prebid-server/issues/new) and we'll provide guidance. ## User Documentation Human readable documentation for bid adapters is required in the separate [prebid.github.io](https://github.com/prebid/prebid.github.io) repository. We will not merge your bid adapter until you've at least opened a documentation PR and comment with a link to it. -1. If you already have a Prebid.js bid adapter, update your existing bidder file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/modules to add the `pbs: true` variable in the header section. If your Prebid Server bidding parameters are different from your Prebid.js parameters, please include the differences in this document for publishers to be aware. -1. If you don't have a Prebid.js bid adapter, create a new file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/modules using this template: +1. If you already have a Prebid.js bid adapter, update your existing bidder file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders to add the `pbs: true` variable in the header section. If your Prebid Server bidding parameters are different from your Prebid.js parameters, please include the differences in this document for publishers to be aware. +1. If you don't have a Prebid.js bid adapter, create a new file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders using this template: ``` --- @@ -1201,11 +1168,15 @@ dchain_supported: true/false userId: media_types: banner, video, audio, native safeframes_ok: true/false -bidder_supports_deals: true/false +deals_supported: true/false +floors_supported: true/false +fpd_supported: true/false pbjs: true/false pbs: true/false pbs_app_supported: true/false prebid_member: true/false +multiformat_supported: will-bid-on-any, will-bid-on-one, will-not-bid +ortb_blocking_supported: true/partial/false --- ### Note: @@ -1231,7 +1202,10 @@ Notes on the metadata fields: - If you support adding a demand chain on the bid response, add `dchain_supported: true`. Default is false. - If your bidder doesn't work well with safeframed creatives, add `safeframes_ok: false`. This will alert publishers to not use safeframed creatives when creating the ad server entries for your bidder. No default. - If your bidder supports mobile apps, set `pbs_app_supported: true`. No default value. -- If your bidder supports deals, set `bidder_supports_deals: true`. No default value. +- If your bidder supports deals, set `deals_supported: true`. No default value. +- If your bidder supports floors, set `floors_supported: true`. No default value. +- If you support first party data, you must document what exactly is supported and then you may set `fpd_supported: true`. No default value. +- If you support any OpenRTB blocking parameters, you must document what exactly is supported and then you may set `ortb_blocking_supported` to ‘true’,’partial’, or ‘false’. No default value. In order to set ‘true’, you must support: bcat, badv, battr, and bapp. - If you're a member of Prebid.org, add `prebid_member: true`. Default is false. @@ -1248,13 +1222,6 @@ Notes on the metadata fields: - `adapters/{bidder}/{bidder}_test.go` - `adapters/{bidder}/{bidder}test/exemplary/*.json` - `adapters/{bidder}/{bidder}test/supplemental/*.json` - - `adapters/{bidder}/{bidder}test/params/race/{mediaType}.json` -- User Syncer - If You Have One - - `adapters/{bidder}/usersync.go` - - `adapters/{bidder}/usersync_test.go` - - `usersync/usersyncers/syncer.go` -- User Syncer - If You Don't - - `usersync/usersyncers/syncer_test.go` - Register With The Core - `openrtb_ext/bidders.go` - `exchange/adapter_builders.go` @@ -1263,7 +1230,7 @@ Notes on the metadata fields: ## Contribute -Whew! You're almost done. Thank you for taking the time to develop a Prebid Server bid adapter. When you're ready, [contribute](https://github.com/prebid/prebid-server/blob/master/docs/developers/contributing.md) your new bid adapter by opening a PR to the [PBS-Go GitHub repository](https://github.com/prebid/prebid-server) with the name "New Adapter: {Bidder}". +Thank you for taking the time to develop a Prebid Server bid adapter. When you're ready, [contribute](https://github.com/prebid/prebid-server/blob/master/docs/developers/contributing.md) your new bid adapter by opening a PR to the [PBS-Go GitHub repository](https://github.com/prebid/prebid-server) with the name "New Adapter: {Bidder}". {: .alert.alert-warning :} You don't need to ask permission or open a GitHub issue before submitting an adapter. diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md index 692954b274..ff54c340ef 100644 --- a/prebid-server/developers/add-new-bidder-java.md +++ b/prebid-server/developers/add-new-bidder-java.md @@ -19,7 +19,7 @@ This document guides you through the process of developing a new bid adapter for **NOTE:** There are two implementations of Prebid Server, [PBS-Go](https://github.com/prebid/prebid-server) and [PBS-Java](https://github.com/prebid/prebid-server-java). We recommend you build new adapters for PBS-Go and allow us to port it to PBS-Java within a couple of months. -## Overview +## Introduction Bid adapters are responsible for translating an [OpenRTB 2.5 Bid Request](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=13) to your bidding server's protocol and mapping your server's response to an [OpenRTB 2.5 Bid Response](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=32). @@ -29,7 +29,7 @@ An OpenRTB 2.5 Bid Request contains one or more Impressions, each representing a ### Choose A Name -You will need to choose a unique name for your bid adapter. Names should be written in lower case and may not contain special characters or emoji. If you already have a Prebid.js bid adapter, we encourage you to use the same name with the same bidder parameters. You may not name your adapter `general`, `context`, or `prebid` as those have special meaning in various contexts. Existing bid adapter names are [maintained here](https://github.com/prebid/prebid-server-java/tree/master/src/main/java/org/prebid/server/bidder). +You will need to choose a unique name for your bid adapter. Names should be written in lower case and may not contain special characters or emoji. If you already have a Prebid.js bid adapter, we encourage you to use the same name with the same bidder parameters. You may not name your adapter `all`, `context`, `data`, `general`, `prebid`, `skadn` or `tid` as those have special meaning in various contexts. Existing bid adapter names are [maintained here](https://github.com/prebid/prebid-server-java/tree/master/src/main/java/org/prebid/server/bidder). We ask that the first 6 letters of the name you choose be unique among the existing bid adapters. This consideration helps with generating targeting keys for use by some ad exchanges, such as Google Ad Manager. @@ -37,7 +37,7 @@ Throughout the rest of this document, substitute `{bidder}` with the name you've ### Respect The Rules -We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://docs.prebid.org/wrapper_code_of_conduct.html) and [module rules](https://docs.prebid.org/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions. +We are proud to run the Prebid Server project as a transparent and trustworthy header bidding solution. You are expected to follow our community's [code of conduct](https://prebid.org/code-of-conduct/) and [module rules](/dev-docs/module-rules.html) when creating your adapter and when interacting with others through issues, code reviews, and discussions. **Please take the time to read our rules in full.** Below is a summary of some of the rules which apply to your Prebid Server bid adapter: - Adapters must not modify bids from demand partners, except to either change the bid from gross to net or from one currency to another. @@ -58,6 +58,10 @@ Occasionally, we'll introduce changes to the core framework as part of our ongoi Please be attentive in reading and responding to emails and [GitHub issues](https://github.com/prebid/prebid-server-java/issues) from publishers, hosts, and Prebid.org project maintainers. If we receive complaints about your bid adapter and you do not respond to our communications, we may disable your adapter by default or remove it from the project entirely. +## Generic Adapter + +Before creating your own bid adapter, consider looking into [generic adapter implementation](https://github.com/prebid/prebid-server-java/blob/master/src/main/java/org/prebid/server/bidder/GenericBidder.java). Its main purpose is to simplify testing of PBS. As this adapter just passes requests through without any additional manipulations with data, it can be used to test behaviour of PBS core logic. But, it can be also used as template for simple bid adapters or even for aliasing the very basic ones. + ## Create Your Adapter Prebid Server bid adapters consist of several components: bidder config yaml, bidder parameters, bid adapter code, configuration for framework and default configuration(.yaml) values. This chapter will guide you though each component. @@ -78,13 +82,8 @@ Create a file with the path `static/bidder-info/{bidder}.yaml` and begin with th ```yaml adapters: yourBidderCode: - enabled: false endpoint: http://possible.endpoint - pbs-enforces-gdpr: true - pbs-enforces-ccpa: true - modifying-vast-xml-allowed: true - deprecated-names: - aliases: + endpoint-compression: gzip (or none) meta-info: maintainer-email: maintainer@email.com app-media-types: @@ -109,10 +108,12 @@ adapters: Modify this template for your bid adapter: - Change the maintainer email address to a group distribution list on your ad server's domain. A distribution list is preferred over an individual mailbox to allow for robustness, as roles and team members naturally change. -- Change the `modifyingVastXmlAllowed` value to `true` if you'd like to opt-in for video impression tracking. -- Change the `enabled` value to `true` if you'd like to make your bid adapter enabled. +- Change the `modifying-vast-xml-allowed` value to `false` if you'd like to opt out of video impression tracking. It defaults to `true`. +- Change the `pbs-enforces-ccpa` to `false` if you'd like to disable ccpa enforcement. Defaults to `true`. - Change the `vendor-id` value to id of your bidding server as registered with the [GDPR Global Vendor List (GVL)](https://iabeurope.eu/vendor-list-tcf-v2-0/). Leave this as `0` if you are not registered with IAB Europe. +- Choose the `supported-vendors` constants: These constants should be unique. The list of existing vendor constants can be found [here](https://github.com/prebid/prebid-server-java/blob/master/src/main/java/org/prebid/server/bidder/ViewabilityVendors.java). - Remove the `capabilities` (app/site) and `mediaTypes` (banner/video/audio/native) combinations which your adapter does not support. +- If your auction endpoint supports gzip compression, setting 'endpoint-compression' to 'gzip' will save on network fees. - Change the `cookie-family-name` to the name which will be used for storing your user sync id within the federated cookie. Please keep this the same as your bidder name. If you implemented a user syncer, you'll need to provide a default endpoint. The user sync endpoint is composed of two main parts, the url of your user syncer and a redirect back(redirect-url) to Prebid Server. The url of your user syncer is responsible for reading the user id from the client's cookie and redirecting to Prebid Server with a user id macro resolved. @@ -124,6 +125,25 @@ The url of your user syncer can make use of the following privacy policy macros - Change the `usersync:type` value to `redirect` or `iframe` specific to your bidder. +### Default bidder configuration + +Prebid Server has default configuration for common bidder properties, which can be overriden by bidders in their +configurations. + +Default configuration: + +```yaml +adapter-defaults: + enabled: false + pbs-enforces-ccpa: true + modifying-vast-xml-allowed: true +``` + +There are also some default properties which can't be overridden in adapter-defaults, but rather in particular adapter's config: +- `aliases`: Defaults to empty +- `deprecated-names`: Defaults to empty +- `extra-info`: Defaults to empty + ### Create bidder alias If you want to add bidder that is an alias of existing bidder, you need just to update configuration of parent bidder: @@ -131,12 +151,7 @@ Example of adding bidder alias: ```yaml adapters: yourBidderCode: - enabled: false - endpoint: http://possible.endpoint - pbs-enforces-gdpr: true - pbs-enforces-ccpa: true - modifying-vast-xml-allowed: true - deprecated-names: + ... aliases: yourBidderAlias: endpoint: http://possible.alias/endpoint @@ -148,26 +163,6 @@ adapters: - video usersync: cookie-family-name: yourBidderCode - meta-info: - maintainer-email: maintainer@email.com - app-media-types: - - banner - - video - - audio - - native - site-media-types: - - banner - - video - - audio - - native - supported-vendors: - vendor-id: your_vendor_id - usersync: - url: your_bid_adapter_usersync_url - redirect-url: /setuid?bidder=yourBidderCode&gdpr={%raw%}{{gdpr}}{%endraw%}&gdpr_consent={%raw%}{{gdpr_consent}}{%endraw%}&us_privacy={%raw%}{{us_privacy}}{%endraw%} - cookie-family-name: yourBidderCode - type: redirect - support-cors: false ``` Aliases are configured by adding child configuration object at `adapters.yourBidderCode.aliases.yourBidderAlias` @@ -350,7 +345,7 @@ Now it's time to write the bulk of your bid adapter code. Each adapter has its own directory (a 'package' in java parlance) for all code and tests associated with translating an OpenRTB 2.5 Bid Request to your bidding server's protocol and mapping your server's response to an OpenRTB 2.5 Bid Response. The use of separate packages provide each adapter with its own naming scope to avoid conflicts and gives the freedom to organize files as you best see fit (although we make suggestions in this guide). Create a file with the path `org.prebid.server.bidder.{bidder}/{bidder}Bidder.java`. Your bid adapter code will need to implement Bidder interface where `T` is a model which will represent HttpRequest body. -- The `Bidder` interface consisting of the `MakeRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. +- The `Bidder` interface consisting of the `MakeHttpRequests` method to create outgoing requests to your bidding server and the `MakeBids` method to create bid responses. Here is a reference implementation for a bidding server which uses the OpenRTB 2.5 protocol: @@ -397,20 +392,20 @@ public class {bidder}Bidder implements Bidder { @Override public Result>> makeHttpRequests(BidRequest request) { - return Result.of(Collections.singletonList(HttpRequest.builder() + return Result.withValue(HttpRequest.builder() .method(HttpMethod.POST) .uri(endpointUrl) .headers(HttpUtil.headers()) .payload(request) .body(mapper.encode(request)) - .build()), Collections.emptyList()); + .build())); } @Override public final Result> makeBids(HttpCall httpCall, BidRequest bidRequest) { try { final BidResponse bidResponse = mapper.decodeValue(httpCall.getResponse().getBody(), BidResponse.class); - return Result.of(extractBids(httpCall.getRequest().getPayload(), bidResponse), Collections.emptyList()); + return Result.withValues(extractBids(httpCall.getRequest().getPayload(), bidResponse)); } catch (DecodeException | PreBidException e) { return Result.withError(BidderError.badServerResponse(e.getMessage())); } @@ -455,9 +450,9 @@ public class {bidder}Bidder implements Bidder { ``` -#### MakeRequests +#### MakeHttpRequests -The `MakeRequests` method is responsible for returning none, one, or many HTTP requests to be sent to your bidding server. Bid adapters are forbidden from directly initiating any form of network communication and must entirely rely upon the core framework. This allows the core framework to optimize outgoing connections using a managed pool and record networking metrics. The return type `adapters.RequestData` allows your adapter to specify the HTTP method, url, body, and headers. +The `MakeHttpRequests` method is responsible for returning zero or more HTTP requests to be sent to your bidding server. Bid adapters are forbidden from directly initiating any form of network communication and must entirely rely upon the core framework. This allows the core framework to optimize outgoing connections using a managed pool and record networking metrics. The return type `adapters.RequestData` allows your adapter to specify the HTTP method, url, body, and headers. This method is called once by the core framework for bid requests which have at least one valid Impression for your adapter. Impressions not configured for your adapter will be removed and are not accessible. @@ -479,10 +474,7 @@ The argument, `request`, is the OpenRTB 2.5 Bid Request object. Extension inform

    -The `MakeRequests` method is expected to return a `List` object representing the HTTP calls to be sent to your bidding server and a `List errors` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please use different methods in `Result` class specific to your case. - -{: .alert.alert-info :} -HTTP calls to your bidding server will automatically prefer GZIP compression. You should not specify it yourself using headers. You don't have to worry about decompressing the response in `MakeBids` either, as that will be taken care of automatically. +The `MakeHttpRequests` method is expected to return a `List` object representing the HTTP calls to be sent to your bidding server and a `List errors` for any issues encountered creating them. If there are no HTTP calls or if there are no errors, please use different methods in `Result` class specific to your case. An Impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the Impression into multiple calls and merge the responses. @@ -514,7 +506,7 @@ If your bidding server supports multiple currencies, please be sure to pass thro Please ensure you forward the bid floor (`request.imp[].bidfloor`) and bid floor currency (`request.imp[].bidfloorcur`) values to your bidding server for enforcement. -There are a several values of a bid that publishers expect to be populated. Some are defined by the OpenRTB 2.5 specification and some are defined by Prebid conventions. +There are a several values of a bid request that publishers may supply that your adapter and endpoint should be aware of. Some are defined by the OpenRTB 2.5 specification and some are defined by Prebid conventions: {: .table .table-bordered .table-striped } | Parameter | Definer | Path & Description @@ -533,9 +525,22 @@ There are a several values of a bid that publishers expect to be populated. Some | Video | OpenRTB | `request.imp[].video`
    The publisher is specifying video ad requirements or preferences. | Rewarded inventory | OpenRTB | `request.imp[].ext.prebid.is_rewarded_inventory`
    Signal to indicate the inventory is rewarded. +##### Request compression + +If you want your request body to be GZIP compressed, you should add `Content-Encoding` header with `gzip` value. +
    + Example: Creating headers for gzip compressed request. +```java +private static MultiMap resolveHeaders() { + return HttpUtil.headers() + .add(HttpUtil.CONTENT_ENCODING_HEADER, HttpHeaderValues.GZIP); + } +``` +
    + #### Response -The `MakeBids` method is responsible for parsing the bidding server's response and mapping it to the [OpenRTB 2.5 Bid Response object model](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=32). +The `MakeBids` method in your adapter is responsible for parsing the bidding server's response and mapping it to the [OpenRTB 2.5 Bid Response object model](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf#page=32). This method is called for each response received from your bidding server within the bidding window (`request.tmax`). If there are no requests or if all requests time out, the `MakeBids` method will not be called. @@ -563,7 +568,7 @@ Please review the entire [OpenRTB 2.5 Bid Response](https://www.iab.com/wp-conte | `.Bids[].Bid.Price` | Required | Net price CPM of the bid, not gross price. Publishers can correct for gross price bids by setting Bid Adjustments to account for fees. We recommend the most granular price a bidder can provide. | `.Bids[].Bid.W` | Optional | Width of the creative in pixels. | `.Bids[].Bid.H` | Optional | Height of the creative in pixels. -| `.Bids[].Bid.Ext` | Optional | Embedded JSON containing Prebid metadata (see below) or custom information. +| `.Bids[].Bid.Ext.Prebid.Meta` | Optional | Embedded JSON containing Prebid metadata (see below) or custom information. {: .alert.alert-info :} We recommend resolving creative OpenRTB macros in your adapter. Otherwise, AUCTION_PRICE will eventually get resolved by the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative), but by then the bid price will be in the ad server currency and quantized by the price granularity. @@ -581,57 +586,32 @@ If you'd like to support Long Form Video Ad Pods, then you'll need to provide th {: .alert.alert-info :} Either `.Bids[].BidVideo.PrimaryCategory` or `.Bids[].Bid.Cat` should be provided. -Prebid has historically struggled with sharing granular bid response data with publishers, analytics, and reporting systems. To address this, we've introduced a standard object model. We encourage adapters to provide as much information as possible in the bid response. +##### Metadata + +In order to share granular bid response data with publishers, analytics, and reporting systems, we've introduced a standard object model. We encourage adapters to provide as much information as possible in the bid response. {: .alert.alert-danger :} -Bid metadata will be *required* in Prebid.js 5.x+ release, specifically for AdvertiserDomains and MediaType. We recommend making sure your adapter sets these values or Prebid.js may throw out the bid. +Bid metadata will be *required* in Prebid.js 5.X+ release, specifically for bid.ADomain and MediaType. We recommend making sure your adapter sets these values or Prebid.js may throw out the bid. {: .table .table-bordered .table-striped } | Path | Description | | - | - | +| `.DemandSource` | Bidder-specific demand source | | `.NetworkID` | Bidder-specific network/DSP id | | `.NetworkName` | Bidder-specific network/DSP name | | `.AgencyID` | Bidder-specific agency id | | `.AgencyName` | Bidder-specific agency name | | `.AdvertiserID` | Bidder-specific advertiser id | | `.AdvertiserName` | Bidder-specific advertiser name | -| `.AdvertiserDomains` | Advertiser domains for the landing page(s). Should match `.Bids[].Bid.ADomain` | | `.BrandID` | Bidder-specific brand id for advertisers with multiple brands | | `.BrandName` | Bidder-specific brand name | | `.dchain` | Demand Chain Object | `.PrimaryCategoryID` | Primary IAB category id | | `.SecondaryCategoryIDs` | Secondary IAB category ids | -| `.MediaType` | Either `banner`, `audio`, `video`, or `native`. Should match `.Bids[].BidType` | +| `.MediaType` | Either `banner`, `audio`, `video`, or `native`. This is used in the scenario where a bidder responds with a mediatype different than the stated type. e.g. native when the impression is for a banner. One use case is to help publishers determine whether the creative should be wrapped in a safeframe. |

    -### Simple Bidder Creation -Remember if your bidder does not have much specific logic beyond standard OpenRTB 2.5, you don't have to implement `Bidder` -but could choose to extend OpenrtbBidder(where T is ImpExt type), which already implements Bidder and has a default implementation of different methods. You can override each of them with your own implementation as needed. - -Here is the list of methods in OpenrtbBidder which you can override: - -1) `void validateRequest(BidRequest bidRequest)` - - A hook for bidder-specific request validation if any is required. - - -2) `Imp modifyImp(Imp imp, T impExt)` - - A hook for bidder-specific impression changes, impression validation and impression extension validation if any are required - - -3) `void modifyRequest(BidRequest bidRequest, BidRequest.BidRequestBuilder requestBuilder, List> impsWithExts)` - - A hook for any request changes other than Imps (although Impressions can be modified as well) - - -4) `BidType getBidType(String impId, List imps)` - - A hook for resolving bidder-specific bid type. - ---- -Using this class(OpenrtbBidder), you can define whether the outgoing -requests can contain multiple impressions (`RequestCreationStrategy.SINGLE_REQUEST`) or whether each each request should have only one impression (`RequestCreationStrategy.REQUEST_PER_IMP`). Pass this value to parent constructor as the second argument. - -Check the class file to find which methods are overridable. - ### Create Config Class Go to `org.prebid.server.spring.config.bidder` and create new class `Configuration{bidder}` @@ -644,13 +624,9 @@ import org.prebid.server.bidder.BidderDeps; import org.prebid.server.bidder.{bidder}.{bidder}Bidder; import org.prebid.server.json.JacksonMapper; import org.prebid.server.spring.config.bidder.model.BidderConfigurationProperties; -import org.prebid.server.spring.config.bidder.model.UsersyncConfigurationProperties; import org.prebid.server.spring.config.bidder.util.BidderDepsAssembler; -import org.prebid.server.spring.config.bidder.util.BidderInfoCreator; import org.prebid.server.spring.config.bidder.util.UsersyncerCreator; import org.prebid.server.spring.env.YamlPropertySourceFactory; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; @@ -664,18 +640,7 @@ import javax.validation.constraints.NotBlank; public class {bidder}Configuration { private static final String BIDDER_NAME = "{bidder}"; - - @Value("${external-url}") - @NotBlank - private String externalUrl; - - @Autowired - private JacksonMapper mapper; - - @Autowired - @Qualifier("{bidder}ConfigurationProperties") - private BidderConfigurationProperties configProperties; - + @Bean("{bidder}ConfigurationProperties") @ConfigurationProperties("adapters.{bidder}") BidderConfigurationProperties configurationProperties() { @@ -683,20 +648,29 @@ public class {bidder}Configuration { } @Bean - BidderDeps {bidder}BidderDeps() { - final UsersyncConfigurationProperties usersync = configProperties.getUsersync(); - + BidderDeps{bidder}BidderDeps(BidderConfigurationProperties {bidder}ConfigurationProperties, + @NotBlank @Value("${external-url}") String externalUrl, + JacksonMapper mapper) { + return BidderDepsAssembler.forBidder(BIDDER_NAME) - .withConfig(configProperties) - .bidderInfo(BidderInfoCreator.create(configProperties)) - .usersyncerCreator(UsersyncerCreator.create(usersync, externalUrl)) - .bidderCreator(() -> new {bidder}Bidder(configProperties.getEndpoint(), mapper)) + .withConfig({bidder}ConfigurationProperties) + .usersyncerCreator(UsersyncerCreator.create(externalUrl)) + .bidderCreator(config -> new {bidder}Bidder(config.getEndpoint(), mapper)) .assemble(); } } ``` -### Converting Floor Prices (optional) +### Currency + +Prebid Server is a global product that is currency agnostic. Publishers may ask for bids in any currency. It's totally fine if your bidding endpoint only supports a single currency, but your adapter needs to deal with it. This section will describe how to do so. + +Here are 3 key points to consider: + +1. If your endpoint only bids in a particular currency, then your adapter must not blindly forward the openrtb to your endpoint. You should instead set $.cur to your server's required currency. +2. Your adapter must label bid responses properly with the response currency. i.e. if you only bid in USD, then your adapter must set USD as the response currency. PBS will convert to the publisher's requested currency as needed. See the [currency feature](/prebid-server/features/pbs-currency.html) for more info. +3. You should be aware that floors can be defined in any currency. If your bidding service supports floors, but only in a particular currency, then you must read use the CurrencyConversionService before sending $.imp[].bidfloor and $.imp[].bidfloorcur to your endpoint. + If you need to convert floor prices from one currency into something your endpoint expects, you can use the convertCurrency function from CurrencyConversionService component. 1) Inject CurrencyConversionService to your {bidder}Configuration class and pass it to your bidder constructor. @@ -752,6 +726,98 @@ public {bidder}Bidder(String endpointUrl, CurrencyConversionService currencyCon

    +### Price Floors + +Prebid server manages the OpenRTB floors values (imp.bidfloor and imp.bidfloorcur) at the core level using the [Price Floors feature](/features/pbs-floors.html). Minimally, bid adapters are expected to read these values and pass them to the endpoint. + +However, as described in the feature documentation, some adapters may benefit from access to more granular values. The primary use case is for multi-format as [detailed in the document](/prebid-server/features/pbs-floors.html#bid-adapter-floor-interface). To implement this, you may use the overloaded `getFloor()` function which can use more specific values for certain fields. + +Here are the instructions: + +1) Inject `PriceFloorResolver` to your {bidder}Configuration class and pass it to your bidder constructor. + +```java +BidderDeps {bidder}BidderDeps(BidderConfigurationProperties {bidder}ConfigurationProperties, + @NotBlank @Value("${external-url}") String externalUrl, + PriceFloorResolver floorResolver, + JacksonMapper mapper) { + +... + +.bidderCreator(() -> new {bidder}Bidder(configProperties.getEndpoint(), floorResolver, mapper)) +``` + +2) Create an additional class variable `private final PriceFloorResolver floorResolver` and update constructor in your {bidder}Bidder class to set this variable. + +```java +private final PriceFloorResolver floorResolver; +private final String endpointUrl; +private final JacksonMapper mapper; + +public {bidder}Bidder(String endpointUrl, PriceFloorResolver floorResolver, JacksonMapper mapper) { + this.endpointUrl = HttpUtil.validateUrl(Objects.requireNonNull(endpointUrl)); + this.floorResolver = Objects.requireNonNull(floorResolver); + this.mapper = Objects.requireNonNull(mapper); + } +``` + +3) Use `floorResolver.resolve(BidRequest bidRequest, + PriceFloorRules floorRules, + Imp imp, + ImpMediaType mediaType, + Format format, + List warnings)` for resolving specific floor values in your {bidder}Bidder class. + +
    + Example: Updating bidFloor values. + +```java + private Imp makeImp(Imp imp, BidRequest bidRequest) { + final PriceFloorResult priceFloorResult = resolvePriceFloors( + bidRequest, + imp, // com.iab.openrtb.request.Imp + specificMediatype, // org.prebid.server.proto.openrtb.ext.request.ImpMediaType + specificFormat, // com.iab.openrtb.request.Format (size) + priceFloorsWarnings); + + return imp.toBuilder() + .bidfloor(ObjectUtil.getIfNotNull(priceFloorResult, PriceFloorResult::getFloorValue)) + .bidfloorcur(ObjectUtil.getIfNotNull(priceFloorResult, PriceFloorResult::getCurrency)) + .build(); + } + + private PriceFloorResult resolvePriceFloors(BidRequest bidRequest, + Imp imp, + ImpMediaType mediaType, + Format format, + List warnings) { + + return floorResolver.resolve( + bidRequest, + extractFloorRules(bidRequest), + imp, + mediaType, + format, + warnings); + } +``` +
    + +4) Let the Price Floors feature know about the floors you're using. To do that, enrich BidderBid with `priceFloorInfo` + +```java +private static BidderBid createBidderBid(Bid bid, Imp imp, BidType bidType, String currency) { + + return BidderBid.builder() + .bid(bid) + .type(bidType) + .bidCurrency(currency) + .priceFloorInfo(imp != null ? PriceFloorInfo.of(imp.getBidfloor(), imp.getBidfloorcur()) : null) + .build(); + } +``` +

    + ## Test Your Adapter This chapter will guide you through the creation of automated unit and integration tests to cover your bid adapter code. We use GitHub Action Workflows to ensure the code you submit passes validation. You can run the same validation locally with this command: @@ -770,25 +836,25 @@ Try to create models by using following methods specified to your case in your t ```java private static BidRequest givenBidRequest( - Function bidRequestCustomizer, - Function impCustomizer) { + UnaryOperator bidRequestCustomizer, + UnaryOperator impCustomizer) { return bidRequestCustomizer.apply(BidRequest.builder() .imp(singletonList(givenImp(impCustomizer)))) .build(); } - private static BidRequest givenBidRequest(Function impCustomizer) { + private static BidRequest givenBidRequest(UnaryOperator impCustomizer) { return givenBidRequest(identity(), impCustomizer); } - private static Imp givenImp(Function impCustomizer) { + private static Imp givenImp(UnaryOperator impCustomizer) { return impCustomizer.apply(Imp.builder() .ext(mapper.valueToTree(ExtPrebid.of(null, ExtImp{bidder}.of(param, secondParam))))) .build(); } - private static BidResponse givenBidResponse(Function bidCustomizer) { + private static BidResponse givenBidResponse(UnaryOperator bidCustomizer) { return BidResponse.builder() .seatbid(singletonList(SeatBid.builder().bid(singletonList(bidCustomizer.apply(Bid.builder()).build())) .build())) @@ -808,7 +874,6 @@ Go to `test-application.properties` file and add folowing properties ```yaml adapters.{bidder}.enabled=true adapters.{bidder}.endpoint=http://localhost:8090/{bidder}-exchange -adapters.{bidder}.pbs-enforces-gdpr=true adapters.{bidder}.usersync.url=//{bidder}-usersync ``` @@ -1094,8 +1159,6 @@ import io.restassured.response.Response; import org.json.JSONException; import org.junit.Test; import org.junit.runner.RunWith; -import org.skyscreamer.jsonassert.JSONAssert; -import org.skyscreamer.jsonassert.JSONCompareMode; import org.springframework.test.context.junit4.SpringRunner; import java.io.IOException; @@ -1105,7 +1168,6 @@ import static com.github.tomakehurst.wiremock.client.WireMock.equalTo; import static com.github.tomakehurst.wiremock.client.WireMock.equalToJson; import static com.github.tomakehurst.wiremock.client.WireMock.post; import static com.github.tomakehurst.wiremock.client.WireMock.urlPathEqualTo; -import static io.restassured.RestAssured.given; import static java.util.Collections.singletonList; @RunWith(SpringRunner.class) @@ -1115,8 +1177,6 @@ public class {bidder}Test extends IntegrationTest { public void openrtb2AuctionShouldRespondWithBidsFrom{bidder}() throws IOException, JSONException { // given WIRE_MOCK_RULE.stubFor(post(urlPathEqualTo("/{bidder}-exchange")) - .withHeader("Accept", equalTo("application/json")) - .withHeader("Content-Type", equalTo("application/json;charset=UTF-8")) .withRequestBody(equalToJson(jsonFrom("openrtb2/{bidder}/test-{bidder}-bid-request.json"))) .willReturn(aResponse().withBody(jsonFrom("openrtb2/{bidder}/test-{bidder}-bid-response.json")))); @@ -1126,22 +1186,11 @@ public class {bidder}Test extends IntegrationTest { .willReturn(aResponse().withBody(jsonFrom("openrtb2/{bidder}/test-cache-{bidder}-response.json")))); // when - final Response response = given(SPEC) - .header("Referer", "http://www.example.com") - .header("X-Forwarded-For", "193.168.244.1") - .header("User-Agent", "userAgent") - .header("Origin", "http://www.example.com") - // this uids cookie value stands for {"uids":{"{bidder}":"BTW-UID"}} - .cookie("uids", "eyJ1aWRzIjp7ImJldHdlZW4iOiJCVFctVUlEIn19") - .body(jsonFrom("openrtb2/{bidder}/test-auction-{bidder}-request.json")) - .post("/openrtb2/auction"); + final Response response = responseFor("openrtb2/{bidder}/test-auction-{bidder}-request.json", + Endpoint.OPENRTB2_AUCTION); // then - final String expectedAuctionResponse = openrtbAuctionResponseFrom( - "openrtb2/{bidder}/test-auction-{bidder}-response.json", - response, singletonList("{bidder}")); - - JSONAssert.assertEquals(expectedAuctionResponse, response.asString(), JSONCompareMode.NON_EXTENSIBLE); + assertJsonEquals("openrtb2/{bidder}/test-auction-{bidder}-response.json", response, singletonList("{bidder}")); } } @@ -1164,8 +1213,8 @@ The next time you use `/openrtb2/auction`, the OpenRTB request sent to your Bidd Human readable documentation for bid adapters is required in the separate [prebid.github.io](https://github.com/prebid/prebid.github.io) repository. We will not merge your bid adapter until you've at least opened a documentation PR and comment with a link to it. -1. If you already have a Prebid.js bid adapter, update your existing bidder file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/modules to add the `pbs: true` variable in the header section. If your Prebid Server bidding parameters are different from your Prebid.js parameters, please include the differences in this document for publishers to be aware. -1. If you don't have a Prebid.js bid adapter, create a new file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/modules using this template: +1. If you already have a Prebid.js bid adapter, update your existing bidder file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders to add the `pbs: true` variable in the header section. If your Prebid Server bidding parameters are different from your Prebid.js parameters, please include the differences in this document for publishers to be aware. +1. If you don't have a Prebid.js bid adapter, create a new file in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders using this template: ``` --- @@ -1182,11 +1231,15 @@ dchain_supported: true/false userId: media_types: banner, video, audio, native safeframes_ok: true/false -bidder_supports_deals: true/false +deals_supported: true/false +floors_supported: true/false +fpd_supported: true/false pbjs: true/false pbs: true/false pbs_app_supported: true/false prebid_member: true/false +multiformat_supported: will-bid-on-any, will-bid-on-one, will-not-bid +ortb_blocking_supported: true/partial/false --- ### Note: @@ -1212,7 +1265,10 @@ Notes on the metadata fields: - If you support adding a demand chain on the bid response, add `dchain_supported: true`. Default is false. - If your bidder doesn't work well with safeframed creatives, add `safeframes_ok: false`. This will alert publishers to not use safeframed creatives when creating the ad server entries for your bidder. No default. - If your bidder supports mobile apps, set `pbs_app_supported`: true. No default value. -- If your bidder supports deals, set `bidder_supports_deals: true`. No default value. +- If your bidder supports deals, set `deals_supported: true`. No default value. +- If your bidder supports floors, set `floors_supported: true`. No default value. +- If you support first party data, you must document what exactly is supported and then you may set `fpd_supported: true`. No default value. +- If you support any OpenRTB blocking parameters, you must document what exactly is supported and then you may set `ortb_blocking_supported` to ‘true’,’partial’, or ‘false’. No default value. In order to set ‘true’, you must support: bcat, badv, battr, and bapp. - If you're a member of Prebid.org, add `prebid_member: true`. Default is false. @@ -1226,8 +1282,8 @@ Notes on the metadata fields: - Adapter Code - `org/prebid/server/bidder/{bidder}/{bidder}Bidder.java` - `org/prebid/server/bidder/{bidder}/{bidder}BidderTest.java` (test directory) - - `org/prebid/server/it/{bidder}Test.java` (test directory) - Integration test files + - `org/prebid/server/it/{bidder}Test.java` (test directory) - `resources/org/prebid/server/it/openrtb2/{bidder}/test-auction-{bidder}-request.json` (test directory) - `resources/org/prebid/server/it/openrtb2/{bidder}/test-auction-{bidder}-response.json` (test directory) - `resources/org/prebid/server/it/openrtb2/{bidder}/test-{bidder}-bid-request.json` (test directory) diff --git a/prebid-server/developers/module-atags.md b/prebid-server/developers/module-atags.md new file mode 100644 index 0000000000..483e68af3d --- /dev/null +++ b/prebid-server/developers/module-atags.md @@ -0,0 +1,233 @@ +--- +layout: page_v2 +sidebarType: 5 +title: Prebid Server | Developers | Module Analytics Tags Conventions +sidebar_entry: /prebid-server/developers/add-a-module.html +--- + +# Prebid Server - Module Analytics Tags Conventions +{: .no_toc} + +* TOC +{:toc } + +## Overview + +Analytics Tags (aka ‘ATags’) are a log mechanism provided by PBS-core to allow modules +to inform analytics adapters about what happened in the request. +Use of the Analytics Tag structure is completely optional. It's meant +to be used when there are application or reporting reasons for sharing module results. +See the [Prebid Server module overview](/prebid-server/developers/add-a-module.html) for background information. + +This document defines a convention aimed at allowing module developers to create +consistent ATags that can be easily read by analytics adapters. + +![Prebid Server ATags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"} + +1. Modules may return a data structure containing ATags to PBS-Core. +2. PBS-Core adds any ATags to the 'invocation context' data structure. +3. Analytics modules have access to the invocation context. + +## Analytics Tag Conventions + +The general idea is that ATags are a list of module-specific "activities" that have these attributes: +- activity name: should be unique within the context of this module. e.g. 'enrich-request' +- an overall status +- an array of specific results within the activity +- within the results: + - status of each result + - scope of the result + - module-specific values for the result + +Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/ortb2-blocking.html): + +``` +[{ + // scenario: response from bidderA blocked on badv for imp=1 + activities: [{ + name: "enforce-blocking", + status: "success", // no errors from the module + results: [{ + status: "success-block", + values: { // these are module-specific details about the result + "attributes": ["badv"], + "adomain": ["bad.com"] + }, + appliedto: { + "bidder": "bidderA", + impids: ["1"] + } + },{ + status: "success-allow", + // no details needed when the response isn't blocked + appliedto: { + "bidder": "bidderA", + "impids": ["2","3","4"] + } + }] + }] +``` + +The following table contains the field conventions. + +{: .table .table-bordered .table-striped } +| ATag Attr | Required? | Description | Type | +|---+---+---+---| +| activities | yes | One or more activities carried out by the module. | array of objects | +| activities .name | yes | Name of the activity. Must be documented and unique within the module. | string | +| activities .status | yes | Did the module operate successfully? Values are "error" or "success". | string | +| activities. results | no | Service-dependent details for what the service actually did. | array of objects | +| activities. results. status | no | Detailed status for this specific action. Values: "error", "success-allow", "success-block", "success-modify" | string | +| activities. results. values | no | service-specific details | object | +| activities. results .appliedto | no | Which object(s) the service examined or modified. | object | +| activities. results. appliedto. impids | no | The service examined these specific impression objects or bid responses corresponding to imp objects | array of strings | +| activities. results. appliedto. bidders | no | The service examined these specific bidders within the request or response. | array of strings | +| activities. results. appliedto. bidder | no | The service examined this specific bidder (singular) within the request or response. | string | +| activities. results. appliedto. request | no | The service examined the entire openrtb request object. This is in case the module updated something not adunit-specific. | boolean | +| activities. results. appliedto. response | no | The service examined the entire openrtb response object. This is in case the module updated something not adunit-specific. | boolean | + + +## Designing Analytics Tags + +ATags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be +reported as a separate activity, or perhaps everything the module does is lumped +as one activity. + +Once the activities are defined, determine what reportable metric would be useful. Examples: + +- percentage of impressions enriched +- percentage of imps where a specific bidder was removed due to optimization +- A/B testing data +- percentage and value of bid responses that were rejected due to creative validations + +{: .alert.alert-info :} +**Case study:** for the ORTB2 Blocking module, the requirement was to be able +to report on what percentage of responses from each bidder were being thrown +away due to blocking rules. This could have been done by defining a separate 'activity' for each of the 4 types of enforcement, but it was decided +to just have one kind of activity ('enforce-blocking') and get the specific +details as part of the 'value'. There was no requirement to report on the +outbound part of what the module does, so no ATags are created for that part +of the functionality. + +Once you know what reports are desired, figure out which activity 'results' +are needed to generate those numbers. + +{: .alert.alert-info :} +For the ORTB2 Blocking module, the numbers needed are how often a given +bidder has a response compared to how often their responses are rejected. +So overall the block rate is: successBlock divided by (successBlock + successAllow). + +## Document the Analytics Tags Produced + +Be sure to detail the results in your module documentation so that analytics adapters are +aware of what they can look for. + +Let them know: +- which activities your module supports +- what kind of results to expect +- whether the results objects have module-specific `values` + +## Parsing the Invocation Context + +If you're an analytics adapter, you will be given the entire PBS 'invocation context', which contains a wealth of information about the auction. + +In short, to get analytics tags, you'll need to parse this data structure: + +- Loop through stages[] + - If the stage has relevant info, loop through outcomes[] + - Outcomes.entity is a label describing the contents + - Loop through groups[] + - Loop through invocationresults[] + - if `hookid.modulecode` is relevant for your analytics, grab `analyticstags` + +Here's an example of the data structured as JSON, though the details +of the actual object will differ in PBS-Java and PBS-Go. +``` + "stages": [ + { + "stage": "raw-auction-request", + "outcomes": [ + { + "entity": "bidrequest", + "executiontimemillis": 246, + "groups": [ + { + "executiontimemillis": 190, + "invocationresults": [ + { + "hookid": { + "modulecode": "MODULE1", + "hookimplcode": "HOOK_A" + }, + "executiontimemillis": 123, + "status": "success", + "action": "update", + "debugmessages": [ + "debug message" + ], + "analyticstags": { + "activities": [ + { + "name": "device-id", + "status": "success", + "results": [ + { + "status": "success", + "values": { + "some-field": "some-value" + }, + "appliedto": { + "impids": [ "impId1" ] + } + } + ] + } + ] + } + }, + { + "hookid": { + "modulecode": "MODULE1", + "hookimplcode": "HOOK_B" + }, + "status": "success", + "message": "inventory has no value", + "action": "reject" + } + ] + } + ] + } + ] + }, + { + "stage": "bidder-request", + "outcomes": [ + { + "entity": "pubmatic", // entity is biddercode for some stages + "executiontimemillis": 246, + "groups": [ + "invocationresults": { + "hookid": { ... } + "analyticstags": [{ + ... + ] + } + ] + }, + { + "entity": "adform", + "executiontimemillis": 246, + "groups": [...] + } + ] + } + ] +``` + +See the implementation guide for your platform for specific syntax. + +## Further Reading + +- [PBS Module Overview](/prebid-server/developers/add-a-module.html) +- [PBS Module Implementation](/prebid-server/developers/add-a-module.html) diff --git a/prebid-server/developers/pbs-cookie-sync.md b/prebid-server/developers/pbs-cookie-sync.md index 5469f89994..d806607537 100644 --- a/prebid-server/developers/pbs-cookie-sync.md +++ b/prebid-server/developers/pbs-cookie-sync.md @@ -50,47 +50,59 @@ POST https://prebid-server.example.com/cookie_sync 3) When it receives the response, Prebid.js loops through each element of `bidder_status[]`, dropping a pixel for each `bidder_status[].usersync.url`. -4) The bidder-specific endpoints read the users's cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html) +4) The bidder-specific endpoints read the users' cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html) -5) When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and will update the `uids` cookie if allowed. +5) When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and if allowed, update the `uids` cookie. ### Setting the uids cookie from AMP Cookie sync for AMP works in a way quite similar to Prebid.js. -1) The Prebid Server hosting company places a modified version of the `load-cookie` script onto a CDN. This script is part of the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative/blob/master/src/cookieSync.js) repo. - -Note that the only two values currently valid for 'endpoint' are 'appnexus' and 'rubicon' -- other host companies should update their copy to include their endpoint. +1) The Prebid Server hosting company places the [load-cookie.html](#manually-initiating-a-sync) file onto a CDN. This script is part of the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative/blob/master/src/cookieSync.js) repo. See [the AMP implementation guide](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for more information. -2) The publisher places the 'load-cookie' script into the page: +2) The publisher places the 'load-cookie' iframe into the page: ``` + src="https://PROVIDED_BY_HOSTCOMPANY/load-cookie.html?source=amp&endpoint=HOSTCOMPANY&max_sync_count=5"> ``` -Note: if the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`. +{: .alert.alert-info :} +If the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`. 3) At runtime, the `load-cookie` script just calls the Prebid Server /cookie_sync endpoint. The rest works the same as described for Prebid.js above. +### Cooperative Syncing + +Prebid Server supports a 'Cooperative Syncing' mode where all enabled bidders may be returned in a sync request even if they aren't on this particular page. This allows bidders to get their IDs in place for the next page where they are utilized. + +Cooperative syncing can be configured at the host level. See the doc for [PBS-Java](https://github.com/prebid/prebid-server-java/blob/master/docs/config-app.md) and [PBS-Go](https://github.com/prebid/prebid-server/blob/master/config/usersync.go). + +This is how to control the coop syncing behavior from Prebid.js: +``` +pbjs.setConfig({ + s2sConfig: { + ... + coopSync: true, + userSyncLimit: 5 + ... + } +``` ## Bidder Instructions for Building a Sync Endpoint -Building a sync endpoint is optional -- mobile-only bidders don't benefit from -ID syncing. But for browser-based bidding, ID syncing can help improve buyer bid rate. There are two main options a bidder can choose to support: +Building a sync endpoint is optional -- there is no benefit from ID syncing for mobile-only bidders. For browser-based bidding, ID syncing can help improve buyer bid rate. There are two main options a bidder can choose to support: - redirect: the client will drop an IMG tag into the page, then call the bidder's URL which needs to redirect to the Prebid Server /setuid endpoint. - iframe: the client will drop an IFRAME tag into the page, then call the bidder's URL which responds with HTML and Javascript that calls the Prebid Server /setuid endpoint at some point. -PBS-Java allows bidders to support both options. - Bidders must implement an endpoint under their domain which accepts an encoded URI for redirects. This URL should be able to accept privacy parameters: - gdpr: if 0, declares this request isn't in GDPR scope. If 1, declares it is in scope. Otherwise indeterminate. @@ -99,20 +111,24 @@ Bidders must implement an endpoint under their domain which accepts an encoded U The specific attributes can differ for your endpoint. For instance, you could choose to receive gdprConsent rather than gdpr_consent. -Here's an example that shows the privacy macros as coded into PBS-Go: +Here's an example that shows the privacy macros as configured in PBS-Go: ``` -GET some-bidder-domain.com/usersync-url?gdpr={%raw%}{{.GDPR}}&gdpr_consent={{.GDPRConsent}}&us_privacy={{.USPrivacy}}{%endraw%}&redirectUri=prebid-server.example.com%2Fsetuid%3Fbidder%3Dsomebidder%26uid%3DYOURMACRO +userSync: + redirect: + url: https://some-bidder-domain.com/usersync-url?gdpr={%raw%}{{.GDPR}}{%endraw%}&consent={%raw%}{{.GDPRConsent}}{%endraw%}&us_privacy={%raw%}{{.USPrivacy}}{%endraw%}&redirect={%raw%}{{.RedirectURL}}{%endraw%} + userMacro: YOURMACRO ``` + PBS-Java uses slightly different macros in the bidder config: ``` - usersync: - url: https://some-bidder-domain.com/usersync-url?gdpr={%raw%}{{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}{%endraw%}&redirectUri= - redirect-url: /setuid?bidder=acuityads&gdpr={{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}&uid=YOURMACRO +usersync: + url: https://some-bidder-domain.com/usersync-url?gdpr={%raw%}{{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}{%endraw%}&redirectUri= + redirect-url: /setuid?bidder=acuityads&gdpr={%raw%}{{gdpr}}{%endraw%}&gdpr_consent={%raw%}{{gdpr_consent}}{%endraw%}&us_privacy={%raw%}{{us_privacy}}{%endraw%}&uid=YOURMACRO ``` -In either case, the {%raw%}{{}}{%endraw%} macros are resolved by PBS. +In either case, the {%raw%}{{...}}{%endraw%} macros are resolved by PBS. -{: .alert.alert-info :} -Important: The "YOURMACRO" string here needs to be whatever your sync endpoint will recognize and resolve to the user's ID from your domain. Some examples of macros that bidders use: $UID, ${UID}, $$visitor_cookie$$, ${DI_USER_ID}, etc. Every bidder has their own value here. +{: .alert.alert-warning :} +The "YOURMACRO" string here needs to be whatever your sync endpoint will recognize and resolve to the user's ID from your domain. Some examples of macros that bidders use: $UID, ${UID}, $$visitor_cookie$$, ${DI_USER_ID}, etc. Every bidder has their own value here. Here's how this all comes together: @@ -124,6 +140,39 @@ Here's how this all comes together: Then the next time the client then calls `www.prebid-domain.com/openrtb2/auction`, the ID for `mybidder` will be available in the Cookie. Prebid Server will then stick this value into `request.user.buyeruid` in the OpenRTB request it sends to `mybidder`'s bid adapter. +## Manually initiating a sync + +Where Prebid.js isn't present, like in the AMP scenario, the call to /cookie_sync doesn't happen automatically. +If there are scenarios where Prebid.js isn't around to initiate the /cookie_sync call, publishers can choose to put an iframe on their page. +Here's how you could invoke it with an iframe: + +``` +