my Target SDK provides the ability to display ads in your application using your own visual components. The SDK downloads the data and provides the application with an ad model with certain properties for filling in the visual component, as well as methods for calculating impressions and processing clicks. The SDK also provides a ready-made, customizable visual component that you can use in your application, instead of creating your own.
The native banner does not support MTRGMediaAdView and therefore cannot display media content (videos, flashcards, large picture).
Initialization
To display native banners in your application, you need to create an instance of the MTRGNativeBannerAd class. To create an instance of MTRGNativeBannerAd, you must specify your slotId.
@interface YourViewController : UIViewController
@end
@implementation YourViewController
{
MTRGNativeBannerAd *_ad;
}
- (void)initAd
{
// Enabling debugging mode
// [MTRGManager setDebugMode:YES];
// Creating an instance of MTRGNativeAd
_ad = [MTRGNativeBannerAd nativeBannerAdWithSlotId:YOUR_SLOT_ID];
}
Loading ads
To receive notifications (such as a successful download of data or a download error, a click on an advertisement), you must install a delegate implementing the MTRGNativeBannerAd protocol for the created instance of MTRGNativeBannerAdDelegate, after which you can start downloading data.
@interface YourViewController : UIViewController <MTRGNativeBannerAdDelegate>
@end
@implementation YourViewController
{
MTRGNativePromoAd *_ad;
}
- (void)initAd
{
// Creating an instance of MTRGNativeAd
_ad = [MTRGNativeBannerAd nativeBannerAdWithSlotId:YOUR_SLOT_ID];
// Installing the delegate
_ad.delegate = self;
// Starting the data load
[_ad load];
}
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onLoadFailedWithError:(NSError *)error nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onAdShowWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onAdClickWithClickedView:(UIView *)clickedView nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onShowModalWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onDismissModalWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onLeaveApplicationWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
Media file upload policy
The upload policy sets the behavior of the SDK if it failed to upload media files for advertising. The policy is set in the bannerMediaRecovery property for instances of the MTRGNativeBannerAd and MTRGNativeBannerAdLoader classes. Acceptable values are skip (default) and retry.
If MTRGNativeBannerAd failed to download media files during startup, then when:
- skip, the SDK finishes loading all ads and calls the onLoadFailedWithError:nativeBannerAd delegate method.:
- retry, the SDK will repeat the media upload the specified number of times. If the media files still cannot be downloaded, onLoadFailedWithError:nativeBannerAd: will be called in the delegate.
If MTRGNativeBannerAdLoader failed to load media files in the banner during startup, then when:
- skip, the SDK will skip this banner. Moreover, it will not affect the loading of other banners in the loader.
- retry, the SDK will repeat the media download for this banner the specified number of times. If they still fail to download them, the SDK will skip such a banner.
The policy is also taken into account when auto-upload is turned off, when media files are loaded asynchronously at the time of calling the method Registrview.
With auto-upload turned off, if MTRGNativeBannerAd failed to upload media files to the registerView, then when:
- skip, the SDK will cancel the download of media files that have not yet been uploaded, and will call the onMediaLoadFailedWithNativeBannerAd: method for mediaDelegate.
- retry, the SDK will repeat the download of media files the specified number of times. If he still fails to load them, the onMediaLoadFailedWithNativeBannerAd: method will be called in mediaDelegate.
In addition to the download policy, it is possible to set a timeout for downloading media files. It is set to the bannerMediaTimeout property and acts on media files within the banner.
Autoloading images and video
By default, all images of the advertising banner are loaded and cached. You can disable automatic image loading, but keep in mind that it will take additional time to download them, which will create an additional delay in displaying ads in your application.
_ad.cachePolicy = MTRGCachePolicyNone;
[_ad load];
Acceptable values: MTRGCachePolicyAll (default), MTRGCachePolicyImages, MTRGCachePolicyNone.
If preloading is enabled, the corresponding images will be uploaded and stored in the cache in parallel with loading the main data of the advertising banner.
If preloading of images is disabled, they will be asynchronously and automatically loaded at the time of the call to the method registerView. No additional actions are required.
Notifications about media files downloading
In order to receive notifications about downloading media files (in the case of non-automatic downloads), you must implement the MTRGNativeBannerAdMediaDelegate protocol and set the mediaDelegate property for the MTRGNativeBannerAd object.
@protocol MTRGNativeBannerAdMediaDelegate <NSObject>
- (void)onIconLoadWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
- (void)onAdChoicesIconLoadWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
- (void)onMediaLoadFailedWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
@end
Ad Closing Notifications and Ad Closing Management
In order to receive notifications about ad closures and manage ad closures, you must set a delegate implementing the MTRGNativeBannerAdChoicesOptionDelegate protocol in the adChoicesOptionDelegate property. The protocol contains several methods:
- shouldCloseAutomatically – tells the SDK whether to close ads automatically. If the method returns YES, the SDK will automatically hide the ad. If NO, then the opportunity to hide is provided to the developer. The method is optional and returns YES by default;
- onClose Automatically: notifies the developer that the advertisement was hidden automatically using the SDK. Thus, this method will be called only if shouldCloseAutomatically returns YES;
- closeIfAutomaticallyDisabled: notifies the developer that he needs to hide the ad himself. Thus, this method will be called only if shouldCloseAutomatically returns NO.
Displaying ads
After successfully uploading the data, you can use the properties of the resulting banner instance to populate your visual component. The availability of properties depends on the type of advertised object. They vary for applications and websites.
To display the icon, use the MTRGIconAdView provided by the SDK.
After filling in the visual component, you must register it in the MTRGNativeBannerAd instance using the registerView method. If you are going to use the same visual component to display other ads, you must first call the unregisterView method on the current instance of MTRGNativeBannerAd before calling the registrerview on another instance. Impressions and clicks are processed automatically, and the application should not block or intercept user events on this visual component. The available properties are described below and examples of filling in visual components for various types of advertised objects are provided.
Visual components (both standard and proprietary) should be placed inside the MTRGNativeAdContainer container. In this case, both the component itself and the container can be passed to the registerView method.
When creating a container, the AdView visual component will be added as a subview to the container and stretched to fit the container.
To get the height of a visual component depending on its width (required for embedding in a TableView/collectionView), you need to call the sizeThatFits method from the container (the method call is proxied in AdView).
After creating the container, you need to establish a correspondence between the available properties of the visual component and the properties of the container.
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
// The title of the ads
NSString *title = banner.title;
// Age limit. May be nil
NSString *ageRestrictions = banner.ageRestrictions;
// Disclaimer. May be nil
NSString *disclaimer = banner.disclaimerInfo.text;
// The text of the "Ads" label
NSString *advertisingLabel = banner.advertisingLabel;
// Icon
MTRGImageData *icon = banner.icon;
// The text of the action for the button
NSString *ctaText = banner.ctaText;
// Properties that are only available for ads that advertise apps
if (banner.navigationType == MTRGNavigationTypeStore))
{
// App Rating (0-5)
NSNumber *rating = banner.rating;
// Number of ratings
NSUInteger votes = banner.votes;
}
// Properties available only for ads that advertise websites
else if (banner.navigationType == MTRGNavigationTypeWeb)
{
// Site domain
NSString *domain = banner.domain;
}
// Example of filling in a visual component
UIView *adView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 300, 50)];
MTRGIconAdView *iconAdView = [MTRGNativeViewsFactory createIconAdView];
iconAdView.frame = CGRectMake(0, 0, 50, 50);
UILabel *titleLabel = [[UILabel alloc] initWithFrame:CGRectMake(60, 15, 140, 20)];
titleLabel.text = title;
UIButton *ctaButton = [[UIButton alloc] initWithFrame:CGRectMake(210, 10, 80, 30)];
[ctaButton setTitle:ctaText forState:UIControlStateNormal];
[adView addSubview:titleLabel];
[adView addSubview:iconAdView];
[adView addSubview:ctaButton];
MTRGNativeAdContainer *containerView = [MTRGNativeAdContainer createWithAdView:adView];
containerView.titleView = titleLabel;
containerView.iconView = iconAdView;
containerView.ctaView = ctaButton;
// Registering the visual component
[nativeBannerAd registerView:containerView withController:self];
// Adding it to the screen
[self.view addSubview:containerView];
}
AdChoices icon
The myTarget SDK automatically adds the AdChoices icon to each visual component. By default, the icon is added to the upper-right corner of the visual component, but you can select your preferred corner using 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. After that, when configuring the visual component, you need to create an MTRGAdChoicesView and add it to the advertising component. This way you can control the position and size of the AdChoices icon, as well as set your own image. If the image has not been installed, then the SDK will put its AdChoices icon in the MTRGAdChoicesView after you register the visual component in the advertising object.
- (void)setupAdChoicesView
{
_ad.adChoicesPlacement = MTRGAdChoicesPlacementManual;
MTRGAdChoicesView *adChoicesView = MTRGNativeViewsFactory.createAdChoicesView;
// Installing our own image
adChoicesView.imageView.image = [UIImage imageNamed:@"AdChoices"];
[_adView addSubview:adChoicesView];
// You can use Autolayout or frames to position and specify dimensions adChoicesView
}
Manual rendering of the AdChoices icon
To fully control the AdChoices display component, set the adChoicesPlacement property to MTRGAdChoicesPlacementDrawingManual. Then the creation, display of content, icon placement and click processing are completely given to the developers. However, the SDK provides an AdChoices icon that you can use in your component (items "Auto-upload image and video" and "Notification of successful asset upload"). You can get information about the presence of AdChoices (hasAdChoices property) and the icon (adChoicesIcon property) from MTRGNativeBanner. To notify the SDK that the AdChoices icon has been clicked, the handleAdChoicesClickWithController:sourceView: method must be called for the advertising 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 specify dimensions adChoicesImageView
}
// Notifying the 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 method registrerview:withController. In this case, the entire area of the visual component is clickable. The My Target SDK provides the ability to specify specific visual components that will be monitored for clicks. To do this, use the method registrerview:with Controller:withClickableViews:
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
...
...
...
// Registering a visual component with a clickable title and a call-to-action button
[nativeBannerAd registerView:adView withController:self withClickableViews:@[titleLabel, ctaButton]];
// Adding 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 implementing the MTRGMenuFactory protocol to the appropriate initializer. The protocol requires you to implement a method for creating a menu. The menu should implement the MTRGMenu protocol. By default, the SDK uses a UIAlertController with the ActionSheet style.
// Example of menu implementation
// Adding a model MTRGMenuAction в _items. An array of objects that will need to be shown in the menu
- (void)addMenuAction:(nonnull MTRGMenuAction *)action
{
[_items addObject:action];
}
// Based on _items creating UIAlertController and display it
- (void)presentInViewController:(nonnull UIViewController *)viewController sourceView:(nullable UIView *)sourceView
{
UIAlertControllerStyle style = UIAlertControllerStyleAlert;
UIAlertController *alert = [UIAlertController 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 a built-in visual component
My Target SDK provides a ready-made, customizable visual component, the appearance of which you can customize to match the design of your application.
The examples below describe the properties available for configuration.
MTRGNativeBannerAdView
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
// Creating a visual component
MTRGNativeBannerAdView *adView = [MTRGNativeViewsFactory createNativeBannerAdView];
adView.banner = banner;
// Configurable internal visual components
UILabel *titleLabel = adView.titleLabel;
MTRGIconAdView *iconAdView = adView.iconAdView;
UILabel *domainLabel = adView.domainLabel;
UILabel *disclaimerLabel = adView.disclaimerLabel;
MTRGStarsRatingLabel *ratingStarsView = adView.ratingStarsLabel;
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 disclaimerMargins = adView.disclaimerMargins;
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;
// Registering the visual component
[nativeBannerAd registerView:adView withController:self];
// Adding it to the screen
[self.view addSubview:adView];
}
Loading of multiple banners
My Target SDK provides the MTRGNativeBannerAdLoader class, which allows you to load from 1 to 20 banners in one request. For MTRGNativeBannerAdLoader, you can configure all the same parameters that are available for configuration in MTRGNativeBannerAd (for example, user gender and age parameters, auto-upload of images and videos). The myTarget 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.
// Enabling debugging mode
// [MTRGManager setDebugMode:YES];
// Creating MTRGNativeBannerAdLoader
MTRGNativeBannerAdLoader *nativeBannerAdLoader = [MTRGNativeBannerAdLoader loaderForCount:COUNT slotId:YOUR_SLOT_ID];
// Loading banners
[nativeBannerAdLoader loadWithCompletionBlock:^(NSArray<MTRGNativeBannerAd *> * _Nonnull nativeBannerAds, NSError * _Nullable error)
{
for (MTRGNativeBannerAd *nativeBannerAd in nativeBannerAds)
{
// Installing the delegate
nativeBannerAd.delegate = self;
MTRGNativeBanner *banner = nativeBannerAd.banner;
// Code similar to the method onLoadWithNativeBanner protocol MTRGNativeBannerAdDelegate
}
}];
The resulting array will contain from 0 to COUNT MTRGNativeBannerAd objects. Each of them contains an already loaded MTRGNativeBanner, and you need to work with each of them in the same way as described in this documentation above, starting with calling the onLoadWithNativeBanner method.