MPStreamAdPlacer /2.4.0

@interface MPStreamAdPlacer : NSObject <MPMoPubAdPlacer>

The MPStreamAdPlacer class enables you to retrieve native ads from the MoPub ad server and place them into any custom UI component that represents a stream of content. It does not actually present or insert any ads on its own; you must provide a delegate conforming to the MPStreamAdPlacerDelegate protocol to handle ad insertions.

Important: If you are inserting ads into a UITableView or UICollectionView, first consider whether the UITableViewAdPlacer or UICollectionViewAdPlacer classes are sufficient for your use case before choosing to use this class.

Your app’s first responsibility when creating a stream ad placer is to communicate the state of your stream. Specifically, you must provide it with the count of the original content items in your stream using -setItemCount:forSection:, so that it can determine where and how many ads should appear. Additionally, you must also make sure to notify the ad placer of any insertions, deletions, or rearrangement of content items or sections.

Use the -loadAdsForAdUnitID: method to tell the stream ad placer to begin retrieving ads. In order to optimize performance, this call may not immediately result in the ad placer asking its delegate to insert any ads. Instead, the ad placer decides whether to insert ads by determining what content items are currently visible. This means that your delegate may be intermittently informed about new insertions, and is meant to minimize situations in which ads are requested for positions in the stream that have a low likelihood of visibility.

Your delegate should respond to insertion callbacks by updating your stream’s data source so that it knows to render an ad (rather than an original content item) at the given index path. Note that the implementation may vary depending on the design of your data source.

For rendering ads, use -renderAdAtIndexPath:inView: to populate a view with the contents of an ad.

Public Properties

NSArray/visibleIndexPaths /+2.4.0

  • Description: An array of NSIndexPath objects representing the positions of items that are currently visible on the screen. The stream ad placer uses the contents of this array to determine where ads should be inserted. It calculates an on-screen range and uses a small look-ahead to place ads where the user is likely to view them.

  • Declaration:

    @property (readwrite, strong, nonatomic) NSArray *visibleIndexPaths;
    
  • Parameters: None.

Public Methods

+/placerWithViewController:adPositioning:rendererConfigurations: /+2.4.0

  • Description: Creates and returns a new ad placer that can display ads in a stream.

  • Declaration:

    + (instancetype)placerWithViewController:(UIViewController *)controller
                               adPositioning:(MPAdPositioning *)positioning
                      rendererConfigurations:(NSArray *)rendererConfigurations;
    
  • Parameters:

    • controller: The view controller that should be used to present modal content.
    • positioning: The positioning object that specifies where ads should be shown in the stream.
    • rendererConfigurations: An array of MPNativeAdRendererConfiguration objects that control how the native ad is rendered. Pass in configurations that can render any ad type that may be displayed for the given ad unit.

-/setItemCount:forSection: /+2.4.0

  • Description: Lets the ad placer know of how many items are in a section. This allows the ad placer to place ads more effectively around its visible range.

  • Declaration:

    - (void)setItemCount:(NSUInteger)count forSection:(NSInteger)section;
    
  • Parameters:

    • count: How many items are in the section.
    • section: The section that the ad placer is recording the count for.

-/renderAdAtIndexPath:inView: /+2.4.0

  • Description: Uses the corresponding rendering class to render content in the view.

  • Declaration:

    - (void)renderAdAtIndexPath:(NSIndexPath *)indexPath inView:(UIView *)view;
    
  • Parameters:

    • indexPath: The index path of the cell you want to render.
    • view: The view you want to render your contents into.

-/sizeForAdAtIndexPath:withMaximumWidth: /+2.4.0

  • Description: Get the size of the ad at the index path.

  • Declaration:

    - (CGSize)sizeForAdAtIndexPath:(NSIndexPath *)indexPath
                withMaximumWidth:(CGFloat)maxWidth;
    
  • Parameters:

    • indexPath: Retrieve the size at indexPath.
    • maxWidth: The maximum acceptable width for the view.

-/loadAdsForAdUnitID: /+2.4.0

  • Description: Requests ads from the MoPub ad server using the specified ad unit ID.

  • Declaration:

    - (void)loadAdsForAdUnitID:(NSString *)adUnitID;
    
  • Parameters:

    • adUnitID: A string representing a MoPub ad unit ID.

-/loadAdsForAdUnitID:targeting: /+2.4.0

  • Description: Requests ads from the MoPub ad server using the specified ad unit ID and targeting parameters.

  • Declaration:

    - (void)loadAdsForAdUnitID:(NSString *)adUnitID
                   targeting:(MPNativeAdRequestTargeting *)targeting;
    
  • Parameters:

    • adUnitID: A string representing a MoPub ad unit ID.
    • targeting: An object containing targeting information, such as geolocation data.

-/isAdAtIndexPath: /+2.4.0

  • Description: Returns whether an ad is ready to be displayed at the indexPath.

  • Declaration:

    - (BOOL)isAdAtIndexPath:(NSIndexPath *)indexPath;
    
  • Parameters:

    • indexPath: The index path to examine for ad readiness.

-/adjustedNumberOfItems:inSection: /+2.4.0

  • Description: Returns the number of items in the given section of the stream, including any ads that have been inserted.

  • Declaration:

    - (NSUInteger)adjustedNumberOfItems:(NSUInteger)numberOfItems
                            inSection:(NSUInteger)section;
    
  • Parameters:

    • numberOfItems: The number of content items.
    • section: The whose adjusted number of items the method will retrieve.

-/adjustedIndexPathForOriginalIndexPath: /+2.4.0

  • Description: Returns the index path representing the location of an item after accounting for ads that have been inserted into the stream.

  • Declaration:

    - (NSIndexPath *)adjustedIndexPathForOriginalIndexPath:(NSIndexPath *)indexPath;
    
  • Parameters:

    • indexPath: An index path object identifying the original location of a content item, before any ads have been inserted into the stream.

-/originalIndexPathForAdjustedIndexPath: /+2.4.0

  • Description: Asks for the original position of a content item, given its position in the stream after ads have been inserted. If the specified index path does not identify a content item, and instead, an ad, this method will return nil.

  • Declaration:

    - (NSIndexPath *)originalIndexPathForAdjustedIndexPath:(NSIndexPath *)indexPath;
    
  • Parameters:

    • indexPath: An index path object identifying an item in the stream, after ads have been inserted.

-/adjustedIndexPathsForOriginalIndexPaths: /+2.4.0

  • Description: Returns the index paths representing the locations of items after accounting for ads that have been inserted into the stream.

  • Declaration:

    - (NSArray *)adjustedIndexPathsForOriginalIndexPaths:(NSArray *)indexPaths;
    
  • Parameters:

    • indexPaths: An array of index path objects each identifying the original location of a content item, before any ads have been inserted into the stream.

-/originalIndexPathsForAdjustedIndexPaths: /+2.4.0

  • Description: Retrieves the original positions of content items, given their positions in the stream after ads have been inserted. If a specified index path does not identify a content item, and instead, an ad, it will not be included in the result.

  • Declaration:

    - (NSArray *)originalIndexPathsForAdjustedIndexPaths:(NSArray *)indexPaths;
    
  • Parameters:

    • indexPaths: An array of index path objects each identifying an item in the stream, after ads have been inserted.

Notifying the Ad Placer of Content Updates

-/insertItemsAtIndexPaths: /+2.4.0

  • Description: Tells the ad placer that content items have been inserted at the specified index paths. This method allows the ad placer to adjust its ad positions correctly.

  • Declaration:

    - (void)insertItemsAtIndexPaths:(NSArray *)originalIndexPaths;
    
  • Parameters:

    • originalIndexPaths: An array of NSIndexPath objects that identify positions where content has been inserted.

-/deleteItemsAtIndexPaths: /+2.4.0

  • Description: Tells the ad placer that content items have been deleted at the specified index paths. This method allows the ad placer to adjust its ad positions correctly, and remove from the stream if necessary.

  • Declaration:

    - (void)deleteItemsAtIndexPaths:(NSArray *)originalIndexPaths;
    
  • Parameters:

    • originalIndexPaths: An array of NSIndexPath objects that identify positions where content has been deleted.

-/moveItemAtIndexPath:toIndexPath: /+2.4.0

  • Description: Tells the ad placer that a content item has moved from one index path to another. This method allows the ad placer to adjust its ad positions correctly.

  • Declaration:

    - (void)moveItemAtIndexPath:(NSIndexPath *)fromIndexPath
                  toIndexPath:(NSIndexPath *)toIndexPath;
    
  • Parameters:

    • fromIndexPath: The index path identifying the original location of the item.
    • toIndexPath: The destination index path for the item.

-/insertSections: /+2.4.0

  • Description: Tells the ad placer that sections have been inserted at the specified indices. This method allows the ad placer to adjust its ad positions correctly.

  • Declaration:

    - (void)insertSections:(NSIndexSet *)sections;
    
  • Parameters:

    • sections: An NSIndexSet that identifies the positions where sections have been inserted.

-/deleteSections: /+2.4.0

  • Description: Tells the ad placer that sections have been deleted at the specified indices. This method allows the ad placer to adjust its ad positions correctly.

  • Declaration:

    - (void)deleteSections:(NSIndexSet *)sections;
    
  • Parameters:

    • sections: An NSIndexSet that identifies the positions where sections have been deleted.

-/moveSection:toSection: /+2.4.0

  • Description: Tells the ad placer that a section has moved from one index to another. This method allows the ad placer to adjust its ad positions correctly.

  • Declaration:

    - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection;
    
  • Parameters:

    • section: The index identifying the original location of the section.
    • newSection: The destination index for the section.

Last updated May 06, 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.)