VK Ad SDK provides the ability to display ads in your app using native visual components.
The SDK loads the ad and gives the app an ad model with specific properties and methods for counting impressions and handing clicks.
The API also provides a build-in visual component that you can use in your app, instead of creating your own.
Initialization
To display native ads in your app, you must create an instance of the MTRGNativeAd class and specify your slotId.
@interface YourViewController : UIViewController@end@implementation YourViewController{ MTRGNativeAd *_ad;}- (void)initAd{ // Enabling debug mode // [MTRGManager setDebugMode:YES]; // Create an instance of MTRGNativeAd _ad = [MTRGNativeAd nativeAdWithSlotId:YOUR_SLOT_ID];}
Loading ads
To receive notifications (such as a successful data download or a download error, a click on an ad), you must set the created instance of MTRGNativeAd to a delegate that implements the MTRGNativeAdDelegate protocol, and then you can start the data download.
@interface YourViewController : UIViewController <MTRGNativeAdDelegate>@end@implementation YourViewController{ MTRGNativePromoAd *_ad;}- (void)initAd{ // Create an instance of MTRGNativeAd _ad = [MTRGNativeAd nativeAdWithSlotId:YOUR_SLOT_ID]; // Set the delegate _ad.delegate = self; // Start loading ad [_ad load];} - (void)onLoadWithNativePromoBanner:(MTRGNativePromoBanner *)promoBanner nativeAd:(MTRGNativeAd *)nativeAd{} - (void)onNoAdWithReason:(NSString *)reason nativeAd:(MTRGNativeAd *)nativeAd{} - (void)onAdClickWithNativeAd:(MTRGNativeAd *)nativeAd{} - (void)onShowModalWithNativeAd:(MTRGNativeAd *)nativeAd{} - (void)onDismissModalWithNativeAd:(MTRGNativeAd *)nativeAd{} - (void)onLeaveApplicationWithNativeAd:(MTRGNativeAd *)nativeAd{}- (void)onVideoPlayWithNativeAd:(MTRGNativeAd *)nativeAd{}- (void)onVideoPauseWithNativeAd:(MTRGNativeAd *)nativeAd{}- (void)onVideoCompleteWithNativeAd:(MTRGNativeAd *)nativeAd{}
Media download policy
The loading policy specifies the behaviour of the SDK if it fails to load media files for advertisements. The policy is set in the bannerMediaRecovery property of instances of MTRGNativeAd and MTRGNativeAdLoader classes. Valid values are skip (default) and retry.
If MTRGNativeAd fails to load media files on autoload, then at:
- skip, SDK will finish loading all adverts and call the
onLoadFailedWithError:nativeAddelegate method: - retry, the SDK will retry loading the media a specified number of times. If the media files still fail to load,
onLoadFailedWithError:nativeAd:will be called in the delegate.
If MTRGNativeAdLoader failed to load the media files in the banner on autoload, when:
- skip, SDK will skip this banner. And it will not affect the loading of other banners loader.
- retry, SDK will repeat loading media for this banner the specified number of times. If it still fails to load them, SDK will skip this banner.
The policy is also taken into account when autoloading is turned off, when media files are loaded asynchronously at the moment of registerView method call.
When autoloading is disabled, if MTRGNativeAd fails to load media files into registerView, then the:
- skip, SDK will cancel media files that have not yet been downloaded and call the
onMediaLoadFailedWithNativeAd: method of mediaDelegate. - retry, the SDK will retry loading the media files a specified number of times. If it still fails to load them, the
onMediaLoadFailedWithNativeAd:method ofmediaDelegatewill be called.
In addition to the upload policy, it is also possible to set a timeout for media files to be uploaded. It is set in the bannerMediaTimeout property and applies to media files within the banner.
Autoloading images and video
By default, all media objects (images, videos) of the ad banner are loaded and cached. You can switch off automatic loading of images and/or videos, but you should take into account that it will take additional time to load them, which will create an additional delay in displaying ads in your application.
_ad.cachePolicy = MTRGCachePolicyNone;[_ad load];
Valid values: MTRGCachePolicyAll (default), MTRGCachePolicyImages, MTRGCachePolicyVideo, MTRGCachePolicyNone.
If preloading is enabled, the corresponding media files (images and/or video) will be downloaded and stored in the cache in parallel with the loading of the main banner ad data.
If image preloading is disabled, images will be asynchronously loaded automatically when the registerView method is called. No additional actions are required.
Notifications about media files downloading
In order to receive notifications about media files downloading (in case of non-automatic downloading) it is necessary to implement the MTRGNativeAdMediaDelegate protocol and set the mediaDelegate property of the MTRGNativeAd object.
@protocol MTRGNativeAdMediaDelegate <NSObject>- (void)onIconLoadWithNativeAd:(MTRGNativeAd *)nativeAd;- (void)onImageLoadWithNativeAd:(MTRGNativeAd *)nativeAd;- (void)onAdChoicesIconLoadWithNativeAd:(MTRGNativeAd *)nativeAd;- (void)onMediaLoadFailedWithNativeAd:(MTRGNativeAd *)nativeAd;@end
Ad Closing Notifications and Ad Closing Management
In order to receive ad closing notifications and manage ad closing it is necessary to set a delegate that implements the MTRGNativeAdChoicesOptionDelegate protocol in the adChoicesOptionDelegate property. The protocol contains several methods.
- shouldCloseAutomatically - informs SDK whether to automatically close ads. If the method returns YES, the SDK will automatically hide the ads. If NO, the ability to hide is given to the developer. The method is optional and returns YES by default.
- onCloseAutomatically - notifies the developer that the ad has been automatically hidden by the SDK. So this method will be called only if shouldCloseAutomatically returns YES.
- closeIfAutomaticallyDisabled - notifies the developer that he needs to hide the ads himself. So this method will be called only if shouldCloseAutomatically returns NO.
Displaying ads
After successfully loading the ad, you can use the properties of the banner object to initialize your visual component. Which properties are available depends on what is being advertised, i.e. they differ for apps and websites.
To display icon image you should use MTRGIconAdView class. To display main image, carousel and video playback, you must use an instance of MTRGMediaAdView class from myTarget SDK.
myTargetSDK automatically detects if MTRGMediaAdView is contained within visual component and adds a horizontal cards slider (if cards exists in banner) or video (if there is no cards but video exists).
After initializing a visual component, use the registerView method to register it with the MTRGNativeAd instance. If you are going to use the same visual component to display other ads, you must first call the unregisterView method on the current MTRGNativeAd instance before calling registerView on another MTRGNativeAd instance. Impressions and clicks are processed automatically, and the application should not block or capture user touch events on this visual component. The properties available are described below, and examples of initializing visual components for different types of banners are given.
Visual components (built-in and custom) should be embedded into MTRGNativeAdContainer object.
You can pass either component itself or container when call method registerView.
When container created, visual component adView will be added as subview of container and will fit it's bounds.
In order to calculate height of visual component depending on it's width (required for TableView/CollectionView), you can call method sizeThatFits of container object.
When container created, you should setup bindings between properties of visual component (adView) and container's properties.
- (void)onLoadWithNativePromoBanner:(MTRGNativePromoBanner *)promoBanner nativeAd:(MTRGNativeAd *)nativeAd{ // Ad title NSString *title = promoBanner.title; // Main text NSString *descriptionText = promoBanner.descriptionText; // Age restriction. Can be nil NSString *ageRestrictions = promoBanner.ageRestrictions; // Disclaimer. Can be nil NSString *disclaimer = promoBanner.disclaimer; // "Advertising" label text NSString *advertisingLabel = promoBanner.advertisingLabel; // Icon MTRGImageData *icon = promoBanner.icon; // Call-to-action text for the button NSString *ctaText = promoBanner.ctaText; // Properties available only for ads promoting apps if (promoBanner.navigationType == MTRGNavigationTypeStore)) { // App rating (0-5) NSNumber *rating = promoBanner.rating; // Number of votes NSUInteger votes = promoBanner.votes; // App category NSString *category = promoBanner.category; // App subcategory NSString *subcategory = promoBanner.subcategory; } // Properties available only for ads promoting websites else if (promoBanner.navigationType == MTRGNavigationTypeWeb) { // Website domain NSString *domain = promoBanner.domain; } // Example of filling a visual component UIView *adView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 300, 300)]; UILabel *titleLabel = [[UILabel alloc] initWithFrame:CGRectMake(70, 10, 200, 20)]; titleLabel.text = title; UILabel *descLabel = [[UILabel alloc] initWithFrame:CGRectMake(70, 50, 200, 40)]; descLabel.text = descriptionText; UIButton *ctaButton = [[UIButton alloc] initWithFrame:CGRectMake(210, 260, 80, 30)]; [ctaButton setTitle:ctaText forState:UIControlStateNormal]; // Create an instance of MTRGMediaAdView MTRGMediaAdView *mediaView = [MTRGNativeViewsFactory createMediaAdView]; mediaView.frame = CGRectMake(10, 100, 280, 150); MTRGIconAdView *iconAdView = [MTRGNativeViewsFactory createIconAdView]; iconAdView.frame = CGRectMake(10, 10, 50, 50); [adView addSubview:titleLabel]; [adView addSubview:descLabel]; [adView addSubview:iconAdView]; [adView addSubview:mediaView]; [adView addSubview:ctaButton]; MTRGNativeAdContainer *containerView = [MTRGNativeAdContainer createWithAdView:adView]; containerView.titleView = titleLabel; containerView.descriptionView = descLabel; containerView.iconView = iconAdView; containerView.mediaView = mediaView; containerView.ctaView = ctaButton; // Register the view [nativeAd registerView:containerView withController:self]; // Add it to the screen [self.view addSubview:containerView];}
Native ad assets
The library contains both mandatory and optional elements. The rules of ad placement require only mandatory elements to be displayed.
However, layouts with a full set of components are more clickable, so we recommend using them.
| Ad asset | Required |
| Advertising label | Yes |
| Age restrictions | Yes |
| Disclaimer | Yes |
| Domain | Yes |
| Title | Yes |
| Menu icon | Yes |
| Icon | Yes, for app ads |
| Call-to-action | Yes |
| MediaAdView | Yes |
| Description | No |
| Rating | No |
Use a layout that displays the entire set of mandatory and optional ad components
Setting size of MediaAdView
Aspect ratio of loaded image can be different to size of mediaView and you should adjust size using actual mediaAdView.aspectRatio value.
Notification about size change can be received using delegate onImageSizeChanged of object mediaAdView
mediaAdView.delegate = self;- (void)onImageSizeChanged:(MTRGMediaAdView *)mediaAdView{ CGFloat currentAspect = mediaView.frame.size.width / mediaView.frame.size.height; NSLog(@"current aspect of media view: %f", currentAspect); CGFloat actualAspect = mediaView.aspectRatio; NSLog(@"actual aspect of media view: %f", actualAspect);}
AdChoices icon
VK Ad SDK automatically adds an adChoices icon to each visual component. By default, the icon is added to the top-right corner of the visual component, but you can choose your preferred corner with the adChoicesPlacement property:
..._ad.adChoicesPlacement = MTRGAdChoicesPlacementTopRight;[_ad load];
Manual positioning of the AdChoices icon
To manually position the icon, set the adChoicesPlacement property to MTRGAdChoicesPlacementManual. Then, when configuring the visual component, you need to create an MTRGAdChoicesView and add it to the ad component. This way you can control the position and size of the adChoices icon, as well as set your own picture.
If no picture has been installed, the SDK will put its AdChoices icon in the MTRGAdChoicesView after you register the visual component in the ad object.
- (void)setupAdChoicesView{ _ad.adChoicesPlacement = MTRGAdChoicesPlacementManual; MTRGAdChoicesView *adChoicesView = MTRGNativeViewsFactory.createAdChoicesView; // Set your picture adChoicesView.imageView.image = [UIImage imageNamed:@"AdChoices"]; [_adView addSubview:adChoicesView]; // You can use Autolayout or frames to position and size adChoicesView}
Manual rendering of the AdChoices icon
To fully control the AdChoices display component, you need to set adChoicesPlacement property to MTRGAdChoicesPlacementDrawingManual. Then the creation, content display, icon placement and click handling are completely up to the developers.
However, the SDK provides an AdChoices icon that you can use in your component (the "Auto-loading images and videos" and "Notification of successful uploading of Assets" items).
Get information about the presence of AdChoices (hasAdChoices property) and the icon (adChoicesIcon property) from MTRGNativePromoBanner.
To notify SDK that the AdChoices icon has been clicked, the handleAdChoicesClickWithController:sourceView: method must be called on the ad object.
- (void)setupAdChoicesView{ _ad.adChoicesPlacement = MTRGAdChoicesPlacementDrawingManual; _adChoicesButton = UIButton.new; [_adChoicesButton setImage:_ad.banner.adChoicesIcon.image forState:UIControlStateNormal]; [_adChoicesButton addTarget:self action:@selector(adChoicesClick) forControlEvents:UIControlEventTouchUpInside]; [_adView addSubview:_adChoicesButton]; // You can use Autolayout or frames to position and size adChoicesImageView}// Notify SDK that the AdChoices component has been clicked- (void)adChoicesClick{ [_ad handleAdChoicesClickWithController:self sourceView:_adChoicesButton];}
Setting clickable area
In the example above, the visual component is registered using the registerView:withController method. In this case, the entire area of the visual component is clickable. MyTarget SDK provides the ability to register list of visual components that can be clicked. To do this, use the registerView:withController:withClickableViews method:
- (void)onLoadWithNativePromoBanner:(MTRGNativePromoBanner *)promoBanner nativeAd:(MTRGNativeAd *)nativeAd{ ... ... ... // Register the view with clickable titleView and button [nativeAd registerView:adView withController:self withClickableViews:@[titleLabel, ctaButton]]; // Add it to the screen [self.view addSubview:adView];}
Managing the display of the AdChoices menu
To control the display of AdChoices options, you need to pass an object that implements the MTRGMenuFactory protocol to the corresponding initializer. The protocol requires to implement a method to create a menu. The menu, on the other hand, must implement the MTRGMenu protocol. By default, the SDK uses the UIAlertController with the actionSheet style.
// Example of menu implementation// Add MTRGMenuAction model to _items. An array of objects to be shown in the menu- (void)addMenuAction:(nonnull MTRGMenuAction *)action{ [_items addObject:action];}// Based on _items, create a UIAlertController and display it- (void)presentInViewController:(nonnull UIViewController *)viewController sourceView:(nullable UIView *)sourceView{ UIAlertControllerStyle style = UIAlertControllerStyleAlert; MTRGAlertController *alert = [MTRGAlertController alertControllerWithTitle:nil message:nil preferredStyle:style]; for (MTRGMenuAction *item in _items.copy) { UIAlertActionStyle actionStyle = (item.style == MTRGMenuActionStyleDefault) ? UIAlertActionStyleDefault : UIAlertActionStyleCancel; UIAlertAction *action = [UIAlertAction actionWithTitle:item.title style:actionStyle handler:^(UIAlertAction * _Nonnull action) { [item handleClick]; }]; [alert addAction:action]; } [viewController presentViewController:alert animated:YES completion:nil];}
Using built-in visual component
VK Ad SDK provides built-in visual component whose appearance you can customize to fit the design of your app.
We give an example below and describe the settings available.
MTRGNativeAdView
- (void)onLoadWithNativePromoBanner:(MTRGNativePromoBanner *)promoBanner nativeAd:(MTRGNativeAd *)nativeAd{ // Create an instance of MTRGNativeAdView MTRGNativeAdView *adView = [MTRGNativeViewsFactory createNativeAdView]; adView.banner = promoBanner; // Available for customization internal views UILabel *titleLabel = adView.titleLabel; UILabel *descriptionLabel = adView.descriptionLabel; MTRGIconAdView *iconAdView = adView.iconAdView; MTRGMediaAdView *mediaView = adView.mediaAdView; UILabel *domainLabel = adView.domainLabel; UILabel *categoryLabel = adView.categoryLabel; UILabel *disclaimerLabel = adView.disclaimerLabel; MTRGStarsRatingView *ratingStarsView = adView.ratingStarsView; UILabel *votesLabel = adView.votesLabel; UIView *buttonView = adView.buttonView; UILabel *buttonToLabel = adView.buttonToLabel; UILabel *ageRestrictionsLabel = adView.ageRestrictionsLabel; UILabel *adLabel = adView.adLabel; // Margins UIEdgeInsets titleMargins = adView.titleMargins; UIEdgeInsets domainMargins = adView.domainMargins; UIEdgeInsets categoryMargins = adView.categoryMargins; UIEdgeInsets descriptionMargins = adView.descriptionMargins; UIEdgeInsets disclaimerMargins = adView.disclaimerMargins; UIEdgeInsets imageMargins = adView.imageMargins; UIEdgeInsets iconMargins = adView.iconMargins; UIEdgeInsets ratingStarsMargins = adView.ratingStarsMargins; UIEdgeInsets votesMargins = adView.votesMargins; UIEdgeInsets buttonMargins = adView.buttonMargins; UIEdgeInsets buttonCaptionMargins = adView.buttonCaptionMargins; UIEdgeInsets adLabelMargins = adView.adLabelMargins; UIEdgeInsets ageRestrictionsMargins = adView.ageRestrictionsMargins; // Register the view [nativeAd registerView:adView withController:self]; // Add it to the screen [self.view addSubview:adView];}
Loading multiple banners
VK Ad SDK provides the MTRGNativeAdLoader class, which allows you to load from 1 to 20 banners with a single request.
For MTRGNativeAdLoader, you can configure all the same settings that are available for configuration in MTRGNativeAd (for example, user gender and age settings, autoloading images and videos).
VK Ad SDK does not guarantee that the number of banners specified in the COUNT parameter will be loaded - this parameter indicates the maximum number of banners you want to receive.
// Enable debug mode// [MTRGManager setDebugMode:YES];// Creating MTRGNativeAdLoaderMTRGNativeAdLoader *nativeAdLoader = [MTRGNativeAdLoader loaderForCount:COUNT slotId:YOUR_SLOT_ID];// Loading banners[nativeAdLoader loadWithCompletionBlock:^(NSArray<MTRGNativeAd *> * _Nonnull nativeAds){ for (MTRGNativeAd *nativeAd in nativeAds) { // Installing the delegate nativeAd.delegate = self; MTRGNativePromoBanner *promoBanner = nativeAd.banner; // Code similar to protocol MTRGNativeAdDelegate method onLoadWithNativePromoBanner } }}];
The resulting array will contain from 0 to COUNT MTRGNativeAd objects - each of them contains an already loaded MTRGNativePromoBanner and each of them must be treated in the same way as described in this documentation above, starting with calling the onLoadWithNativePromoBanner method.
Mediation with other advertising SDKs
Mediation with Mopub SDK is supported for native advertising.