- Build against Base SDK
7.0or later. Deployment target: iOS6.0or later. - Use
Xcode 5or later.
CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like Taboola in your projects.
You can install it with the following command:
$ gem install cocoapodsTo integrate Taboola into your Xcode project using CocoaPods, specify it in your Podfile:
- Objective-C
pod 'TaboolaSDK'- Swift
use_frameworks!
pod 'TaboolaSDK'Then, run the following command:
$ pod installTo include Taboola in your app using Interface Builder:
- Add
UIViewto your ViewController.TaboolaViewsubclassesUIViewand behaves just like any other standard iOS view. - In the Identity Inspector set the custom class to
TaboolaView;
Import TaboolaView into your source files (or into your bridging header if you're using with Swift and not using frameworks with Cocoapods):
#import <TaboolaSDK/TaboolaView.h>If you are using Swift and frameworks, then you can just import Taboola into your Swift source file:
import TaboolaSDK
TaboolaView* taboolaView = [[TaboolaView alloc] initWithFrame:<CGRect>];
taboolaView.delegate = self;
taboolaView.ownerViewController = self;Get the following parameters from your Taboola account manager:
// An identification of a Taboola recommendation unit UI template (you might use different UI templates in different parts of the app, in which case you will need to get the applicable mode for each UI template)
taboolaView.mode = @"my-mode";// An identification of your publisher account on the Taboola system
taboolaView.publisher = @"my-publisher";// Sets the page type of the page on which the widget is displayed (one of article, photo, video, home, category, search)
taboolaView.pageType = @"my-page-type";// Sets the canonical URL for the page on which the widget is displayed
taboolaView.pageUrl = @"my-page-url";// An identification of a specific placement in the app (you might place Taboola recommendation units in multiple placements in the app, in which case you should get applicable placement ids for each such placement)
taboolaView.placement = @"my-placement";After setting all properties, call fetchContent to load the TaboolaView content:
// After initializing the TaboolaView, this method should be called to actually fetch the recommendations
[taboolaView fetchContent];Optionally set a TaboolaViewDelegate TaboolaView.delegate = self to intercept recommendation clicks. If recommendation clicks are not intercepted, they will be presented by a Taboola powered in-app browser. Also important to note that TaboolaView also fires notifications that can be caught by any object inside the app, in case you want to react to these notifications elsewhere in your code.
- (BOOL)taboolaViewItemClickHandler:(NSString *)pURLString :(BOOL)isOrganic;Return: YES if the view should begin loading content; otherwise, NO. Default value is YES.
// Triggered when the TaboolaView resizes after content render
- (void)taboolaViewResizeHandler;
// Triggered after the TaboolaView is succesfully rendered
- (void)taboolaDidReceiveAd:(UIView *)view;
// Triggered after the TaboolaView fails to render
- (void)taboolaDidFailAd:(NSError *)error;A code similar to this should be added to your ViewController viewDidLoad method:
- (void)viewDidLoad{
[super viewDidLoad];
// Load taboolaView
taboolaView.delegate = self;
taboolaView.ownerViewController = self;
taboolaView.mode = @"my-mode";
taboolaView.publisher = @"my-publisher";
taboolaView.pageType = @"article";
taboolaView.pageUrl = @"http://www.example.com";
taboolaView.placement = @"Mobile";
taboolaView.autoResizeHeight = YES;
taboolaView.enableClickHandler = YES;
taboolaView.logLevel = LogLevelDebug;
// Optional - add more page commands if needed
NSDictionary *lPageDictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"http://www.example.com/ref", @"referrer", nil];
[taboolaView setOptionalPageCommands:lPageDictionary];
// target_type should be "mix", unless specified otherwise by your Taboola account manager
NSDictionary *lModeDictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"mix", @"target_type", nil];
[taboolaView setOptionalModeCommands:lModeDictionary];
// Fill taboolaView with recommendations
[mTaboolaView fetchContent];
}TaboolaView allows app developers to intercept recommendation clicks in order to create a click-through or to override the default way of opening the recommended article in the device built-in browser outside of the app. Please note that TaboolaView also fires notifications that can be caught by any object inside the app, in case you want to react to these notifications elsewhere in your code
In order to intercept clicks, you should implement the protocol TaboolaViewDelegate and connect TaboolaView to your delegate. The ViewController in which TaboolaView is displayed might be a good candidate to implement TaboolaViewDelegate.
TaboolaViewDelegate includes the method:
- (BOOL)taboolaViewItemClickHandler:(NSString *)pURLString:(BOOL)isOrganic;This method will be called every time a user clicks a recommendation, right before triggering the default behavior. The app can intercept the click there, and should return a boolean value:
- Returns NO - abort the default behavior (in which case the app should display the recommendation content on its own - e.g. using a custom in-app browser).
- Returns YES - this will allow the app to implement a click-through and continue with the default click handling behavior (which will display the clicked content with an in-app browser).
isOrganic indicates whether the item clicked was an organic content recommendation or not.
Best practice would be to suppress the default behavior for organic items, and instead open the relevant screen in your app which shows that piece of content.
- (BOOL)taboolaViewItemClickHandler:(NSString *)pURLString:(BOOL)isOrganic{
NSLog(@"Start load request on first screen: %@ isOrganic? %@", pURLString, isOrganic ? @"YES":@"NO");
if (isOrganic){
NSLog(@"organic items should open as native app pages.");
}
return YES;
}By default, TaboolaView automatically adjusts its own height in run time to show the entire widget.
TaboolaView may resize its height after loading recommendations, to make sure that the full content is displayed (based on the actual widget mode loaded).
After resize, TaboolaView will call taboolaViewResizeHandler method of the @protocol TaboolaViewDelegate, to allow the host app to adjust its layout to the changes. (This behavior may be disabled by setting the property autoResizeHeight to false.)
The file TaboolaViewResources.bundle includes the default icons for the TaboolaView in-app browser. These icons can be replaced by providing an alternative TaboolaViewResources.bundle file which contains the following files:
- back_icon.png
- forward_icon.png
If the user chose to allow IDFA sharing with the host app, the IDFA is sent to the Taboola server as a page command with the key “device”
The taboolaView widget also reports his status to the host app via NSNotificationCenter notifications (in addition to calling the TaboolaViewDelegate methods). This allows the host app to be more loosely coupled with the taboolaView. All notifications include a reference to the taboolaView itself. Here’s the list of notifications sent:
- taboolaDidReceiveAd - When the widget successfully loads its content.
- taboolaViewResized - When the taboolaView changes its height to adapt to its content. The notification data includes the new height.
- taboolaItemDidClick - When the user clicks an item on the taboolaView.
- taboolaDidFailAd - When the taboolaView fails to load its content. The error is included in the notification data.
This repository includes an example iOS app which uses the Taboola SDK, here . To use it, just clone this repository and open the project wih Xcode.
In case you encounter some issues when integrating the SDK into your app, try recreating the scenario within the example app. This might help isolate the problem, and in case you weren't able to solve it, you'll be able to send the example app with your recreated issue to Taboola's support for more help.
Taboola iOS SDK supports mediation via these platforms:
In order to configure mediation of Taboola SDK, via DFP follow the steps listed below:
@interface TBViewControllerDfp () <GADBannerViewDelegate> {
GADBannerView *dfpBannerView;
}// Define custom GADAdSize of 480x320 for GADBannerView.
GADAdSize customAdSize = GADAdSizeFromCGSize(CGSizeMake(480, 320));
CGPoint point = CGPointMake(0, 40);
dfpBannerView = [[GADBannerView alloc] initWithAdSize:customAdSize origin:point];
[self.view addSubview:dfpBannerView];
dfpBannerView.delegate = self;
dfpBannerView.adUnitID = @"your-unit-id";
dfpBannerView.rootViewController = self;- (void)viewDidAppear:(BOOL)animated {
[dfpBannerView loadRequest:[GADRequest request]];
}// Define custom GADAdSize of 480x320 for GADBannerView.
let customAdSize = GADAdSizeFromCGSize(CGSize(width: 480, height: 320))
let point = CGPoint(x: 0, y: 40)
let dfpBannerView = GADBannerView(adSize: customAdSize, origin: point)
view.addSubview(dfpBannerView)
dfpBannerView.delegate = self
dfpBannerView.adUnitID = "your_unit_id"
dfpBannerView.rootViewController = self
dfpBannerView.load(GADRequest())3.2.5 Add Adapter files into your project (available on GitHub):
DfpTaboolaEventBanner.hDfpTaboolaEventBanner.m
- Class name:
DfpTaboolaEventBanner - Parameters: Parameters for the Taboola SDK can be configured from the DFP web interface.
- Configuring from DFP web interface: The "parameter" field in the DFP custom event configuration screen, should contain a JSON string with the required properties. Notice that strings should be enclosed within escaped double quotes.
{
\"publisher\":\"<publisher code>\",
\"mode\":\"<mode>\",
\"url\":\"<url>\",
\"placement\":\"<placement>\",
\"article\":\"<article>\",
\"referrer\":\"<ref url>"
}In order to configure mediation of Taboola SDK, via MoPub follow the steps listed below:
@interface TBViewControllerMopub () <MPAdViewDelegate> {
MPAdView *moPubView;
}moPubView = [[MPAdView alloc]initWithAdUnitId:@"your-unit-id" size:MOPUB_MEDIUM_RECT_SIZE];
moPubView.delegate = self;
CGPoint framePosition = CGPointMake(CGRectGetMidX(self.view.bounds) - (MOPUB_MEDIUM_RECT_SIZE.width/2), 40);
moPubView.frame = CGRectMake(framePosition.x, framePosition.y, MOPUB_MEDIUM_RECT_SIZE.width, MOPUB_MEDIUM_RECT_SIZE.height);
[self.view addSubview:moPubView];
[moPubView loadAd];
[super viewDidLoad];- (UIViewController *)viewControllerForPresentingModalView {
return self;
}moPubView = MPAdView(adUnitId: "your-unit-id", size: MOPUB_MEDIUM_RECT_SIZE)
moPubView.delegate = self
var framePosition = CGPoint(x: CGFloat(self.view.bounds.midX - (MOPUB_MEDIUM_RECT_SIZE.width / 2)), y: CGFloat(40))
moPubView.frame = CGRect(x: CGFloat(framePosition.x), y: CGFloat(framePosition.y), width: CGFloat(MOPUB_MEDIUM_RECT_SIZE.width), height: CGFloat(MOPUB_MEDIUM_RECT_SIZE.height))
self.view.addSubview(moPubView)
moPubView.loadAd()
super.viewDidLoad()3.3.5 Add Adapter files into your project (available on GitHub):
MoPubCustomEventBanner.hMoPubCustomEventBanner.m
- Class name:
MoPubCustomEventBanner - Parameters: Parameters for the Taboola SDK can be configured from the MoPub web interface.
- Configuring from DFP web interface: The "parameter" field in the MoPub custom event configuration screen, should contain a JSON string with the required properties. Notice that strings should be enclosed within escaped double quotes.
{
"publisher":"<publisher code>",
"mode":"<mode>",
"url":"<url>",
"article":"<article>",
"placement":"<placement>",
"referrer":"<http://www.example.com/ref>"
}// Mandatory. Sets the publisher id
@property(nonatomic, strong) NSString *publisher // Mandatory. Sets the widget UI mode (template)
@property(nonatomic, strong) NSString *mode // Mandatory. Sets the widget placement code (for reporting /; configuration purposes)
@property(nonatomic, strong) NSString *placement // Mandatory. Sets the canonical URL for the page on which the widget is displayed
@property(nonatomic, strong) NSString *pageUrl // Optional. Sets the page id of the page on which the widget is displayed (default to auto generate from the URL)
@property(nonatomic, strong) NSString *pageId // Optional. Attaches a TaboolaViewDelegate to the TaboolaView. Allows intercepting clicks.
@property(nonatomic, weak) id<TaboolaViewDelegate> delegate // Optional. Taboola in-app web-browser will be used to present selected content if this viewController is provided. If not provided, clicks will be opened in Safari.
@property(nonatomic, weak) UIViewController *ownerViewController // Optional. controls whether to show or hide the action buttons on the in-app browser. Default YES
@property(nonatomic, readwrite) BOOL showBrowserIcons // Optional. sets the background color for the in-app browser. Default #f5f6f4
@property (nonatomic, strong) UIColor *browserBackColor // Optional. Sets the color for the in-app browser title text. Default #007cff
@property (nonatomic, strong) UIColor *browserTitleTextColor // Optional. when enabled, TaboolaView automatically resizes its height after rendering the widget, Default YES
@property(nonatomic, readwrite) BOOL autoResizeHeight // Optional. Mediation provider.
@property (nonatomic) NSString* mediation Optional. Allows setting additional page commands to the Taboola widget, as used in the Taboola JavaScript API. @param pCommands list of commands.
- (void)setOptionalPageCommands:(NSDictionary *)pCommands;Optional. Allows setting additional mode commands to the Taboola widget, as used in the Taboola JavaScript API. @param pCommands list of commands.
- (void)setOptionalModeCommands:(NSDictionary *)pCommands;After initializing the TaboolaView, this method should be called to actually fetch the recommendations
- (void)fetchContent;Resets the TaboolaView - All conents and pushed commands are cleared. new commands must be pushed before fetching data again.
- (void)reset;Refreshes the recommendations displayed on the TaboolaView.
- (void)refresh;This program is licensed under the Taboola, Inc. SDK License Agreement (the “License Agreement”). By copying, using or redistributing this program, you agree to the terms of the License Agreement. The full text of the license agreement can be found at https://github.com/taboola/taboola-ios/blob/master/LICENSE. Copyright 2017 Taboola, Inc. All rights reserved.