Integrate Native Ads on Vungle SDK v.6 for iOS

Vungle Agent

September 17, 2024 17:36

Welcome to Vungle's early access to Native Ads! Starting with Vungle SDK v.6.11.0-early1, Vungle supports native ads. To participate in the early access release, contact your account manager.

Understand Native Ads

Native ads are named this way because they are “native” to your app’s content format. Instead of giving you a banner or fullscreen ad, the SDK provides your application the components of the ad and allows your application to control the arrangement and presentation of the ad. Because you, the publisher, control the ad’s format, you can keep it consistent with the look and feel of your app. This gives the user a more seamless advertising experience than do other ad formats.

Impressions for native ads are fired and counted when one pixel of the ad is on screen.

Step 1. Complete Basic Integration

To integrate banner ads in your iOS app, begin by following the instructions in the basic integration article. This Native Ads article contains supplementary information and assumes you have completed basic integration.

Step 2. Receive Delegate Callbacks

Set the viewController as delegate. This is a very important step for every format.

You must set the viewController (or any class a you prefer) as VungleNativeAdDelegate to receive delegate callbacks as follows:

- (void)nativeAdDidLoad:(VungleNativeAd *)nativeAd;
- (void)nativeAd:(VungleNativeAd *)nativeAd didFailWithError:(NSError *)error;
- (void)nativeAdDidTrackImpression:(VungleNativeAd *)nativeAd;
- (void)nativeAdDidClick:(VungleNativeAd *)nativeAd;

When a native ad is loaded, a nativeAd object is returned to you through nativeAdDidLoad callback. You can retrieve all strings through this object.

self.adTitleLabel.text = self.nativeAd.title;
self.adBodyLabel.text = self.nativeAd.bodyText;
[self.adCallToActionButton setTitle:self.nativeAd.callToAction forState:UIControlStateNormal];
self.adSponsorLabel.text = self.nativeAd.sponsoredText;
double rating = self.nativeAd.adStarRating;

Step 3. Load, Display, and Close a Native Ad

Request a Native Ad

Make sure the Vungle SDK is initialized before requesting a native ad.

IMPORTANT: Be sure to close the last native ad before requesting a new one. Calling the unregisterView API on loaded native ads frees up utilized resources and prevents memory leaks.

self.nativeAd = [[VungleNativeAd alloc] initWithPlacementID:self.placementID];
self.nativeAd.delegate = self;
[self.nativeAd loadAd];

Display a Native Ad

Playing a native ad is different from playing other ad formats. You are responsible for the layout and presentation of the ad. You must prepare UIViews, Text Fields, and Buttons inside the main UIView (a container to hold all components for a Native Ad).

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
VungleOptionsView: An option view to display privacy icon
UILabel: A label to display ad body text
UIButton: A button to display Call to Action (CTA) text

You can access all the strings and the value through public APIs:

@property (nonatomic, copy, readonly) NSString *title;
@property (nonatomic, copy, readonly) NSString *bodyText;
@property (nonatomic, copy, readonly) NSString *callToAction;
@property (nonatomic, assign, readonly) double adStarRating;
@property (nonatomic, copy, readonly) NSString *sponsoredText;

You have two options for preparing and displaying a Native Ad; both are detailed below. In each, you will pass the UIViews through the API(s) shown, so that the Vungle SDK can attach the corresponding images to the UIViews.

/**
 * Pass UIViews and UIViewController to prepare to display a native ad, then display.
 * @param view: a container view in which a native ad will be displayed
 * @param mediaView: a VungleMediaView to display the media (image/video).
 * @param iconView: a UIImageView to display the app icon
 * @param viewController: a UIViewController to present SKStoreProductViewController
 */
- (void)registerViewForInteraction:(UIView *)view
                         mediaView:(VungleMediaView *)mediaView
                          iconView:(nullable UIImageView *)iconView
                    viewController:(nullable UIViewController *)viewController;

If you want to specify clickable areas for the Native Ad to be displayed, you can include an array of UIView objects using the API below.

/**
 * Pass UIViews and UIViewController to prepare to display a Native ad, then display.
 * Also, specify the clickable area.
 * @param view: a container view in which a native ad will be displayed
 * @param mediaView: a VungleMediaView to display the media (image/video).
 * @param iconView: a UIImageView to display the app icon
 * @param viewController: a UIViewController to present SKStoreProductViewController
 * @param clickableViews: an array of UIViews which you would like to set clickable
 * If nil or empty, the view will be clickable.
 */
- (void)registerViewForInteraction:(UIView *)view
                         mediaView:(VungleMediaView *)mediaView
                          iconView:(nullable UIImageView *)iconView
                    viewController:(nullable UIViewController *)viewController
                    clickableViews:(nullable NSArray *)clickableViews;

Call the API as shown to start to display the Native Ad:

[self.nativeAd registerViewForInteraction:self.adUIView
                                mediaView:self.adMediaView
                                 iconView:self.adIconView
                           viewController:self];

When specifying clickable views, the API call for loading and displaying a Native Ad might look like this:

[self.nativeAd registerViewForInteraction:self.adUIView
                                mediaView:self.adMediaView
                                 iconView:self.adIconView
                           viewController:self]
clickableViews:@[self.adUIView, self.adMediaView, self.adIconView];

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

After a native ad has started to play, the SDK automatically re-requests a new ad, regardless of whether the is_auto_cached flag is set to ‘true’ or ‘false’.

Configure the Native Ad for Display Using Storyboard

Create storyboard elements for the Native Ad using available Objective-C objects, and connect them to outlet properties in the class you will use to present your Native Ad (shown below).
Create the UIView and the VungleMediaView in the storyboard where your Native Ad will be presented.
Connect the VungleMediaView in the storyboard to the outlet property adMediaView in the code:
Before calling the method to display the Native Ad, you must add a line of code to specify the position of the privacy icon. This position should be one of the available positions in the NativeAdOptionsPosition enum found in VungleNativeAd.h.
The line of code to be added looks like this (note that this example uses one enum value when any of the four would be acceptable):
Specify Position of Privacy Icon
```
self.nativeAd.adOptionsPosition = NativeAdOptionsPositionTopLeft;
```
If no position is specified, the default position will be used to display the privacy icon in the top right.
When the native ad loads successfully, set the VNGAdOptionsView’s nativeAd property equal to the Native Ad which loads successfully, as shown. Please note here that the nativeAd object that is assigned to the self.nativeAd property in your class is the instance included in the delegate callback.
Set the nativeAd Property
```
self.nativeAd = nativeAd;
```

Make the assignment described above after calling the method that displays the Native Ad; for example:

[self.nativeAd registerViewForInteraction:self.adUIView
                                    mediaView:self.adMediaView
                                     iconView:self.adIconView
                               viewController:self];
self.adOptionsView.nativeAd = self.nativeAd;

Close a Native Ad

To close a native ad, call the following API:

/**
 * Dismiss the currently displaying Native ad.
 */
- (void)unregisterView;

Step 4. 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.