Small Banner / MREC

This article will go through all the steps required to display Small Banner and MREC ads in your application.

Last updated 5 months ago

Was this helpful?

Small Banner / MREC

This article will go through all the steps required to display Small Banner and MREC ads in your application.

Ogury offers two banner sizes that can fit specific positions on the screen and can be seamlessly integrated within your application's content:

Small Banner (320x50)
MREC (300x250)

Prerequisites

Ensure you have registered your application on the Ogury Dashboard. If not, please refer to the page before proceeding.

Step 1: Create a Small Banner / MREC ad unit

on your asset page in the Ogury Dashboard.
, as you will need it for integration. It is in the form of a UUID, which consists of a 36-character string formatted as follows: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where each x represents a hexadecimal digit.

In the following code samples, this ad unit ID will be represented as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Step 2: Load a Small Banner / MREC

To load a Small Banner or MREC ad, instantiate an OguryBannerAdView object with the right size (small_banner_320x50 or mrec_300x250) and call its load() method.

import UIKit
import OguryAds

class ViewController: UIViewController {
    private(set) var bannerAdView: OguryBannerAdView!
    private(set) var mrecAdView: OguryBannerAdView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        bannerAdView = OguryBannerAdView(adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                                             size: .small_banner_320x50()) // for Small Banner ad unit
                                             // size: .mrec_300x250()) // for MREC ad unit
        bannerAdView.load()
    }
}

#import "ViewController.h"
#import <OguryAds/OguryAds.h>

@interface ViewController ()
@property (nonatomic, retain) OguryBannerAdView *bannerAdView
@property (nonatomic, retain) OguryBannerAdView *mrecAdView;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                                                               size:[OguryAdsBannerSize small_banner_320x50]]; // for Small Banner ad unit
                                                               // size:[OguryAdsBannerSize mrec_300x250]]; // for MREC ad unit
    [self.bannerAdView load];  
}

@end

OguryBannerAdView requires the following parameters:

size: Specifies the banner size, determining whether the ad is a Small Banner (320x50) or MREC (300x250). This parameter is of type OguryBannerAdSize, an enum with values small_banner_320x50() and mrec_300x250().

Make sure the ad unit ID you provide matches the size you select.

If you are developing a mediation adapter, you must pass an additional parameter, OguryMediation which should be instantiated with:

name: the name of the mediation.
version: the version of the mediation SDK.

// exactly the same for the mrec, just fill in the proper size
self.bannerAdView = OguryBannerAdView(
    adUnitId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
        size: .small_banner_320x50(), // for Small Banner ad unit
        // size: .mrec_300x250(), // for MREC ad unit
    mediation: OguryMediation(name: "your mediation name", 
                              version: "your mediation SDK version")
)

// exactly the same for the mrec, just fill in the proper size
OguryMediation *mediation = [[OguryMediation alloc] initWithName:@"your mediation name" version:@"your mediation SDK version"];
self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 
                                                           size:[OguryAdsBannerSize small_banner_320x50]  // for Small Banner ad unit
                                                           // size:[OguryAdsBannerSize small_banner_320x50]  // for MREC ad unit
                                                      mediation:mediation];

Step 3: Register for callbacks

You can monitor the lifecycle of your Small banner / MREC ad by implementing the OguryBannerAdViewDelegate protocol. This delegate provides real-time updates on key events, such as successful ad loading, display or errors.

To use it, set your class as the delegate of OguryBannerAdView and implement the necessary methods. This ensures timely notifications, allowing you to manage the ad experience effectively.

override func viewDidLoad() {
    super.viewDidLoad()
    bannerAdView = OguryBannerAdView(
        adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        size: .small_banner_320x50()) // for Small Banner ad unit
        // size: .mrec_300x250()) // for MREC ad unit
    )
    bannerAdView.delegate = self
    bannerAdView.load()
}

// Called when the ad is loaded and ready to be shown
func bannerAdViewDidLoad(_ bannerAdView: OguryBannerAdView) {
    // Call show() to display the ad
}

// Called when an impression is recorded
func bannerAdViewDidTriggerImpression(_ bannerAdView: OguryBannerAdView) {
    // Track ad performance here
}

// Called when the user clicks on the ad
func bannerAdViewDidClick(_ bannerAdView: OguryBannerAdView) {
    // Handle ad click tracking here
}

// Called when the ad is closed
func bannerAdViewDidClose(_ bannerAdView: OguryBannerAdView) {
    // Resume app flow after ad is closed
}

// In case you attach the banner to controller which is presented modally
func presentingViewController(forBannerAdView bannerAd: OguryBannerAdView) -> UIViewController? {
}

// Called when the ad fails to load or display
func bannerAdView(_ bannerAdView: OguryBannerAdView, 
          didFailWithError error: OguryAdError) {
    switch error.type {
        case .load:
            // Handle loading error
        case .show:
            // Handle display error
    }
}

- (void)viewDidLoad {
    [super viewDidLoad];
    self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitID:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                                                       size:[OguryAdsBannerSize small_banner_320x50]]; // for Small Banner ad unit
                                                       // size:[OguryAdsBannerSize mrec_300x250]]; // for MREC ad unit
    [self.bannerAdView load];
}

// Called when the ad is loaded and ready to be shown
- (void)bannerAdViewDidLoad:(OguryBannerAdView *)bannerAdView {
    // call [interstitialAd show] to display the ad
}

// Called when an impression is recorded
- (void)bannerAdViewDidTriggerImpression:(OguryBannerAdView *)bannerAdView { {
    // Track ad performance here
}

// Called when the user clicks on the ad
- (void)bannerAdViewDidClick:(OguryBannerAdView *)bannerAdView {
    // Handle ad click tracking here
}

// Called when the ad is closed
- (void)bannerAdViewDidClose:(OguryBannerAdView *)bannerAdView {
    // Resume app flow after ad is closed
}

// In case you attach the banner to controller which is presented modally
- (UIViewController *_Nullable)presentingViewControllerForBannerAdView:(OguryBannerAdView *)bannerAdView {
}

// Called when the ad fails to load or display
- (void)bannerAdView:(OguryBannerAdView *)bannerAdView 
    didFailWithError:(OguryAdError *)error  {
    switch (error.type) {
        case OguryAdErrorTypeLoad:
            // Handle loading error
        case OguryAdErrorTypeShow:
            // Handle display error
    }
}

Step 4: Show a Small Banner / MREC ad

To display a Small Banner or MREC ad, you simply need to attach the instance of OguryBannerAdView to one of your view.

if bannerAdView.isLoaded {
    // The ad is loaded and ready to be displayed.
    yourView.addSubview(bannerAdView)
} else {
    // The ad is not loaded yet. Handle this situation appropriately.
}

if (self.bannerAdView.isLoaded) {
    [yourView addSubview:bannerAdView];
}

We recommend to attach the Small Banner or MREC ad once it is loaded. Use the bannerAdViewDidLoad callback to receive real-time notifications when the ad is ready.

Make sure to call the addSubview method in the main thread, otherwise, an exception will result.

Step 4: Destroying the Small Banner / MREC ad

The Small Banner and MREC ads are automatically destroyed when your ViewController is deallocated. If you need to manually destroy it, call the destroy method as follows:

bannerAdView.destroy()

[bannerAdView destroy];

Since the destroy() method is asynchronous, we strongly recommend that you nil out your banner reference inside the bannerAdViewDidClose: callback.

Please note that if you nil out your banner reference just after calling destroy(), there will be no callbacks since the delegate is destroyed along with the banner.

Step 5: Test your integration

After registering your app, it may take up to 15 minutes before ads are available.

Since our algorithm uses personalized targeting, you may not receive ads during testing. To obtain test ads, you can append _test to your Small Banner / MREC ad unit ID in the code, for example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_test.

Advanced topics

Error handling

If you are unable to load or display any Small Banner or MREC ads, we recommend logging callbacks from the OguryBannerAdViewDelegate to monitor the ad's lifecycle, especially the bannerAdView:didFailWithError: callback. This method provides an an OguryAdError instance containing important error details:

type: indicates the error type through the OguryAdErrorType enum, which distinguishes between loading errors (OguryAdErrorTypeLoad) and showing errors (OguryAdErrorTypeShow).
code: An integer that identifies the specific error. The enums OguryLoadErrorCode and OguryShowErrorCode define potential error codes that may occur during loading or showing ads. Further details on these enums are provided in the tables below.
localizedDescription: A descriptive message that provides additional context about the error.

You can utilize these details to diagnose the issue and take appropriate action to resolve it.

OguryLoadErrorCode

Enum value

Description

SDKNotStarted

The load could not proceed because the SDK appears to have not been started.

SDKNotProperlyInitialized

The load could not proceed because the SDK is not properly initialized.

NoActiveInternetConnection

The load could not proceed because there is no active Internet connection.

InvalidConfiguration

The load could not proceed due to an invalid SDK configuration.

AdDisabledCountryNotOpened

The load could not proceed because ads are disabled; the user’s country is not yet available for advertising.

AdDisabledConsentDenied

The load could not proceed because ads are disabled; the user has denied consent for advertising.

AdDisabledConsentMissing

The load could not proceed because ads are disabled; the user consent is missing or has not been provided.

AdDisabledUnspecifiedReason

The load could not proceed because ads are disabled for an unspecified reason.

AdRequestFailed

The load failed because the ad request encountered an error, and the server returned an unexpected response.

NoFill

No ad is currently available for this placement (no fill).

AdParsingFailed

The ad could not be loaded due to a failure in parsing.

AdPrecachingFailed

The ad could not be loaded due to a failure in ad precaching.

AdPrecachingTimeout

The ad could not be loaded as precaching exceeded the time limit and timed out.

OguryShowErrorCode

Enum value

Description

SDKNotStarted

The ad could not be displayed because the SDK appears to have not been started.

SDKNotProperlyInitialized

The ad could not be displayed because the SDK is not properly initialized.

NoActiveInternetConnection

The ad could not be displayed because there is no active Internet connection.

InvalidConfiguration

The ad could not be displayed due to an invalid SDK configuration.

AdDisabledCountryNotOpened

The ad could not be displayed because ads are disabled; the user’s country is not yet available for advertising.

AdDisabledConsentDenied

The ad could not be displayed because ads are disabled; the user has denied consent for advertising.

AdDisabledConsentMissing

The ad could not be displayed because ads are disabled; the user consent is missing or has not been provided.

AdDisabledUnspecifiedReason

The ad could not be displayed because ads are disabled for an unspecified reason.

AdExpired

The ad could not be displayed because the retention time of the loaded ad has expired.

NoAdLoaded

No ad has been loaded.

ViewInBackground

The ad could not be displayed because the application was running in the background.

AnotherAdAlreadyDisplayed

The ad could not be displayed because another ad is currently being displayed.

WebviewTerminatedBySystem

The ad could not be displayed because the WebView was terminated by the system, resulting in the ad being unloaded due to high resource consumption by the application.

ViewControllerPreventsAdFromBeingDisplayed

The ad could not be displayed because a ViewController is currently being presented, preventing the ad from displaying.

Last updated 5 months ago

Was this helpful?

Ogury offers two banner sizes that can fit specific positions on the screen and can be seamlessly integrated within your application's content:

Small Banner (320x50)
MREC (300x250)

Prerequisites

Ensure you have registered your application on the Ogury Dashboard. If not, please refer to the page before proceeding.

Step 1: Create a Small Banner / MREC ad unit

on your asset page in the Ogury Dashboard.
, as you will need it for integration. It is in the form of a UUID, which consists of a 36-character string formatted as follows: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where each x represents a hexadecimal digit.

In the following code samples, this ad unit ID will be represented as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Step 2: Load a Small Banner / MREC

To load a Small Banner or MREC ad, instantiate an OguryBannerAdView object with the right size (small_banner_320x50 or mrec_300x250) and call its load() method.

import UIKit
import OguryAds

class ViewController: UIViewController {
    private(set) var bannerAdView: OguryBannerAdView!
    private(set) var mrecAdView: OguryBannerAdView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        bannerAdView = OguryBannerAdView(adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                                             size: .small_banner_320x50()) // for Small Banner ad unit
                                             // size: .mrec_300x250()) // for MREC ad unit
        bannerAdView.load()
    }
}

#import "ViewController.h"
#import <OguryAds/OguryAds.h>

@interface ViewController ()
@property (nonatomic, retain) OguryBannerAdView *bannerAdView
@property (nonatomic, retain) OguryBannerAdView *mrecAdView;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                                                               size:[OguryAdsBannerSize small_banner_320x50]]; // for Small Banner ad unit
                                                               // size:[OguryAdsBannerSize mrec_300x250]]; // for MREC ad unit
    [self.bannerAdView load];  
}

@end

OguryBannerAdView requires the following parameters:

adUnitID: the ad unit ID for the Small Banner or MREC ad. If you do not have one, please refer to the to create it.
size: Specifies the banner size, determining whether the ad is a Small Banner (320x50) or MREC (300x250). This parameter is of type OguryBannerAdSize, an enum with values small_banner_320x50() and mrec_300x250().

Make sure the ad unit ID you provide matches the size you select.

If you are developing a mediation adapter, you must pass an additional parameter, OguryMediation which should be instantiated with:

name: the name of the mediation.
version: the version of the mediation SDK.

// exactly the same for the mrec, just fill in the proper size
self.bannerAdView = OguryBannerAdView(
    adUnitId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
        size: .small_banner_320x50(), // for Small Banner ad unit
        // size: .mrec_300x250(), // for MREC ad unit
    mediation: OguryMediation(name: "your mediation name", 
                              version: "your mediation SDK version")
)

// exactly the same for the mrec, just fill in the proper size
OguryMediation *mediation = [[OguryMediation alloc] initWithName:@"your mediation name" version:@"your mediation SDK version"];
self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 
                                                           size:[OguryAdsBannerSize small_banner_320x50]  // for Small Banner ad unit
                                                           // size:[OguryAdsBannerSize small_banner_320x50]  // for MREC ad unit
                                                      mediation:mediation];

Step 3: Register for callbacks

To use it, set your class as the delegate of OguryBannerAdView and implement the necessary methods. This ensures timely notifications, allowing you to manage the ad experience effectively.

If the bannerAdView:didFailWithError: callback is triggered, refer to the section below for detailed information on troubleshooting.

override func viewDidLoad() {
    super.viewDidLoad()
    bannerAdView = OguryBannerAdView(
        adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        size: .small_banner_320x50()) // for Small Banner ad unit
        // size: .mrec_300x250()) // for MREC ad unit
    )
    bannerAdView.delegate = self
    bannerAdView.load()
}

// Called when the ad is loaded and ready to be shown
func bannerAdViewDidLoad(_ bannerAdView: OguryBannerAdView) {
    // Call show() to display the ad
}

// Called when an impression is recorded
func bannerAdViewDidTriggerImpression(_ bannerAdView: OguryBannerAdView) {
    // Track ad performance here
}

// Called when the user clicks on the ad
func bannerAdViewDidClick(_ bannerAdView: OguryBannerAdView) {
    // Handle ad click tracking here
}

// Called when the ad is closed
func bannerAdViewDidClose(_ bannerAdView: OguryBannerAdView) {
    // Resume app flow after ad is closed
}

// In case you attach the banner to controller which is presented modally
func presentingViewController(forBannerAdView bannerAd: OguryBannerAdView) -> UIViewController? {
}

// Called when the ad fails to load or display
func bannerAdView(_ bannerAdView: OguryBannerAdView, 
          didFailWithError error: OguryAdError) {
    switch error.type {
        case .load:
            // Handle loading error
        case .show:
            // Handle display error
    }
}

- (void)viewDidLoad {
    [super viewDidLoad];
    self.bannerAdView = [[OguryBannerAdView alloc] initWithAdUnitID:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                                                       size:[OguryAdsBannerSize small_banner_320x50]]; // for Small Banner ad unit
                                                       // size:[OguryAdsBannerSize mrec_300x250]]; // for MREC ad unit
    [self.bannerAdView load];
}

// Called when the ad is loaded and ready to be shown
- (void)bannerAdViewDidLoad:(OguryBannerAdView *)bannerAdView {
    // call [interstitialAd show] to display the ad
}

// Called when an impression is recorded
- (void)bannerAdViewDidTriggerImpression:(OguryBannerAdView *)bannerAdView { {
    // Track ad performance here
}

// Called when the user clicks on the ad
- (void)bannerAdViewDidClick:(OguryBannerAdView *)bannerAdView {
    // Handle ad click tracking here
}

// Called when the ad is closed
- (void)bannerAdViewDidClose:(OguryBannerAdView *)bannerAdView {
    // Resume app flow after ad is closed
}

// In case you attach the banner to controller which is presented modally
- (UIViewController *_Nullable)presentingViewControllerForBannerAdView:(OguryBannerAdView *)bannerAdView {
}

// Called when the ad fails to load or display
- (void)bannerAdView:(OguryBannerAdView *)bannerAdView 
    didFailWithError:(OguryAdError *)error  {
    switch (error.type) {
        case OguryAdErrorTypeLoad:
            // Handle loading error
        case OguryAdErrorTypeShow:
            // Handle display error
    }
}

Step 4: Show a Small Banner / MREC ad

To display a Small Banner or MREC ad, you simply need to attach the instance of OguryBannerAdView to one of your view.

if bannerAdView.isLoaded {
    // The ad is loaded and ready to be displayed.
    yourView.addSubview(bannerAdView)
} else {
    // The ad is not loaded yet. Handle this situation appropriately.
}

if (self.bannerAdView.isLoaded) {
    [yourView addSubview:bannerAdView];
}

We recommend to attach the Small Banner or MREC ad once it is loaded. Use the bannerAdViewDidLoad callback to receive real-time notifications when the ad is ready.

Make sure to call the addSubview method in the main thread, otherwise, an exception will result.

Step 4: Destroying the Small Banner / MREC ad

The Small Banner and MREC ads are automatically destroyed when your ViewController is deallocated. If you need to manually destroy it, call the destroy method as follows:

bannerAdView.destroy()

[bannerAdView destroy];

Since the destroy() method is asynchronous, we strongly recommend that you nil out your banner reference inside the bannerAdViewDidClose: callback.

Please note that if you nil out your banner reference just after calling destroy(), there will be no callbacks since the delegate is destroyed along with the banner.

Step 5: Test your integration

After registering your app, it may take up to 15 minutes before ads are available.

Ogury exclusively serves ads to users who have provided their consent. Before conducting any tests, it is essential to ensure that your implementation complies with applicable privacy regulations. For more information on the regulations supported by Ogury, please visit the page.

For further details on test mode and enabling debug logs, please refer to the page.

Advanced topics

Error handling

type: indicates the error type through the OguryAdErrorType enum, which distinguishes between loading errors (OguryAdErrorTypeLoad) and showing errors (OguryAdErrorTypeShow).
code: An integer that identifies the specific error. The enums OguryLoadErrorCode and OguryShowErrorCode define potential error codes that may occur during loading or showing ads. Further details on these enums are provided in the tables below.
localizedDescription: A descriptive message that provides additional context about the error.

You can utilize these details to diagnose the issue and take appropriate action to resolve it.

OguryLoadErrorCode

Enum value

Description

SDKNotStarted

The load could not proceed because the SDK appears to have not been started.

SDKNotProperlyInitialized

The load could not proceed because the SDK is not properly initialized.

NoActiveInternetConnection

The load could not proceed because there is no active Internet connection.

InvalidConfiguration

The load could not proceed due to an invalid SDK configuration.

AdDisabledCountryNotOpened

The load could not proceed because ads are disabled; the user’s country is not yet available for advertising.

AdDisabledConsentDenied

The load could not proceed because ads are disabled; the user has denied consent for advertising.

AdDisabledConsentMissing

The load could not proceed because ads are disabled; the user consent is missing or has not been provided.

AdDisabledUnspecifiedReason

The load could not proceed because ads are disabled for an unspecified reason.

AdRequestFailed

The load failed because the ad request encountered an error, and the server returned an unexpected response.

NoFill

No ad is currently available for this placement (no fill).

AdParsingFailed

The ad could not be loaded due to a failure in parsing.

AdPrecachingFailed

The ad could not be loaded due to a failure in ad precaching.

AdPrecachingTimeout

The ad could not be loaded as precaching exceeded the time limit and timed out.

OguryShowErrorCode

Enum value

Description

SDKNotStarted

The ad could not be displayed because the SDK appears to have not been started.

SDKNotProperlyInitialized

The ad could not be displayed because the SDK is not properly initialized.

NoActiveInternetConnection

The ad could not be displayed because there is no active Internet connection.

InvalidConfiguration

The ad could not be displayed due to an invalid SDK configuration.

AdDisabledCountryNotOpened

The ad could not be displayed because ads are disabled; the user’s country is not yet available for advertising.

AdDisabledConsentDenied

The ad could not be displayed because ads are disabled; the user has denied consent for advertising.

AdDisabledConsentMissing

The ad could not be displayed because ads are disabled; the user consent is missing or has not been provided.

AdDisabledUnspecifiedReason

The ad could not be displayed because ads are disabled for an unspecified reason.

AdExpired

The ad could not be displayed because the retention time of the loaded ad has expired.

NoAdLoaded

No ad has been loaded.

ViewInBackground

The ad could not be displayed because the application was running in the background.

AnotherAdAlreadyDisplayed

The ad could not be displayed because another ad is currently being displayed.

WebviewTerminatedBySystem

The ad could not be displayed because the WebView was terminated by the system, resulting in the ad being unloaded due to high resource consumption by the application.

ViewControllerPreventsAdFromBeingDisplayed

The ad could not be displayed because a ViewController is currently being presented, preventing the ad from displaying.