Custom Network Best Practices

Although we support JavaScript tags from custom JavaScript networks through the MoPub UI, we discourage using this functionality. MoPub does not provide technical support for problems arising from a custom network’s tags. We recommend using a maximum of two tags, to minimize the adverse downstream effects of using this method.

MoPub has no visibility into third-party code developed by other networks. Implementing custom JavaScript networks via JavaScript tags is therefore a complex integration. When you work with third-party networks using the custom network integration, we strongly recommend following the best practices listed below to avoid any third-party discrepancies.

Impression Counting

Networks that count impressions on “load/request” when the ad is not on screen may observe discrepancies in impressions.


To help minimize discrepancies, include the correct cache-busting method 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 learn 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 about correct click macro placement within your tags. Incorrect implementation or lack of implementation will result in discrepancies.

MRAID or Rich Media tags

Separate JavaScript Tags

Split HTML and MRAID into two different tags and traffic them to different creative tags when possible. If the ad network must run both MRAID and HTML creative through the same JS tag, then it must be set up as a creative within a line item, and the MRAID option must be selected; otherwise MRAID may not serve properly.

We do not currently support scheduling MRAID tags in the Networks tab.

Synchronous and Asynchronous Tags

Generally, a tag is considered synchronous if the network decision to show an ad or fail over occurs before the webview’s window.onload event. If it occurs afterward, it is asynchronous.

  • HTML: Both synchronous and asynchronous HTML JavaScript tags are supported.

  • MRAID: Only synchronous MRAID JavaScript tags are supported.

Make sure the MRAID option is selected for the MRAID creative only when the network decision to show an ad or fail over happens synchronously; otherwise MRAID may not serve properly.

MRAID Failover Support in MoPub SDK

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

  • iOS:
    • MRAID interstitials and banners: failover works as of iOS SDK v3.4+
  • Android:
    • MRAID banner: failover works as of Android SDK v3.5+
    • MRAID interstitial: failover works as of Android SDK v4.16+

MoPub Failover Tag

The passback or failover tag is a MoPub SDK-only feature and can only be used by Custom JavaScript Networks (JS tags). When the ad network experiences time-outs caused by an extensive creative load time, or does not have an eligible ad to show (no fill), it must properly call MoPub’s failover tag. Proper implementation of the failover tag ensures that our ad server can call the next item in the waterfall based on priority.

If the ad network cannot implement the failover tag on their end, move the network to the end of your waterfall to avoid issues with fill rate and revenue loss for the ad unit.

Call the MoPub failover tag synchronously, before any other content. When the failover tag is not implemented properly, impression discrepancies and problems with the delivery of budgeted line items have been reported.

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

  • Asynchronously: Some scripts can be loaded simultaneously; this implementation can cause MoPub to erroneously identify the load as a full ad response, and fire an impression pixel when there is no ad shown to the user.

How the Failover Tag Works

<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 tells MoPub that there is “no fill” by calling our failover tag, the same ad request moves down the waterfall after appending &fail=1 at the end of the ad request and by excluding (exclude=) that specific adgroup or line item ID that was scheduled in the UI.

Because of the limitations explained above, we recommend that publishers always place all JavaScript Custom JavaScript Networks as low as possible in their waterfall to avoid discrepancy problems with other supported demand sources.

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.)