Avocarrot iOS SDK
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
AvocarrotSDK Jenkins autobuild 4.10.2 Oct 8, 2018
DemoApp Jenkins autobuild 4.10.2 Oct 8, 2018
.gitignore init Jun 22, 2017
CHANGELOG.md Jenkins autobuild 4.10.2 Oct 8, 2018
MANUAL_INTEGRATION.md AdColony support removed Nov 16, 2017
README.md Jenkins autobuild 4.9.0 Feb 7, 2018

README.md

Table of contents

Avocarrot Support

Additional documentation regarding integration of the Avocarrot SDK into your iOS app can be found under the following links:

Initialization

Avocarrot iOS SDK supports iOS 8.0 or higher.

You can add AvocarrotSDK to your project using Cocoapods (recommended) or manually

Adding through Cocoapods

Note: If you don't have pods in your project, set them up using the Getting Started guide

From version 4.5 Avocarrot SDK uses modular system to distribute based on subspecs:

  • By default Avocarrot SDK pod provides SDK with our native assets ad format only, add pod 'avocarrot-ios-sdk' to your Podfile to integrate it to your project.
  • If you want to use custom set of SDK modules, include pod 'avocarrot-ios-sdk/Core to your Podfile and then select additional modules below.

Native assets

  • If you want to use the Avocarrot native assets, add pod 'avocarrot-ios-sdk/NativeAssets' to your Podfile

Banners

  • If you want to use the Avocarrot banners, add pod 'avocarrot-ios-sdk/Banner' to your Podfile

Interstitials

  • If you want to use the Avocarrot interstitials, add pod 'avocarrot-ios-sdk/Interstitial' to your Podfile

Videos

  • If you want to use the Avocarrot videos, add pod 'avocarrot-ios-sdk/Video' to your Podfile

Rendered native ads

  • If you want to use the Avocarrot native views, add pod 'avocarrot-ios-sdk/NativeView' to your Podfile

Warning: Some Xcode versions support new settings only after the Xcode reboot. This also cleans the Xcode cache and remedies other problems.

TO DO list if you have a linking problem:

  • Clean Build
  • Restart Xcode
  • Delete your DerivedData folder in ~/Library/Developer/Xcode/DerivedData
  • Restart the computer

ATS settings in iOS 9.0 and greater

Since the Avocarrot SDK uses 3rd party networks to load ads and we have no control over these networks loading their content via https, you should disable ATS for your application to ensure the Avocarrot SDK behaves as intended. To disable ATS add the following settings to your application Info.plist file:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key><true/>
    <key>NSAllowsArbitraryLoadsForMedia</key><true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key><true/>
</dict>

Standard banners

AdUnitId for testing (STANDARD): "04c447d7-ffb8-4ba1-985e-4d2b9f88cd69" Available banner sizes:

  • AVOBannerViewSizeSmall (320x50) (recommended)
  • AVOBannerViewSizeLarge (728x90)

Use the following methods in your UIViewController subclass:

- (void)loadBannerWithSize:(AVOBannerViewSize)size
                  adUnitId:(NSString *_Nonnull)adUnitId
                   success:(void (^ _Nullable)(AVOBannerView *_Nonnull bannerAd))success
                   failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

For example:

objective-c

#import <AvocarrotBanner/AvocarrotSDK+AVOBannerView.h>
...
[self.bannerView stop];
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadBannerWithSize:AVOBannerViewSizeSmall
                                  adUnitId:@"04c447d7-ffb8-4ba1-985e-4d2b9f88cd69"
                                   success:^(AVOBannerView * _Nonnull bannerAd) {
                                       __strong __typeof__(self) sSelf = weakSelf;
                                       sSelf.bannerView = bannerAd;
                                       [sSelf.view addSubview:bannerAd];
                                 } failure:nil];

swift

import AvocarrotBanner
...
if bannerView != nil {
    bannerView?.stop()
    bannerView?.removeFromSuperview()
    bannerView = nil
}

AvocarrotSDK.shared.loadBanner(with: AVOBannerViewSizeSmall,
                               adUnitId: "04c447d7-ffb8-4ba1-985e-4d2b9f88cd69",
                               success: { [weak self] (bannerAd) in
                                           guard let sSelf = self else {
                                               return
                                           }
                                           sSelf.bannerView = bannerAd
                                           sSelf.view.addSubview(bannerAd)
                               }, failure: nil)

Add the following code to viewDidAppear and viewWillDisappear methods:

objective-c

#import <AvocarrotBanner/AvocarrotSDK+AVOBannerView.h>
...
- (void)viewDidAppear:(BOOL)animated {
	[super viewDidAppear:animated];
	[self.bannerView resumeAutoUpdate];
}

- (void)viewWillDisappear:(BOOL)animated {
	[super viewWillDisappear:animated];
	[self.bannerView pauseAutoUpdate];
}

swift

import AvocarrotBanner
...
override func viewDidAppear(animated: Bool) {
    bannerView?.resumeAutoUpdate()
}


override func viewDidDisappear(animated: Bool) {
    bannerView?.pauseAutoUpdate()
}

If you want to switch banner auto-update off:

self.bannerView.autoUpdate = NO;

If you want to stop and remove banner from screen:

[self.bannerView stop];

Standard banner events handling

To process banner events, you should implement blocks or subscribe to notifications:

Method Description NSNotificationCenter key
(void (^ _Nullable)(void))success Called after the banner is served successfully.
(void (^ _Nullable)(AVOError *_Nonnull error))failure Called if the banner was not downloaded.
- (instancetype _Nonnull)onClick:(nullable void (^)(void))block Called after a click on a banner. After this event app will be minimized and an external browser will be opened. kAVONotification_BannerClicked

Interstitials

AdUnitId for testing (INTERSTITIAL): "2cb34a73-0012-4264-9526-bde1fce2ba92". Interstitial size is defined automatically, depending on the screen size.

Use the following method in your UIViewController subclass:

objective-c

- (void)loadInterstitialWithAdUnitId:(NSString *_Nonnull)adUnitId
        success:(void (^ _Nullable)(AVOInterstitial *_Nonnull interstitial))success
        failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

The loadInterstitialWithAdUnitId method is to load the interstitial and call the success block if the interstitial loaded. From the success block you can save it to your UIViewController subclass property, show it immediately or do nothing.

For example:

objective-c

#import <AvocarrotInterstitial/AvocarrotSDK+AVOInterstitial.h>
...
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadInterstitialWithAdUnitId:@"2cb34a73-0012-4264-9526-bde1fce2ba92"
                     success:^(AVOInterstitial * _Nonnull interstitial) {
                        __strong __typeof__(self) sSelf = weakSelf;
                        sSelf.intestitial = interstitial;
                        [interstitial showFromViewController:sSelf];
                    } failure:nil];

swift

import AvocarrotInterstitial
...
AvocarrotSDK.shared.loadInterstitial(withAdUnitId: "2cb34a73-0012-4264-9526-bde1fce2ba92",
                                  success: { [weak self] (interstitial) in
                                      guard let sSelf = self else {
                                         return
                                      }
                                      sSelf.interstitial = interstitial
                                      interstitial.show(from: sSelf)
                               }, failure: nil)

Interstitial events handling

To process interstitial events, you should implement blocks or subscribe to notifications. The following is available:

Method Description NSNotificationCenter key
(void (^ _Nullable)(AVOInterstitial *_Nonnull interstitial))success Called after the interstitial is served. After this method is called, the interstitial is ready to be displayed.
(void (^ _Nullable)(AVOError *_Nonnull error))failure Called if the interstitial was not downloaded.
- (instancetype _Nonnull)onClick:(nullable void (^)(void))block Called after a click on the interstitial. After this event an external browser or a SKStoreProductViewController will be opened. kAVONotification_InterstitialClicked
- (instancetype _Nonnull)onDidHide:(nullable void (^)(void))block Called after the interstitial disappears from the screen. kAVONotification_InterstitialDidHide
- (instancetype _Nonnull)onDidShow:(nullable void (^)(void))block Called after the interstitial is displayed. kAVONotification_InterstitialDidShow
- (instancetype _Nonnull)onWillHide:(nullable void (^)(void))block Called after the tap on the "close" button, directly before the interstitial disappears. kAVONotification_InterstitialWillHide
- (instancetype _Nonnull)onWillLoad:(nullable void (^)(void))block Called before sending interstitial request to server. kAVONotification_InterstitialWillLoad
- (instancetype _Nonnull)onWillShow:(nullable void (^)(void))block Called before displaying the interstitial. kAVONotification_InterstitialWillShow

Video Ads

ID of video ad space for testing (VIDEO): "87f65c4c-f12d-4bb6-96fd-063fe30c4d69"

Use the following methods in your UIViewController subclass:

objective-c

- (void)loadVideoWithAdUnitId:(NSString *_Nonnull)adUnitId
        success:(void (^ _Nullable)(AVOVideo *_Nonnull video))success
        failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

For example:

objective-c

#import <AvocarrotVideo/AvocarrotSDK+AVOVideo.h>
...
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadVideoWithAdUnitId:@"87f65c4c-f12d-4bb6-96fd-063fe30c4d69"
                     success:^(AVOVideo *video) {
                        __strong __typeof__(self) sSelf = weakSelf;
                        [video showFromViewController:sSelf];
                     } failure:nil];

swift

import AvocarrotVideo
...
AvocarrotSDK.shared.loadVideo(withAdUnitId: "87f65c4c-f12d-4bb6-96fd-063fe30c4d69", success: { [weak self]
    video in
    guard let sSelf = self else {
       return
    }
    video.show(from: sSelf)
}, failure: nil)

Video events handling

To process video ad events, you should implement blocks or subscribe to notifications. The following is available:

Method Description NSNotificationCenter key
(void (^ _Nullable)(AVOVideo *_Nonnull video))success Called after the video is served. After this method is called, the video ad is ready to be displayed.
(void (^ _Nullable)(AVOError *_Nonnull error))failure Called if the video ad was not downloaded.
- (instancetype _Nonnull)onWillShow:(nullable void (^)(void))block Called when the video will show (will be shown). kAVONotification_VideoWillShow
- (instancetype _Nonnull)onDidShow:(nullable void (^)(void))block Called when the video did show (is shown). kAVONotification_VideoDidShow
- (instancetype _Nonnull)onWillHide:(nullable void (^)(void))block Called when the video will hide (will be closed). kAVONotification_VideoWillHide
- (instancetype _Nonnull)onDidHide:(nullable void (^)(void))block Called when the video is hidden (is closed). kAVONotification_VideoDidHide
- (instancetype _Nonnull)onStart:(nullable void (^)(void))block Called when the video is started. kAVONotification_VideoStarted
- (instancetype _Nonnull)onPause:(nullable void (^)(void))block Called when the video is paused. kAVONotification_VideoPause
- (instancetype _Nonnull)onResume:(nullable void (^)(void))block Called when the video is resumed. kAVONotification_VideoResume
- (instancetype _Nonnull)onComplete:(nullable void (^)(void))block Called when showing of a video has been completed. kAVONotification_VideoCompleted
- (instancetype _Nonnull)onWillLoad:(nullable void (^)(void))block Called before sending the video request to server. kAVONotification_VideoWillLoad
- (instancetype _Nonnull)onClick:(nullable void (^)(void))block Called after a click on the video. After this event an external browser or a SKStoreProductViewController will be opened. kAVONotification_VideoClicked

Native assets

AdUnitId for testing (Native ad): "7f900c7d-7ce3-4190-8e93-310053e70ca2"

Our native assets are raw ad data without any pre-defined wrapping UI. We only request the container of this data for event registration. The layout for a native assets is configured by developers with the help of the Interface Builder (creating .xib file) or manual creation of UI controls in code. Use the following methods in your UIViewController subclass:

objective-c

- (void)loadNativeAdWithAdUnitId:(NSString *_Nonnull)adUnitId
        success:(UIView * _Nullable (^ _Nonnull)(AVONativeAssets *_Nonnull nativeAd))success
        failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

swift

func loadNativeAd(withAdUnitId adUnitId: String,
                  success: @escaping (AVONativeAssets) -> UIView?,
                  failure: ((AVOError) -> ()))?)

The following method performs asynchronous downloading: raw native data without downloading linked resources and requests a container view for this data.

There is a common algorithm to use when implementing a custom native ad:

  1. Create your own subclass of UIView with any name (MyNativeBannerView for example) which will be used as ad view container.
  2. Render the other controls such as labels, buttons and image views, in the ad view container.
  3. Call loadNativeAdWithAdUnitId: etc with the required parameters, where the adUnitId is your private advertising space ID. Success block will be called when the native ad is successfully downloaded. Method returns the raw data object AVONativeAssets and requests your ad container where the ad will be rendered (required for registration of clicks and impressions), you can register ad container for interaction later by using this method of AVONativeAssets: - (instancetype _Nonnull)registerViewForInteraction:(nonnull UIView *)view forClickableSubviews:(nullable NSArray<UIView *> *)subviews, also you can display AdChoices icon and register it for click processing and redirecting user to AdChoices program website: - (instancetype _Nonnull)registerAdChoicesView:(nonnull UIView *)adChoicesView, failure block will be called when the native ad download fails, and returns AVOError
  4. Show the ad container on the screen.

For example:

objective-c

#import <AvocarrotNativeAssets/AvocarrotSDK+AVONativeAssets.h>
...
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadNativeAdWithAdUnitId:self.unitID
                     success:^UIView * _Nonnull(AVONativeAssets * _Nonnull nativeAd) {
                            __strong __typeof__(self) sSelf = weakSelf;
                            CustomNativeView *nativeView = [CustomNativeView new];
                            [nativeView fillWithNativeAd:nativeAd];

                            [[[[nativeAd onImpression:^{
                                NSLog(@"Ad Impressed");
                            }] onClick:^{
                                NSLog(@"Ad Clicked");
                            }] onLeftApplication:^{
                                NSLog(@"Left application");
                            }] registerViewForInteraction:nativeView forClickableSubviews:nil];

                            [sSelf.view addSubview:nativeView];

                            return nativeView;
                     } failure:^(AVOError * _Nonnull error) {
                            NSLog(@"Native ad loading error: %@", [error localizedDescription]);
}];

swift

import AvocarrotNativeAssets
...
AvocarrotSDK.shared.loadNativeAd(withAdUnitId: "",
                 success: { [weak self] (ad: AVONativeAssets) -> UIView? in
                        guard let sSelf = self else {
                           return
                        }
                        let containerView = CustomNativeView()
                        containerView.fillWithNativeAd(ad)

                        ad.onClick({
                            print("Clicked")
                        }).onImpression({
                            print("Impressed")
                        }).onLeftApplication({
                            print("Left application")
                        }).registerView(forInteraction: containerView, forClickableSubviews: nil)

                        sSelf.view.addSubview(containerView)

                        return containerView

                 }) { (error) in
                        print("Native ad loading error: \(error.localizedDescription)")
}

To process custom native ad events, you should implement blocks. The following is available:

Method Description
- (instancetype _Nonnull)onImpression:(nullable void (^)(void))impression Called when ad impression has been counted.
- (instancetype _Nonnull)onClick:(nullable void (^)(void))click Called when ad click has been counted.
- (instancetype _Nonnull)onLeftApplication:(nullable void (^)(void))leftApplication Called when application has been left after click.

Native ads

AdUnitId for testing (Native ad): "7f900c7d-7ce3-4190-8e93-310053e70ca2"

A native ad is a raw representation of an ad without any pre-defined wrapping UI, which gives developers the freedom to design and control the ad, or for the easiest integration you could use our customizable templates: List, Feed, Grid and GridIcon based on AVONativeAdsTemplateType enum. You can also choose Server template (i.e Dynamic Template), which will be downloaded from the server based on your color preferences. The main advantage of this template is the possibility to change the color scheme of the native ad after your app has been uploaded to the AppStore. The full list of templates is available in the AVONativeAdsTemplateType enum.

Use this method to represent native ads by our templates:

objective-c

- (void)loadNativeAdWithAdUnitId:(NSString *_Nonnull)adUnitId
            parentViewController:(UIViewController *_Nonnull)viewController
                    templateType:(AVONativeAdsTemplateType)templateType
                         success:(void (^ _Nullable)(UIView *_Nonnull adNativeViewContainer))success
                         failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure
           templateCustomization:(void (^ _Nullable)(AVOTemplateCustomizationObject *_Nonnull templateCustomizationObject))templateCustomization;

swift

func loadNativeAd(withAdUnitId adUnitId: String,
                  parentViewController viewController: UIViewController,
                  templateType: AVONativeAdsTemplateType,
                  success: ((UIView) -> ())?,
                  failure: ((AVOError) -> ())?,
                  templateCustomization: ((AVOTemplateCustomizationObject) -> ())?)

List of available template customizations is here

For example:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadNativeAdWithAdUnitId:@"7f900c7d-7ce3-4190-8e93-310053e70ca2"
                             parentViewController:self
                                     templateType:AVONativeAdsTemplateTypeList
                                          success:^(UIView * _Nonnull adNativeViewContainer) {
                                              __strong __typeof__(self) sSelf = weakSelf;
                                              [sSelf.view addSubview:adNativeViewContainer];
                                          } failure:nil
                            templateCustomization:nil];

swift

import AvocarrotNativeView
...
AvocarrotSDK.shared.loadNativeAd(withAdUnitId: "7f900c7d-7ce3-4190-8e93-310053e70ca2",
                                      parentViewController: self,
                                      templateType: .list,
                                      success: { [weak self] (view) in
                                        guard let sSelf = self else {
                                           return
                                        }
                                        self.view.addSubview(view)
            }, failure: nil,
               templateCustomization: nil)

The custom layout for a native ad is configured by developers with the help of the Interface Builder (creating .xib file) or manual creation of UI controls in code. Use the following methods in your UIViewController subclass:

objective-c

- (void)loadNativeAdWithAdUnitId:(NSString *_Nonnull)adUnitId
        parentViewController:(UIViewController *_Nonnull)viewController
        adViewClassForRendering:(Class _Nonnull)adViewClass
        success:(void (^ _Nullable)(UIView *_Nonnull adNativeViewContainer))success
        failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

swift

func loadNativeAd(withAdUnitId adUnitId: String,
                      parentViewController viewController: UIViewController,
                      adViewClassForRendering adViewClass: AnyClass,
                      success: ((UIView) -> ())?,
                      failure: ((AVOError) -> ())?)

The following method performs async downloading of native ads with all linked resources and renders ad data into bound UI controls after that.

There is a common algorithm to use when implementing a native ad:

  1. Create your own subclass of AVONativeView with any name (MyNativeBannerView for example)
  2. Choose one of two options:
    • XIB option - Design the layout of MyNativeBannerView in a separate XIB file. The developer should bind the desired UI controls in this XIB and properties from <AVONativeViewInterface>, which AVONativeView adopts. The implementation of MyNativeBannerView class has to override + (NSString *)xibName method, which returns the name of the same XIB.
    • Coding option - The implementation of MyNativeBannerView class must be performed by the creation and placement of UI controls using <AVONativeViewInterface>, which AVONativeView adopts.
  3. Call loadNativeAdWithAdUnitId: etc with the required parameters, where the adUnitId is your private advertising space ID and className is the name of the MyNativeBannerView class. After downloading the ad data, the SDK immediately initiates MyNativeBannerView class created in step 2. After, the SDK renders the native ad data inside the controls boundaries. Not all controls are filled this way, but only the main ones:avoTitleTextLabel, avoMainTextLabel, avoIconImageView, avoMainMediaView. When the rendering has finished, the successful completion block with this instance will be called.
  4. Show native ad view container on the screen.

For example:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
__weak typeof(self) weakSelf = self;
[AvocarrotSDK.sharedSDK loadNativeAdWithAdUnitId:@"7f900c7d-7ce3-4190-8e93-310053e70ca2"
                       parentViewController:self
                       classForRendering:NSStringFromClass([MyNativeBannerView class])
                       success:^(UIView *adNativeViewContainer) {
                           __strong __typeof__(self) sSelf = weakSelf;
                           UIView *nativeView = adNativeViewContainer;
                           nativeView.frame = sSelf.adContainerView.bounds;
                           [sSelf.adContainerView addSubview:nativeView];
                       } failure:^(NSError *error) {
}];

swift

import AvocarrotNativeView
...
AvocarrotSDK.shared.loadNativeAd(withAdUnitId: "7f900c7d-7ce3-4190-8e93-310053e70ca2", parentViewController: self, adViewClassForRendering: classForRendering, success: {
    [weak self] (nativeview) in
    guard let sSelf = self else {
       return
    }
    nativeview.frame = sSelf.adContainerView.bounds
    sSelf.adContainerView.addSubview(nativeview)
}, failure: nil)

To process native view events, you should implement blocks. The following is available:

Method Description NSNotificationCenter key
- (instancetype _Nonnull)onImpression:(nullable void (^)(void))impression Called when ad impression has been counted. kAVONotification_NativeAssetsImpressed
- (instancetype _Nonnull)onClick:(nullable void (^)(void))click Called when ad click has been counted. kAVONotification_NativeAssetsClicked
- (instancetype _Nonnull)onLeftApplication:(nullable void (^)(void))leftApplication Called when application has been left after click. kAVONotification_NativeAssetsLeftApplication

Stream adapter

AdUnitId for testing (like for native ad): "7f900c7d-7ce3-4190-8e93-310053e70ca2"

Stream adapter is a smart technology to add native ads as items in your feeds based on UITableView or UICollectionView. Settings for stream adapter are returned from the server side and you can change it as you wish.

To simplify integration for Stream Adapter you can use our customizable templates: List, Feed, Grid and GridIcon based on AVONativeAdsTemplateType enum:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (void)createStreamAdapterForTableView:(UITableView *_Nonnull)tableView
                   parentViewController:(UIViewController *_Nonnull)viewController
                               adUnitId:(NSString *_Nonnull)adUnitId
                           templateType:(AVONativeAdsTemplateType)templateType
                               delegate:(id <AVOTableViewStreamAdapterDelegate> _Nullable)delegate
                  templateCustomization:(void (^ _Nullable)(AVOTemplateCustomizationObject *_Nonnull templateCustomizationObject))templateCustomization
                                success:(void (^ _Nullable)(AVOTableViewStreamAdapter *_Nonnull streamAdapter))success
                                failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;


- (void)createStreamAdapterForCollectionView:(UICollectionView *_Nonnull)collectionView
                        parentViewController:(UIViewController *_Nonnull)viewController
                                    adUnitId:(NSString *_Nonnull)adUnitId
                                templateType:(AVONativeAdsTemplateType)templateType
                                    delegate:(id <AVOCollectionViewStreamAdapterDelegate> _Nullable)delegate
                       templateCustomization:(void (^ _Nullable)(AVOTemplateCustomizationObject *_Nonnull templateCustomizationObject))templateCustomization
                                     success:(void (^ _Nullable)(AVOCollectionViewStreamAdapter *_Nonnull streamAdapter))success
                                     failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

swift

import AvocarrotNativeView
...
func createStreamAdapter(for tableView: UITableView,
                         parentViewController viewController: UIViewController,
                         adUnitId: String,
                         templateType: AVONativeAdsTemplateType,
                         delegate: AVOTableViewStreamAdapterDelegate?,
                         templateCustomization: ((AVOTemplateCustomizationObject) -> ())?,
                         success:((AVOTableViewStreamAdapterDelegate) -> ())?,
                         failure:((AVOError) -> ())?)

func createStreamAdapter(for collectionView: UICollectionView,
                         parentViewController viewController: UIViewController,
                         adUnitId: String,
                         templateType: AVONativeAdsTemplateType,
                         delegate: AVOCollectionViewStreamAdapterDelegate?,
                         templateCustomization: ((AVOTemplateCustomizationObject) -> ())?,
                         success:((AVOCollectionViewStreamAdapter) -> ())?,
                         failure:((AVOError) -> ())?)

List of available template customizations is here

If you want to use your own representation of a native ad, use these methods:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (void)createStreamAdapterForTableView:(UITableView *_Nonnull)tableView
                   parentViewController:(UIViewController *_Nonnull)viewController
                               adUnitId:(NSString *_Nonnull)adUnitId
                              delegate:(id <AVOTableViewStreamAdapterDelegate> _Nullable)delegate
               adViewClassForRendering:(Class _Nonnull)adViewClass
                               success:(void (^ _Nullable)(AVOTableViewStreamAdapter *_Nonnull streamAdapter))success
                               failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

- (void)createStreamAdapterForCollectionView:(UICollectionView *_Nonnull)collectionView
                        parentViewController:(UIViewController *_Nonnull)viewController
                                    adUnitId:(NSString *_Nonnull)adUnitId
                                    delegate:(id <AVOCollectionViewStreamAdapterDelegate> _Nullable)delegate
                     adViewClassForRendering:(Class _Nonnull)adViewClass
                                     success:(void (^ _Nullable)(AVOCollectionViewStreamAdapter *_Nonnull streamAdapter))success
                                     failure:(void (^ _Nullable)(AVOError *_Nonnull error))failure;

swift

import AvocarrotNativeView
...
func createStreamAdapter(for tableView: UITableView,
                         parentViewController viewController: UIViewController,
                         adUnitId: String,
                         delegate: AVOTableViewStreamAdapterDelegate?,
                         adViewClassForRendering adViewClass: AnyClass,
                         success:((AVOTableViewStreamAdapterDelegate) -> ())?,
                         failure:((AVOError) -> ())?)

func createStreamAdapter(for collectionView: UICollectionView,
                         parentViewController viewController: UIViewController,
                         adUnitId: String,
                         delegate: AVOCollectionViewStreamAdapterDelegate?,
                         adViewClassForRendering adViewClass: AnyClass,
                         success:((AVOCollectionViewStreamAdapter) -> ())?,
                         failure:((AVOError) -> ())?)

These methods work the same way as Native Ads. You have to use the instructions of this type of ad to set adViewClass field in methods, but you need to implement AVOCollectionViewStreamAdapterDelegate protocol or set estimatedItemSize property of your UICollectionViewFlowLayout.

For UITableView you have to do nothing in UITableViewDelegate and UITableViewDataSource methods to add ads in your feed, native ads will be added automatically.

For UICollectionView you have to do nothing in UICollectionViewDelegate and UICollectionViewDelegate methods to add ads in your feed, native ads will be added automatically. Only UICollectionViewFlowLayout is supported. To add ads to custom layout UICollectionView use AVONativeAdsProvider class.

Note for custom collection view layout: if you want to know the original index path of a cell in your feed without ads use this method (it may be important to load data from your data array):

- (NSIndexPath * _Nullable)originalIndexPath:(NSIndexPath * _Nonnull)indexPath;

If you want to use methods of UITableView and UICollectionView which work with NSIndexPath please use UITableView (AVOStreamAdapter) and UICollectionView (AVOStreamAdapter) categories (declared in AVOTableViewStreamAdapter.h and AVOCollectionViewStreamAdapter.h). There categories contain methods with avo_ prefix which return original indexPaths.

To process stream adapter events, you should implement blocks or subscribe to notifications. The following is available:

Method Description NSNotificationCenter key
- (instancetype _Nonnull)onAdsDidLoad:(nullable void (^)(void))block Called after ads for stream adapter have been loaded. After this event you can reload your UITableView/UICollectionView or could wait - ads will be added automatically during scrolling. kAVONotification_StreamAdapterAdsDidLoad
- (instancetype _Nonnull)onAdsFailed:(nullable void (^)(void))block Called after ads for stream adapter failed to load. kAVONotification_StreamAdapterAdsFailed

Note: Currently stream adapter doesn't support dynamic modification of data source (insert, move, delete of items). This support will be added soon.

To delete ads from your UITableView or UICollectionView just use that code:

objective-c

[self.tableView resetStreamAdapter];
[self.collectionView resetStreamAdapter];

swift

tableView.resetStreamAdapter()
collectionView.resetStreamAdapter()

Native ads provider

AdUnitId for testing (like for native ad): "7f900c7d-7ce3-4190-8e93-310053e70ca2"

Native ads provider is more flexible approach to add rendered native ads for UITableView or UICollectionView instead of the complex Stream Adapter classes (AVOTableViewStreamAdapter or AVOCollectionViewStreamAdapter).

To simplify integration for both Stream Adapter and Native Ads Provider you can use our customizable templates: List, Feed, Grid and GridIcon based on AVONativeAdsTemplateType enum.

To create AVONativeAdsProvider object use this method:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (AVONativeAdsProvider *_Nonnull)createNativeAdsProviderForAdunit:(NSString *_Nonnull)adUnitId
                                                      templateType:(AVONativeAdsTemplateType)templateType
                                                          userData:(NSDictionary <NSString *, id> * _Nullable)userData
                                             templateCustomization:(void (^ _Nullable)(AVOTemplateCustomizationObject *_Nonnull templateCustomizationObject))templateCustomization;

swift

import AvocarrotNativeView
...
func createNativeAdsProvider(forAdunit adUnitId: String,
                             templateType: AVONativeAdsTemplateType,
                             userData: [String: id]?,
                             templateCustomization: ((_ templateCustomizationObject: AVOTemplateCustomizationObject) -> Void)? = nil) -> AVONativeAdsProvider

List of available template customizations is here

Also if you want to use your own representation of a native ad, use this method:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (AVONativeAdsProvider *_Nonnull)createNativeAdsProviderForAdunit:(NSString *_Nonnull)adUnitId
                                           adViewClassForRendering:(Class _Nonnull)adViewClass
                                                          userData:(NSDictionary <NSString *, id> * _Nullable)userData;

swift

import AvocarrotNativeView
...
func createNativeAdsProvider(forAdunit adUnitId: String,
                             adViewClassForRendering adViewClass: AnyClass,
                             userData: [String: id]?) -> AVONativeAdsProvider;

After creating AVONativeAdsProvider object you have to preload need amount of ads by using this method of AVONativeAdsProvider:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (void)preloadAdsInCache:(NSUInteger)preloadCount
     parentViewController:(UIViewController *_Nonnull)viewController
                  didLoad:(void (^ _Nullable)(NSUInteger preloadCount))successBlock
                  didFail:(void (^ _Nullable)(AVOError *_Nonnull error))errorBlock;

swift

import AvocarrotNativeView
...
func preloadAds(inCache preloadCount: Int,
                parentViewController viewController: UIViewController,
                didLoad successBlock: ((_ preloadCount: Int) -> Void)? = nil,
                didFail errorBlock: ((_ error: AVOError) -> Void)? = nil)

After getting success callback you are able to get rendered native ads from your AVONativeAdsProvider object by using this method:

objective-c

#import <AvocarrotNativeView/AvocarrotNativeView.h>
...
- (AVONativeView* _Nullable)getNextAdView;

swift

import AvocarrotNativeView
...
func getNextAdView() -> AVONativeView?

Note: This method gets next native ad from the ring cache. Each ad will be inserted repeatedly every 'preloadCount' interval until it's tapped or impression is counted and as result ad is automatically replaced with a new one.

Native templates customization

To customize our templates use AVOTemplateCustomizationObject instance which is returned in each native request method. List of available customizations:

Property of the AVOTemplateCustomizationObject Description
avoBackgroundColor Color of the ad cells
avoTitleFont Font of the title label in the ad cells
avoTitleColor Text color of the title label in the ad cells
avoTitleLeftOffset Left offset for the title label in the ad cells
avoTitleRightOffset Right offset for the title label in the ad cells
avoTitleTextStyle Text style for the title label in the ad cells (could be uppercase, lowercase, capitalize and default)
avoDescriptionTextFont Font of the description label in the ad cells
avoDescriptionTextColor Text color of the description label in the ad cells
avoDescriptionTextLeftOffset Left offset for the description label in the ad cells
avoDescriptionTextRightOffset Right offset for the description label in the ad cells
avoCoverMediaLeftOffset Left offset for the ad main media view
avoCoverMediaRightOffset Right offset for the ad main media view
avoCoverMediaTopOffset Top offset for the ad main media view
avoCoverMediaBottomOffset Bottom offset for the ad main media view
avoCoverMediaCornerRadius Corner radius of the ad main media layer
avoCoverMediaAutoPlayEnabled Enabling of video autoplay for main media view
avoCTAFont Call to action label font
avoCTAColor Call to action view background color
avoCTATextColor Call to action label text color
avoCTABorderColor Call to action layer border color
avoCTACornerRadius Call to action layer corner radius
avoCTABorderWidth Call to action layer border width
avoCTARightOffset Right offset for ad call to action view
avoCTABottomOffset Bottom offset for ad call to action view
avoCTATextStyle Text style for the call to action label in the ad cells (could be uppercase, lowercase, capitalize and default)
avoSponsoredFont Sponsored label font
avoSponsoredColor Sponsored label text color
avoSponsoredTextStyle Text style for the sponsored label in the ad cells (could be uppercase, lowercase, capitalize and default)
avoIconLeftOffset Left offset for ad app icon view
avoIconTopOffset Top offset for ad app icon view
avoIconHeight Height for ad app icon view
avoIconWidth Width for ad app icon view
avoIconCornerRadius Corner radius of ad app icon layer
avoIconContentMode Content mode of ad app icon view
avoMediaContentRatio Content ratio for the ad main media view (grid template)
avoTextContentRatio Content ratio for the ad description (grid template)
avoGridIconTemplateTitleIconBottomOffest Bottom offset for the title label (grid icon template)
avoGridIconTemplateIconCTATopOffset Top offset for the call to action label (grid icon template)

Other

Test mode (development mode)

During the development phase, it is highly recommended to set testMode to YES to work with test ads only. The default setting is NO.

#import <AvocarrotCore/Avocarrot.h>
...
AvocarrotSDK.testMode = YES;

User data

To include user data in the SDK, please set up the following properties:

#import <AvocarrotCore/Avocarrot.h>
...
+ (void)setBirthday:(NSDate *_Nonnull)birthday;

+ (void)setGender:(AVOUserGender)userGender;

+ (void)setInterests:(NSArray<NSString *> *_Nonnull)interests;

For example:

#import <AvocarrotCore/Avocarrot.h>
...
[AvocarrotSDK setGender:AVOUserGenderMale];
[AvocarrotSDK setBirthday:[NSDate date]];
[AvocarrotSDK setInterests:@[@"running", @"shopping", @"fitness", @"sport"]];