Getting Started with iOS SDK

Before You Start Make Sure:

• at least one App and Placement are added on Publisher Portal
• SDK is installed
• SDK is initialised
• Placements have “Testing” status in order to get a test ad,  for testing the integration

1. Requesting ads

To request an ad you should retrieve the Placement object from the Controller.

DIOPlacement *placement = [[DIOController sharedInstance] placementWithId:@"5678"];

    You can customise video settings for all units (both are YES by default)

    placement.showSoundControl = NO;
    placement.defaultMute = NO;

Then issue a new DIOAdRequest object from the Placement object:

DIOAdRequest *request = [placement newAdRequest];

To execute an Ad Request (asynchronous operation):

[request requestAdWithAdReceivedHandler:^(DIOAdProvider *adProvider) {
 // Success
} noAdHandler:^(NSError *error){
 // Failure
}];

You may add data about the user or the context of the ad to the Ad Request. As a best practice, we advise our publishers to add as much user data to their Ad Requests as possible. The reason  is, this gives advertisers visibility into the parameters of each user within your app, and in doing so, allows advertisers to bid more intelligently. Meaning a higher CPM payout for you.

[request setContentKeywords:@[@"house of cards", @"ronaldo"]];

[adRequest setUserId:@"some user ID"];

[adRequest setBuyerId:@"some buyer ID"];

[adRequest setIABPageCats:@[@"IAB12", @"IAB6-1", @"IAB48-84"]];

[adRequest setIABSectionCats:@[@"IAB2", @"IAB61-12", @"IAB1-1"]];

In case you are requesting Banner or Medium Rectangle ads, specify the expected position of the ad on a screen as follows:

[request setPosition:DIOBannerPositionAboveTheFold];
[request setPosition:DIOBannerPositionBelowTheFold];

Note: Ad Request properties should be added prior to executing the ad request.

2. Loading ads

Use the DIOAdProvider to load the ad:

[adProvider loadAdWithLoadedHandler:^(DIOAd *ad) {
 // Success
} failedHandler:^(NSError *error){
 // Failure
}];

All the video ads are muted by default. There is an option to mute/unmute ad using:

[ad toggleSound:(bool) muted];

If you previously requested ad attributes like ‘Advertiser Name’ and ‘Advertiser Click URL’, you can access them as follows:

NSString *name = ad.avertiserName;
NSString *clickURL = ad.advertiserClickURL;

You also can retrieve additional data of current ad:

NSLog(@"=================== advertiserName = %@", ad.advertiserName);
NSLog(@"=================== advertiserClickURL = %@", ad.advertiserClickURL);
NSLog(@"=================== ecpm = %@", ad.ecpm);
NSLog(@"=================== crid = %@", ad.crid);
NSLog(@"=================== cid = %@", ad.cid);
NSLog(@"=================== adomain = %@", ad.adomain); // NSArray
NSLog(@"=================== auctionId = %@", ad.auctionId);
NSLog(@"=================== msessId = %@", ad.msessId);

A/B testing labels can be defined via:

[request setLabels:@[@"blue", @"red"]]

Note:
We provide GDPR compliance through the IAB’s GDPR Transparency and Consent framework. If you use a CMP that implements this IAB standard, we will be able to pick the consent state from your integrated CMP and apply it in our ad serving.

Rendering Ads from oRTB Response

Before start make sure you initialised SDK and have active placements within your inventory on display.io Platform.

Once you got an oRTB response string you can load the ad for one of your placement. You can create any Ad Unit you want, supported  Ad Unit list you can find at Ad Units Integration section.
Note: you are responsible for creating Ad Unit that match retrieved ad size. E.g. if you got oRTB response with ad size 300×250 you should not create Interstitial or Interscroller ad from that markup.

To create the Ad from oRTB response follow the next sample:

id responseData; // your oRTB response in NSDictionary format

if ([self.placement isKindOfClass:[DIOInFeedPlacement class]]) {

        DIOInFeedPlacement* inFeedPlacement = (DIOInFeedPlacement*)self.placement;

        [inFeedPlacement loadInfeedFromORTB:response
                                                adReceivedHandler:^(DIOAd *ad) {
            // the ad is ready to be rendered
        }
                                                      noAdHandler:^(NSError *error) {
            // handle fail to load event
        }];
       
    } else if ([self.placement isKindOfClass:[DIOInterscrollerPlacement class]]) {

        DIOInterscrollerPlacement* interscrollerPlacement = (DIOInterscrollerPlacement*)self.placement;

        [interscrollerPlacement loadInterscrollerFromORTB:response

                                                              adReceivedHandler:^(DIOAd *ad, DIOInterscrollerContainer *container) {
             // the ad is ready to be rendered
        }
                                                                    noAdHandler:^(NSError *error) {
            // handle fail to load event
        }];
        
    } else if ([self.placement isKindOfClass:[DIOInterstitialPlacement class]]) {

        DIOInterstitialPlacement* interstitialPlacement = (DIOInterstitialPlacement*)self.placement;

        [interstitialPlacement loadInterstitialFromORTB: response adReceivedHandler:^(DIOAd * ad) {

            [ad showAdFromViewController:self eventHandler:^(DIOAdEvent event) {

                switch (event) {
                    case DIOAdEventOnShown:
                        NSLog(@"AD_EVENT_HANDLER:  AD SHOWN");
                        break;

                    case DIOAdEventOnFailedToShow:
                        NSLog(@"AD_EVENT_HANDLER:  AD FAILED TO SHOW");
                        break;

                    case DIOAdEventOnClicked:
                        NSLog(@"AD_EVENT_HANDLER:  AD CLICKED");
                        break;

                    case DIOAdEventOnClosed:
                        NSLog(@"AD_EVENT_HANDLER:  AD CLOSED");
                        break;

                    case DIOAdEventOnAdCompleted:
                        NSLog(@"AD_EVENT_HANDLER:  AD COMPLETED");
                        break;

                    case DIOAdEventOnSwipedOut:
                        NSLog(@"AD_EVENT_HANDLER:  AD SWIPED OUT");
                        break;

                    case DIOAdEventOnSnapped:
                        NSLog(@"AD_EVENT_HANDLER:  AD SNAPPED");
                        break;

                    case DIOAdEventOnMuted:
                        NSLog(@"AD_EVENT_HANDLER:  AD MUTED");
                        break;

                    case DIOAdEventOnUnmuted:
                        NSLog(@"AD_EVENT_HANDLER:  AD UNMUTED");
                        break;
                }
            }];
          
        } noAdHandler:^(NSError * e) {
            // handle fail to load event
        }];

    } else if ([self.placement isKindOfClass:[DIOBannerPlacement class]]) {

        [((DIOBannerPlacement*)self.placement) loadBannerFromORTB:response

                                                adReceivedHandler:^(DIOAd *ad) {
            // the ad is ready to be rendered           
        }
                                                      noAdHandler:^(NSError *error) {
            // handle fail to load event
        }];

    } else if ([self.placement isKindOfClass:[DIOMediumRectanglePlacement class]]) {

        [((DIOMediumRectanglePlacement*)self.placement)loadMRectFromORTB:response

                                                       adReceivedHandler:^(DIOAd *ad) {
            // the ad is ready to be rendered
        }
                                                             noAdHandler:^(NSError *error) {
            // handle fail to load event
        }];
       
    } else if ([self.placement isKindOfClass:[DIOHeadlinePlacement class]]) {

        DIOHeadlinePlacement* headlinePlacement = (DIOHeadlinePlacement*)self.placement;

        [headlinePlacement loadHeadlineFromORTB:response

                                                    adReceivedHandler:^(DIOAd *ad, DIOHeadlineContainer *container) {

            // the ad is ready to be rendered
        }
                                                          noAdHandler:^(NSError *error) {
            // handle fail to load event
        }];      
    }