Integrate Native Ads

Julia Stein

September 17, 2024 17:35

To integrate any ad format, you must first have completed the instructions in the basic integration article.

Native ads are composed of assets that are presented to users via UI components native to the platform. They’re displayed using the same classes you already use in your storyboards, and can be formatted to match your app's visual design. When a native ad loads, your app receives an ad object containing its assets, and your app (rather than the SDK) is then responsible for displaying them. This differs from other ad formats, which don't allow you to customize the appearance of the ad.

Broadly speaking, there are two parts to successfully implementing native ads: loading an ad via the SDK and displaying the ad content in your app.

Create a Native Ad

To integrate a native ad in your iOS app, import VungleAdsSDK, and add an instance variable for VungleNative in your ViewController.swift file (or ViewController.h file for Objective-C).

import UIKit
import VungleAdsSDK

class LONativeAdViewController: UIViewController {
    private var nativeAd: VungleNative?

#import "LONativeAdViewController.h"
#import <VungleAdsSDK/VungleAdsSDK.h>

@interface LONativeAdViewController () <VungleNativeDelegate>
@property (nonatomic, strong) VungleNative *nativeAd;
@end

Add the code below to your method where you want to prepare the VungleNative instance. To create the VungleNative, you will need a Placement ID.
SwiftObjective-C
```
self.nativeAd = VungleNative(placementId: <YOUR_PLACEMENT_ID>)
self.nativeAd?.delegate = self
```
```
self.nativeAd = [[VungleNative alloc] initWithPlacementId:<YOUR_PLACEMENT_ID>];
self.nativeAd.delegate = self;
```
Note that you must set your ViewController (or any class that declares conformance to VungleNativeDelegate) to the delegate property of the VungleNative instance (refer to the Register for Callbacks section below).

Load a Native Ad

Once you create the VungleNative instance, you can load an ad by calling load().

self.nativeAd = VungleNative(placementId: <YOUR_PLACEMENT_ID>)
self.nativeAd?.delegate = self
self.nativeAd?.load()

self.nativeAd = [[VungleNative alloc] initWithPlacementId:<YOUR_PLACEMENT_ID>];
self.nativeAd.delegate = self;
[self.nativeAd load:nil];

Your ViewController (or any class that conforms to VungleNativeDelegate) will receive notification of load success or error through delegate callback methods (refer to the Register for Callbacks section below).

Prepare the Native Ad for Display

Playing a native ad is different from playing other ad formats. You are responsible for the layout and presentation of the ad. To begin, refer to this native ad layout and description of UI elements.

Native Ad UI Elements

These are the UI elements illustrated in the layout above:

UIView: A main view that contains all other native ad components
UIImageView: A view to display an icon image
VungleMediaView: A view to display a main image
UILabel: A label to display the ad title
UILabel: A label to display app rating
UILabel: A label to display "Sponsored By" text
UIImage: Privacy icon image (refer to the Display Privacy Icon section below)
UILabel: A label to display ad body text
UIButton: A button to display Call to Action (CTA) text

You must prepare UIViews (1), UILabel (4, 5, 6), and UIButtons (9) inside the main UIView (a container to hold all components for a Native ad). You must create the UI elements listed below (with the exception of UIImage (7, the Privacy icon image, which is discussed in the Display Privacy Icon section).

Prepare the Ad

To integrate native ads in your iOS app, open Main.storyboard, add UI elements to your ViewController.

Now that you have created all the UI elements for showing a native ad, you must reference these UI elements in the ViewController interface:

//Native Ad UI Components
@IBOutlet weak var nativeAdView: UIView!
@IBOutlet weak var iconView: UIImageView!
@IBOutlet weak var mediaView: MediaView!
@IBOutlet weak var titleLbl: UILabel!
@IBOutlet weak var ratingLbl: UILabel!
@IBOutlet weak var sponsorLbl: UILabel!
@IBOutlet weak var adTextLbl: UILabel!
@IBOutlet weak var downloadBtn: UIButton!

// Native Ad UI Components
@property (nonatomic, weak) IBOutlet UIView *nativeAdView;
@property (nonatomic, weak) IBOutlet UIImageView *iconView;
@property (nonatomic, weak) IBOutlet MediaView *mediaView;
@property (nonatomic, weak) IBOutlet UILabel *titleLbl;
@property (nonatomic, weak) IBOutlet UILabel *ratingLbl;
@property (nonatomic, weak) IBOutlet UILabel *sponsorLbl;
@property (nonatomic, weak) IBOutlet UILabel *adTextLbl;
@property (nonatomic, weak) IBOutlet UIButton *downloadBtn;

You can access all the string values through public APIs. Assign the string values to your text fields (referring to the layout illustration above, these are fields 4, 5, 6, 8, and the button text in 9).

self.titleLbl.text = self.nativeAd?.title
self.ratingLbl.text = "Rating: \(nativeAd?.adStarRating ?? 0)"
self.sponsorLbl.text = self.nativeAd?.sponsoredText
self.adTextLbl.text = self.nativeAd?.bodyText
self.downloadBtn.setTitle(self.nativeAd?.callToAction, for: .normal)

self.titleLbl.text = self.nativeAd.title;
self.ratingLbl.text = [NSString stringWithFormat:@"Rating: %f", self.nativeAd.adStarRating > 0 ? self.nativeAd.adStarRating : 0];
self.sponsorLbl.text = self.nativeAd.sponsoredText;
self.adTextLbl.text = self.nativeAd.bodyText;
[self.downloadBtn setTitle:self.nativeAd.callToAction forState:UIControlStateNormal];

Display a Native Ad

There are two options regarding clickable areas when you display your native ad:

Option 1: You can make the entire ad area clickable, meaning that clicking anywhere on the ad registers an event. To do this, simply do not pass in clickable areas.
Option 2: You can designate clickable areas, and clicking only on those areas will register an event. To do this, pass in clickable areas as described below.

In both options, you will pass the UIViews through the API(s) shown, so that the Vungle SDK can attach the corresponding images to the UIViews. Each option is detailed below. For both options, note that:

View and mediaView are required; other arguments are optional.
ViewController is used to present SKStoreProductView; otherwise, SDK will use the top-most ViewController.
SDK will make all items in the clickableViews array for CTA clickable; if it’s nil, the SDK will make the view (container UIView) clickable.

Option 1: No Clickable Areas Specified; Entire Ad Is Clickable

Pass your UIViews (1, 2, and 3 in Native Ad UI Elements above) through the API(s) shown, so that the Vungle SDK can attach the corresponding images to the UIViews as shown:

/// Pass UIViews and UIViewController to prepare and display a Native ad.
/// - Parameters:
///   - view a container view in which a native ad will be displayed. This view will be clickable.
///   - mediaView a MediaView to display the ad's image or video
///   - iconImageView a UIImageView to display the app icon
///   - viewController a UIViewController to present SKStoreProductViewController
@objc public func registerViewForInteraction(view: UIView,
                                             mediaView: MediaView,
                                             iconImageView: UIImageView?,
                                             viewController: UIViewController?)

Samples:

self.nativeAd?.registerViewForInteraction(view: self.nativeAdView,
                                          mediaView: self.mediaView,
                                          iconImageView: self.iconView,
                                          viewController: <YOUR_ViewController>)

[self.nativeAd registerViewForInteractionWithView: self.nativeAdView 
                                        mediaView: self.mediaView
                                    iconImageView: self.iconView
                                   viewController: <YOUR_ViewController>];

Option 2. Specify Clickable Areas

To specify clickable areas within the native ad, you can include an array of UIView objects using the following API. With clickableViews registered, the advertised app can be presented to the user by clicking on a view.

/// Pass UIViews and UIViewController to prepare and display a Native ad.
/// - Parameters:
///   - view a container view in which a native ad will be displayed.
///   - mediaView a MediaView to display the ad's image or video.
///   - iconImageView a UIImageView to display the app icon.
///   - viewController a UIViewController to present SKStoreProductViewController.
///   - clickableViews an array of UIViews that you would like to set clickable.
///   If nil or empty, the mediaView will be clickable.
@objc public func registerViewForInteraction(view: UIView,
                                             mediaView: MediaView,
                                             iconImageView: UIImageView?,
                                             viewController: UIViewController?,
                                             clickableViews: [UIView]?)

Samples:

self.nativeAd?.registerViewForInteraction(view: self.nativeAdView,
                                          mediaView: self.mediaView,
                                          iconImageView: self.iconView,
                                          viewController: <YOUR_ViewController>,
                                          clickableViews: [self.iconView, self.downloadBtn, self.nativeAdView])

[self.nativeAd registerViewForInteractionWithView: self.nativeAdView
                                        mediaView: self.mediaView
                                    iconImageView: self.iconView
                                   viewController: <YOUR_ViewController>
                                   clickableViews:@ [self.iconView, self.downloadBtn, self.nativeAdView]];

Display Privacy Icon

Specify where the privacy icon will be displayed in your nativeAdView. You can choose from NativeAdOptionsPosition enum (.topLeft, .topRight, .bottomLeft, and .bottomRight), and set it to adOptionsPosition property.

self.nativeAd?.adOptionsPosition = .topRight

self.nativeAd.adOptionsPosition = NativeAdOptionsPositionTopRight;

Dismiss the Native Ad

When the native display is completed, you can call unregisterView() to close the ad experience. You must also remove the delegate and set your native ad instance to nil.

self.nativeAd?.unregisterView()
self.nativeAd?.delegate = nil
self.nativeAd = nil

[self.nativeAd unregisterView];
self.nativeAd.delegate = nil;
self.nativeAd = nil;

Register for Callbacks

To receive notifications for ad events, declare conformance to the VungleNativeDelegate protocol and implement callback methods. Each of the callback methods is optional, so you can implement only the methods you want.

extension LONativeAdViewController: VungleNativeDelegate {
    // Ad load Events
    func nativeAdDidLoad(_ native: VungleNative) {
        print("nativeAdDidLoad")
    }
    
    func nativeAdDidFailToLoad(_ native: VungleNative, withError: NSError) {
        print("nativeAdDidFailToLoad")
    }
    
    // Ad Lifecycle Events
    func nativeAdDidFailToPresent(_ native: VungleNative, withError: NSError) {
        print("nativeAdDidFailToPresent")
    }
    
    func nativeAdDidTrackImpression(_ native: VungleNative) {
        print("nativeAdDidTrackImpression")
    }
    
    func nativeAdDidClick(_ native: VungleNative) {
        print("nativeAdDidClick")
    }
}

#pragma mark - VungleNative Delegate Methods
// Ad load Events
- (void)nativeAdDidLoad:(VungleNative *)native {
  NSLog(@"nativeAdDidLoad");
}
- (void)nativeAdDidFailToLoad:(VungleNative *)native
                    withError:(NSError *)withError {
  NSLog(@"nativeAdDidFailToLoad");
}
// Ad Lifecycle Events
- (void)nativeAdDidFailToPresent:(VungleNative *)native
                       withError:(NSError *)withError {
  NSLog(@"nativeAdDidFailToPresent");
}
- (void)nativeAdDidTrackImpression:(VungleNative *)native {
  NSLog(@"nativeAdDidTrackImpression");
}
- (void)nativeAdDidClick:(VungleNative *)native {
  NSLog(@"nativeAdDidClick");
}

Test a Native Ad

You can test a Native ad in one of two ways: by setting your app status to Test Mode so that Vungle can deliver test ads to your app, or by adding a test device to your app so that Vungle can deliver test ads specifically to the test device. Follow the instructions in Test Your Integration: Test Mode and Test Devices.

Additional Resources

Refer to our Native ad examples: