Apps Tab: Manage Ad Units

Ad units exist within the context of an app. So if you haven’t already created an app, refer to these instructions to create one first. You can then manage ad units and their waterfalls from the Apps tab. Use this document to:

Understand Ad Units

Ad units are often referred to as placements because they define the place in your app where you want to show an ad. Examples include showing an ad at the end of a level in a game, or in the middle of a feed. Each ad unit accommodates one format. You can use an ad unit to show ads from the MoPub Marketplace (where auctions are held on your inventory), or you can have various demand sources fill an ad unit in a process called mediation.

There is a one-to-many relationship between apps and ad units. Every app must have at least one ad unit, but as you can see from our definition, most apps have many ad units to accommodate various placements and formats.

Create an Ad Unit

For any ad unit, setup within the Publisher UI is only the first half of the job. After you’ve created the ad unit within the UI, you’ll need to include the proper SDK code within your app to request and show the ad unit. We provide those instructions in our platform-specific SDK integration articles.

  1. To create an ad unit in the Publisher UI, navigate to the Apps tab, click on the app to which you’re adding an ad unit, and click New ad unit in the top right corner. The New ad unit page displays:

    New Ad Unit

  2. In the New ad unit page, enter a name for your ad unit.

  3. Selecting a format. Refer to the MoPub website to learn more about different ad formats. Refer to format unification to learn more about the simplified format selection. Specify the settings necessary for the ad format you have selected:

    • Banner ads usually appear at the top or bottom of your app’s screen and are supported in two standard sizes: Banner and Medium Rectangle.

      Specify your banner ad settings:

      • Set frequency caps (optional): When you create a banner ad unit, you can set optional frequency caps for hourly and daily impressions per user. Frequency caps limit the number of ads that can be shown on this impression. For instance, your strategy may be to limit the frequency of ads in a new app when you’re trying to drive engagement, or to show more ads of one format and fewer of another. Read more about frequency capping here.

      • Set refresh interval (required): You must set the refresh interval for your banner ad. The refresh interval is the number of seconds until the next ad unit displays. For example, if you set a refresh interval of 30 seconds, the next ad will display 30 seconds later. Typically, a refresh interval of 30 is optimal for most application and ad types.
        Set the refresh interval when you first create the ad unit. You can change it anytime by clicking Edit Ad Unit Settings in the ad unit page.
        We recommend that you turn refresh settings off on the side of any networks you are mediating; for instance, if you are mediating Facebook Audience Network in your waterfall, turn any refresh rate settings off on the FAN dashboard and control them here instead.

      • Advanced Options: Set a fallback size (optional): For banner format only, you can select a fallback size of either 320x50 (default) or 728x90. This option is an available helper if a publisher is on an SDK less than 5.8.0 or does not specify a size in the SDK on 5.8.0 or above.

    • A fullscreen ad occupies the entire screen and can be an interstitial or a rewarded ad. Fullscreen experiences commonly incorporate rich media and video to offer a higher level of interactivity compared to banner ads.

      New Fullscreen Ad Unit

      Specify your fullscreen ad settings:

      • Select a layout (required): Select portrait (vertical) or landscape (horizontal) layout for your fullscreen ad; the layout should match your app orientation.

      • Set frequency caps (optional): You can set optional frequency caps for hourly and daily impressions per user. Frequency caps limit the number of ads that can be shown on this impression. For instance, your strategy may be to limit the frequency of ads in a new app when you’re trying to drive engagement, or to show more ads of one format and fewer of another. Read more about frequency capping here.

    • Use the native format to create ads that match the look and feel of your app. If you are adding native ads inside of a content stream, you can use the native ads location control feature to specify where the ads appear in the stream.

      Displaying native ads requires:

      • MoPub SDK v.3.0 or higher, but we strongly recommend upgrading to our latest version.
      • The MPAdPlacer API described in the iOS and Android documentation.

      New Native Ad Unit

      Specify your native ad settings:

      • Enable or disable video: Select whether to enable or disable video ads in your native ad.

      • Set frequency caps (optional): You can set optional frequency caps for hourly and daily impressions per user. Frequency caps limit the number of ads that can be shown on this impression. For instance, your strategy may be to limit the frequency of ads in a new app when you’re trying to drive engagement, or to show more ads of one format and fewer of another. Read more about frequency capping here.

      • Set ad positions: The native ads positions settings specify where the ads appear in the stream. Use this setting to achieve an ideal balance between content and ads within your app without changing your app code or releasing a new version. Balance ads with content by setting the starting position for ads within your content stream and changing how often an ad appears. We recommend starting at position ‘3’ and repeating at an interval of ‘10’ positions.

        • Place ads in these positions: In the example settings shown above, your ads would appear in positions 1, 4, and 7. After position 7, your ads would appear every 5 positions, unless you uncheck the After placed ads, show ads every… option or specify a different interval.

        • After placed ads, show ads every… This setting is optional. The frequency control will begin counting after the last starting position that you enter. You cannot enter a frequency of ‘1’ because this would display ads in every position. Entering a frequency of ‘0’ would display the ad in the first spot in the feed, before your app content. ‘255’ is the last fixed position supported.

      If you have an iOS app that uses sections in its stream, you can define specific positions by using the following notation: [section].[position]. For example, 0.3. 255.

    • You can set up numerous kinds of currencies and reward your users using a server-side callback to your reward server. Upon the completion of a rewarded video, the MoPub SDK notifies the MoPub ad server of the completed video. The MoPub Ad Server notifies your callback endpoint. Your reward server then provides the reward to the user.

      Rewarded Video Process

      Specify your rewarded video settings:

      New Rewarded Video Ad Unit

      • Set frequency caps (optional): You can set optional frequency caps for hourly and daily impressions per user. Frequency caps limit the number of ads that can be shown on this impression. For instance, your strategy may be to limit the frequency of ads in a new app when you’re trying to drive engagement, or to show more ads of one format and fewer of another. Read more about frequency capping here.

      • Server-side callback URL: Enter your callback URL, followed by any macros you choose to use here.

        The callback URL is the endpoint that our MoPub ad server hits to notify you of a completed rewarded video viewing. Server-side callbacks are discussed in more detail below.

      • Specify rewards: Click Add a reward to specify a currency and an amount. You can define multiple currencies, as shown in the example below.

        Add Rewards

    Each of these ad formats enables you to enter an optional frequency cap.

    Frequency caps limit the number of ads that can be shown to an individual user. For example, if you only want a user to see one ad a day from a particular network, cap it at one daily impression; if you want your users to see only two interstitial ads per day, cap your interstitial ad unit to two daily impressions. You can apply frequency caps to ad units, line items, and network segments.

    Ads that have been cached on device before the frequency cap is met will still be displayed if the show() method is executed. This is because frequency capping is controlled by the MoPub ad server. When the frequency cap is reached, all subsequent ad requests will return no fill. Take for example a line item whose setup has a frequency cap of 2 impressions per day, and the ad units under that line item are banner and interstitial. Expect the following behavior for this example:

    1. The banner ad unit shows an ad from the frequency capped line item.
    2. The interstitial ad unit caches an ad from the frequency capped line item.
    3. The banner ad unit shows another ad from the frequency capped line item.
    4. The frequency cap is reached.
    5. The interstitial ad is shown to the user with the ad from the frequency capped line item.
    6. Number of impressions shown from the line item is 3 because the interstitial ad was cached before the frequency cap was reached.
    7. Future ad requests will skip this line item until the frequency threshold is reset.

    When a frequency cap has been reached, ad requests continue to be made for the line item, but always return no fill. Take this into consideration when monitoring the fill rate for the line item within MoPub. This does not affect external DSP or Network fill rate, because no attempts are made to the demand sources set for the line item once the frequency cap is reached.

    Time-wise, frequency capping is dictated by the device’s time setting. We support daily and hourly frequency capping time intervals. The day for frequency capping starts and ends at 12 am UTC. There is no notion of a rolling 24-hour window; the start and end times are static. Hourly frequency capping resets at the top of every hour. There is no concept of a rolling 60-minute window; the start and end times are static. For example:

    • 17:00 EST (22:00 UTC): User sees an ad that is frequency capped to 1 impression per day.
    • 22:00 EST (01:00 UTC): User sees the same ad again. This is allowed because the new day for frequency capping started at 19:00 EST.
    • 2:45 EST: User sees an ad from a line item that is frequency capped to 1 impression per hour.
    • 3:05 EST: User sees another ad from the same line item. This is allowed because the hour has changed from 2:00 to 3:00.

    The rewarded video format accommodates server-side callbacks.

    Callback macros dynamically populate the data you need to reward the user. For the most secure results, we strongly recommended that you use the %%CUSTOMER_ID%%, %%ID%%, and %%VERIFIER%% macros at minimum. The following table lists the available callback macros:

    Macro Format Description
    %%AD_REVENUE%% double Net revenue received by publisher for serving the ad
    %%ADUNITID%% string Ad unit ID
    %%ADVERTISING_ID%% string Advertising ID (IDFA/GAID) for the user’s device
    %%CURRENCY_TYPE%% string Currency type selected in the ad unit page in the reward section
    %%CURRENCY_VALUE%% integer Currency value entered in the ad unit page in the reward section
    %%CUSTOMER_ID%% string Strongly recommended, this is the customer or user ID supplied in the ad request
    %%ID%% string Strongly recommended, this is MoPub’s unique transaction ID
    %%PLACEMENTID%% string App ID
    %%TIMESTAMP%% long Time at which the reward was recorded on the MoPub server
    %%VERIFIER%% string Strongly recommended, this is a security token to verify that the request came from MoPub
    %%CUSTOM_DATA%% string Custom data string passed via the MoPub SDK. This can be a base64 encoded JSON object with application state
    %%CUSTOM_EVENT_CLASS_NAME%% string Custom Event Class name that uniquely identifies the demand source that provided the ad

    Here is an example of a server-side callback URL with macros:

    https://api.example.com/callback.php?customer_id=%%CUSTOMER_ID%%&id=%%ID%%&hash=%%VERIFIER%%&value=%%CURRENCY_VALUE%%&type=%%CURRENCY_TYPE%%

    Here is the callback after being populated with data from the MoPub ad server:

    https://api.example.com/callback.php?customer_id=3453523454&id=70bae1905f7844a3a012a5f4173021db&hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10&value=20&type=Coins

  4. Click Save. You will receive code integration instructions in the UI and by email. These instructions include an ad unit ID, which you will need to complete ad configuration within your app code. You can also select View code integration for an existing ad unit from the top right corner to learn its ad unit ID:

    View Code Integration

    Copy the ad unit ID:

    Code Integration

    Head over to your app’s code to configure the ad units using our SDK for Android, iOS, or Unity.

Drill Into Ad Unit Details

Clicking on any of the ad units listed takes you to the Ad Unit Details page, where you can examine all the demand sources defined for that ad unit.

Ad Unit Details

The Ad Unit Details page displays the same metrics you saw in the App Details page, but at the individual ad unit level. You can also review and manage the waterfall for the ad unit. In the Ad Unit Details page, you can:

  • Edit: Edit an existing ad unit by clicking Edit ad unit in the top right corner. This displays the information you filled out when first creating your new ad unit.
  • Delete: Delete an unwanted ad unit by clicking the drop menu in the top right corner, next to Edit ad unit.
  • Analyze: Analyze your ad units by the same metrics that you saw in the Apps page. You can filter your report by geos, ad source types, status, and priority. You can also adjust the time frame.
  • Export: Export your report to a file. The data exported will be for the date range you have specified on the page, and will include all the metrics you find on the page: date, requests, impressions, fill rate, clicks, and CTR.
  • Update: Edit the status (enabled/disabled), priority, and CPM for any of the ad unit’s ad sources.
  • Drill in: Click on any ad source to drill into its order details.

Manage Your Waterfall

Use the Apps tab to manage the waterfall for each ad unit.

(Note that while you manage your waterfall here, this is not where you first create it. To create a waterfall item for an ad unit, you must first create an order, and within it a line item mapped to this ad unit. After that, you can manage your ad unit’s waterfall here in the Apps tab’s Ad Unit Details page.)

Understand Waterfalls

A waterfall is a list of ad sources for each ad unit. When you’re ready to serve an ad, MoPub makes a call to the first ad source in your waterfall (the first ad source is the one with the highest priority and the highest CPM within that priority). If that ad source does not return an ad, MoPub calls the next item in your waterfall, and so on. A waterfall can consist of the following types of ad sources:

  • MoPub Marketplace: MoPub Marketplace fills your ad impressions by running a real-time auction, in which demand-side platform (DSPs) partners bid on your impressions. Set it up in the Marketplace tab.

  • Mediation networks: For many ad networks, you can integrate that ad network’s SDK with MoPub’s. MoPub can then direct ad requests to that SDK via mediation. Add mediation networks in the Networks tab.

  • Direct-sold ads: Ads that, as the publisher, you sell directly to your advertiser via the Orders tab. They are served from MoPub’s ad serving infrastructure.

For each ad unit, your waterfall can differ by ad sources, their priorities, and the CPMs you set. There are many considerations involved in creating the most profitable waterfall. Refer to our articles on waterfall latency and our recommendations for adding networks in the Networks tab.

Analyze Your Waterfall

  • Filter the waterfall: You can filter for single or multiple geos to view different waterfalls. All the data will update based on the geo-filters you have put in place. Both the charts and the data in the columns of the waterfall update based on the geos selected:

    • Single geo-filter: If you filter for one country (for example, US), you will see any ad source in the waterfall that includes US targeting. This means that you could see lines that target US/UK/RO, US only, ROW that includes the US, etc.

    • Multiselect geo-filter: If you geo-filter for multiple countries (for example, US and CA), you will see ad sources in the waterfall targeted to US OR CA or both US and CA. You could see lines targeted to US only, CA only, US and CA, US/CA/RO/UK, ROW that includes either US or CA, etc.

    • Exclude countries: You can use the Select all link to select all geos and unselect the few that you’d like to exclude.

    When you apply a geo-filter, the impression column changes to display X of Y impressions. This reflects your filter. For example, if a line item targets both US and CA, and you filter only for CA, the line item will display ‘10 of 50’ impressions under the Impression column, meaning that 10 of the 50 impressions come from CA.

  • Sort the waterfall: If you filter by priority, from highest to lowest, the secondary filter, rate, will also be sorted from highest to lowest.

Update Your Waterfall

  • Update the priority and eCPMs: The Ad Unit Details page gives you easy access to update priority and CPM rates instead of going to other tabs to update. However, you can also update your priority and eCPMs in the Segments tab, Marketplace tab, Line Item Details page, or the Order Details page. Wherever you make the changes, other pages will reflect your updates.

    If priority is not editable for certain waterfall items, it’s because the item is either a network segment CPM or Marketplace tab price floor, which are both fixed at priority 12. If you want to change those priorities, you can pause that row and create a new line item to adjust the priority in the Ad Unit Details page.

Last updated September 16, 2019

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.

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