Basic Integration
iOS Web - Basic Integration
You are viewing the V4 docs. (For the V3 docs, go here.)
While reading the documentation, take a look at our Sample App.
This integration requires you to connect JavaScript code (in your web content) with native application code.
Initialize Taboola
The initialization steps in this section are the same for Classic and Web integrations.
In your AppDelegate
class, create a TBLPublisherInfo
object and initialize Taboola:
#import <TaboolaSDK/TaboolaSDK.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Immediately after application launch...
// Initialize a TBLPublisherInfo instance with your unique 'publisherName':
TBLPublisherInfo *publisherInfo = [[TBLPublisherInfo alloc]initWithPublisherName:@"<publisherName>"];
// Initialize Taboola for your application:
[Taboola initWithPublisherInfo:publisherInfo];
// (Optional) Set *global* feature flags:
[Taboola setGlobalExtraProperties:@{@"<feature flag key>":@"<value>"}];
// (Optional) Set the desired log level:
[Taboola setLogLevel:LogLevelDebug];
return YES;
}
import TaboolaSDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Immediately after application launch...
// Initialize a TBLPublisherInfo instance with your unique 'publisherName' (aka 'Publisher ID'):
let publisherInfo = TBLPublisherInfo.init(publisherName: "<publisherName>")
// Initialize Taboola for your application:
Taboola.initWith(publisherInfo)
// (Optional) Set *global* feature flags:
Taboola.setGlobalExtraProperties(["<feature flag key>":"<value>"])
// (Optional) Set the desired log level:
Taboola.setLogLevel(LogLevel.debug)
return true
}
publisherName
publisherName
(aka Publisher ID) is a unique, alphabetic String. It might contain dashes - e.g."<<publisherID>>"
- but not spaces.To obtain your Publisher ID, contact your Taboola Account Manager.
AppDelegate
Initialize Taboola in your
AppDelegate
class - or as early as possible within the app.
Logging
(Optional) To set the desired log level, use the
setLogLevel
method.For more detail, see: Setters.
Add Taboola JS tags
- Add the following meta tag to the section of your web content:
<meta name='viewport' content='width=device-width, user-scalable=no'/>
- Add the following JS tag to the section of your web content, and edit the default text:
<script type="text/javascript">
window._taboola = window._taboola || [];
_taboola.push({page_type:'auto', url:'page_url'});
!function (e, f, u, i) {
if (!document.getElementById(i)){
e.async = 1;
e.src = u;
e.id = i;
f.parentNode.insertBefore(e, f);
}
}(document.createElement('script'),document.getElementsByTagName('script')[0],
'https://cdn.taboola.com/libtrc/publisher_id/mobile-loader.js',
'tb_mobile_loader_script');
</script>
Editing instructions:
Default text | Instructions | Notes |
---|---|---|
page_type | Replace this with the relevant page type (as provided by Taboola - e.g. article ):article:'auto' | Possible values:video , article , photo , search , category , home . |
'auto' | To obtain an automated ID, leave this param as is:article:'auto' Else, insert your own, internal ID: article:'123' | Specifies the ID of this page, for the given page type. |
'page_url' | Insert the canonical web URL of the page:url:'https://www.example.com/articles?id=123' | Required so that Taboola can crawl the page for metadata and contextual data. |
publisher_id | Insert your Publisher ID (as provided by Taboola - e.g. '<<publisherID>>' ) into the URL:'https://cdn.taboola.com/libtrc/<<publisherID>>/mobile-loader.js' |
- For each placement, add the following JS tag to the of your web content, and edit the param values:
<div id="<<containerId>>"></div>
<script type="text/javascript">
window._taboola = window._taboola || [];
_taboola.push({mode: 'mode-here',
container: 'container-id-here',
placement: 'placement-here',
target_type: '<<targetType>>'});
// Notice - this part is unique to mobile SDK JS integrations!
_taboola["mobile"] = window._taboola["mobile"] || [];
_taboola["mobile"].push({
publisher:'publisher-id-here'
});
_taboola.push({
flush: true
});
</script>
Params
mode
- The UI Mode ID of the placement, as provided by Taboola - e.g.'<<mode>>'
.container
- The ID of your HTML element that contains the Taboola content - e.g. '<<containerId>>
'.placement
- The placement name, as provided by Taboola - e.g.'<<placementName>>'
.target_type
- The target type, as provided by Taboola - e.g.'<<targetType>>'
.publisher
- Your Publisher ID (aka Account ID) - a unique, alphabetic string, as provided by Taboola - e.g.'<<publisherID>>'
.
Build Taboola content instances
Guidelines
- The goal is to wrap your web view with Taboola services.
- For each page, initialize 1
TBLWebPage
instance, and create 1TBLWebUnit
instance only. (You are not required to keep a reference to thisTBLWebUnit
instance.)- Each placement is implemented via a JS tag (not via a
TBLWebUnit
instance). These JS tags inject Taboola content into your own content.
In your Controller class:
- Initialize a
TBLWebPage
instance:
#import <TaboolaSDK/TaboolaSDK.h>
@property (nonatomic, strong) TBLWebPage *webPage;
- (void)viewDidLoad {
// Step 1 (this step):
_webPage = [[TBLWebPage alloc]initWithDelegate:self];
}
import TaboolaSDK
var webPage: TBLWebPage? // Page
override func viewDidLoad() {
// Step 1 (this step):
webPage = TBLWebPage.init(delegate: self)
}
- Create a single
TBLWebUnit
instance, for theTBLWebPage
that you initialized:
#import <TaboolaSDK/TaboolaSDK.h>
@property (nonatomic, strong) TBLWebPage *webPage;
@property (nonatomic, strong) TBLWebUnit *webUnit;
- (void)viewDidLoad {
// Step 1:
_webPage = [[TBLWebPage alloc]initWithDelegate:self];
// Step 2 (this step):
_webUnit = [webPage createUnitWithWebView:<webview>];
// (Apply optional setters here, if needed...)
}
import TaboolaSDK
var webPage: TBLWebPage? // Page
var webUnit: TBLWebUnit?
override func viewDidLoad() {
// Step 1:
webPage = TBLWebPage.init(delegate: self)
// Step 2 (this step):
webUnit = webPage?.createUnit(with: webView)
// (Apply optional setters here, if needed...)
}
- Make sure that your web view allows inline video via JavaScript. You can enable this via the StoryBoard or via code.
Example (via code):
WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
[config setAllowsInlineMediaPlayback:YES];
[config.preferences setJavaScriptCanOpenWindowsAutomatically:YES];
let config = WKWebViewConfiguration()
config.allowsInlineMediaPlayback = true
config.preferences.javaScriptCanOpenWindowsAutomatically = true
allowsInlineMediaPlayback
The
allowsInlineMediaPlayback
flag ensures that video content remains within the placement container and does not expand to fill the entire view.
- Once you have created the single
TBLWebUnit
instance, your integration is complete. The rest of the work is done by the JS tags. However, if you are usingUIPageViewController
, see the instructions below.
The Click Event
Taboola Web Integration provides a TBLWebPageDelegate
for event handling.
If desired, you can intercept the click event, and open organic content directly within your app:
- (BOOL)webView:(WKWebView *)webView didClickPlacementName:(NSString *)placementName itemId:(NSString *)itemId clickUrl:(NSString *)clickUrl isOrganic:(BOOL)organic {
// Insert your code here...
// Return 'NO' to handle the click event yourself - or 'YES' for Taboola to handle it.
// Note: you can override the default behavior for *organic* content only.
return YES;
}
func webView(_ webView: WKWebView!, didClickPlacementName placementName: String!, itemId: String!, clickUrl: String!, isOrganic organic: Bool) -> Bool {
// Insert your code here...
// Return 'false' if you are handling the click event yourself, or 'true' if you want Taboola SDK to handle the click event.
// Note: you can override the default behavior for *organic* content only.
return true;
}
You can override the default behavior for organic content only.
For more information, see Event Handling and didClickPlacementName.
Working with UIPageViewController
When working with UIPageViewController
, make sure to fetch Taboola content when the next page is visible to the user (not before).
- For each JS tag in the of your web content, add
lazyFetch: true
:
<script type="text/javascript">
...
_taboola["mobile"].push( {
lazyFetch: true // If you are using a `UIPageViewController`
});
</script>
- Because you added a
lazyFetch
directive within the JS tag, you must fetch Taboola content via your view controller:
// Invoke *once only*, from within `viewWillAppear()`:
[_webUnit fetchContent:self.webView]; // When using `UIPageViewController`
// Invoke *once only*, from within `viewWillAppear()`:
webUnit?.fetchContent(webView) // When using `UIPageViewController`
UIPageViewController
If you prefetch more than 1 page using
UIPageViewController
:
- Fetch Taboola content when the next page is visible to the user - i.e. in the
viewWillAppear
method.- Fetch content once only (not every time the
viewWillAppear
method is fired).
Dark Mode
Dark mode is not supported by default. For dark-mode placements, contact your Taboola Account Manager.
Once Taboola has configured your dark-mode placements, you can use the following code in your application:
[_webPage setPageExtraProperties:@{@"darkMode":@"true"}];
webPage?.pageExtraProperties = ["darkMode":"true"]
Well Done!
You have completed the basic integration steps!
If everything is working smoothly, take a look at the What's Next section below.
Taboola content not rendering?
- Test with the same params as the sample app, and see if those work.
- Still stuck? Submit a question In our forum.
What's next?
- For handling clicks and other important events, see Event Handling.
- In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR and CCPA respectively.
- If you have not already done so, make sure to look at our sample app.
- Once you are complete, submit your app for review - see the App Verification section.
IMPORTANT
Prior to launch, you must provide Taboola with a test app for verification. Skipping this step may result in a significant loss of revenue.
See: App Verification
Updated about 1 month ago