Interstitial

This article will guide you through all the steps necessary to display an Interstitial ad in your application

Interstitial ads are skippable fullscreen ads.

Prerequisites

Ensure your application is registered on the Ogury Dashboard. If not, please refer to the Getting Started page before proceeding.

Step 1: Create an Interstitial ad unit

• Create an Interstitial ad unit on your asset page in the Ogury Dashboard.

• Copy the ad unit ID, 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 an Interstitial ad

To load an Interstitial ad, instantiate an OguryInterstitialAd object and call its load() method.

Swift

import UIKit
import OguryAds

class ViewController: UIViewController {
    private(set) var interstitialAd: OguryInterstitialAd!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        interstitialAd = OguryInterstitialAd(adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        interstitialAd.load()
    }
}

Objective-C

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

@interface ViewController ()
@property (nonatomic, retain) OguryInterstitialAd *interstitialAd;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.interstitialAd = [[OguryInterstitialAd alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"];
    [self.interstitialAd load];  
}

@end

OguryInterstitialAd requires the following parameter:

• adUnitID: the ad unit ID for the Interstitial ad. If you do not have one, please refer to the first step to create it.

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.

Swift

self.interstitialAd = OguryInterstitialAd(
    adUnitId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
    mediation: OguryMediation(name: "your mediation name", 
                              version: "your mediation SDK version")
)

Objective-C

OguryMediation *mediation = [[OguryMediation alloc] initWithName:@"your mediation name" version:@"your mediation SDK version"];
self.interstitialAd = [[OguryInterstitialAd alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" mediation:mediation];

Step 3: Register for callbacks

You can monitor the lifecycle of your Interstitial ad by implementing the OguryInterstitialAdDelegate 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 OguryInterstitialAd and implement the necessary methods. This ensures timely notifications, allowing you to manage the ad experience effectively.

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

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    interstitialAd = OguryInterstitialAd(
        adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    )
    interstitialAd.delegate = self
    interstitialAd.load()
}

// Called when the ad is loaded and ready to be shown
func interstitialAdDidLoad(_ interstitialAd: OguryInterstitialAd) {
    // Call show() to display the ad
}

// Called when an impression is recorded
func interstitialAdDidTriggerImpression(_ interstitialAd: OguryInterstitialAd) {
    // Track ad performance here
}

// Called when the user clicks on the ad
func interstitialAdDidClick(_ interstitialAd: OguryInterstitialAd) {
    // Handle ad click tracking here
}

// Called when the ad is closed
func interstitialAdDidClose(_ interstitialAd: OguryInterstitialAd) {
    // Resume app flow after ad is closed
}

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

Objective-C

 - (void)viewDidLoad {
    [super viewDidLoad];
    self.interstitialAd = [[OguryInterstitialAd alloc] initWithAdUnitID:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"];
    [self.interstitialAd load];
}

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

// Called when an impression is recorded
- (void)interstitialAdDidTriggerImpression:(OguryInterstitialAd *)interstitialAd { {
    // Track ad performance here
}

// Called when the user clicks on the ad
- (void)interstitialAdDidClick:(OguryInterstitialAd *)interstitialAd {
    // Handle ad click tracking here
}

// Called when the ad is closed
- (void)interstitialAdDidClose:(OguryInterstitialAd *)interstitialAd {
    // Resume app flow after ad is closed
}

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

Step 4: Show an Interstitial ad

To display a loaded Interstitial ad, invoke the show() method on the instantiated OguryInterstitialAd object.

Swift

if interstitialAd.isLoaded {
    // The ad is loaded and ready to be displayed.
    interstitialAd.show(in: self)
} else {
    // The ad is not loaded yet. Handle this situation appropriately.
}

Objective-C

if (self.interstitialAd.isLoaded) {
    [self.interstitialAd showAdInViewController:self];
}

The show() method requires the following parameter:

• A reference to the ViewController where the Interstitial ad will be presented.

Always verify that the ad is loaded before invoking the show() method, particularly if you are not calling it from the interstitialAdDidLoad callback.

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 Privacy compliance page.

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

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

Advanced topics

Error handling

If you are unable to load or display any Interstitial ads, we recommend logging callbacks from the OguryInterstitialAdDelegate to monitor the ad's lifecycle, especially the interstitial interstitialAd:didFailWithError: callback. This method provides 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.