Impression Tracking

OpenRTB 2.5 FAQ

Important Note

For OpenRTB 2.5 MoPub will support ‘imptrackers’ and/or the ‘burl’ field in the bid response. Both fields will fire exactly the same and at least one is required. Additional details can be found in our OpenRTB 2.5 spec.

Please be advised that all MoPub Marketplace inventory requires fully secure creatives, as specified by the field. Further details on secure creative here.

1. What is ‘burl’ and ‘imptrackers’ and why is it important?

  • The ‘burl’ and ‘imptrackers’ attribute is a form of notification that MoPub uses to notify the bidder of a cleared impression. A cleared impression is one that has won during an auction and was successfully shown to the end-user. The ‘burl’ or ‘imptrackers’ method is much preferred over tracking pixels embedded into ad markup as it decreases latency, redirects, duplicates and discrepancies. The ‘burl’ field supports a single impression tracking URL while ‘imptrackers’ is an array that can support multiple impression tracking URLs.

2. Is ‘burl’ absolutely required?

  • Yes.

3. What happens if we do not include ‘burl’ or ‘imptrackers’?

  • Your bid responses will be flagged as invalid and rejected from the auction.

4. If ‘burl’ does not fire, will we be billed?

  • No.

5. How does ‘burl’ work?

  • Bidder populates the ‘burl’ field in bid response object.
  • Marketplace servers append ‘burl’ field value of JSON bid response into a JavaScript array which contains additional MoPub impression trackers along with the ‘burl’.
  • The JS array is inserted into the ad server payload passed down to the client device. Also included is a JS function trackImpressionHelper() which controls the firing of the JS array URLs by listening for the appropriate signal from the MoPub SDK.
  • The SDK will render all ad markup, call the MoPub-inserted trackImpressionHelper() function, which then calls all impression URLs in the impression array; one of which is the ‘burl’ directly (See #8 for more details on this step).

6. Does the ‘burl’ fire from the client device or MoPub’s exchange servers?

  • ‘burl’ fires from the client device, not from the exchange.

7. What are the benefits of firing the ‘burl’ from the client?

  • Firing ‘burl’ from the client device ensures atomicity with regard to:
    1. A successful ad render and
    2. Impression notification. In other words, firing ‘burl’ from the client ensures that we only notify the bidder when the ad has successfully rendered.

8. When will the ‘burl’ and ‘imptrackers’ fire?

  • ‘burl’ will fire when:
    1. all assets in the ad markup are successfully retrieved and
    2. the webview (actual ad slot) becomes visible to the user
      • Banners: Banner webviews are always visible, so when all assets are retrieved and rendered successfully, the ‘burl’ will fire.
      • Interstitials: MoPub pre-caches interstitials, so only when the assets have been retrieved AND the publisher has called displayInterstitialWebview(), will the ‘burl’ fire.

9. What macros must be included in ‘burl’?

  • MoPub’s billing system reports off of the impression tracker (‘burl’) using the ${AUCTION_ID} macro for Impressions and ${AUCTION_PRICE} macro for Spend. We also post-process all of our data (de-duplicate) based on the ${AUCTION_ID} macro to ensure that you are not charged for a duplicate impression in the rare case this should happen.
  • We require all bidders in our exchange to adhere to the same reporting logic for “impressions” and “spend” as MoPub auction mechanics.

10. What other macros do we support in ‘burl’?

  • Please see the “Substitution Macros” section in our RTB 2.5 spec

11. Can I use macros in the ad markup in addition to ‘burl’?

  • Short answer: Yes
  • Long answer: Only reporting based off of ‘burl’ will be considered for billing purposes. All impression trackers in the ad markup are only for the bidder’s purposes and will not be considered for reporting/billing data.

12. What if we explicitly insert the auction ID value into ‘burl’ ourselves, do I still have to include the ${AUCTION_ID} macro?

  • Short answer: No
  • Long answer: We strongly recommend using the ${AUCTION_ID} vs. explicitly inserting the value into ‘imptrackers’ because the macro guarantees that MoPub will substitute the value correctly when the ‘burl’ is called back to the bidder.
  • MoPub can not be responsible for any technical issues (or otherwise) impacting billing/reporting as a result of your bidder incorrectly inserting the ${AUCTION_ID} value into ‘burl’. Secondary motivation for this approach is that inserting a static value (the macro) into your ‘burl’ would likely result in less processing overhead on your bidder’s part than the dynamic value insertion method.

13. Do you support dynamically serving of ad markup via ‘burl’?

  • No. Ad markup must be returned in the bid response, at the time of auction.

14. Do you still need auction place macros for nURL on RTB 2.5?

  • No. MoPub doesn’t record nURL for 2.5 but inserting the ${AUCTION_ID} macro is still recommended for bidder tracking purposes.

15. Can we leave our 1×1 impression pixels in the ad markup anyway?

  • They can be in there; but to re-state, we will only consider, bill, and troubleshoot impression discrepancies that are based off of ‘burl’ or ‘imptrackers’. Additionally, impressions in the ad markup will fire on LOAD while ‘burl’ will fire on SHOW.
  • If you would like to be notified of a win notification, you can leverage the nurl (bid.nurl) or nurls array (bid.ext.nurls).
    • nurl
      • MoPub fires and forgets nurl with a 1 second timeout
      • If the server does not accept the request within that time limit then it is dropped.
      • Fired server-side

16. Is the ‘burl’ a HTTP GET or POST request?

  • GET request.

17. What parameters are included in ‘burl’ other than the substituted macros?

  • We do not insert/modify anything with regard to your ‘burl’. The structure, syntax, and information included in ‘burl’ are 100% dependent on what the bidder supplies when sending back a bid response.

18. What happens if I receive duplicate ‘burl’ calls?

  • Occasional/stray duplicate network calls are an inherent part of the HTTP stack at scale.
  • It is the responsibility of the bidder to post-process all (de-duplicate) impression (‘burl’) and click data. We also post-process all of our data (de-duplicate) based on the ${AUCTION_ID} macro to ensure that you are not charged for a duplicate impression, in the rare case this should happen.

The following questions apply to interstitial & native ad formats only.

19. What is pre-caching?

  • All publishers integrated with the MoPub SDK pre-caches interstitial and native ad requests. This means that there are two states:
    • “LOAD” – when the ad is loading/caching
    • “SHOW” – when the end user sees it
  • MoPub limits its impression trackers (including the bidder ‘burl’) to be fired on SHOW only
  • ANY other pixels embedded in creative (e.g., tracker for a non ‘burl’ integrated bidder, or other third-party trackers in the markup) will fire on “LOAD” and thus create discrepancy with our trackers or ‘burl’.
  • Please note that not all pre-cached ad format auctions that win & are loaded on the device will ultimately show and create a cleared impression.
    • “Cleared impression” is defined as one that is actually shown to the end-user and the metric a bidder is charged on.
    • A common use-case for this: the user may be playing a game when the interstitial is loaded in the background but quits out of the game before the interstitial is shown.
  • A bidder is charged only on “SHOW”, ie: only when the ad is displayed to the end user:
    • Auction win = They have won 2nd price auction, markup is sent to and loaded on the device
    • Auction clear = Ad Shown – this is the impression event and what we charge a bidder for

20. Why does MoPub pre-cache?

  • We pre-cache to create a better user-experience for the end user.

21. What are average latency times between “LOAD” and “SHOW” for these pre-cached ads?

  • Please contact your assigned account manager to request this information.

22. What if I want to append the Publisher ID or App ID into the imptracker?

  • You are welcome to append the Publisher ID or App ID into the imptracker. Please bear in mind that some IDs can be ‘Blind’ IDs, which may contain non-url-safe characters and should be url-encoded if included.

Last updated August 28, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)