Getting Started

Native ads let you design ad units that match the look and feel of your app's content.

Prerequisites

• Getting Started
• Ad Parameters

NAMSDK Import

Import the SDK module.

Swift

import GFPSDK

Objective-C

@import GFPSDK;

Initializing Native Ad Providers

With the Pod for the native ad provider you want to integrate added to your project, initialize via GFPAdManager. (Perform this only once when the app launches.)

Provider Option	Ad Provider	CocoaPods
GFPNativeProviderOptionNDA	Naver NDA	pod 'GFPSDK/MediationNDA'
GFPNativeProviderOptionDFP	Google GAM (Google Ad Manager)	pod 'GFPSDKMediationDFP'
GFPNativeProviderOptionFAN	Meta Audience Network	pod 'GFPSDKMediationFAN'
GFPNativeProviderOptionInMobi	InMobi	pod 'GFPSDKMediationInMobi'
GFPNativeProviderOptionVungle	Liftoff (Vungle)	pod 'GFPSDKMediationVungle'
GFPNativeProviderOptionLAN	LINE Ads Network	pod 'GFPSDKMediationLAN'
GFPNativeProviderOptionBidMachine	BidMachine	pod 'GFPSDKMediationBidMachine'
GFPNativeProviderOptionPangle	Pangle	pod 'GFPSDKMediationPangle'

Swift

// Add cocoapods dependencies if integrating DFP, NDA, Inmobi, or Facebook ads.
GFPAdManager.setup(withPublisherCd: "publisherCd") { (error : GFPError?) in
    print("Setup Eror: \(String(describing: error?.description))")
}

Objective-C

// Add cocoapods dependencies if integrating DFP, NDA, Inmobi, or Facebook ads.
[GFPAdManager setupWithPublisherCd:@"publisherCd" completionHandler:^(GFPError * _Nullable error) {
    NSLog(@"Setup ERROR: %@", error);
}];

tip

For detailed GFPAdManager configuration, refer to Ad Manager Setup.

Writing the View Controller

Create a view controller (MyViewController) and perform the following in the header file (MyViewController.h).
(In this example, a single view controller implements all event protocols.)

1. Declare a GFPAdLoader *adLoader property on the view controller.
2. Implement the GFPAdLoaderDelegate protocol on the view controller.
3. Declare a GFPNativeAd *nativeAd property on the view controller.
4. Implement the GFPNativeAdDelegate protocol on the view controller.

GFPAdLoaderDelegate delivers events related to native (and banner) ad loading, while GFPNativeAdDelegate delivers events such as impression, click, and rendering errors for the loaded native object.

Swift

// MyViewController.h
import GFPSDK

class MyViewController : UIViewController, GFPAdLoaderDelegate, GFPNativeAdDelegate {
    private var adLoader : GFPAdLoader?

    private var nativeAd : GFPNativeAd?
    private var nativeAdView : GFPNativeAdView?
}

Objective-C

// MyViewController.h

@import GFPSDK;

@interface MyViewController : UIViewController <GFPAdLoaderDelegate, GFPNativeAdDelegate>

@property (nonatomic) GFPAdLoader *adLoader;

@property (nonatomic) GFPNativeAd *nativeAd;
@property (nonatomic) GFPNativeAdView *nativeAdView;

@end

Creating GFPAdLoader and Requesting an Ad

In the viewDidLoad method of MyViewController.m, create an instance of GFPAdLoader and request an ad.

• When creating a GFPAdLoader instance, provide your issued Ad Unit ID along with user information set in GFPAdParam. GFPAdParam is used for targeting to improve ad performance.

Swift

override func viewDidLoad() {
    super.viewDidLoad()
        
    let adParam = GFPAdParam()
    adParam.yearOfBirth = 1990
    adParam.gender = .male
    ...
        
    self.adLoader = GFPAdLoader(unitID: "UnitId", rootViewController: self, adParam: adParam)
        
    let nativeOption = GFPAdNativeOptions()
    nativeOption.renderingSetting = ... // Rendering settings for the native ad to be loaded
    self.adLoader?.setNativeDelegate(self, nativeOptions: nativeOption)

    self.adLoader?.delegate = self
    self.adLoader?.loadAd()
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];

    GFPAdParam *adParam = [[GFPAdParam alloc]init];
    adParam.yearOfBirth = 1990;
    adParam.gender = GFPAdParamGenderTypeMale;
    ...

    self.adLoader = [[GFPAdLoader alloc] initWithUnitID:self.unitID
                                             rootViewController:self
                                                        adParam:adParam];
        
    GFPAdNativeOptions *nativeOptions = [[GFPAdNativeOptions alloc] init];
    nativeOptions.renderingSetting = ...; // Rendering settings for the native ad to be loaded
    [self.adLoader setNativeDelegate:self nativeOptions:nativeOptions];
    
    // Request ad
    self.adLoader.delegate = self;
    [self.adLoader loadAd];
}

tip

When an ad request succeeds, the adLoader:didReceiveNativeAd: method of GFPAdLoaderDelegate is called.

GFPAdLoaderDelegate

By implementing GFPAdLoaderDelegate, you can receive ad load-related events through the corresponding methods.

On Ad Load Success

When a native ad loads successfully, a GFPNativeAd object is returned as the response.
You use the GFPNativeAd object to create the native ad view (UIView). For instructions on how to build a native ad view using the GFPNativeAd object, refer to the native ad view creation section.

Swift

func adLoader(_ unifiedAdLoader: GFPAdLoader!, didReceive nativeAd: GFPNativeAd!) {
      // Create ad view using the nativeAd object
      ...
}

Objective-C

- (void)adLoader:(GFPAdLoader *)unifiedAdLoader didReceiveNativeAd:(GFPNativeAd *)nativeAd {
      // Create ad view using the nativeAd object
      ...
}

On Ad Load Failure

Swift

func adLoader(_ unifiedAdLoader: GFPAdLoader!, didFailWithError error: GFPError!, responseInfo: GFPLoadResponseInfo!) {
    ...
}

Objective-C

- (void)adLoader:(GFPAdLoader *)unifiedAdLoader didFailWithError:(GFPError *)error responseInfo:(GFPLoadResponseInfo *)responseInfo {
    ...
}

Rendering Native Ads

Once GFPNativeAd has loaded successfully, you can render the native ad.
To do so, you need a view object that defines the elements of the native ad, and this object must subclass GFPNativeAdView. In this document, Interface Builder is used to configure the view.

Creating the Native Ad View

1. Create a view (xib) for the native ad and set the Custom Class to GFPNativeAdView in Xcode's Identity Inspector tab.

2. Create each asset view (title, body, etc.) that makes up the native ad view, and connect them to the corresponding outlets of GFPNativeAdView in the Connections Inspector tab.

• The mediaView used to display the ad's video or image must also have its Custom Class set to GFPMediaView.

GFPNativeAdView IBOutlet List

Outlet	Type	Description
mediaView	GFPMediaView	Media view displaying the ad image or video
iconView	UIImageView	Advertiser icon image
titleLabel	UILabel	Ad title
bodyLabel	UILabel	Ad body text
advertiserLabel	UILabel	Advertiser name
socialContextLabel	UILabel	Social context (e.g., "123 likes")
callToActionLabel	UILabel	Call-to-action button label
adChoicesView	UIView	AdChoices view (automatically inserted for DFP ads)
adBadgeLabel	UILabel	"Ad" badge label
noticeLabel	UILabel	Ad notice label
serviceAdBadgeView	UIView	Service ad badge view

socialContextLabel, adBadgeLabel, noticeLabel, and serviceAdBadgeView may not have values depending on the ad creative.

If additional labels are needed, you can register and retrieve them using the methods below.

Swift

// Register an additional label
nativeAdView.setExtraLabel(with: "custom_key", label: myLabel)

// Retrieve an additional label
let label = nativeAdView.extraLabel(with: "custom_key")

Objective-C

// Register an additional label
[nativeAdView setExtraLabelWith:@"custom_key" label:myLabel];

// Retrieve an additional label
UILabel *label = [nativeAdView extraLabelWith:@"custom_key"];

3. After loading the native ad, you can implement it in the following form.

Swift

func adLoader(_ unifiedAdLoader: GFPAdLoader!, didReceive nativeAd: GFPNativeAd!) { 

    // Register native ad object and delegate   
    self.nativeAd = nativeAd
    self.nativeAd?.delegate = self

    // Set native ad assets            
    self.nativeAdView?.titleLabel?.text = nativeAd.title
    self.nativeAdView?.bodyLabel?.text = nativeAd.body
    self.nativeAdView?.advertiserLabel?.text = nativeAd.advertiser
    self.nativeAdView?.callToActionLabel?.text = nativeAd.callToAction
    ...

    // Assigning the native ad to the view object starts iconView/mediaView rendering and view tracking.
    self.nativeAdView?.nativeAd = nativeAd

    // Add as subview
    self.view.addSubview(self.nativeAdView!)
}

Objective-C

- (void)adLoader:(GFPAdLoader *)unifiedAdLoader didReceiveNativeAd:(GFPNativeAd *)nativeAd {

    // Register native ad object and delegate
    self.nativeAd = nativeAd;
    self.nativeAd.delegate = self;
    
    // Set native ad assets
    self.nativeAdView.titleLabel.text = nativeAd.title;
    self.nativeAdView.bodyLabel.text = nativeAd.body;
    self.nativeAdView.advertiserLabel.text = nativeAd.advertiser;
    self.nativeAdView.callToActionLabel.text = nativeAd.callToAction;
    ...
    
    // Assigning the native ad to the view object starts iconView/mediaView rendering and view tracking. 
    self.nativeAdView.nativeAd = nativeAd;
    
    // Add as subview
    [self.view addSubview:self.nativeAdView]
}

GFPNativeAdDelegate

Events are delivered when the native ad is shown or clicked.

On Ad Impression

Swift

func nativeAdWasSeen(_ nativeAd: GFPNativeAd) {
    ...
}

Objective-C

- (void)nativeAdWasSeen:(GFPNativeAd *)nativeAd {
    ...
}

On Ad Rendered

Swift

func nativeAdWasRendered(_ nativeAd: GFPNativeAd) {
    ...
}

Objective-C

- (void)nativeAdWasRendered:(GFPNativeAd *)nativeAd {
    ...
}

On Click

Swift

func nativeAdWasClicked(_ nativeAd: GFPNativeAd) {
    ...
}

Objective-C

- (void)nativeAdWasClicked:(GFPNativeAd *)nativeAd {
    ...
}

On Rendering Error

Swift

func nativeAd(_ nativeAd: GFPNativeAd, didFailWithError error: GFPError) {
    ...
}

Objective-C

- (void)nativeAd:(GFPNativeAd *)nativeAd didFailWithError:(GFPError *)error {
    ...
}

When the Ad is Muted by the User

When an ad is muted, a callback notifies the service of the mute action. After muting, NAMSDK displays a screen saying "This ad will no longer be shown." Whether to remove the ad from the screen or continue displaying it is determined by the service's own policy.

Swift

func nativeAdWasMuted(_ nativeAd: GFPNativeAd) {
    
}

Objective-C

- (void)nativeAdWasMuted:(GFPNativeAd *)nativeAd {

}

On Mute Cancelled

Swift

func nativeAdWasCanceledMute(_ nativeAd: GFPNativeAd) {

}

Objective-C

- (void)nativeAdWasCanceledMute:(GFPNativeAd *)nativeAd {

}

In-App Browser Presented / Dismissed Events

Called when the default in-app browser is presented or dismissed after an ad click.

Swift

func nativeAdDidPresentDefaultInAppBrowser(_ nativeAd: GFPNativeAd) {
    // In-app browser presented
}

func nativeAdDidDismissDefaultInAppBrowser(_ nativeAd: GFPNativeAd) {
    // In-app browser dismissed
}

Objective-C

- (void)nativeAdDidPresentDefaultInAppBrowser:(GFPNativeAd *)nativeAd {
    // In-app browser presented
}

- (void)nativeAdDidDismissDefaultInAppBrowser:(GFPNativeAd *)nativeAd {
    // In-app browser dismissed
}

Resource Reload Events

Called when an ad resource reload succeeds or fails at the point a reload is needed.

Swift

func nativeAdDidReloaded(_ nativeAd: GFPNativeAd) {
    // Reload succeeded
}

func nativeAd(_ nativeAd: GFPNativeAd, didReloadFailWithError error: GFPError) {
    // Reload failed
}

Objective-C

- (void)nativeAdDidReloaded:(GFPNativeAd *)nativeAd {
    // Reload succeeded
}

- (void)nativeAd:(GFPNativeAd *)nativeAd didReloadFailWithError:(GFPError *)error {
    // Reload failed
}

userInterestDelegate

Setting GFPNativeAd.userInterestDelegate lets you receive notifications when the user's interest in the ad changes.

Swift

self.nativeAd?.userInterestDelegate = self

// GFPUserInterestDelegate
func ad(_ ad: NSObject, didChangeUserInterest userInterest: Bool) {
    // userInterest: whether the user is showing interest in the ad
}

Objective-C

self.nativeAd.userInterestDelegate = self;

// GFPUserInterestDelegate
- (void)ad:(NSObject *)ad didChangeUserInterest:(BOOL)userInterest {
    // userInterest: whether the user is showing interest in the ad
}

Other

Rendering Native Ads Using the Ad Provider's Native Ad Object Directly

The GFPNativeAd object holds the original native object obtained from the native ad provider, accessible via the adProviderNativeAd field of the GFPNativeAd object.

Additionally, the adProviderType of the GFPNativeAd object identifies which ad provider the currently loaded native ad belongs to. By upcasting the adProviderNativeAd object to the corresponding provider's native type based on adProviderType, you can access each ad provider's original native object.

Finally, using this original native object, you build the native ad view according to each ad provider's guide.

Swift

import FBAudienceNetwork    // FAN SDK
import GoogleMobileAds      // DFP SDK

func adLoader(_ unifiedAdLoader: GFPAdLoader!, didReceive nativeAd: GFPNativeAd!) {

    // Register native ad object and delegate   
    self.nativeAd = nativeAd
    self.nativeAd?.delegate = self

    if nativeAd.adProviderType == .FAN {
        // FAN native ad case
        ...            
    } else if nativeAd.adProviderType == .DFP {
        // DFP native ad case
        ...
    }
}

Objective-C

@import FBAudienceNetwork;    // FAN SDK
@import GoogleMobileAds;      // DFP SDK

- (void)adLoader:(GFPAdLoader *)unifiedAdLoader didReceiveNativeAd:(GFPNativeAd *)nativeAd {

    // Register native ad object and delegate
    self.nativeAd = nativeAd;
    self.nativeAd.delegate = self;

    if (_nativeAd.adProviderType == GFPNativeAdProviderTypeFAN) {
        // FAN native ad case
        ...


    } else if (gfpNativeAd.adProviderType == GFPNativeAdProviderTypeDFP) {
        // DFP native ad case
        ...
    }

}

Native Ad Implementation Guides by Provider

• Facebook FAN Guide
• Google DFP Guide
• InMobi Guide

Ad Invalidation Check

Native ads have an expiration time, so when displaying preloaded and cached ads, you must use the isAdInvalidate method to check whether the ad has expired. Displaying an expired ad will not earn you any compensation for the impression.

Swift

func adLoader(_ unifiedAdLoader: GFPAdLoader!, didReceive nativeAd: GFPNativeAd!) {

    // Register native ad object and delegate   
    self.nativeAd = nativeAd
    self.nativeAd?.delegate = self

    // Check if ad is already expired or invalidated, and do not show ad if that is the case.
    // You will not get paid to show an invalidated ad.
    if nativeAd.isAdInvalidate {
        print("This ad has been invalidated. Try again!")
        return
    }
}

Objective-C

- (void)adLoader:(GFPAdLoader *)unifiedAdLoader didReceiveNativeAd:(GFPNativeAd *)nativeAd {

    // Register native ad object and delegate
    self.nativeAd = nativeAd;
    self.nativeAd.delegate = self;

    // Check if ad is already expired or invalidated, and do not show ad if that is the case.
    // You will not get paid to show an invalidated ad.
    if (nativeAd.isAdInvalidate) {
        NSLog(@"This ad has been invalidated. Try again!");
        return;
    }
}