The Nexverse SDK provides a powerful and flexible solution for monetizing your iOS application through various ad formats. This guide walks you through the integration process and demonstrates how to implement each ad type effectively.

Installation

The SDK can be integrated into your iOS project using Nexverse.xcframework. Follow these steps to set up the framework:

  1. Drag and drop the downloaded Nexverse.xcframework into the target of your project.
  2. Navigate to your project’s general settings and scroll to the “Frameworks, Libraries, and Embedded Content” section.
  3. Select “Embed & Sign” for Nexverse.xcframework.

Add the Nexverse pod into the Podfile of your project as shown below.

If your project does not have Podfile then configure Cocoapods into your project first. Here is a guide.

  # Podfile
pod 'Nexverse', 'x.x.x' # Replace 'x.x.x' with the desired version

After adding the pod, run the following command in your terminal:

  pod install

Initialization

Before using any of the SDK’s features, you must initialize it with your account configuration. This one-time setup should be performed as early as possible in your app’s lifecycle, ideally right after launch.

Here’s how to initialize the SDK in your AppDelegate:

  import Nexverse

// ...existing code...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let initConfig = InitConfig(
        nexverseAccountId: "replace-with-actual-account-id",
        shouldTakeGDPRConsent: false, // Optional, set to true if you want to share GDPR consent
        tcfConsentString: "replace-with-tcf-consent-string", // Optional, required for GDPR compliance
    )

    NexverseAdManager.initialise(initConfig)

    return true
}
  
  // Import needs to be added to .h files.
@import Nexverse; // OR #import <Nexverse/Nexverse.h>

// ...existing code...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    GetInitConfig *config = [[GetInitConfig alloc] initWithNexverseAccountId:@"replace-with-actual-account-id"
                                                       shouldTakeGDPRConsent:NO
                                                            tcfConsentString:@"replace-with-tcf-consent-string"];

    [NexverseAdManager initialise: config :^(BOOL isSuccess) {
        // handle success/failure.
    }];
}

Additional Configuration

Location Permission (Optional)

To improve ad targeting and provide a better advertising experience, you can include location permission in your app. Add the following to your Info.plist:

  <key>NSLocationWhenInUseUsageDescription</key>
<string>A simple text that describes why your app needs the location</string>

Load & Render Ads

Nexverse provides all standard ad formats supported by market leaders. Each format is designed to maximize revenue while maintaining a great user experience.

Prerequisites

  • configId: A unique identifier based on the ad format and placement in your app. Obtain this from your Nexverse publisher dashboard. The SDK uses this ID to request and render appropriate ads for each placement.

Banner ads are a reliable way to monetize your app with minimal impact on user experience. The BannerView class handles the loading and display of banner ads, supporting various formats including image, video, and HTML (Rich Media).

Create and Load

Here’s how to implement a banner ad:

  import Nexverse

class BannerDemoViewController: UIViewController {

    private var bannerView: BannerView!

    override func loadView() {
        super.loadView()
        createAd()
    }

    func createAd() {
        // 1. Create a BannerView
        let adSize = CGSize(width: 300, height: 250)
        bannerView = BannerView(
            frame: CGRect(origin: .zero, size: adSize),
            configID: "replace-with-actual-config-id",
            adSize: adSize
        )

        // 2. Configure the BannerView
        bannerView.delegate = self
        bannerView.adFormat = .banner // Use .video for video banners, for all the rest use .banner
        bannerView.videoParameters.placement = .InBanner

        view.addSubview(bannerView)

        // 3. Load the banner ad
        bannerView.loadAd()
    }
}
  
  // BannerDemoViewController.m file.

#import "BannerDemoViewController.h"
@import Nexverse;

@interface BannerDemoViewController ()

@property (nonatomic, strong) BannerView *bannerView;

@end

@implementation BannerDemoViewController

- (void)loadView {
    [super loadView];
    [self createAd];
}

- (void)createAd {
    // 1. Create a BannerView
    CGSize adSize = CGSizeMake(300, 250);
    self.bannerView = [[BannerView alloc] initWithFrame:CGRectMake(0, 0, adSize.width, adSize.height)
                                               configID:@"replace-with-actual-config-id"
                                                 adSize:adSize];

    // 2. Configure the BannerView
    self.bannerView.delegate = self;
    self.bannerView.adFormat = AdFormat.banner; // Use AdFormat.video for video banners, for all the rest use AdFormat.banner
    self.bannerView.videoParameters.placement = PBPlacement.InBanner;

    [self.view addSubview:self.bannerView];

    // 3. Load the banner ad
    [self.bannerView loadAd];
}

@end

Delegate Events

Implement these delegate methods to handle banner ad events: 

  // MARK: - BannerViewDelegate
extension BannerDemoViewController: BannerViewDelegate {

    func bannerViewPresentationController() -> UIViewController? {
        return self
    }

    func bannerView(_ bannerView: BannerView, didReceiveAdWithAdSize adSize: CGSize) {
        // Handle successful ad load
    }

    func bannerView(_ bannerView: BannerView, didFailToReceiveAdWith error: any Error) {
        // Handle ad load failure
    }

    func bannerViewWillLeaveApplication(_ bannerView: BannerView) {
        // Handle app leaving foreground
    }

    func bannerViewWillPresentModal(_ bannerView: BannerView) {
        // Handle modal presentation
    }

    func bannerViewDidDismissModal(_ bannerView: BannerView) {
        // Handle modal dismissal
    }
}
  
  // BannerDemoViewController.h file.
@interface BannerDemoViewController : UIViewController <BannerViewDelegate>

@end

// BannerDemoViewController.m file
@implementation BannerDemoViewController

- (UIViewController *)bannerViewPresentationController {
    /// Asks the delegate for a view controller instance to use for presenting modal views
    /// as a result of user interaction on an ad. Usual implementation may simply return self,
    /// if it is view controller class.

    return self;
}

- (void)bannerView:(BannerView *)bannerView didReceiveAdWithAdSize:(CGSize)adSize {
    // Handle successful ad load
}

- (void)bannerView:(BannerView *)bannerView didFailToReceiveAdWith:(NSError *)error {
    // Handle ad load failure
}

- (void)bannerViewWillLeaveApplication:(BannerView *)bannerView {
    // Handle app leaving foreground
}

- (void)bannerViewWillPresentModal:(BannerView *)bannerView {
    // Handle modal presentation
}

- (void)bannerViewDidDismissModal:(BannerView *)bannerView {
    // Handle modal dismissal
}

@end

Interstitial Ads

Interstitial ads are full-screen advertisements that provide high-impact experiences at natural transition points in your app. The SDK supports both display and video formats through the InterstitialRenderingAdUnit class.

Create and Load

Here’s how to implement an interstitial ad:

  import Nexverse

class InterstitialDemoViewController: UIViewController {

    private var adUnit: InterstitialRenderingAdUnit!

    override func loadView() {
        super.loadView()
        createAd()
    }

    func createAd() {
        // 1. Create a InterstitialRenderingAdUnit
        adUnit = InterstitialRenderingAdUnit(configID: "replace-with-actual-config-id")

        // 2. Configure the InterstitialRenderingAdUnit
        // [.video] for video interstitial & [.video, .banner] for multiformat
        adUnit.adFormats = [.banner]
        adUnit.delegate = self

        // 3. Load the interstitial ad
        // NOTE: This will just load the ad,
        // adUnit.show() needs to be called from relevant delegate event. Check next section.
        adUnit.loadAd()
    }
}
  
  // InterstitialDemoViewController.m file.

#import "InterstitialDemoViewController.h"
@import Nexverse;

@interface InterstitialDemoViewController ()

@property (nonatomic, strong) InterstitialRenderingAdUnit *adUnit;

@end

@implementation InterstitialDemoViewController

- (void)loadView {
    [super loadView];
    [self createAd];
}

- (void)createAd {
    // 1. Create a InterstitialRenderingAdUnit
    self.adUnit = [[InterstitialRenderingAdUnit alloc] initWithConfigID:@"replace-with-actual-config-id"];

    // 2. Configure the InterstitialRenderingAdUnit
    // For video, use [[NSSet alloc] initWithObjects:AdFormat.video, nil];
    // For multiformat, use [[NSSet alloc] initWithObjects:AdFormat.banner, AdFormat.video, nil];
    self.adUnit.adFormats = [[NSSet alloc] initWithObjects:AdFormat.banner, nil];
    self.adUnit.delegate = self;

    // 3. Load the interstitial ad
    // NOTE: This will just load the ad,
    // [adUnit show] needs to be called from relevant delegate event. Check next section.
    [self.adUnit loadAd];
}

@end

Delegate Events

Handle interstitial ad events through these delegate methods:

  extension InterstitialDemoViewController: InterstitialAdUnitDelegate {

    func interstitialDidReceiveAd(_ interstitial: InterstitialRenderingAdUnit) {
        // Show interstitial from a viewController
        interstitial.show(from: self)
    }

    func interstitial(_ interstitial: InterstitialRenderingAdUnit, didFailToReceiveAdWithError error: (any Error)?) {
        // Handle ad load failure
    }

    func interstitialWillPresentAd(_ interstitial: InterstitialRenderingAdUnit) {
        // Handle ad presentation
    }

    func interstitialDidDismissAd(_ interstitial: InterstitialRenderingAdUnit) {
        // Handle ad dismissal
    }

    func interstitialWillLeaveApplication(_ interstitial: InterstitialRenderingAdUnit) {
        // Handle app leaving foreground
    }

    func interstitialDidClickAd(_ interstitial: InterstitialRenderingAdUnit) {
        // Handle ad click
    }
}
  
  
// InterstitialDemoViewController.h file.
@interface InterstitialDemoViewController : UIViewController <InterstitialAdUnitDelegate>

@end

// InterstitialDemoViewController.m file
@implementation InterstitialDemoViewController

- (void)interstitialDidReceiveAd:(InterstitialRenderingAdUnit *)interstitial {
    // Show interstitial from a viewController
    [self.interstitial showFrom:self];
}

- (void)interstitial:(InterstitialRenderingAdUnit *)interstitial didFailToReceiveAdWithError:(NSError *)error {
    // Handle ad load failure
}

- (void)interstitialWillPresentAd:(InterstitialRenderingAdUnit *)interstitial {
    // Handle ad presentation
}

- (void)interstitialDidDismissAd:(InterstitialRenderingAdUnit *)interstitial {
    // Handle ad dismissal
}

- (void)interstitialWillLeaveApplication:(InterstitialRenderingAdUnit *)interstitial {
    // Handle app leaving foreground
}

- (void)interstitialDidClickAd:(InterstitialRenderingAdUnit *)interstitial {
    // Handle ad click
}

@end

Native Ads

Native ads offer the most customizable ad experience, allowing you to match your app’s look and feel perfectly. The SDK provides various classes to load and display native ads that integrate seamlessly with your UI.

Request Native Ad and Assets

Here’s a comprehensive implementation of native ads:

  import Nexverse

class NativeAdDemoViewController: UIViewController {

    private var nativeUnit: NativeRequest!
    private var nativeAd: NativeAd?

    // 1. Create Native Ad UI with your interface guidelines.
    @IBOutlet weak var titleLabel: UILabel!
    @IBOutlet weak var iconView: UIImageView!
    @IBOutlet weak var mainImageView: UIImageView!
    @IBOutlet weak var bodyLabel: UILabel!
    @IBOutlet weak var callToActionButton: UIButton!
    @IBOutlet weak var sponsoredLabel: UILabel!

    // 2. Define all the assets required to load in native form.
    private var nativeRequestAssets: [NativeAsset] {
        let image = NativeAssetImage(minimumWidth: 200, minimumHeight: 50, required: true)
        image.type = ImageAsset.Main

        let icon = NativeAssetImage(minimumWidth: 20, minimumHeight: 20, required: true)
        icon.type = ImageAsset.Icon

        let title = NativeAssetTitle(length: 90, required: true)
        let body = NativeAssetData(type: DataAsset.description, required: true)
        let cta = NativeAssetData(type: DataAsset.ctatext, required: true)
        let sponsored = NativeAssetData(type: DataAsset.sponsored, required: true)

        return [title, icon, image, sponsored, body, cta]
    }

    // Optional - Define trackers.
    private var eventTrackers: [NativeEventTracker] {
        [NativeEventTracker(event: EventType.Impression, methods: [EventTracking.Image, EventTracking.js])]
    }

    override func loadView() {
        super.loadView()
        createAd()
    }

    func createAd() {
        // 3. Create a NativeRequest
        nativeUnit = NativeRequest(
            configId: "replace-with-actual-config-id",
            assets: nativeRequestAssets
        )

        // 4. Configure the NativeRequest
        nativeUnit.context = ContextType.Social
        nativeUnit.placementType = PlacementType.FeedContent
        nativeUnit.contextSubType = ContextSubType.Social
        nativeUnit.eventtrackers = eventTrackers

        // 5. Make a request to Nexverse Server
        nativeUnit.fetchDemand { [weak self] bidInfo in

            guard let self = self else { return }

            // 6. Find cached native ad
            guard let cacheId = bidInfo.targetingKeywords?["hb_cache_id_local"] else { return }

            // 7. Create a NativeAd
            guard let nativeAd = NativeAd.create(cacheId: cacheId) else { return }

            nativeAd.delegate = self
            self.nativeAd = nativeAd

            // 8. Render the native ad
            self.titleLabel.text = nativeAd.title
            self.bodyLabel.text = nativeAd.text

            if let iconString = nativeAd.iconUrl {
                ImageHelper.downloadImageAsync(iconString) { result in
                    if case let .success(icon) = result {
                        DispatchQueue.main.async {
                            self.iconView.image = icon
                        }
                    }
                }
            }

            if let imageString = nativeAd.imageUrl {
                ImageHelper.downloadImageAsync(imageString) { result in
                    if case let .success(image) = result {
                        DispatchQueue.main.async {
                            self.mainImageView.image = image
                        }
                    }
                }
            }

            self.callToActionButton.setTitle(nativeAd.callToAction, for: .normal)
            self.sponsoredLabel.text = nativeAd.sponsoredBy

            self.nativeAd?.registerView(view: self.view, clickableViews: [self.callToActionButton])
        }
    }
}
  
  // NativeAdDemoViewController.h file.

#import <UIKit/UIKit.h>

@interface NativeAdDemoViewController : UIViewController

// 1. Create Native Ad UI with your interface guidelines.
@property (weak, nonatomic) IBOutlet UILabel *titleLabel;
@property (weak, nonatomic) IBOutlet UIImageView *iconView;
@property (weak, nonatomic) IBOutlet UIImageView *mainImageView;
@property (weak, nonatomic) IBOutlet UILabel *bodyLabel;
@property (weak, nonatomic) IBOutlet UIButton *callToActionButton;
@property (weak, nonatomic) IBOutlet UILabel *sponsoredLabel;

-(id)init;

@end

// NativeAdDemoViewController.m file.

#import "NativeAdDemoViewController.h"
@import Nexverse;

@interface NativeAdDemoViewController ()

@property (nonatomic) NativeAd * nativeAd;
@property (nonatomic) NativeRequest * nativeUnit;

@end

@implementation NativeAdDemoViewController

- (void)loadView {
    [super loadView];
    [self createAd];
}

- (void)createAd {
    // 2. Define all the assets required to load in native form.
    NativeAssetImage *image = [[NativeAssetImage alloc] initWithMinimumWidth:200 minimumHeight:50 required:true];
    image.type = ImageAsset.Main;

    NativeAssetImage *icon = [[NativeAssetImage alloc] initWithMinimumWidth:20 minimumHeight:20 required:true];
    icon.type = ImageAsset.Icon;

    NativeAssetTitle *title = [[NativeAssetTitle alloc] initWithLength:90 required:true];
    NativeAssetData *body = [[NativeAssetData alloc] initWithType:DataAssetDescription required:true];
    NativeAssetData *cta = [[NativeAssetData alloc] initWithType:DataAssetCtatext required:true];
    NativeAssetData *sponsored = [[NativeAssetData alloc] initWithType:DataAssetSponsored required:true];

    // Optional - Define trackers.
    NativeEventTracker * eventTracker = [[NativeEventTracker alloc] initWithEvent:EventType.Impression
                                                                          methods:@[EventTracking.Image, EventTracking.js]];
    // 3. Create a NativeRequest
    self.nativeUnit = [[NativeRequest alloc] initWithConfigId:@"replace-with-actual-config-id"
                                                       assets:@[title, icon, image, sponsored, body, cta]
                                                eventTrackers:@[eventTracker]];

    // 4. Configure the NativeRequest
    self.nativeUnit.context = ContextType.Social;
    self.nativeUnit.placementType = PlacementType.FeedContent;
    self.nativeUnit.contextSubType = ContextSubType.Social;

    // 5. Make a request to Nexverse Server
    @weakify(self);
    [self.nativeUnit fetchDemandWithCompletionBidInfo:^(PBMBidInfo * _Nonnull bidInfo) {

        // 6. Find cached native ad
        NSDictionary * targetingKeywords = bidInfo.targetingKeywords ?: @{};
        NSString * cacheId = [targetingKeywords valueForKey:@"hb_cache_id_local"];

        // 7. Create a NativeAd
        NativeAd * nativeAd = [NativeAd createWithCacheId:cacheId];

        if (nativeAd == nil) {
            return;
        }

        nativeAd.delegate = self;
        self.nativeAd = nativeAd;

        // 8. Render the native ad
        self.titleLabel.text = self.nativeAd.title;
        self.bodyLabel.text = self.nativeAd.text;

        [[NSURLSession.sharedSession dataTaskWithURL:[NSURL URLWithString:self.nativeAd.iconUrl] completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
            dispatch_async(dispatch_get_main_queue(), ^{
                self.iconView.image = [[UIImage alloc] initWithData:data];
            });
        }] resume];

        [[NSURLSession.sharedSession dataTaskWithURL:[NSURL URLWithString:self.nativeAd.imageUrl] completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
            dispatch_async(dispatch_get_main_queue(), ^{
                self.mainImageView.image = [[UIImage alloc] initWithData:data];
            });
        }] resume];

        [self.callToActionButton setTitle:self.nativeAd.callToAction forState:UIControlStateNormal];
        self.sponsoredLabel.text = self.nativeAd.sponsoredBy;

        [self.nativeAd registerViewWithView:self.view clickableViews:@[self.callToActionButton]];
    }];
}

@end

Delegate Events

Implement these methods to handle native ad events:

  extension NativeAdDemoViewController: NativeAdEventDelegate {

    func adDidExpire(ad: NativeAd) {
        // Handle ad expiration
    }

    func adWasClicked(ad: NativeAd) {
        // Handle ad click
    }

    func adDidLogImpression(ad: NativeAd) {
        // Handle impression logging
    }
}
  
  // NativeAdDemoViewController.h file.
@interface NativeAdDemoViewController : UIViewController <NativeAdEventDelegate>

@end

// NativeAdDemoViewController.m file
@implementation NativeAdDemoViewController

- (void)adDidExpireWithAd:(NativeAd *)ad {
    // Handle ad expiration
}

- (void)adWasClickedWithAd:(NativeAd *)ad {
    // Handle ad click
}

- (void)adDidLogImpressionWithAd:(NativeAd *)ad {
    // Handle impression logging
}

@end

Rewarded Ads

Rewarded ads offer users in-app rewards for watching video advertisements. This format typically shows high engagement rates and provides a positive user experience through value exchange.

Create and Load

Here’s how to implement rewarded ads:

  class RewardedAdDemoViewController: UIViewController {

    private var adUnit: RewardedAdUnit!

    override func loadView() {
        super.loadView()
        createAd()
    }

    func createAd() {
        // 1. Create a RewardedAdUnit
        adUnit = RewardedAdUnit(configID: "replace-with-actual-config-id")
        adUnit.delegate = self

        // 2. Load the rewarded ad
        // NOTE: This will just load the ad,
        // adUnit.show() needs to be called from relevant delegate event. Check next section.
        adUnit.loadAd()
    }
}
  
  // RewardedAdDemoViewController.m file.

#import "RewardedAdDemoViewController.h"
@import Nexverse;

@interface RewardedAdDemoViewController ()

@property (nonatomic, strong) RewardedAdUnit * adUnit;

@end

@implementation RewardedAdDemoViewController

- (void)loadView {
    [super loadView];
    [self createAd];
}

- (void)createAd {
    // 1. Create a RewardedAdUnit
    self.adUnit = [[RewardedAdUnit alloc] initWithConfigID:@"replace-with-actual-config-id"];
    self.adUnit.delegate = self;

    // 2. Load the rewarded ad
    // NOTE: This will just load the ad,
    // [adUnit show] needs to be called from relevant delegate event. Check next section.
    [self.adUnit loadAd];
}
@end

Delegate Events

Handle rewarded ad events through these delegate methods:

  extension RewardedAdDemoViewController: RewardedAdUnitDelegate {

    func rewardedAdDidReceiveAd(_ rewardedAd: RewardedAdUnit) {
        // Show rewardedAd from a viewController
        if rewardedAd.isReady {
            rewardedAd.show(from: self)
        }
    }

    func rewardedAd(_ rewardedAd: RewardedAdUnit, didFailToReceiveAdWithError error: (any Error)?) {
        // Handle ad load failure
    }

    func rewardedAdUserDidEarnReward(_ rewardedAd: RewardedAdUnit, reward: NexverseReward) {
        // Handle reward distribution
    }

    func rewardedAdWillPresentAd(_ rewardedAd: RewardedAdUnit) {
        // Handle ad presentation
    }

    func rewardedAdDidDismissAd(_ rewardedAd: RewardedAdUnit) {
        // Handle ad dismissal
    }

    func rewardedAdWillLeaveApplication(_ rewardedAd: RewardedAdUnit) {
        // Handle app leaving foreground
    }

    func rewardedAdDidClickAd(_ rewardedAd: RewardedAdUnit) {
        // Handle ad click
    }
}
  
  // RewardedAdDemoViewController.h file.
@interface RewardedAdDemoViewController : UIViewController <RewardedAdUnitDelegate>

@end

// RewardedAdDemoViewController.m file
@implementation RewardedAdDemoViewController

- (void)rewardedAdDidReceiveAd:(RewardedAdUnit *)rewardedAd {
    // Show rewardedAd from a viewController
    if (rewardedAd.isReady) {
        [rewardedAd showFrom:self];
    }
}

- (void)rewardedAd:(RewardedAdUnit *)rewardedAd didFailToReceiveAdWithError:(NSError *)error {
    // Handle ad load failure
}

- (void)rewardedAdUserDidEarnReward:(RewardedAdUnit *)rewardedAd reward:(NexverseReward *)reward {
    // Handle reward distribution
}

- (void)rewardedAdWillPresentAd:(RewardedAdUnit *)rewardedAd {
    // Handle ad presentation
}

- (void)rewardedAdDidDismissAd:(RewardedAdUnit *)rewardedAd {
    // Handle ad dismissal
}

- (void)rewardedAdWillLeaveApplication:(RewardedAdUnit *)rewardedAd {
    // Handle app leaving foreground
}

- (void)rewardedAdDidClickAd:(RewardedAdUnit *)rewardedAd {
    // Handle ad click
}

@end