📘

Have you gone through the instructions of Getting started?

• Make sure to complete the [SDK installation](🔗) before performing the procedures in the following article.

• Widget via Native supports iOS version 6.0 and above. iOS deployment target should be set to 6.0 or later.

📘

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 TaboolaWidget

### 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 a 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 widget, 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: Adjust the Widget height

Taboola Widget adjusts it height automatically. We highly recommend to use this option as the final height of the widget may dynamically change according to the different UI mode that is loaded in Taboola Backstage.

In order to adjust your app layout to these changes, set 'autoResizeHeight' to YES (This is the default) and listen to the height parameter within the `didLoadPlacementNamed` delegate (See in Step 7)

Please keep in mind that the widget height can change throughout the app lifecycle **after** the first loading event - make sure you are listening to the `didLoadPlacementNamed` for any height change.

If wish to adjust the size of Taboola Widget manually, you can do so by setting `autoResizeHeight` to `NO`.

## Step 7: 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:

### 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 to override the default way of opening the organic recommended article.

The 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

🚧

Important!

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

### 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

### 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 8: Resetting Taboola When Closing the Screen

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

## Step 9: 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

## 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](🔗)