PubGuru Key-Value Pairs (KVPs) Explained

At MonetizeMore, we use numerous key-value pairs (KVPs) to pass information for targeting and tracking in the ad stack.  Here’s what each KVP means:

  • m2_bidder: bidder code for the winner of the header bidding auction for that impression
  • m2_pb: top bid value of the winner of the header bidding auction for that impression.  PubGuru has international currency support, so the currency is whatever the publisher is using in DFP.
  • m2_size: size of the winner’s creative for the header bidding auction for that impression.
  • m2_config: represents the HB code version as well as the config name.  This allows us to compute performance of different versions of our HB code.
  • m2_bidder_list: for a tiny percentage of pageviews, we drop one bidder out of the auction.  This allows us to see the lift caused by each bidder.  Each character in this string corresponds to a bidder.  We’ve used this to find bidders who were just backfilling others, or slowing the auction to the point of lowering page RPM.
  • test1, test10, test50, test90: periodically, publishers want to test line items being eligible on only certain pageviews.  For each of these, they default to a value of “0”.  On 1% of pageviews, test1 = 1.  On 10% of pageviews, test10 = 1.  On 50% of pageviews, test50 = 1.  And on 90% of pageviews, test90 = 1.
  • m2_traffic: although we default to running header bidding on 100% of pageviews, we can disable header bidding on a percentage of pageviews.  This KVP tells you whether HB was enabled for that impression, and what percentage of pageviews it was enabled for.  So, for example, “hbon-50” means 50% of the pageviews for that segment had HB enabled, and for that particular impression, HB was enabled.
  • m2_overbid: by default, we set up HB line items to a bid cap of $20 USD or the foreign currency equivalent for publishers using other currencies in their DFP account.  Any bid over this cap is rounded down to the cap.  This is because DFP has both a lifetime line item cap and an active line item cap.  Irresponsibly creating line items can utterly destroy a DFP account, and because DFP accounts are bound to AdX and Adsense accounts, it destroy’s a publisher’s whole Google chain of accounts.  This is unquestionably bad.  Yet, some publishers have audiences where it may be beneficial to raise the bid cap beyond $20.  Since there is no lifetime KVP cap, we use m2_overbid to track bids which are coming in over the bid cap and being rounded down.  Publishers who see non-negligible bids above their cap will have their cap raised.
  • m2_timeout: this is a combo KVP used to track the time for the auction.  The KVP takes the following format: t#e#, or sometimes t#e#x#.  The number that follows the t is the base timeout that is set for the auction.  The number that follows the e is the actual elapsed time for the auction.  Sometimes this is shorter than the timeout (all bids back early and DFP was ready to fire impressions).   Sometimes this is longer than the timeout (usually from DFP not being ready).
  • m2_auction_extension: this combo KVP is used to track the parameters being tested for auction extension.  With auction extension, we check the publisher’s bid density and distribution for that pageview, and potentially extend the auction if it’s likely to be profitable to do so.
  • pageview: this is set to 1 for each new pageview.  To calculate the number of pageviews in which our technology actually ran, sum the total number of filled and unfilled impressions pageview=1.  This may be different from Google Analytics because GA is usually not adblocked whereas DFP is adblocked.  Ignore the revenue number.
  • session: this is similar to the pageview KVP except it tracks sessions instead.  To calculate the number of sessions in which our technology actually ran, sum the total number of filled and unfilled impressions where session=1.  Again, this can differ from GA because of adblock.
  • request_uri: some publishers wish to track the revenue by article.  The easiest method for publishers to do this is the request_uri revenue attribution.  This is everything after the domain name.  It’s important to note though that KVPs have a cap of 40 characters, so publishers with long URLs can have their request_uri values truncated.
  • session_depth: represents the pageview number in the user’s session.  Some publishers only want to enable certain demand partners in later pageviews in the session.
  • a9: PubGuru supports sideloading of Amazon A9’s header bidding technology.  A9 is not handled inside our wrapper, but we do sync the two timeouts between HB and A9 so that neither can end the auction early.  In this KVP, we track state of A9 at the time the impression fires.
  • google: Google as an advertising company requires publisher content to be brand safe and generally family friendly.  In order to accommodate this, we have a warning system that looks for and identifies controversial content.  The publisher can then set google=0, google=no, or google=off in order to disable all Google line items for that impression.
  • wrapper: typically used when a publisher has set up a 50/50 test between PubGuru and another wrapper.  As long as this is set to 50%, one can simply compare the total revenue between the two wrapper segments to see which has the higher page RPM.

Revenue Attribution KVPs

PubGuru Header Bidding also supports revenue attribution.  This is done through UTMs, and each UTM has a corresponding KVP: utm_source, utm_campaign, utm_content, utm_term, utm_medium.  Because DFP does not support reports on multiple KVPs, we also support combo KVPs:

  • utm_source_campaign: source and campaign separated by a colon
  • utm_scm: source, campaign, and medium, separated by colons

Third Party KVPs

Some of our ad partners also add KVPs in the ad stack.  These include:

  • amznbid: the bid hash for Amazon A9.
  • oxb, ox160x600, ox300x250, ox300x600, ox320x50, ox728x90, and similar: some implementations of OpenX’s bidder have used these KVPs.

Kean Graham

CEO and Founder at MonetizeMore

Kean is the resident expert in Ad Optimization covering areas like AdSense Optimization, DFP Management, and third-party ad network partnerships. Kean believes in the supremacy of direct publisher deals and holistic optimization as keys to effective and consistent ad revenue increases.

Get our latest ad optimization tips delivered to your inbox

Submit a Comment

Your email address will not be published. Required fields are marked *