You are here: Developers > OpenX Bidder for Apps iOS > OXMBidderManager

OXMBidderManager

Last updated on July 27, 2017

If you would like to use your own prefetch or caching method, you can use OXMBidderManager. However, there are several things you will need to set up and handle manually using this class:

  • OXMAdCallParams for passing additional data
  • Timeout
  • receiveBid and bidFail
  • Auto-refresh
  1. Initialize the OpenX SDK at app launch:

  2. 
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    				
    	//Required: Initialize OpenX Ads
    	[OXMBidderForAppsConfiguration initializeSDK];
    	return YES;
    }
    		
  3. Create an instance of OXMBidderManager and conform to the OXMBidderManagerDelegate protocol.

    
    							@interface YourViewController : UIViewController <OXMBidderManagerDelegate>
    							@property (strong, nonatomic) OXMBidderManager *bidderManager;
    							@end
     
    							@implementation YourViewController
    							- (void)viewDidLoad {
    							[super viewDidLoad];
     
    							// Setup and configure your MPAdView as you would normally, but do not call loadAd on it yet.
    							self.mpAdView = [[MPAdView alloc] initWithAdUnitId:@"e4ff514ac14f4ec2a1cc989830cd61df" size:CGSizeMake(320, 50)];
    							self.mpAdView.delegate = self;
    							[self.mpAdViewContainer addSubview:self.mpAdView];
     
    							/*
    							Instead of calling loadAd, first instantiate an instance of 
    							OXMBidderManager which will be used to retrieve a bid from OpenX. Be sure 
    							to assign a delegate that conforms to the OXMBidderManagerDelegate 
    							protocol.
    							*/
    							self.bidderManager = [[OXMBidderManager alloc] init];
    							self.bidderManager.delegate = self;
     
    							// Call loadWithOpenXDomain:thirdPartyAdUnitID:clientTimeout,
    							// taking note that this is the first load and must be handled differently.
    							self.firstLoad = YES;
    							[self loadOpenXAd];
    							}
    			

  4. Create and configure an OXMAdCallParams 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 what data you can pass, see Data enrichment.
  5. Call loadWithOpenXDomain:thirdPartyAdUnitID:clientTimeout. 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.
  6. 
    
    						@implementation YourViewController
     
    						- (void) loadOpenXAd {
    						/*
    						Make a request to OpenX with the OpenX delivery domain, the MoPub ad unit 
    						ID and a timeout for which OpenX needs to respond before being considered 
    						a failed bid. The timeout is useful to ensure that waiting on the request 
    						to OpenX does not introduce unnecessary latency for your users.
    						*/
     
    						// Set parameters
    						OXMAdCallParams* adCallParams = [[OXMAdCallParams alloc] init];
    						adCallParams.appKeywords = @"utility,testing";
    						adCallParams.userGender = OXMGenderMale;
    						[self.bidderManager loadWithOpenXDomain:ExampleDeliveryDomain thirdPartyAdUnitID:self.mpAdView.adUnitId clientTimeout:3.0 adCallParams:adCallParams];
    						}
     
    						@end
    				

  7. When the load call completes, it will call one of two methods on its delegate.

    - (void)receiveBid:(OXMBidderResponseContainer *)container is called when OpenX successfully receives a bid. You will be supplied with an OXMBidderResponseContainer object. See OXMBidderResponseContainer for the properties of this object.

    Within receiveBid, you should update your MPAdView'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 OXMBidderResponseContainer.preBidValue. We also pass a keyword named m_cache_key which allows fetching the cached OXMBidderResponseContainer object from our caching service, and m_request_data as a backup to run the request again in the unlikely event of 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. miss. For an example of these keys in action, please see OXMBannerCustomEvent.m.

    Since MPAdView.keywords is just an NSString, care should be taken to properly append OpenX keywords. MoPub's format is a comma (,) delimited string of key/value pairs (key:value). Example: "key1:val1,key2:val2".

    If it is the first load, we have to explicitly tell the MPAdView to start. Thereafter, it will automatically refresh itself (unless auto refresh is disabled).

    
    					
    						@implementation YourViewController
    						- (void)receiveBid:(OXMBidderResponseContainer *) container {
    						/*
    						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 MPAdView.keywords is just 
    						an NSString, care should be taken to properly append OpenX keywords.
    						MoPub's format is a comma (,) delimited string of key/value pairs 
    						(key:value).
    						*/
    						self.mpAdView.keywords = [OXMFunctions setOpenXParamsOnThirdPartyObject:mpAdView bidderResponseContainer:container];
    						if (self.firstLoad) {
    						dispatch_async(dispatch_get_main_queue(), ^{
    						[self.mpAdView loadAd];
    						});
    						self.firstLoad = NO;
    						}
    						}
    						@end
    				

    - (void)bidFail:(NSError *) error is called when OpenX fails to return a bid. This can be because of no ad, timeout, or misconfiguration.

    
    						@implementation YourViewController
    						- (void)bidFail:(NSError *) 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.
    						*/
    						self.mpAdView.keywords = [OXMFunctions setOpenXParamsOnThirdPartyObject:mpAdView bidderResponseContainer:nil];
     
    						if (self.firstLoad) {
    						dispatch_async(dispatch_get_main_queue(), ^{
    						[self.mpAdView loadAd];
    						});
    						self.firstLoad = NO;
    						}
    						}
    						@end
    			
  8. Auto-refresh: Implement the MPAdViewDelegate method adViewDidLoadAd in which we will request another ad and update the MPAdView's keywords. This will allow auto-refresh to work seamlessly:
    
    						- (void)adViewDidLoadAd:(MPAdView *)view {
    						/*
    						The MoPub Ad View has finished loading. Fetch another OpenX ad. When the
    						MPAdView refreshes and requests another ad from MoPub the request will 
    						have updated keywords.
    						*/
    						[self loadOpenXAd];
    						}
    			
  9. In order to render the ads returned from OpenX, you will need to implement an MPBannerCustomEvent and an MPInterstitialCustomEvent. You can find reference implementations of both within the provided project as OXMBannerCustomEvent and OXMInterstitialCustomEvent.
  10. After you have finished setting up your integration, make sure that it is working correctly by completing the self-test.

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:

Self-test

Bidder for Apps setup checklist

Data enrichment

OXMBidderResponseContainer

ATS support

Troubleshooting

Flexible ad sizes support

 

Feedback form