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 userMake 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
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.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
Parameters | Mid Article Widget | Below Article Widget |
publisher | "sdk-tester-demo" | "sdk-tester-demo" |
placement | "Mid Article" | "Below Article" |
PageUrl | "https://blog.taboola.com" | "https://blog.taboola.com" |
PageType | "home" | "home" |
TargetType | "mix" | "mix" |
mode | "alternating-widget-without-video-1-on-1" | "alternating-widget-without-video-1x4" |
## 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](🔗)