Getting Started - PubMatic/ios-openwrap-ima-sample GitHub Wiki

This sample application illustrates how to enable OpenWrap header bidding for an in-stream video ad in an iOS app.

High-level process overview

OTT Workflow

  1. The sample app sends the video ad request to the OpenWrap server.
  2. OpenWrap sends the ad call to the OpenWrap partners that are configured by the publisher.
  3. OpenWrap returns the winning ad to the application.
  4. The application prepares the GAM AdTag URL with the winning bid targeting attributes.
  5. IMA SDK makes an ad request using the AdTagURL from step 4.
  6. GAM performs an auction between OpenWrap Bid and GAM campaigns.
  7. IMA SDK renders the winning video ad.

Ad Server configuration for OpenWrap

This step is required so the GAM ad server can allocate impressions to the winning partner based on the actual bid price.

Please work with your PubMatic contact to complete this step.

More about the Sample Application

  1. Download source code using this repository.

  2. Install IMA SDK using pod install --repo-update in the same directory as the Podfile. See the CocoaPods Guides for more information on installing and updating pods.

  3. Open the .xcworkspace file with Xcode and run the app.

Note: You can reuse the OpenWrap Module in your application from this source code. This module uses the OpenWrap Video API to fetch video ads from the Open wrap server.

Integration steps

The following steps describe how the sample application has been integrated with OpenWrap Video and IMA SDK.

Step 1: Getting Bids from OpenWrap

This application uses various classes implemented in OpenWrap Module, which are used to fetch the video bids using OpenWrap Video API and passes the bid targeting to IMA SDK to perform the auction and render the video ad.

Note: App inventory transparency is very important to the buyers. You must set the App Store storeURL for your app before you request an ad. The Store URL should be the URL where users can download your app from the App Store.

The integration the ViewController looks like:

#import "ViewController.h"
#import "POWAdsLoader.h"

@interface ViewController () <POWAdsLoaderDelegate>
// Point of interaction with OpenWrap. Requests an ad from OpenWrap and passes the response to ViewController.
@property (nonatomic, strong) POWAdsLoader *openWrapAdsLoader;
@end

@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];

    // Set application info.
    POWApplicationInfo *appInfo = [POWApplicationInfo new];

    // Mandatory: Set app store URL.
    appInfo.storeURL = @"https://itunes.apple.com/app/id378458261";
    [POWConfiguration sharedConfig].appInfo = appInfo;

    // Created ad request with the OpenWrap publisher ID, profile ID and ad size.
    POWAdRequest *adRequest = [[POWAdRequest alloc] initWithPublisherId:@"<#OpenWrap_PubId#>"
                                                              profileId:@<#OpenWrap_Profile_Id>
                                                               adUnitId:<#DFP_Ad_Unit#>
                                                                andSize:<#Ad_size#>];

    // Create OpenWrap Ad Loader
    self.openWrapAdsLoader = [POWAdsLoader new];
    
    // Set OpenWrap Ad Loader delegate
    self.openWrapAdsLoader.delegate = self;
    
    // Request OpenWrap Ad Load to load ad
    [self.openWrapAdsLoader requestAdsWithRequest:adRequest];
}

// Method to get request url for IMA SDK
- (NSString *)imaAdTagUrl {
    return @"<#IMA_Ad_Tag_URL#>";
}

See Supported Parameters for more information about passing user- and application-specific parameters, CCPA, GDPR, etc. to OpenWrap.

Step 2: Prepare GAM URL with OW bid targeting

  1. Once the OpenWrap bid is received in adsLoader:didLoadAd: delegate method, get the targeting information from POWAdResponse object. Convert this targeting to a query string using method urlQueryStringWithEncoding:NO
  2. Encode the targeting info string using method urlEncode, and set as a value to “cust_params” query parameter of IMA ad tag URL.
  3. Pass this newly formed IMA ad tag URL to IMA SDK to request the ad.
- (void)adsLoader:(POWAdsLoader *)loader didLoadAd:(POWAdResponse *)adResponse {
    NSLog(@"Successfully received response from OpenWrap. Response: %@", adResponse.targettingInfo);

    // 1. Get the targeting info as a query parameter string for a URL
    NSString *customParam = [adResponse.targettingInfo urlQueryStringWithEncoding:NO];
    
    // 2. Encode OpenWrap bid targeting info string and append to cust_params
    NSString *updatedAdTagURL = [NSString stringWithFormat:@"%@&cust_params=%@", [self imaAdTagUrl], [customParam urlEncode]];
    
    // 3. Request ad from IMA/GAM
    [self requestAds:updatedAdTagURL];
}

- (void)adsLoader:(POWAdsLoader *)loader didFailWithError:(NSError *)error {
    NSLog(@"Failed to receive response from OpenWrap: %@", error);
    
    // OpenWrap failed to respond, request IMA SDK with default url.
    [self requestAds:[self imaAdTagUrl]];
}

Step 3: Requesting GAM Ads

Once GAM AdTagURI is prepared with bid targeting from OpenWrap, continue with the IMA SDK initialization. For example:

// Request Ad from IMA SDK
- (void)requestAds:(NSString *)adTagURL {

    // Create an ad display container for ad rendering.
    IMAAdDisplayContainer *adDisplayContainer =
    [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                        companionSlots:nil];

    // Create an ad request with our ad tag, display container, and optional user context.
    IMAAdsRequest *request =
    [[IMAAdsRequest alloc] initWithAdTagUrl:adTagURL
                         adDisplayContainer:adDisplayContainer
                            contentPlayhead:self.contentPlayhead
                                userContext:nil];
    
    // Request ad from IMA ad loader
    [self.imaAdsLoader requestAdsWithRequest:request];
}

Supported Parameters & Testing

See Supported Parameters and Testing for information about passing user- and application-specific parameters, CCPA, GDPR, etc. to OpenWrap.

⚠️ **GitHub.com Fallback** ⚠️