You are here: Developers > OpenX Bidder for Apps Android > BidderManager

BidderManager

Last updated on July 27, 2017

If you would like to use your own prefetch or caching method, you can use BidderManager.

  1. Initialize the OpenX BidderOpenX's header bidding solution. Bidder enables publishers to realize the true value of their direct and indirect inventory in real time. "Bidder" can also mean a program designed to bid in real time on inventory in the OpenX Ad Exchange. adapter.

    Activity context is needed by the OpenX adapter to initialize devicemanager, locationmanager, and networkmanager to enhance the adrequest.

    You may want to initialize logging during development. Allowed log levels are:

    BFALogger.LogLevel.WARN

    BFALogger.LogLevel.INFO

    BFALogger.LogLevel.NONE

    
    if (!BFAConfiguration.isSDKInit) {
    	BFAConfiguration.initSDK(this, this, BFALogger.LogLevel.NONE);
    }
    BFAManagersResolver.getInstance().prepare(this);
    					

    Tip: With INFO/WARN, if ad requests to OpenX are failing, you will know what's going on. The log messages will include the version of Bidder for Apps that you are using.

    Example log message:

    11-14 09:46:01.796 7626-7626/com.openx.openx_appstore_demo W/OpenXBidder: OpenX BidderForApps v2.0.0 - Bad server response - [Adunits field empty in JSON response!]

  2. Once the OpenX Bidder adapter is initialized, create an instance of BidderManager and implement BidReceivedHandler.
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
    
    	//Set up and configure your MopubView as you would normally, but do not call loadAd on it yet.
    	MoPubView mopubView = new MoPubView(context);
    	mopubView.setAdUnitId("your_adunit");
    
    	mopubView.setBannerAdListener(this);
    	/*Instead of calling loadAd, first instantiate an instance of
    	BidderManager which will be used to retrieve a bid from OpenX. Be sure
    	to assign a listener that conforms to the BidReceivedHandler interface.
    	*/
    	BidderManager bidderManager = new BidderManager(new BidReceivedHandler() {
    		@Override
    		public void onBidReceive(Bidder.BidderResponseContainer bidResponse) {
    			//Implement this as demonstrated in the later steps.
    		}
    
    		@Override
    		void bidFail(AdError error) {
    			//Implement this to handle a case when OpenX fails to get Bidresponse.
    		}
    	});
    
    	where Bidder.BidderResponseContainer is:
    	public static class BidderResponseContainer {
    		...
    		public int bidValue;
    		...
    		public String impressionUrl;
    		...
    		public String clickUrl;
    		....
    		public String adHTML;
    		...
    		public boolean isMRAID;
    	}
    	...
    	bidderManager.load(domain, adunit, clienttimeout, adcallParams);
    }
    					
  3. Create and configure an AdCallParams instance to set additional data for this ad requestCommunication from a web browser or app to an ad server to display an ad.. You will set this up in the next step.

    For details on the AdCallParams object, see data enrichment.

  4. Call bidManager.load(OPENX_DELIVERY_DOMAIN, MOPUB_AD_UNIT_ID, CLIENT_TIMEOUT_IN_SECS, AdCallParams). Your account manager will provide you with the OpenX domain. The timeout is useful to ensure that waiting on the request to OpenX does not introduce unnecessary latency for your users.
    
    bidManager.load(OPENX_DELIVERY_DOMAIN, MOPUB_AD_UNIT_ID, CLIENT_TIMEOUT_IN_SECS, AdCallParams);
    
    //where,
    //OPENX_DELIVERY_DOMAIN = Bidder Domain
    //MOPUB_AD_UNIT_ID = MoPub Adunit
    //CLIENT_TIMEOUT_IN_SECS = timeout in seconds. This is the time within which the bidder response is expected. Recommended >2.5 seconds
    //AdCallParams = AdCallParams object that includes the extra params from publishers for better targeting.
    					
  5. When the load call completes, it will call one of two methods on its listener: receiveBid() or bidFail().

    receiveBid(BidderResponseContainer container) is triggered when OpenX successfully receives a bid. You will be supplied with a BidderResponseContainer object which has the following properties.

    Field

    Type

    Description

    isMRAID

    Boolean

    Indicates whether or not the ad is MRAIDMobile Rich Ad Interface Definitions, a type of API framework for interfacing between an ad creative and native mobile capabilities..

    preBidValue

    int

    The bid value in micros.

    impressionURL

    String

    The impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions. URL to track an impression.

    clickURL

    String

    The click URL to track a click.

    adHTML

    String

    The HTML of the creativeThe media asset associated with an ad, such as an image or video file. to render.

    keywords

    String

    Keywords to pass to MoPub. Includes the OpenX bid value and a cacheThis is a temporary storage area that houses frequently accessed data and keeps it ready for speedy access. This saves the computer from having to retrieve the information from main memory every time it’s required. In online terms, a cache can store much of a web page’s content instead of requesting all the data from the server again. key for later retrieval of the container.

    width

    int

    The width of the ad creative.

    height

    int

    The height of the ad creative.

    cacheKey

    String

    Unique key to recognize a bid, specifically, the transaction state field of the OpenX ad response.

    Within receiveBid, you should update your MopubView's keywords so that the appropriately-priced OpenX line itemThe primary unit of execution for an order, which represents a specific inventory purchase and the required conditions for ad delivery. will be selected. By default, the line items in MoPub should be set up to target keywords in the format of 'm_ox:%%preBidValue%%' where %%preBidValue%% is the value received from BidderResponseContainer.preBidValue. We also pass a keyword named 'm_cache_key' which allows you to fetch the cachedBidderResponseContainer object from our caching service. For an example of this, please see OXMBannerCustomEvent or OXMInterstitialCustomEvent within OpenX's adapter files.

    Since MopubView.keywords is just a string, care should be taken to properly append our keywords. MoPub's format is a comma-delimited string of key/value pairs (key:value). Two helper APIs are provided in BidderResponseContainer to help with the same:

    • setOpenXKeywords. Append OpenX bidder keywords to the MopubView's keywords. This can be used to append OpenX keywords to Mopub's keywords with a Mopub's allowed delimiter.
      
      String combinedKeywords = container.setOpenXKeywords(mopubView.getKeywords());
      //where,
      //mopubView.getKeywords() - MopubView's existing keywords.
      //combinedKeywords - keywords after getting appended with OpenX's keywords.
      							
    • removeOpenXKeywords. Remove OpenX bidder keywords from MopubView's keywords. This can be used to keep the MopubView ready with new values before it refreshes.
      
      String kvWithNoBidderVal = container.removeOpenXKeywords(mopubView.getKeywords());
      
      //where,
      //mopubView.getKeywords() - MopubView's existing keywords.
      //kvWithNoBidderVal - keywords after removing OpenX's keywords.
      						

    If it is the first load, MopubView must be explicitly told to load. Thereafter, it will automatically refresh itself (unless auto refresh is disabled).

    Callback with successful OpenX bid

    
    @Override
    //from BestBidReceivedHandler
    public void receiveBid(BidderResponseContainer bidderResponseContainer) {
    						
    	/*
    	In order to compete with MoPub on price, we need to update the ad unit's keywords 
    	so that the appropriately priced OpenX line item will be selected. By default the 
    	line items in MoPub should be setup to target keywords in the format of `m_ox:%%
    	preBidValue%%` where %%preBidValue%% is the value received from
    	OXMBidderResponseContainer.preBidValue. Since MopubView.keywords is just an 
    	NSString, care should be taken to properly append our keywords. MoPub's format is 
    	a comma-delimited string of key/value pairs (key:value).
    	*/
     
    	mopubView.setKeywords(bidderResponseContainer.setOpenXKeywords("married:No"));
     
    	//send MopubView in localExtras to use it in the customBanner class
    	Map<String, Object> localExtras = mopubView.getLocalExtras();
    	localExtras.put("view", mopubView);
    	mopubView.setLocalExtras(localExtras);
     
    	//call mopub's loadAd()
    	mopubView.loadAd();          
    }
    						

    bidFail(AdError error) is called when OpenX fails to return a bid. This can be because of no ad or a timeout. When this is called, you should call loadAd() on MopubView as normal, without OpenX pricing. Please remove any existing OpenX keywords before loadAd() on MopubView.

    
    @Override
    public void bidFail(AdError error) {
    	/*
    	OpenX's bid request failed. This can be because there is no fill from
    	OpenX or the request exceeded the set `clientTimeout`. In either case,
    	you proceed with the MoPub request without an OpenX price.
    	Care should be taken to remove the existing keywords from MopubView. Use
    	container.removeOpenXKeywords(mopubView.getKeywords()); to do the same
    	before loadAd();
    	*/
    	String keywords = container.removeOpenXKeywords(mopubView.getKeywords());
    	mopubView.setKeywords(keywords);
    	mopubView.loadAd();
    }
    						

    Note: In case of bid failure when there is no container, please make sure to remove OpenX keywords yourself. A sample code is as follows:

    
    private static String kvmox = "((m_ox:[a-z0-9]*,)|(,m_ox:[a-z0-9]*)|(m_ox:[a-z0-9]*))" ;
    private static String kvm_cache_key = "((m_cache_key:[a-z0-9A-Z]*,)|(,m_cache_key:[a-z0-9A-Z]*)|(m_cache_key:[a-z0-9A-Z]*))";
    
    /*
    Removes bidder keywords(m_ox:$,m_cache_key:$) from the given keywords
    */
    private String removeOpenXKeywords(String keywords) {
    	String noBidderKv = keywords;
    	if(!TextUtils.isEmpty(noBidderKv)) {
    		noBidderKv = noBidderKv.replaceAll(kvmox, "");
    		noBidderKv = noBidderKv.replaceAll(kvm_cache_key, "");
    	}
    	return noBidderKv;
    }
    					
  6. Implement the listeners BannerAdListener/InterstitialAdListener, in which we will request another ad and update the MopubView’s keywords. This will allow auto refresh to work seamlessly:

    For refresh

    
    @Override
    public void onBannerLoaded(MoPubView banner) {
    	/*The MoPub Ad View has finished loading. Fetch another OpenX ad and 
    	update the keywords, so MopubView has updated keywords at refresh time
    	*/
    	bidManager.load(OPENX_DELIVERY_DOMAIN, MOPUB_AD_UNIT_ID, CLIENT_TIMEOUT_VALUE, AdCallParams);
    	//Update MopubKeywords and set localExtras.
    }
    
    					
  7. Implement MopubView’s AdClick listeners for banners and interstitialsA full-screen ad displayed in content transitions. For example, a video ad that loads between levels of a mobile game. to record click for OpenX, if OpenX wins.
    
    //For banners:
    @Override
    public void onBannerClicked(MoPubView banner) {
    	...
    
    	if(OXMBannerCustomEvent.OXWinner) {
    		//From this mopubview, get it's container from the hashmap. Let container do 
    		//the click tracking. 
    		//In this example, MopubViewsArray is a map containing MopubViews and their containers.
    		BidderResponseContainer eachMopubViewContainer = mopubViewsArray.get(banner);
    		if (eachMopubViewContainer != null) {
    			eachMopubViewContainer.trackClickOnce();
    			//Make it false to facilitate new bid request for a new result.
    			OXMBannerCustomEvent.OXWinner = false;
    		}
    	}
    
    }
    
    //For interstitials:
    @Override
    public void onInterstitialClicked(MoPubInterstitial interstitial) {
    	...
    	if(OXMInterstitialCustomEvent.OXWinner) {
    		bidderResponseContainer.trackClickOnce();
    		//Make it false to facilitate new bid request for a new result.
    		OXMInterstitialCustomEvent.OXWinner = false;
    	}
    }
    
    					
  8. Call bidder destroy() on your app destroy.
    
    @Override
    public void onDestroy() {
    	...
    	bidderManager.destroy();
    	...
    }
    
    					
  9. Once you have set up BidderManager, the next step is to build data enrichment into your integration. Data enrichment can help increase revenue by revealing the value of your inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. to buyers.

Important: Please review the setup checklist. You must complete the self-test before submitting a build to OpenX for final testing. Do not submit your app to the app store before OpenX completes final testing.

See also:

Data enrichment

Bidder for Apps self-testing

Setup checklist

Feedback form