NOTICE: As of version 1.5.1, clicks on non-organic items will be handled by Taboola SDK and the app will not be allowed to override the default click handler. "No" responses from
taboolaViewItemClickHandler
will only be honored for organic items.
- Build against Base SDK
7.0
or later. Deployment target: iOS6.0
or later. - Use
Xcode 5
or 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 cocoapods
To 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 install
To include Taboola in your app using Interface Builder:
- Add
UIView
to your ViewController.TaboolaView
subclassesUIView
and 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 initializing the TaboolaView, this method should be called to actually fetch the recommendations
[taboolaView fetchContent];
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.targetType = @"mix";
// Optional - add more page commands if needed
NSDictionary *lPageDictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"http://www.example.com/ref", @"referrer", nil];
[taboolaView setOptionalPageCommands:lPageDictionary];
// Fill taboolaView with recommendations
[taboolaView fetchContent];
}
// Optionally set the TaboolaViewDelegate, to listen to taboolaView events and clicks
taboolaView.delegate = self;
// To intercept recommendation clicks
- (BOOL)onItemClick:(NSString *)placementName withItemId:(NSString *)itemId withClickUrl:(NSString *)clickUrl isOrganic:(BOOL)organic
Return: YES
if the taboolaView should handle the click; otherwise, NO
. Default value is YES
.
NOTICE: As of version 1.5.1, clicks on non-organic items will be handled by Taboola SDK and the app will not be allowed to override the default click handler. "No" responses from
taboolaViewItemClickHandler
will only be honored for organic items.
This method will be called every time a user clicks a recommendation, right before triggering the default behavior. 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.
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).
organic
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.
Use itemId
in organic clicks for deeplink.
clickUrl
is the url with the redirect.
- (BOOL)onItemClick:(NSString *)placementName withItemId:(NSString *)itemId withClickUrl:(NSString *)clickUrl isOrganic:(BOOL)organic {
NSLog(@"Start load request on first screen: %@ isOrganic? %@", clickUrl, organic ? @"YES":@"NO");
if (organic) {
NSLog(@"organic items should open as native app pages.");
}
return YES;
}
// Triggered after the TaboolaView is succesfully rendered
- (void)taboolaView:(UIView *)taboolaView didLoadPlacementNamed:(NSString *)placementName withHeight:(CGFloat)height;
// Triggered after the TaboolaView fails to render
- (void)taboolaView:(UIView *)taboolaView didFailToLoadPlacementNamed:(NSString *)placementName withErrorMessage:(NSString *)error;
// Triggered when the TaboolaView resizes after content render or orientation change.
- (void)taboolaViewResizedToHeight:(CGFloat)height;
- Choose between fixed or automatic height
By default, TaboolaView automatically adjusts its own height in run time to show the entire widget.
The SDK will automatically decide the height, so you don’t need to give it.
taboolaView.autoResizeHeight = YES; // This is the default, no need to add this code
//Disable scroll inside the widget
taboolaView.scrollEnable = NO;//This is the default, no need to add this code
Set the TaboolaView frame (The most important is the height).
taboolaView.autoResizeHeight = NO;
//Enable scroll inside the widget
taboolaView.scrollEnable = YES;
Our widget is a custom webview. The feed is endless and it has a scroll functionality. When implementing feed, the view has a fixed size, usually in the bottom of the screen. When the app is scrolled and the view is taking up all the screen, the app scroll should hand over the scroll to our view (inner scroll of the webview).
// To enable scroll switch between the scrollView and taboolaView
[taboolaView setInterceptScroll:YES];
By default, TaboolaView automatically adjusts its own height in run time to show the entire widget.
//To get the automatic height
TaboolaView.widgetHeight;
In collectionView or tabolaView, set your cell height with TaboolaView.widgetHeight;
taboolaView.autoResizeHeight = YES; // This is the default, no need to add this code
//Disable scroll inside the widget
taboolaView.scrollEnable = NO;//This is the default, no need to add this code
Set the TaboolaView frame (The most important is the height).
In CollectionView or tableView, set the cell height the same to tabolaView.
taboolaView.autoResizeHeight = NO;
//Enable scroll inside the widget
taboolaView.scrollEnable = YES;
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 its 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 to recreate the scenario within the example app. This might help to 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.h
DfpTaboolaEventBanner.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.h
MoPubCustomEventBanner.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 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. default: false. When set to true, forces TaboolaView to use UIWebView as the widget container instead of WKWebView even when WKWebView is available (iOS 8 and above). Please consult Taboola support or your Taboola account manager before using this feature.
@property(nonatomic, readwrite) BOOL forceLegacyWebView
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;
In order to support the The EU General Data Protection Regulation (GDPR - https://www.eugdpr.org/) in Taboola Mobile SDK,capplication developer should show a pop up asking the user's permission for storing their personal data in the App. In order to control the user's personal data(to store in the App or not) there exists a flag User_opt_out
. It's mandatory to set this flag when using the Taboola SDK. The way to set this flag depends on the type of SDK you are using. By default we assume no permission from the user on a pop up, so the personal data will not be saved.
Below you can find the way how to set the flag on iOS SDK Standard we support. It's recommended to put these lines alongside the other settings, such as publisher name, etc
//load taboolaView
mTaboolaView.delegate = self;
mTaboolaView.ownerViewController = self;
mTaboolaView.mode = @"thumbnails-a";
mTaboolaView.publisher = @"the-publisher-name";
mTaboolaView.pageType = @"article";
mTaboolaView.pageUrl = @"http://www.example.com";
mTaboolaView.placement = @"Mobile second";
//mTaboolaView.targetType = @"mix";
[mTaboolaView setOptionalPageCommands:@{@"user_opt_out":@"true"}];
This program is licensed under the Taboola, Inc. SDK License Agreement (the “License Agreement”). By copying, using or redistributing this program, you agree with 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.