Orders Tab: Manage Line Items
Line items exist within the context of an order. So if you haven’t already created an order, refer to these instructions to create one first. You can then manage line items from the Orders tab. Use this document to:
Understand Line Items
Line items are how you manage your demand inventory. A line item contains the specifics of a demand opportunity; for example, the demand source, the ad format(s), and budgeting and targeting settings. The type of line item you create depends on the type of demand that will flow through the line item. Every line item must have exactly one demand source, and one or more ad units. The line item then has settings that specify targeting and budgeting, and start and end dates.
To create a line item, you must first create:
Note that Marketplace line items require Marketplace approval; and Network line items require you to have added a network in the Networks tab; and Private Marketplace line items require you to have the feature activated by your account team.
Create a Line Item
To create a new line item:
- Navigate to the Orders tab, click on the order to which you want to add a line item, and from its Order Details page, click New line item in the top right corner.
The order to which the line item belongs displays automatically if you entered this workflow from the Orders tab. Enter the line item name.
Select the line item type and priority.
- Type is the demand source the line item will run.
Priority is where the line item sits within an ad unit’s waterfall. Each line item type has a default priority that you can override at anytime.
However, note that the default priorities we suggest do have significance. Any line item of type ‘Marketplace’ or ‘Network’ is assigned a default priority of 12. This is done so that Marketplace bids can compete with your Network eCPMs for every impression. If you accept the default priority of 12 for your Network line items, but change the priority of a Marketplace line item to 10, for example, then the Marketplace bids will always win without consulting your ad networks’ offerings.
Complete the additional settings for your line item choice.
For Network line items only, select a Network from the drop list. For a Network to appear in this, it must already have been configured within the the Networks tab.
- Expand the Other options link to enter an allocation percentage and a refresh interval.
- Allocation percentage: Use this to limit the number of ad requests you send to the line item.
- Refresh interval: The refresh interval only applies to the banner ad format. This interval defines the time period in which an ad unit will self-refresh and make a request to MoPub for another ad. The minimum interval is 10 seconds. The value set here will override the value set within the ad unit. Click Next to go to the Ad Unit Targeting page.
In the Ad Unit Targeting page, select one or more ad units that this line item will target. At least one ad unit is required. You can start typing the name of an app or ad unit to locate a specific one. Or you can filter the list of ad units by platform or format. You can also select to see ad units that are already targeted or ones that are not. Click Next to go to the Audience Targeting page.
If you later return to the Apps tab and navigate to the Ad Unit Details page for the ad unit you targeted with this line item, this line item will appear in the ad unit’s waterfall. You can continue to review and update it from the Ad Unit Details page.
- Complete the Audience Targeting settings. Click Save.
Line Item Types
The first four line item types are all very similar, used for Direct-Sold and Promotional campaigns. The reason we have separated these into four different types is to facilitate different prioritization. In using these line item types, you act as both the publisher who displays the ad in your app, and as the advertiser who provides the ad to display. For this reason, all four of these line item types require you to provide your own creative, which you can do after you have entered your line item settings and clicked Save.
Guaranteed: A Guaranteed line item is typically a Direct-Sold buy with a provided creative or creative tags, targeting criteria, a set CPM for a certain number of impressions, and a start and end date. The demand used within this type of line item should fill 100% of the time. When you’ve created and saved this line item type, you will be asked to add a creative. Default priority: 6.
Non-guaranteed: A Non-guaranteed line item is typically used to traffic a campaign without a guaranteed number of impressions. Non-guaranteed line items are set by default to priority 12, and compete with your ad networks and with MoPub Marketplace as an ad source. When you’ve created and saved this line item type, you will be asked to add a creative. Default priority: 12.
Promotional: A Promotional line item is for your house ads; for example, for advertising one of your apps in another, for advertising the paid version of your app inside your free version; or for other functions such as a “rate this app” line item. When you’ve created and saved this line item type, you will be asked to add a creative. Default priority: 10.
Backfill Promotional: A Backfill line item is typically a promotional line item, such as house ads, that is only used when no other higher priority line item is available. When you’ve created and saved this line item type, you will be asked to add a creative. Default priority: 16, the lowest level.
Private Marketplace: Private Marketplace (PMP) line items represent a private auction with a specific buyer (DSP) and pre-negotiated terms. This type of line item is available for publishers with a managed account, who have had this feature activated by their account team.
Marketplace: This is one of two places to create a Marketplace line item. The first, and recommended, place is the Marketplace tab. There, all your MoPub ad units are listed, and you can turn on Marketplace for any of them by toggling the Enable switch. Doing so assigns a default priority of 12 to any Marketplace-enabled ad unit. Those ad units are then managed by the content filtering rules you apply to them in the Marketplace tab’s Settings sub-menu.
The second, less used, place to create a Marketplace line item is right here, in the New line item page. A Marketplace line item created here (where it defaults to priority 10, but you can assign it any priority) is typically used to set a Marketplace floor price for app users in a particular geography, or to prioritize Marketplace over network campaigns (network line items default to priority 12). Default priority: 10.
Note that Marketplace line items with a default priority other than 12 are not managed by the settings you assign in the Marketplace tab like their priority-12 counterparts, but must be managed in the Content blocking pages under your account settings.
Note: Before you can create a Marketplace line item, you must have Marketplace approval.
Network: A Network line item is used to traffic ad network campaigns, which are typically set to the same priority (priority 12) as the Marketplace campaigns. This way, MoPub Marketplace bids compete against the eCPMs of any of your ad network partners with an ad to show, and this competition drives up your revenue. Default priority: 12.
Note: Before you can create a Network line item, you must add a network in the Networks tab. Only ad networks added in the Networks tab appear in the drop list when you specify the network for your line item.
How Budgeting Works
Before you fill out your budget settings, here are some things you should know about budgeting:
Budget settings you enter in the Publisher UI are used by our budgeting service. For line items with budgets, we first check the budgeting service to confirm available budget for the line item at the time of the ad request. If there is no budget left for the line item, then the next demand source in your waterfall will have a chance to fill the impression.
When setting budget values, keep in mind that line item budgets are padded by 10% to ensure they do not underserve.
The budgeting system operates in Pacific Time (PST), while the MoPub UI displays data in Coordinated Universal Time (UTC). An impression served at 11 pm PST on 03/31/19 will be recorded (and shown in the UI) as an impression served at 6 am UTC on 04/01/19. Ad delivery and budgeting are set up entirely in PST in our UI. For daily budgets, the system resets each day at 12 am PST. It is only the reporting of the delivery (both in the UI and in scheduled reports) that translates into UTC.
You can use the MoPub UI to apply budgets to all line item types except Promotional and Backfill Promotional line items.
How Pacing Works
Budget = ‘Lifetime goal’ and Delivery Speed = ‘Spread evenly’
If you have entered a number of total impressions, then there is a daily/hourly target calculated at the launch of the campaign and assigned to each day, and hour within the day.
The formula is:
Hourly Pacing = Total Budget / Number of Hours in the Run Dates
MoPub does not recalculate or dynamically adjust pacing based on impressions delivered to date. The calculation is static; it is always equal to the budget at that point in time divided by the number of hours within the run dates. With this logic, if a line item has under-paced or over-paced, it will catch up to correct itself as soon as possible, instead of spreading the difference over the remaining days. This will result in a spike or drop in traffic until the number of impressions served is back in line with the daily budget total goal set at the beginning of the run dates.
Here are some common changes made to line items and their effect on budgeting:
If a budgeted line item under-delivers for one or several days, then MoPub will try to catch up to the budget goal you have set as soon as possible. This means that on subsequent days you may see a spike in delivery until the budgeted goal for that moment in time is met.
If a budgeted line item over-delivers for one or several days, then MoPub will stop serving impressions on subsequent days until the number of impressions served is back in line with the budget goal for that moment in time.
If the run date time is shortened, then you will see a spike in delivery immediately, and this will continue until the number of impressions served catches up to where it should be, based on the new hourly pacing calculations.
If the run date time is lengthened, then you will see a stop in delivery until the number of impressions served falls back into line with where it should be based on the new hourly pacing calculations.
Budget = ‘Daily goal’
If you have entered a number of impressions per day, then the budget resets each day at 12 am PST. If the line item over-delivers or under-delivers during the day, it will have no effect on the following days. The following days will continue to serve against the daily budget that was set at the beginning.
Line Item Budget and Schedule Settings
The settings you fill out may vary depending on the line item type you specified above.
Budget is the serving goal for the line item:
- Unlimited goal does not have a serving goal; serve as many impressions as available.
- Lifetime goal has a serving goal to be met across the entire run dates of the campaign. If Delivery speed is set to ‘Spread evenly’, then you must enter an End Date.
- Daily goal has a serving goal to be met each day for the duration of the run dates.
Read more about how pacing works to make an informed choice.
Minimum CPM is the lowest price that you’re willing to be paid per 1000 impression served from Marketplace.
Rate: only appears for certain line item types. It is the estimated CPM value used to prioritize the line item within your waterfall setup. This value is not communicated back to the network.
Delivery speed: appears only if you have set a lifetime or daily goal.
- As fast as possible: Impressions will serve without time-based throttling.
- Spread evenly: Impressions will be allocated evenly by hour throughout the entire run dates. Note that end date is required in order to spread evenly for a lifetime budget.
Read more about how pacing works to make an informed choice.
Schedule: Start date: The start date determines when the line item is eligible to serve impressions. Once the start date has been reached, certain fields will be locked down.
Schedule: End date: Depending on your budget type, an end date may be required.
Daypart targeting: Daypart targeting is used to set specific times and days of the week for your campaign to run. You can set up to 10 daypart combinations for each line item.
Frequency caps: Frequency caps limit the number of impressions that are shown to a particular user. You can add up to 10 frequency caps by minute, hour, day, and/or week. Frequency cap periods cannot exceed 3 weeks. For GDPR, frequency cap periods will be limited to 24 hours for non-consenting users.
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:
- The banner ad unit shows an ad from the frequency capped line item.
- The interstitial ad unit caches an ad from the frequency capped line item.
- The banner ad unit shows another ad from the frequency capped line item.
- The frequency cap is reached.
- The interstitial ad is shown to the user with the ad from the frequency capped line item.
- Number of impressions shown from the line item is 3 because the interstitial ad was cached before the frequency cap was reached.
- 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 frequency capping time intervals ranging from minutes to weeks. 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.
Marketplace visibility: Appears for Marketplace line items only. This value set to ‘blind’ will hide your app name during a Marketplace auction.
DSP: Appears for Private Marketplace line items only. Select a DSP from the drop list.
Buyer price: Appears for Private Marketplace line items only. This is the CPM sent in the Marketplace bid request. If the publisher price has already been entered, this value will be auto-calculated based on the revenue share.
Revenue share: Appears for Private Marketplace line items only. This is the percentage of the spend that goes to the publisher.
Publisher price: Appears for Private Marketplace line items only. This is the net CPM value you are willing to accept from the buyer. If the buyer price has already been entered, this value will be auto-calculated based on the revenue share.
Private data: Private data restricts data passed as keywords in the ad request by default.
Line Item Audience Targeting Settings
Countries: Target your line item to a specific set of countries. Use the type-ahead functionality to quickly add countries from the list, or use the X next to any country you’ve chosen to remove it. By default, when the list is empty, your line item targets all countries. Certain countries cause additional regional targeting options to display; if you select any of those, we recommend selecting the
Wi-Fi OnlyConnectivity setting for it.
You can also target a geographical selection by expressing what countries and regions you want to exclude (Geo targeting: ‘Exclude these locations’). Excluding specific states or regions from US/CAN does not inherit any county inclusion and will target a worldwide audience unless additional locations are added to the exclusion list.
Region targeting: Target your line item to specific regions within the countries you selected in the Countries field. The type-ahead field surfaces City, State or Province (for US and Canada–we recommend selecting the
Wi-Fi OnlyConnectivity setting for this), and Metro Area/DMA regions (for US only–we recommend selecting the
Wi-Fi OnlyConnectivity setting for this) for the countries you have selected. Removing a country from the Countries field removes the regions contained within it.
City targeting: Applying this to a line item makes it eligible to serve if the user’s IP address is located within a 50-mile radius of the targeted city. MoPub city targeting is available for most countries. If you can’t find the city you wish to target, please contact your MoPub team. Avoid contradictory logic; for example, setting ‘Specific regions’ to ‘California’ at the same time as setting ‘Cities’ to ‘New York, NY, US’ results in the line item’s ineligibility to serve anywhere.
ZIP Code targeting: Targeting ZIP codes is only available if your line item if set to target ‘United States’ in the Countries field. Zip code is not supported for any other countries. Removing ‘United States’ from the Countries field removes any previously selected ZIP codes. To target multiple ZIP codes; each ZIP code must be on its own line or separated by a whitespace. ZIP code targeting is only available for line items targeted to ‘Wi-Fi Only’ traffic. The zip code option becomes unavailable if you select carriers.
Connectivity: Carrier targeting is available for the US, Canada, and UK. Use this field to target your line item to deliver ads to specific carriers for the countries you selected in the Countries field. Use the type-ahead field to input carrier names. Removing a country from the Countries field removes the carriers choices for that country. Some Geo targeting options, such as State, Metro Area / DMA, and ZIP code, require Wi-Fi and become unavailable if you target carriers.
Device & OS targeting: Use this field to target your line item to specific operating systems, device types, and versions.
Advanced options: User targeting: Use this option to target users whose devices do or do not have specific applications installed. These must be apps that you own, and you must specify the correct iTunes URL or Android package name in the MoPub UI for both the app and the line for which you want to track conversions. In order to comply with GDPR, we continue to support app targeting for users who have provided consent in the European Economic Area, United Kingdom, and Switzerland. We will not have information about users’ apps for users who have not provided their consent.
Advanced options: Keyword targeting: Use this option to target users by interests or demographics through keywords. To comply with GDPR, if you are not on SDK version 5.0+, do not target interest or demographic keywords for the European Economic Area, United Kingdom, or Switzerland. Additionally, MoPub blocks interest and demographic keywords when a user in these regions has not given consent.
To add keyword targeting, follow these instructions to pass these keywords through the app in the MoPub SDK for iOS or Android. After completing the technical work on the backend, enter one group of keywords per line in the UI; their maximum length is 10K characters. To target multiple keywords, use AND. If you want to use the OR clause, separate the keywords by a new line. To negatively target a property, put a
-in front of the keyword. To target a set of values for one keyword, pass each value with the keyword individually. To negatively target a set of values for one keyword, use the
m_gender:m AND m_age:25
Negative targeting example:
Example of targeting a set of values for one keyword (this only matches line items that target all three values–apple, banana, orange):
fruit:apple AND fruit:banana AND fruit:orange
- Example of negatively targeting a set of values for one keyword (here we exclude a line item from being served when the ad request contains the keyword ‘fruit’ with the values set to ‘apple’, ‘bananas’, or ‘oranges’):
-fruit:apple AND -fruit:banana AND -fruit:oranges
Drill Into Line Item Details
Clicking on a line item from the Order Details page takes you to the Line Item Details page. Here, you can:
- Edit a line item by clicking Edit line item in the top right corner. There, you can edit the settings you filled out when first creating the line item.
- Copy a line item by clicking Edit line item in the top right corner and selecting Copy line item. A new line item will appear and you can edit its name and settings as necessary.
- Archive a line item by clicking Edit line item in the top right corner and selecting Archive line item. Archiving is a way to retire the line item without losing it forever. You can find an archived line item at any time and reinstate it.
- Disable or enable the line item by togging the Enabled switch in the top section.
- Update the line item’s Priority and Rate in the top section.
Last updated October 24, 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.)