com.mopub.nativeads

Class MoPubStreamAdPlacer

java.lang.Object

com.mopub.nativeads.MoPubStreamAdPlacer

public class MoPubStreamAdPlacer
extends java.lang.Object

MoPubStreamAdPlacer facilitates loading ads and placing them into a content stream. If you are inserting ads into a ListView, we recommend that you use a MoPubAdAdapter instead of this class. To start loading ads, call loadAds(java.lang.String). We recommend passing targeting information to increase the chance that you show ads that are relevant to your users. This class is not intended to be used by multiple threads. All calls should be made from the main UI thread.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONTENT_VIEW_TYPE Constant representing that the view type for a given position is a regular content item instead of an ad.

Constructor Summary

Constructors

Constructor and Description
MoPubStreamAdPlacer(android.app.Activity activity) Creates a new MoPubStreamAdPlacer object.
MoPubStreamAdPlacer(android.app.Activity activity, MoPubNativeAdPositioning.MoPubClientPositioning adPositioning) Creates a new MoPubStreamAdPlacer object, using client positioning.
MoPubStreamAdPlacer(android.app.Activity activity, MoPubNativeAdPositioning.MoPubServerPositioning adPositioning) Creates a new MoPubStreamAdPlacer object, using server positioning.

Method Summary

Methods

Modifier and Type	Method and Description
void	bindAdView(NativeAd nativeAd, android.view.View adView) Given an ad and a view, attaches the ad data to the view and prepares the ad for display.
void	clearAds() Stops loading ads, immediately clearing any ads currently in the stream.
void	destroy() Destroys the ad placer, preventing it from future use.
java.lang.Object	getAdData(int position) Returns an ad data object, or null if there is no ad at this position.
int	getAdjustedCount(int originalCount) Returns the number of items considering ads in the stream.
int	getAdjustedPosition(int originalPosition) Returns the position of an item considering ads in the stream.
MoPubAdRenderer	getAdRendererForViewType(int viewType)
android.view.View	getAdView(int position, android.view.View convertView, android.view.ViewGroup parent) Gets the ad at the given position, or null if there is no ad at the given position.
int	getAdViewType(int position) The ad view type for this position.
int	getAdViewTypeCount() Returns the number of ad view types that can be placed by this ad placer.
int	getOriginalCount(int count) Returns the original number of items considering ads in the stream.
int	getOriginalPosition(int position) Returns the original position of an item considering ads in the stream.
void	insertItem(int originalPosition) Inserts a content row at the given position, adjusting ad positions accordingly.
boolean	isAd(int position) Whether the given position is an ad.
void	loadAds(java.lang.String adUnitId) Start loading ads from the MoPub server.
void	loadAds(java.lang.String adUnitId, RequestParameters requestParameters) Start loading ads from the MoPub server, using the given request targeting information.
void	moveItem(int originalPosition, int newPosition) Moves the content row at the given position adjusting ad positions accordingly.
void	placeAdsInRange(int startPosition, int endPosition) Inserts ads that should appear in the given range.
void	registerAdRenderer(MoPubAdRenderer adRenderer) Registers an ad renderer for rendering a specific native ad format in your stream.
int	removeAdsInRange(int originalStartPosition, int originalEndPosition) Removes ads in the given range from [originalStartPosition, originalEndPosition).
void	removeItem(int originalPosition) Removes the content row at the given position, adjusting ad positions accordingly.
void	setAdLoadedListener(MoPubNativeAdLoadedListener listener) Sets a listener that will be called after the SDK loads new ads from the server and places them into your stream.
void	setItemCount(int originalCount) Sets the original number of items in your stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONTENT_VIEW_TYPE

public static final int CONTENT_VIEW_TYPE

Constant representing that the view type for a given position is a regular content item instead of an ad.

See Also:

Constant Field Values

Constructor Detail

MoPubStreamAdPlacer

public MoPubStreamAdPlacer(android.app.Activity activity)

Creates a new MoPubStreamAdPlacer object. By default, the StreamAdPlacer will contact the server to determine ad positions. If you wish to hard-code positions in your app, see MoPubStreamAdPlacer(Context, MoPubClientPositioning).

Parameters:

activity - The activity.

MoPubStreamAdPlacer

public MoPubStreamAdPlacer(android.app.Activity activity,
                   MoPubNativeAdPositioning.MoPubServerPositioning adPositioning)

Creates a new MoPubStreamAdPlacer object, using server positioning.

Parameters:

activity - The activity.

adPositioning - A positioning object for specifying where ads will be placed in your stream. See MoPubNativeAdPositioning.serverPositioning().

MoPubStreamAdPlacer

public MoPubStreamAdPlacer(android.app.Activity activity,
                   MoPubNativeAdPositioning.MoPubClientPositioning adPositioning)

Creates a new MoPubStreamAdPlacer object, using client positioning.

Parameters:

activity - The activity.

adPositioning - A positioning object for specifying where ads will be placed in your stream. See MoPubNativeAdPositioning.clientPositioning().

Method Detail

registerAdRenderer

public void registerAdRenderer(MoPubAdRenderer adRenderer)

Registers an ad renderer for rendering a specific native ad format in your stream. Note that if multiple ad renderers support a specific native ad format, the first one registered will be used. This renderer will automatically create and render your view when you call getAdView(int, android.view.View, android.view.ViewGroup).

Parameters:

adRenderer - The ad renderer.

getAdRendererForViewType

public MoPubAdRenderer getAdRendererForViewType(int viewType)

setAdLoadedListener

public void setAdLoadedListener(MoPubNativeAdLoadedListener listener)

Sets a listener that will be called after the SDK loads new ads from the server and places them into your stream. The listener will be active between when you call loadAds(java.lang.String) and when you call destroy(). You can also set the listener to null to remove the listener. Note that there is not a one to one correspondence between calls to loadAds(java.lang.String) and this listener. The SDK will call the listener every time an ad loads.

Parameters:

listener - The listener.

loadAds

public void loadAds(java.lang.String adUnitId)

Start loading ads from the MoPub server. We recommend using loadAds(String, RequestParameters) instead of this method, in order to pass targeting information to the server.

Parameters:

adUnitId - The ad unit ID to use when loading ads.

loadAds

public void loadAds(java.lang.String adUnitId,
           RequestParameters requestParameters)

Start loading ads from the MoPub server, using the given request targeting information. When loading ads, MoPubNativeAdLoadedListener.onAdLoaded(int) will be called for each ad that is added to the stream. To refresh ads in your stream, call loadAds again. When new ads load, they will replace the current ads in your stream. If you are using MoPubNativeAdLoadedListener you will see a call to onAdRemoved for each of the old ads, followed by a calls to onAdLoaded.

Parameters:

adUnitId - The ad unit ID to use when loading ads.

requestParameters - Targeting information to pass to the ad server.

placeAdsInRange

public void placeAdsInRange(int startPosition,
                   int endPosition)

Inserts ads that should appear in the given range. By default, the ad placer will place ads withing the first 10 positions in your stream, according to the positions you've specified. You can use this method as your user scrolls through your stream to place ads into the currently visible range. This method takes advantage of a short-lived in memory ad cache, and will immediately place any ads from the cache. If there are no ads in the cache, this method will load additional ads from the server and place them once they are loaded. If you call placeAdsInRange again before ads are retrieved from the server, the new ads will show in the new positions rather than the old positions. You can pass any integer as a startPosition and endPosition for the range, including negative numbers or numbers greater than the current stream item count. The ad placer will only place ads between 0 and item count.

Parameters:

startPosition - The start of the range in which to place ads, inclusive.

endPosition - The end of the range in which to place ads, exclusive.

isAd

public boolean isAd(int position)

Whether the given position is an ad. This will return true only if there is an ad loaded for this position. You can listen for ads to load using MoPubNativeAdLoadedListener.onAdLoaded(int).

Parameters:

position - The position to check for an ad, expressed in terms of the position in the stream including ads.

Returns:

Whether there is an ad at the given position.

clearAds

public void clearAds()

Stops loading ads, immediately clearing any ads currently in the stream. This method also stops ads from loading as the user moves through the stream. If you want to just remove ads but want to continue loading them, call removeAdsInRange(int, int). When ads are cleared, MoPubNativeAdLoadedListener.onAdRemoved(int) will be called for each ad that is removed from the stream.

destroy

public void destroy()

Destroys the ad placer, preventing it from future use. You must call this method before the hosting activity for this class is destroyed in order to avoid a memory leak. Typically you should destroy the adapter in the life-cycle method that is counterpoint to the method you used to create the adapter. For example, if you created the adapter in Fragment#onCreateView you should destroy it in {code Fragment#onDestroyView}.

getAdData

public java.lang.Object getAdData(int position)

Returns an ad data object, or null if there is no ad at this position. This method is useful when implementing your own Adapter using MoPubStreamAdPlacer. To avoid worrying about view type, consider using MoPubAdAdapter instead of this class.

Parameters:

position - The position where to place an ad.

Returns:

An object representing ad data.

getAdView

public android.view.View getAdView(int position,
                          android.view.View convertView,
                          android.view.ViewGroup parent)

Gets the ad at the given position, or null if there is no ad at the given position. This method will attempt to reuse the convertView if it is not null, and will otherwise create it. See MoPubAdRenderer.createAdView(Context, ViewGroup).

Parameters:

position - The position to place an ad into.

convertView - A recycled view into which to render data, or null.

parent - The parent that the view will eventually be attached to.

Returns:

The newly placed ad view.

bindAdView

public void bindAdView(NativeAd nativeAd,
              android.view.View adView)

Given an ad and a view, attaches the ad data to the view and prepares the ad for display.

Parameters:

nativeAd - the ad to bind.

adView - the view to bind it to.

removeAdsInRange

public int removeAdsInRange(int originalStartPosition,
                   int originalEndPosition)

Removes ads in the given range from [originalStartPosition, originalEndPosition).

Parameters:

originalStartPosition - The start position to clear (inclusive), expressed as the original content position before ads were inserted.

originalEndPosition - The position after end position to clear (exclusive), expressed as the original content position before ads were inserted.

Returns:

The number of ads removed.

getAdViewTypeCount

public int getAdViewTypeCount()

Returns the number of ad view types that can be placed by this ad placer. The number of possible ad view types is currently 1, but this is subject to change in future SDK versions.

Returns:

The number of ad view types.

See Also:

getAdViewType(int)

getAdViewType

public int getAdViewType(int position)

The ad view type for this position. Returns 0 if this is a regular content item. Otherwise, returns a number between 1 and getAdViewTypeCount(). This method is useful when implementing your own Adapter using MoPubStreamAdPlacer. To avoid worrying about view type, consider using MoPubAdAdapter instead of this class.

Parameters:

position - The stream position.

Returns:

The ad view type.

getOriginalPosition

public int getOriginalPosition(int position)

Returns the original position of an item considering ads in the stream. For example if your stream looks like: Item0 Ad Item1 Item2 Ad Item3 {@code getOriginalPosition(5)} will return {@code 3}.

Parameters:

position - The adjusted position.

Returns:

The original position before placing ads.

getAdjustedPosition

public int getAdjustedPosition(int originalPosition)

Returns the position of an item considering ads in the stream.

Parameters:

originalPosition - The original position.

Returns:

The position adjusted by placing ads.

getOriginalCount

public int getOriginalCount(int count)

Returns the original number of items considering ads in the stream.

Parameters:

count - The number of items in the stream.

Returns:

The original number of items before placing ads.

getAdjustedCount

public int getAdjustedCount(int originalCount)

Returns the number of items considering ads in the stream.

Parameters:

originalCount - The original number of items.

Returns:

The number of items adjusted by placing ads.

setItemCount

public void setItemCount(int originalCount)

Sets the original number of items in your stream. You must call this method so that the placer knows where valid positions are to place ads. After calling this method, the ad placer will call (int) each time an ad is loaded in the stream.

Parameters:

originalCount - The original number of items.

insertItem

public void insertItem(int originalPosition)

Inserts a content row at the given position, adjusting ad positions accordingly. Use this method if you are inserting an item into your stream and want to increment ad positions based on that new item. For example if your stream looks like: Item0 Ad Item1 Item2 Ad Item3 and you insert an item at position 2, your new stream will look like: Item0 Ad Item1 Item2 NewItem Ad Item3

Parameters:

originalPosition - The position at which to add an item. If you have an adjusted position, you will need to call getOriginalPosition(int) to get this value.

removeItem

public void removeItem(int originalPosition)

Removes the content row at the given position, adjusting ad positions accordingly. Use this method if you are removing an item from your stream and want to decrement ad positions based on that removed item. For example if your stream looks like: Item0 Ad Item1 Item2 Ad Item3 and you remove an item at position 2, your new stream will look like: Item0 Ad Item1 Ad Item3

Parameters:

originalPosition - The position at which to add an item. If you have an adjusted position, you will need to call getOriginalPosition(int) to get this value.

moveItem

public void moveItem(int originalPosition,
            int newPosition)

Moves the content row at the given position adjusting ad positions accordingly. Use this method if you are moving an item in your stream and want to have ad positions move as well. For example if your stream looks like: Item0 Ad Item1 Item2 Ad Item3 and you move item at position 2 to position 3, your new stream will look like: Item0 Ad Item1 Ad Item3 Item2

Parameters:

originalPosition - The position from which to move an item. If you have an adjusted position, you will need to call getOriginalPosition(int) to get this value.

newPosition - The new position, also expressed in terms of the original position.