Native Ads Integration For iOS english - unigeniee/Geniee-iOS-SDK GitHub Wiki

Native Ads Integration For iOS

In the native advertising, SDK is providing advertising content ( parts ), rather than to provide a compleated ad layout.
Therefore it is possible to delivery to advertisment in the original design, whatever you want to title, description text, icons etc.
Ads SDK processes Ad impressions , Ad clicks of tracking.

Preparation

Preparation Integration for Native Ads, please look at [Install iOS SDK] below :

Install iOS SDK

Class and Protocol

Class for iOS Native Ad

GNNativeAdRequest : Class to Request Native Ad with asynchronous
GNNativeAd : Class to provide information of Native Ad
GNNativeAdRequestDelegate : Protocol to receive loading event of Native Ad

Request Native Ad

Add GNAdSDK.framework to your project.
Install iOS SDK

Import GNNativeAdRequest.h, GNNativeAd.h

#import <GNAdSDK/GNNativeAdRequest.h>
#import <GNAdSDK/GNNativeAd.h>

Use GNNativeAdRequestDelegate Protocol

@interface TableViewController () <GNNativeAdRequestDelegate>
{
}

Declare GNNativeAdRequest variable
```
GNNativeAdRequest *_nativeAdRequest;
```

Initialize GNNativeAdRequest instance

_nativeAdRequest = [[GNNativeAdRequest sharedManager] initWithID:@"YOUR_SSP_APP_ID"];

multiAd Example for using Initialize API

 _nativeAdRequest = [[GNNativeAdRequest sharedManager] initWithID:@"YOUR_SSP_APP_ID,YOUR_SSP_APP_ID2,...."];

Set up GNNativeAdRequest delegate Notice result of native ad loading event through the delegate. Set the instance of GNNativeAdRequestDelegate to this delegate.
```
_nativeAdRequest.delegate = self;
```
Load Native Ad

single Ad.
```
[_nativeAdRequest loadAds];
```
multi Ad.
```
[_nativeAdRequest multiLoadAds];
```

Implement GNNativeAdRequestDelegate Protocol Implement callback function of GNNativeAdRequestDelegate to receive the result of native ad loading event.

- (void)nativeAdRequestDidReceiveAds:(NSArray*)nativeAds;
- (void)nativeAdRequest:(GNNativeAdRequest *)request didFailToReceiveAdsWithError:(NSError *)error;

Received native ads is return by an array of GNNativeAd arguments. You can use the zoneID field of GNNativeAd to determine which ad has been received. The number of elements in the array GNNativeAd : - one : Set up one APP_ID when Initialize GNNativeAdRequest

Set up delegate to nil, when instance of GNNativeAdRequest is released.
```
- (void)dealloc
{
    _nativeAdRequest.delegate = nil;
}
```

e.g Implementation of UITableViewController :

#import <GNAdSDK/GNNativeAdRequest.h>
#import <GNAdSDK/GNNativeAd.h>

@interface TableViewController () <GNNativeAdRequestDelegate>
{
    GNNativeAdRequest *_nativeAdRequest;
}
@property (nonatomic, strong) NSMutableArray *cellDataList;
@end

@implementation TableViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    _nativeAdRequest = [[GNNativeAdRequest sharedManager] initWithID:@"YOUR_SSP_APP_ID"];
    _nativeAdRequest.delegate = self;
    [_nativeAdRequest multiLoadAds];
}

- (void)nativeAdRequestDidReceiveAds:(NSArray*)nativeAds
{
    for (GNNativeAd *nativeAd in nativeAds) {
        // You can identify the GNNativeAd by using the zoneID field of GNNativeAd.
        //if ([nativeAd.zoneID isEqualToString:@"YOUR_SSP_APP_ID"]) {
        //    [_cellDataList addObject:nativeAd];
        //}
        [_cellDataList addObject:nativeAd];
    }
}

- (void)nativeAdRequest:(GNNativeAdRequest *)request didFailToReceiveAdsWithError:(NSError *)error
{
    NSLog(@"TableViewController: didFailToReceiveAdsWithError : %@.", [error localizedDescription]);
}

Rendering Native Ad

You need to render Native Ad based on information of received data

The type of information data reffer to GNNativeAd.h class
If the information data (NSString type) is not set , it will be nil

If the information data (int, double type) is not set , it will be 0

Name	Type	Data
zoneID	NSString	ID for zone in Geniee
advertiser	NSString	Name of client
title	NSString	Title of feed advertisement
description	NSString	description of advertisment
cta	NSString	text for call to action
icon_aspectRatio	double	Aspect ratio of icon image
icon_url	NSString	URL of icon image
icon_height	int	heigh of icon
icon_width	int	width of icon
screenshots_aspectRatio	double	aspect ratio of screenshot
screenshots_url	NSString	URL of screenshot image
screenshots_height	int	heigh of screenshot image
screenshots_width	int	width of screenshot image
app_appName	NSString	Name of app
app_appid	NSString	App ID(ios:number、Android:package)
app_rating	double	Evaluation of App
app_storeURL	NSString	URL of app store
app_targetAge	NSString	Target age of app (e.g:ios App:rating)

e.g.:Implementation of UITableViewController : When Setting is information of native ad in dashboard below :

title
description
icon image URL

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView
{
    return 1;
}

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    return _cellDataList.count;
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"SampleDataCell";
    TableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier forIndexPath:indexPath];

    if ([_cellDataList objectAtIndex:indexPath.row] isKindOfClass:[GNNativeAd class](/unigeniee/Geniee-iOS-SDK/wiki/_cellDataList-objectAtIndex:indexPath.row]-isKindOfClass:[GNNativeAd-class)) {
        GNNativeAd *nativeAd = (GNNativeAd *)[_cellDataList objectAtIndex:indexPath.row];
        if (nativeAd != nil) {
            cell.nativeAd = nativeAd;
            cell.title.text = nativeAd.title;
            cell.description.text = nativeAd.description;
            cell.icon.image = nil;
            NSURL *url = [NSURL URLWithString:nativeAd.icon_url];
            [TableViewController requestImageWithURL:url completion:^(UIImage *image, NSError *error) {
                if (error) return;
                cell.icon.image = image;
            }];
            [nativeAd trackingImpressionWithView:cell];
        }
    }　else {
        // The other cell rendering (not GNNativeAd)
    }
    return cell;
}

You can refer to GNNativeAd.h class to know opt-out information.

Name	Type	Data
optout_text	NString	Text for displaying opt-out information
optout_image_url	NString	URL of Opt-out image
optout_url	NString	URL of Opt-out page

Get opt-out information from SDK You can use instance of GNNativeAd.h nativeAd to access opt-out information

NString *optout_text = nativeAd.optout_text;
NString *optout_image_url = nativeAd.optout_image_url;
NString *optout_url = nativeAd.optout_url;

Fire click for Opt-out When User clicks to open Opt-out page for setting information, you will open optout_url from your Application

Note: Sometime optout_url can be empty (It means this Ad not support to setup optout information)

Image of UITableViewController

Impression report for Native Ad

You need to report the imoression of advertisment When the Native Ad is rendered.
It is not possible to report for imoression reported again.
You need to request Native Ad again to display new advertismsent.
```
[nativeAd trackingImpressionWithView:cell];
```

Click tracking for Native Ad

When the native ad is clicked, it will start the landing page of advertising in an external browser.
```
[nativeAd trackingClick];
```

e.g.: implementation of UITableViewController

-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    TableViewCell *cell = (TableViewCell*)[tableView cellForRowAtIndexPath:indexPath];
    if (cell.nativeAd != nil) {
        [cell.nativeAd trackingClick];
    } else {
        // The other cell rendering (not GNNativeAd)
    }
}

Control screen transition of the landing page

Landing page of ads start in an external browser by default. It is possible to start in apps browser, when the callback function of GNNativeAdRequestDelegate is implemented And it is also possible to control the activation of an external browser by the returning function.

YES : It will start an external browser.

NO : It will not start the external browser.

- (BOOL)shouldStartExternalBrowserWithClick:(GNNativeAd *)nativeAd landingURL:(NSString *)landingURL;

Re-request Native Ad

It is neccesary to re-request native ads to display new advertismsent.
- single Ad.
```
[_nativeAdRequest loadAds];
```
- multi Ad.
```
 [_nativeAdRequest multiLoadAds];
```

e.g.: UITableViewController

- (void)scrollViewDidScroll:(UIScrollView *)scrollView
{
    [_nativeAdRequest loadAds]; or [_nativeAdRequest multiLoadAds];
}

It receive the result by callback of GNNativeAdRequestDelegate

- (void)nativeAdRequestDidReceiveAds:(NSArray*)nativeAds;
- (void)nativeAdRequest:(GNNativeAdRequest *)request didFailToReceiveAdsWithError:(NSError *)error;

Movie Native Ad

By adding option to allow movies with Native Ad setting information from the management screen, you can acquire video native advertisement.

Classes and Protocol

Video native ads use the following video player classes and protocols.

GNSNativeVideoPlayerView Class for providing video Native Player View.
GNSNativeVideoPlayerDelegate Protocol for receiving video native player's event notification.

Data acquisition for movie native

When viewing movie native ads, please use hasVideoContent() from GNNativeAd instance to make motion picture judgment.

Method	Return type	Contents
hasVideoContent	BOOL	Video ads holding decision

 - (void)nativeAdRequestDidReceiveAds:(NSArray*)nativeAds
 {
     for (GNNativeAd *nativeAd in nativeAds) {
         if ([nativeAd hasVideoContent]) {
             //video implements
         }
     }
 }

Native video implementation method

Import GNSNativeVideoPlayerView header file and add Delegate.

#import <GNAdSDK/GNNativeAdRequest.h>
#import <GNAdSDK/GNNativeAd.h>
#import <GNAdSDK/GNSNativeVideoPlayerView.h>
@interface ViewController <GNSNativeVideoPlayerDelegate>

Generate instances of GNSNativeVideoPlayerView and add views.

Example of generation from GNNativeAd.

GNSNativeVideoPlayerView videoView = [nativeAd getVideoView]; // GNNativeAd nativeAd
[containerView addSubview:videoView]

Example of generation on the application side.

GNSNativeVideoPlayerView videoView = [[GNSNativeVideoPlayerView alloc] initWithFrame:rect]; // CGRect rect
[containerView addSubview:videoView]

Implement the method of GNSNativeVideoPlayerDelegate, Receive video native player's event.

@required
// Sent when an video ad request succeeded.
- (void)onVideoReceiveSetting:(GNSVideoPlayerView*)view;
@optional
// Sent when an video ad request failed.
- (void)onVideoFailWithError:(GNSVideoPlayerView*)view error:(NSError *)error;

// Sent when an video ad play started.
- (void)onVideoStartPlaying:(GNSVideoPlayerView*)view;

// Sent when an video ad okay completed.
- (void)onVideoPlayComplete:(GNSVideoPlayerView*)view;

To distribute multiple native ads, use the GNSNativeVideoPlayerView information of the first argument of load completion.

Set GNSNativeVideoPlayerDelegate to GNSNativeVideoView.

videoView.nativeDelegate = self; // self implemented GNSNativeVideoPlayerDelegate

Set GNNativeAd as an argument and make a video request.

If you generate GNSNativeVideoPlayerView from NativeAd, request it below.
```
[videoView load];
```
If you generate GNSNativeVideoPlayerView on the application side, you set GNNativeAd as an argument and make a video request.
```
[videoView load:nativeAd]
```

If you can prepare the movie, it will judge the movie preparation completion and start the movie.

- (void)onVideoReceiveSetting:(GNSVideoPlayerView*)view {
    // Video preparation completion determination
    if ([videoView isReady]) {
        // Video playback start
        [videoView show];
    }
}

The following values can be acquired as options.

   // Release of videoView
   [videoView remove];
   // Set the mute
   [videoView setMuted:YES]
   // get the mute
   [videoView getMuted]; // true or false, default true
   // Width of video size
   int *width = [videoView getMediaFileWidth]; // 1600
   // Height of video size
   int *height = [videoView getMediaFileHeight]; // 900
   // aspect of video size
   float *aspect = [videoView getMediaFileAspect]; // 1.777..

How to continue to play videos even when the terminal rotates

Please use the following IF to change the size of GNSNativeVideoPlayerView according to the size at terminal rotation.

   -(void)viewDidAppear:(BOOL)animated
   {
       // Rotation notification registration.
       [[UIDevice currentDevice] beginGeneratingDeviceOrientationNotifications];
       NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
       [nc addObserver:self selector:@selector(didChangedOrientation:) name:UIDeviceOrientationDidChangeNotification object:nil];
   }

   - (void)viewDidDisappear:(BOOL)animated
   {
       // Release of rotation notification.
       NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
       [nc removeObserver:self name:UIDeviceOrientationDidChangeNotification object:nil];
       [[UIDevice currentDevice] endGeneratingDeviceOrientationNotifications];
   }

- (void)didChangedOrientation:(NSNotification *)notification
{
   if (videoView) {
       CGRect frame = CGRectMake(0, 0, width, height)
       [videoView setFrame:frame];
   }
}

About stopping automatic playback of movies

As for movie native, the movie area stops playing according to the ratio of the terminal content display area as follows. Playback is stopped at the timing when the ratio changes due to scrolling or when switching to another application.

Movie playing condition ... When the moving picture area is 50% or more of the terminal contents display area
Movie stop condition ... When the moving image area is less than 50% of the terminal contents display area

About multiple videos

For movie display, we recommend one memory per screen due to memory load.
It is recommended to release unnecessary video instances.

Integration Ads SDK in Swift

It is neccesary to write an import statetment in header files to Objective-C bridging header file, when it utilized iOS SDK (Objective-C) class from Swift.

Add <name of project>-Bridging-Header.h file to project.

Add import in <name of project>-Bridging-Header.h file.

#import <GNAdSDK/GNNativeAdRequest.h>
#import <GNAdSDK/GNNativeAd.h>
#import <GNAdSDK/GNSNativeVideoPlayerView.h>

Set file name to [Build Settings] in project Choose the target and set the <name of Project>-Bridging-Header.h to [Build Settings]->[Swift Compiler]->[Code Generattion]->[Objective-C bridging header]