Custom Network Best Practices

While JavaScript tags from Custom JavaScript Networks are supported through the MoPub UI, MoPub cautions usage of this functionality, and does not provide technical support for issues arising from network’s tags. We recommending using no more than 2 tags max, as there are adverse downstream effects of using this method.

Due to the complex nature of these integrations, and the lack of visibility that MoPub has in third party code developed by other networks, it is important to note some key reminders outlined below before implementing Custom JavaScript Networks via JavaScript tags.

While working with third party networks using the custom network integration, MoPub recommends that the publishers follow the best practices listed below to avoid any third party discrepancies.

Impression Counting

Networks counting impressions on “load/request” when the ad is not on screen can observe discrepancies in impressions.


To help minimize discrepancies, the correct cache-busting method should be included in JS tags. If you don’t see a placeholder to add in MoPub’s cache-busting macro, it’s important that you check with the network to find out how cache-busting is handled. Any impression pixel trafficked without a cache-busting method will result in discrepancies.

Click Tracking

If the HTML used for the ad is using an anchor tag <a href> or window.location redirect, the MoPub SDK automatically tracks clicks and fires upon first interaction. Review our documentation on correct click macro placement within your tags. Incorrect implementation or lack of implementation will result in discrepancies.

MRAID/Rich Media tags

HTML and MRAID should be split out into two different tags and trafficked to different creative tags when possible. Make sure the MRAID box is selected for the MRAID creative, otherwise MRAID may not serve properly. Scheduling MRAID tags in the Networks tab is currently not supported.

  • If the ad network must run both MRAID and HTML creative through the same JS tag then it must be setup as a creative within a line item and the MRAID box should be selected, otherwise MRAID may not serve properly.

  • Note that MRAID failover support has been updated on the SDK side. Please follow the list below to ensure that as a publisher your SDK version does support this functionality:


MRAID interstitials and banners, failover works [as of iOS SDK = 3.4]


MRAID banner: failover works [as of Android SDK = 3.5]

MRAID interstitial: failover works [as of Android SDK = 4.16]

Failover Tag

When the ad network experiences time-outs due to the lengthy creative load time or does not have an eligible ad to show (no fill), it should properly call MoPub’s failover tag. Proper implementation of the failover tag will ensure that our ad server can call the next item in the waterfall based on priority.

If the network is not able to implement it on their end, make sure to move the network to the end of your waterfall to avoid issues with fill rate and revenue loss for the ad unit.

The passback/failover tag is a MoPub SDK only feature and can only be used by Custom JavaScript Networks (JS tags).

MoPub failover tag should be called synchronously, before any other content. If not implemented properly, there have been known impression discrepancies and problems with the delivery of budgeted line items.

Synchronously: scripts are loaded sequentially, one after another, starting with the <head> tag

Asynchronously: some scripts can be loaded simultaneously; this implementation can result in MoPub to recognize the load as if it’s a full ad response and fire an impression pixel when there is no ad shown to the user.

MoPub Failover Tag

<script type="text/javascript" charset="utf-8"> loaded=true; window.location="mopub://failLoad"; </script>

The MoPub failover tag works as follows:

  1. When you traffic the MoPub failover tag as a response, it loads in the webview.

  2. The tag redirects the webview to the custom URI of mopub://failLoad

  3. The MoPub SDK has hooks that detect the mopub:// addresses, intercepts it, and using the parameter (failLoad) triggers a particular function. In this situation, the function is the failover function that says, “this ad source had no ad to show, you can fail over”

  4. Once the network lets MoPub know that there is “no fill” by calling our failover tag, same ad request moves down the waterfall after appending &fail=1 at the end of the ad request and by “exclude=” ing that specific adgroup/line item ID that was scheduled in the UI.

Due to the limitations explained above, it’s recommended that the publishers always place all JavaScript Custom JavaScript Networks as low in the waterfall as possible to avoid discrepancy issues with other supported demand sources.

Last updated May 18, 2020

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.

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