Appearance

Interstitial Ads ​

This page documents how to load and display interstitial ads using the Ringier Advertising SDK. Interstitial ads are full-screen ads that appear at natural transition points in your app, such as between screens or after specific user actions.

Important Note: Interstitial ads must be shown within a UIViewController context. Ensure ads are loaded in advance to minimize latency when displaying them.

Overview ​

The SDK provides the RingierAdSDKInterstitialAd class for managing interstitial ads. This class uses a delegate pattern to notify you about ad lifecycle events.

swift
public final class RingierAdSDKInterstitialAd {
    public weak var delegate: RingierAdSDKInterstitialAdDelegate?
    
    public func load(params: RingierAdInterstitialParams, keywords: RingierAd.Keywords)
    public func show(from viewController: UIViewController)
    public func reset()
}

Loading an Interstitial Ad ​

Method Signature ​

swift
public func load(params: RingierAdInterstitialParams, keywords: RingierAd.Keywords)

Description ​

Loads an interstitial ad with the specified parameters and keywords. This function prefetches the ad, preparing it for display using the show(from:) method. The delegate will be notified when the ad finishes loading (successfully or with an error).

Parameters ​

  • params: RingierAdInterstitialParams – Configuration parameters for the interstitial ad.

    • category: The category of the placement (e.g., "Home", "Sports")
    • placementOrAlias: The placement identifier or alias
    • pageType: (Optional) Additional context for the ad request
    • adSizes: (Optional) Desired ad sizes. If nil, all configured sizes are used.

  • keywords: RingierAd.Keywords – Context-specific keywords to refine ad targeting (dictionary of String: String).

Usage Guidelines ​

  • Initialization: Create an instance of RingierAdSDKInterstitialAd and set its delegate before loading.
  • Preloading: Call load() in advance (e.g., during screen initialization) to reduce latency when showing the ad.
  • Delegate Pattern: Implement RingierAdSDKInterstitialAdDelegate to receive load success/failure callbacks.
  • Lifecycle Management: Keep a strong reference to the interstitial ad instance until you're done with it.
  • Reuse: After showing an ad, call reset() before loading a new one with the same instance.

Example ​

swift
import RingierAdSDK

class MyViewController: UIViewController {
    
    // Keep a strong reference to the interstitial ad
    private var interstitialAd: RingierAdSDKInterstitialAd?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        loadInterstitialAd()
    }
    
    private func loadInterstitialAd() {
        // Initialize the interstitial ad
        interstitialAd = RingierAdSDKInterstitialAd()
        interstitialAd?.delegate = self
        
        // Configure interstitial ad parameters
        let params = RingierAdInterstitialParams(
            category: "Home",
            placementOrAlias: "interstitial",
            pageType: "overview"
        )
        
        // Load interstitial ad with keywords
        interstitialAd?.load(params: params, keywords: ["topic": "sports", "section": "home"])
    }
}

// MARK: - RingierAdSDKInterstitialAdDelegate

extension MyViewController: RingierAdSDKInterstitialAdDelegate {
    
    func adDidLoad() {
        print("Interstitial ad loaded successfully and ready to show")
    }
    
    func adDidFailToLoad(error: RingierAdSDKInterstitialError) {
        print("Failed to load interstitial ad: \(error.localizedDescription)")
    }
    
    func adWillPresent() {
        print("Interstitial ad will present")
    }
    
    func adDidDismiss() {
        print("Interstitial ad was dismissed")
        // Clean up after showing
        interstitialAd?.reset()
    }
    
    func adWillDismiss() {
        print("Interstitial ad will dismiss")
    }
    
    func adDidFailToPresent(error: RingierAdSDKInterstitialError) {
        print("Failed to present interstitial ad: \(error.localizedDescription)")
    }
    
    func adDidRecordImpression() {
        print("Interstitial ad recorded an impression")
    }
    
    func adDidRecordClick() {
        print("Interstitial ad recorded a click")
    }
}

Showing an Interstitial Ad ​

Method Signature ​

swift
public func show(from viewController: UIViewController)

Description ​

Presents the loaded interstitial ad from the specified view controller. This method validates that the ad is ready and can be presented from the given view controller before attempting to display it.

Parameters ​

  • viewController: UIViewController – The view controller from which to present the interstitial ad.

Usage Guidelines ​

  • Load First: Always call load(params:keywords:) and wait for interstitialAdDidLoaded() before attempting to show the ad.
  • Context Requirement: Must be called from a valid UIViewController context.
  • Timing: Show the ad at natural transition points (e.g., between screens or after completing an action) to avoid disrupting the user experience.
  • Error Handling: Implement interstitialAdDidFailToPresent(error:) to handle presentation failures.
  • Cleanup: Call reset() after the ad is dismissed if you want to load a new ad with the same instance.

Error Cases ​

The interstitialAdDidFailToPresent(error:) delegate method will be called if:

  • The ad is not loaded or not ready to display
  • The provided view controller is invalid
  • The ad has expired or been invalidated

Example ​

swift
import RingierAdSDK

class MyViewController: UIViewController {
    
    private var interstitialAd: RingierAdSDKInterstitialAd?
    private var isAdReady = false
    
    override func viewDidLoad() {
        super.viewDidLoad()
        loadInterstitialAd()
    }
    
    private func loadInterstitialAd() {
        interstitialAd = RingierAdSDKInterstitialAd()
        interstitialAd?.delegate = self
        
        let params = RingierAdInterstitialParams(
            category: "news",
            placementOrAlias: "interstitial_home",
            pageType: "article",
            adSizes: [CGSize(width: 320, height: 480)]
        )
        
        interstitialAd?.load(params: params, keywords: ["section": "news"])
    }
    
    @IBAction func showAdButtonTapped(_ sender: UIButton) {
        // Only show if ad is ready
        if isAdReady {
            interstitialAd?.show(from: self)
        } else {
            print("Ad is not ready yet")
        }
    }
}

// MARK: - RingierAdSDKInterstitialAdDelegate

extension MyViewController: RingierAdSDKInterstitialAdDelegate {
    
    func adDidLoad() {
        print("Interstitial ad loaded successfully")
        isAdReady = true
        // Now you can call show(from:) when appropriate
    }
    
    func adDidFailToLoad(error: RingierAdSDKInterstitialError) {
        print("Failed to load interstitial ad: \(error.localizedDescription)")
        isAdReady = false
    }
    
    func adWillPresent() {
        print("Interstitial ad will present")
    }
    
    func adDidDismiss() {
        print("Interstitial ad was dismissed")
        isAdReady = false
        
        // Reset the ad for reuse
        interstitialAd?.reset()
        
        // Optionally load the next ad
        loadInterstitialAd()
    }
    
    func adWillDismiss() {
        print("Interstitial ad will dismiss")
    }
    
    func adDidFailToPresent(error: RingierAdSDKInterstitialError) {
        print("Failed to present interstitial ad: \(error.localizedDescription)")
        isAdReady = false
        
        // Handle the error - maybe try loading again
        interstitialAd?.reset()
    }
    
    func adDidRecordImpression() {
        print("Interstitial ad recorded an impression")
    }
    
    func adDidRecordClick() {
        print("Interstitial ad recorded a click")
    }
}

Complete Workflow Example ​

Here's a complete example showing the typical workflow for loading and showing interstitial ads:

swift
import UIKit
import RingierAdSDK

class ArticleViewController: UIViewController {
    
    private var interstitialAd: RingierAdSDKInterstitialAd?
    private var isAdReady = false
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Start loading the ad early
        prepareInterstitialAd()
    }
    
    private func prepareInterstitialAd() {
        interstitialAd = RingierAdSDKInterstitialAd()
        interstitialAd?.delegate = self
        
        let params = RingierAdInterstitialParams(
            category: "articles",
            placementOrAlias: "article_interstitial",
            pageType: "detail"
        )
        
        interstitialAd?.load(
            params: params,
            keywords: [
                "article_id": "12345",
                "category": "technology"
            ]
        )
    }
    
    // Show ad at a natural transition point
    @IBAction func navigateToNextArticle(_ sender: UIButton) {
        if isAdReady {
            // Show the ad before navigation
            interstitialAd?.show(from: self)
        } else {
            // Ad not ready, proceed with navigation
            performNavigation()
        }
    }
    
    private func performNavigation() {
        // Your navigation logic here
        print("Navigating to next article")
    }
    
    deinit {
        // Clean up
        interstitialAd?.reset()
    }
}

// MARK: - RingierAdSDKInterstitialAdDelegate

extension ArticleViewController: RingierAdSDKInterstitialAdDelegate {
    
    func adDidLoad() {
        isAdReady = true
    }
    
    func adDidFailToLoad(error: RingierAdSDKInterstitialError) {
        isAdReady = false
        // Continue with normal flow even if ad fails
    }
    
    func adWillPresent() {
        // Pause any ongoing activities
    }
    
    func adDidDismiss() {
        isAdReady = false
        // Continue with the navigation after ad is dismissed
        performNavigation()
    }
    
    func adWillDismiss() {
        // Prepare to resume activities
    }
    
    func adDidFailToPresent(error: RingierAdSDKInterstitialError) {
        isAdReady = false
        // Continue with navigation even if ad fails to present
        performNavigation()
    }
    
    func adDidRecordImpression() {
        // Track impression in your analytics
    }
    
    func adDidRecordClick() {
        // Track click in your analytics
    }
}

Reset and Reuse ​

After showing an interstitial ad, you should reset the instance before loading a new ad:

swift
func interstitialAdDidDismiss() {
    // Reset the current ad
    interstitialAd?.reset()
    
    // Now you can load a new ad with the same instance
    let newParams = RingierAdInterstitialParams(
        category: "Home",
        placementOrAlias: "interstitial2"
    )
    interstitialAd?.load(params: newParams, keywords: [:])
}

Delegate Protocol ​

All delegate methods are required. Implement all methods to handle the complete ad lifecycle:

  • adDidLoad() – Ad loaded successfully, ready to show
  • adDidFailToLoad(error: RingierAdSDKInterstitialError) – Ad failed to load with specific error
  • adWillPresent() – Ad is about to be presented
  • adDidDismiss() – Ad was dismissed by the user
  • adWillDismiss() – Ad is about to be dismissed
  • adDidFailToPresent(error: RingierAdSDKInterstitialError) – Ad failed to present with specific error
  • adDidRecordImpression() – Ad impression was recorded
  • adDidRecordClick() – User clicked on the ad