SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum


Have you gone through the instructions of Getting started?

  • Make sure to complete the [SDK installation ](๐Ÿ”—๏ปฟ)before performing the procedures in the following article.

  • Feed via Native supports iOS 9.0 and above (deployment target: iOS 9), The maximum supported Base SDK is iOS 13 (recommended), and the Minimum xCode version - 9.2

See our code examples!

On our [Github repository](๐Ÿ”—๏ปฟ), you may find numerousย code examplesย demonstrating the usage of our features.

Stuck? Confused? Use our Support Forum!

If you need quick help in integrating Taboola SDK into your help, you can use our [support forum](๐Ÿ”—๏ปฟ). The forum is monitored continuously by Taboola Support and will respond within 24 business hours.

## Step 1: Import Taboola SDK

For CocoaPods, import `TaboolaSDK` into your bridging header.

๏ปฟ

For Carthage, import the framework:

๏ปฟ

## Step 2: Initialize Taboola

Create a `PublisherInfo` object and init Taboola

๏ปฟ
  • `publisherId` - Your publisher ID as provided to you by Taboola account manager

## Step 3: Adding the TaboolaView

### Using Frames

๏ปฟ

### Using Constraints

Starting from iOS SDK 2.3.7, it is possible to create a `taboolaView` using constraints

๏ปฟ

## Step 4: Set the TaboolaView Object Properties

For your production properties, contact your account manager. For testing properties, see further down in this page.

๏ปฟ
  • `publisher` - Your publisher id parameter as provided by your Taboola account manager

  • `mode` - Your mode parameter as provided by your Taboola account manager

  • `placement` - Your placement parameter as provided by your Taboola account manager

  • `pageUrl` - The full URL of public web page which reflects the current screen's content

  • `pageId` - An internal identification for the current screen's content. Pass this along the page URL to set the item ID as your internal ID

  • `pageType` - Your page type parameter as provided by your Taboola account manager

  • `targetType` - Your target type parameter as provided by your Taboola account manager

## Step 5: Fetch Content

To show the feed, call `fetchContent` when the screen (view) loads

๏ปฟ

Important!

  • To maintain good UX - please fetch content **as soon as the screen loads** and not when the user reaches the Taboola area on the screen

  • When working with `UIPageViewController`, Please fetch the widget content only when the view is visible to the user

  • Make sure you load the `taboolaView` object only from the main UI thread

## Step 6: Set the cell height (In UICollectionView or UITableView)

Taboola Feed is using a static height. Please give the cell containing the feed a static height:

๏ปฟ

## Step 7: Set the scrolling behavior

Taboola Feed has a fixed size, usually in the bottom of the screen. When the user is scrolling down the screen, and the Feed is taking up the entire screen, the scrolling is switched from the app into Taboola Feed.

There are two ways of doing so:

  • Handled by Taboola's SDK - The SDK will detect when the Feed is taking over the screen and will handover the scroll from the app into the Feed.

  • Manually by the app - in case the app is implementing it own custom scrolling by listening to the native OS scroll listener

In addition to the above two ways, the publisher can retain the scrollling back at any time by using the `taboolaView.releaseScroll` method

**Handled by Taboola's SDK** Set the `setInterceptScroll` function to `true` in order to let Taboola's SDK to identify when it's the right moment to conduct the scroll switch from your app to Taboola's Feed

๏ปฟ

**Manually by the app** To manually hand over the scroll from the app into the Feed, you need to listen to the `scrollViewDidScroll` that notifies when the Feed is on the top of the screen and is scrolled up.

๏ปฟ

Example:

๏ปฟ

**releaseScroll method** When the scrolling is controlled by Taboola, after the scroll switch, there are situations where the screen goes back to the top. Usually, it happens after orientation change, after the user clicks an iten and etc. To gain back control over the scrolling, invoke the `releaseScroll` method

๏ปฟ

## Step 8: Show the progress bar

A loading progress bar will show up when switching the scroll to the Taboola Feed. The progress bar will preserve a good UX for your users and smooth the experience when moving the scroll from your app into Taboola Feed.

You can control the UI indicator visibility and color by using the following functions:

  • `setProgressBarColor:@"#4286f4"` - sets the color of the UI indicator, by default the value is dark blue

  • `setProgressBarDuration(3) - sets the progress bar duration in seconds, the default value is 0.7 seconds

  • `setProgressBarEnabled:Yes` - Activate/deactivate the progress bar when the automatic scroll switch is enabled. The default value is `Yes`

๏ปฟ
  • `startProgressBarAnimation` - shows the progress bar on the bottom of the screen, when you manually controlling the scroll switch

## Step 9: Additional Integration Information (Optional)

This section describes some optional points in the integration.

### Delegates

To receive client-side callbacks, the client can set a delegate for each widget. The following events are available:

  • `didLoadPlacementNamed` - Triggered after the TaboolaView is successfully rendered; returns the placement name and the updated height value

  • `didFailToLoadPlacementNamed` - Triggered after the TaboolaView fails to render; returns the placement name and the error string value. Since iOS SDK 2.5.0, it is possible to get the detailed error strings by activating the `detailedErrorCodes` feature flag; `NO_ITEMS` (no fill by Taboola), `WRONG_PARAMS` (wrong "tb_mode" was used), `RESPONSE_ERROR`, `TIMEOUT` (connectivity issue), `UNKNOWN_ERROR`, and `INTERNAL_1`

Example:

๏ปฟ

Important!

It is important to implement the `didFailToLoadPlacementNamed` delegate for the unlikely event of an error or no fill.

### Intercepting Organic Recommendation Items Clicks

The SDK enables app developers to change the default behavior when a user clicks on an organic item. For example, you might want to create a click-through or override the default way of opening the organic recommended article.

๏ปฟ

The above method is called every time a user clicks a recommendation, immediately before triggering the default behavior. If recommendation clicks are not intercepted, they are presented by a Taboola powered in-app browser. It is also important to note that TaboolaView also fires notifications that can be caught by any object inside the app. This is in case you want to react to these notifications elsewhere in your code.

The app can intercept the click there, and returns a boolean value:

  • Returns NO - abort the default behavior (in which case the app displays the recommendation content on its own - e.g. using a custom in-app browser)

  • Returns YES - this enables the app to implement a click-through and continue with the default click handling behavior (which displays the clicked content with an in-app browser)

  • "organic" indicates whether the item clicked was an organic content recommendation or not. Best practice is to suppress the default behavior for organic items. 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

### Replacing the Default In-app Browser Icons

The file <code>TaboolaViewResources.bundle</code> includes the default icons for the TaboolaView in-app browser. You can replace these icons by providing an alternative <code>TaboolaViewResources.bundle</code> file which contains the following files:

  • back_icon.png

  • forward_icon.png

Important!

In some cases the delegates parameters can be with null value. Please make sure to handle such a case in your code.

### Using more than one Taboola asset on the same screen

It is possible to add more than one Taboola asset on the same screen. For example, placing two Taboola widgets on a feed style screen. When doing so it is important to avoid duplicate items on each asset

  1. Set the same `viewId` value for each taboolaWidget object before fetching content. The `viewId` value must be a string of digits. We recommend using the current epoch timestamp. In any case, the `viewId` value can not exceed 19 digits.

  2. Fetch the content for the second asset only after a response is received for the first asset. Please use the `didLoadPlacementNamed` to listen to render is done events

To do so, please make sure you do the following:

๏ปฟ

## Step 10: Resetting Taboola When Closing the Screen

Do not forget to reset Taboola when leaving the current screen.

๏ปฟ

## Step 11: Testing and Examples

You can find code examples on our [Github repository](๐Ÿ”—๏ปฟ).

You can use the following parameters for testing and development. Sponsored items are flagged with an "SC: " prefix in the title; organic items are flagged with an "OC: " prefix in the title

ParametersBelow Article Feed
publisher"sdk-tester-demo"
placement"Feed without video"
PageUrl"https://blog.taboola.com"
PageType"article"
TargetType"mix"
mode"thumbs-feed-01"

## Step 10: Submit Build for QA

When you have finished the integration, contact your account manager and send a debuggable (TestFlight or other beta platform) version of your iOS project.

**You're done!**

## Integration Support

Should you have any problems integrating the product, log a ticket with us by emailing your account manager. For a quick support you can also check our [discussion forum](๐Ÿ”—๏ปฟ)๏ปฟ