Impression Tracking

OpenRTB 2.3 FAQ

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

  • The ‘imptrackers’ attribute is a form of notification that MoPub uses to notify the DSP of a cleared impression. A cleared impression is one that has won during an auction and was successfully shown to the end-user. The ‘imptrackers’ method is much preferred over tracking pixels embedded into ad markup as it decreases latency, redirects, duplicates and discrepancies.

2. Is ‘imptrackers’ absolutely required?

  • Yes.

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

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

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

  • No.

5. How does ‘imptrackers’ work?

  • DSP populates ‘imptrackers’ field in bid response object.
  • Marketplace servers append ‘imptrackers’ field value of JSON bid response into a JavaScript array which contains additional MoPub impression trackers along with the ‘imptrackers’.
  • 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 ‘imptrackers’ directly (See #8 for more details on this step).

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

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

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

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

8. When will the ‘imptrackers’ fire?

  • ‘imptrackers’ 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 ‘imptrackers’ will fire.
      • Interstitials: MoPub pre-caches interstitials, so only when the assets have been retrieved AND the publisher has called displayInterstitialWebview(), will the ‘imptrackers’ fire.

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

  • MoPub’s billing system reports off of the impression tracker (‘imptrackers’) 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 DSPs 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 ‘imptrackers’?

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

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

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

12. What if we explicitly insert the auction ID value into ‘imptrackers’ 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 ‘imptrackers’ is called back to the DSP.
  • 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 ‘imptrackers’. Secondary motivation for this approach is that inserting a static value (the macro) into your ‘imptrackers’ 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 ‘imptrackers’?

  • 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.3?

  • No. MoPub doesn’t record nURL for 2.3 but inserting the ${AUCTION_ID} macro is still recommended for DSP 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 ‘imptrackers’. Additionally, impressions in the ad markup will fire on LOAD while ‘imptrackers’ 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 ‘imptrackers’ a HTTP GET or POST request?

  • GET request.

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

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

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

  • Occasional/stray duplicate network calls are an inherent part of the HTTP stack at scale.
  • It is the responsibility of the DSP to post-process all (de-duplicate) impression (‘imptrackers’) 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 DSP ‘imptrackers’) to be fired on SHOW only
  • ANY other pixels embedded in creative (e.g., tracker for a non ‘imptrackers’ integrated DSP, or other third-party trackers in the markup) will fire on “LOAD” and thus create discrepancy with our trackers or ‘imptrackers’.
  • 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 DSP 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 DSP 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 DSP 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.

Server-to-Server FAQ

  • What is nURL and why is it important?
    • The ‘nurl’ attribute is a form of win notification that MoPub uses to notify the S2S network of a cleared impression. A cleared impression is one that has won during an auction and was successfully shown to the end-user. The nURL method is much preferred over tracking pixels embedded into ad markup as it decreases latency, redirects, duplicates and discrepancies.
  • Is nURL absolutely required?
    • Yes.
  • What happens if we do not include nURL?
    • Your bid responses will be flagged as invalid and rejected from the auction.
  • How does nURL work?
    • S2S network populates ‘nurl’ field in bid response object.
    • Marketplace servers append ‘nurl’ field value of JSON bid response into a JavaScript array which contains additional MoPub impression trackers along with the nURL.
    • 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 nURL directly.
  • Does the nURL fire from the client device or MoPub’s exchange servers?
    • nURL fires from the client device, not from the exchange.
  • What are the benefits of firing the nURL from the client?
    • Firing nURL from the client device ensures atomicity with regard to:
      1. a successful ad render and
      2. impression notification.
    • In other words, firing nURL from the client ensures that we only notify the S2S network when the ad has successfully rendered.

1. When will the nURL fire?

  • nURL 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 nURL will fire.
      • Interstitials: MoPub pre-caches interstitials, so only when the assets have been retrieved AND the publisher has called displayInterstitialWebview(), will the nURL fire.

2. What other macros do we support in nURL?

  • N/A for S2S networks

3. What if we explicitly insert the auction ID value into nURL 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 nURL because the macro guarantees that MoPub will substitute the value correctly when the nURL is called back to the S2S network. 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 nURL. Secondary motivation for this approach is that inserting a static value (the macro) into your nURL would likely result in less processing overhead on your bidder’s part than the dynamic value insertion method.
  • N/A for S2S networks

4. Do you support dynamically serving of ad markup via nURL?

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

5. 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 nURL.

6. Is the nURL a HTTP GET or POST request?

  • GET request.

7. What parameters are included in nURL other than the substituted macros?

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

8. What happens if I receive duplicate nURL calls?

  • Occasional/stray duplicate network calls are an inherent part of the HTTP stack at scale. It is the responsibility of the S2S network to post-process all (de-duplicate) impression (nURL) 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 interstitials only.

9. What is pre-caching?

  • All publishers integrated with the MoPub SDK pre-caches interstitial 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 S2S network nURL) to be fired on SHOW only
  • ANY other pixels embedded in creative (e.g., tracker for a non nURL integrated S2S network, or other third-party trackers in the markup) will fire on “LOAD” and thus create discrepancy with our trackers or nURL.
  • Please note that not all interstitial 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 S2S network 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.
  • The S2S network impression tracker fires only on “SHOW” and the S2S is charged, 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 S2S network for

10. Why does MoPub pre-cache interstitials?

  • We pre-cache interstitials for better user-experience for the end user.
  • S2S networks who want to be notified of both auction wins + auction clears should integrate both a pixel in the markup and nURL.
    • Impression pixel in ad markup: (fires on LOAD), correlates to auction wins
    • nURL: fires on SHOW, correlates to auction clears/charged
  • Recommend 1+ hour for allowed window between auction and cleared impression (nURL)

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

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

Last updated October 10, 2018

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.

© 2018 MoPub Inc.