ο»Ώ
You are viewing the **2.x** docs. For the **3.x** docs (_current version_), go [here](πο»Ώ).
Welcome to the Quick Start Guide for displaying Taboola in your react-native app
React-native plugin versions
Latest Taboola plugin version: 2.3.8 (Released on December, 2022)
The plugin verified working in react versions 0.70, 0.69, 0.68, 0.67, 0.66x, 0.65x, 0.64.x, 0.63.x, 0.62.x, 0.61.x, 0.60.x and 0.59.x
The plugin is using Taboola Android SDK 2.9.3, and Taboola iOS SDK 2.9.2
Take a look at our React-Native [Example App](πο»Ώ)ο»Ώ
## Step 1: Install the native dependencies
To Install the plugin, please open terminal in your project folder and run the following command:
The current stable version is **"2.3.8"** Please make sure you use it in your project's `package.json
`
## Step 2: Prepare the project for the plugin
### Using react-native 0.59.x
#### Android
Create empty folder for the plugin assets - `
Your project]/android/app/src/main/ (+ assets)
`Add the following script to the `
package.json
` file
If you're using AndroidX, please add the following lines:
#### iOS
Start by installing Cocoapods
Add Taboola to your Podfile under `
[your_project/ios/]
`
M1/M1X machines
If you are using an **M1/M1X machine**, add an exclusion for `
arm64
` to your Podile (_as well as_ your project settings). This will prevent potential problems with the **iPhone simulator**.See: [Troubleshooting > iPhone simulator with M1/M1X machine](πο»Ώ)ο»Ώ
Run `
pod install
`Don't forget to link the native dependencies
### Using React Native 0.60.x - 0.69.x
#### Android
Create empty folder for the plugin assets - `
Your project]/android/app/src/main/ (+ assets)
`If you're using AndroidX, please add the following lines:
#### iOS
For all react-native versions start by Installing Cocoapods
Go to `
[your_project]/ios/
`
Run `
pod update
`
## Step 3: Import the plugin to your project
Import Taboola
Use the plugin in your app
## Step 4: Add Taboola Widget or Feed
### Taboola Widget
Define your Taboola parameters for Taboola Widget
mode - Your mode parameter as provided by your Taboola account manager
publisher - Your publisher parameter as provided by your Taboola account manager
pageType - Your page type parameter as provided by your Taboola account manager
pageId - in case you want to pass your own internal id for the current screen (optional), consult with your Taboola account manager
pageUrl - The full URL of a public web page which reflects the current screen's content
placement - Your placement parameter as provided by your Taboola account manager
targetType - Your target type parameter as provided by your Taboola account manager
style - Taboola Widget is using a dynamic height that changes according to the layout design and ad slots within it. Please listen for the height value in the `
onDidLoad
` (see step 7 below) event and set it with `useState
`viewID - When adding more than one Taboola asset to the same screen, add the same "viewId" value for each asset. The value must be a numeric (digits) string
darkMode - a boolean value that sets the Taboola asset color theme. Please make sure your Taboola contact set up a dark UI mode before using it
### Taboola Feed
Define your Taboola parameters for Taboola Feed
mode - Your mode parameter as provided by your Taboola account manager
publisher - Your publisher parameter as provided by your Taboola account manager
pageType - Your page type parameter as provided by your Taboola account manager
pageId - in case you want to pass your own internal id for the current screen (optional), consult with your Taboola account manager
pageUrl - The full URL of a public web page which reflects the current screen's content
placement - Your placement parameter as provided by your Taboola account manager
targetType - Your target type parameter as provided by your Taboola account manager
interceptScroll - For Taboola Feed - set it to true at all times
style - The feed height is fixed to the size of two times the screen. Set `
feedHeight
` to be `const feedHeight = Dimensions.get('window').height * 2
`viewID - When adding more than one Taboola asset to the same screen, add the same "viewId" value for each asset. The value must be a numeric (digits) string
darkMode - a boolean value that sets the Taboola asset color theme. Please make sure your Taboola contact set up a dark UI mode before using it
Horizontal Scrolling (for Android)
If you implemented **horizontal scrolling** in your **Android App**, you must add the following param:
`
extraProperties={{"enableHorizontalScroll": "true"}}
`
Important!
Please note that all of the `
RNTaboolaView
` properties are case sensitive
### To render Taboola in a view -> FlatList:
Important!
When adding Taboola Widget or Feed to a FlatList with React Native version 0.60 and above , please add removeClippedSubviews={false} prop to the FlatList
### To render Taboola in a view:
## Step 5: Click handling
By default, Taboola opens the items (sponsored and organic content) on Chrome Custom Tabs, or in SafariViewController.
You can override the OC (organic items) behavior and open the items as you wish. If youβre handling the OC click, please add `taboolaHandleOrganicClick = {false}
` in the RNTaboolaView properties.
The click handling (SC and OC) is done using the - βonItemClickβ method - which will return the following fields: placementName, itemId, clickUrl, isOrganic.
## Step 6: Events
The plugin can notify upon two events: when the rendering is successful (onDidLoad), and when the rendering fails (onDidFailToLoad)
Please note that the `event.nativeEvent.height
` value can be either string or integer
Important
It is mandatory to implement the events. Not doing so may result stability issues
When adding more than one Taboola asset on the same screen, you must call the 2nd asset only after the first asset finished loading. You should use the `
onDidLoad
` event for doing soIf you use XCode 13 for compiling react native app and have issue with scrolling feed nested in ScrollView component after switching from portrait to landscape mode pass `
nestedScrollEnabled={true}
` prop
## Step 7: Using Taboola Widget/Feed within Navigation (Tabs)
When using Taboola's Widget/Feed within react-native, please make sure the following libraries use the following versions (and above):
## Step 8: Testing & Examples
If you do not yet have your production parameters, please contact your Taboola account manager.
For testing parameters use the following options:
Column Titleο»Ώ | Taboola Widget | Taboola Feed |
publisher | "sdk-tester-demo" | "sdk-tester-demo" |
placement | "Mid Article" | "Feed without video" |
PageUrl | "<https://blog.taboola.com>" | "<https://blog.taboola.com>" |
PageType | "article" | "article" |
TargetType | "mix" | "mix" |
mode | "alternating-widget-without-video-1x4" | "thumbs-feed-01" |
Github example project - <https://github.com/taboola/taboola-react-native-example>
## Step 8: Submit your app for Taboola review
It's mandatory to to submit your app for Taboola review before going live with the plugin. Please send a debuggable build (with the ability to proxy [SSL](πο»Ώ) as desribed [here](πο»Ώ) traffic) to your account or solution manager
## GDPR and CCPA
### GDPR - TCFv1
Taboola React-native plugin 1.x supports the IAB Consent framework (TCFv1). If you implemented a CMP, the plugin will pass the shared consent string to Taboola.
### GDPR - TCFv2
Taboola React-native plugin 2.0.0 and onwards version supports the IAB Consent framework (TCFv2). If you implemented a CMP, the plugin will pass the shared consent string to Taboola.
### GDPR - Passing the consent status directly
It is possible to forward the consent status to Taboola plugin on each time the widget/feed is initialized using a dedicated flag - `cex
`. The consent boolean value (in string format) should be passed on each session.
By default, the value of this flag is set to "true" - allowing Taboola to use the user's data. Please use the flag only when the end-user is GDPR subject and set it to "true" (user provided consent), or "false" (user didn't provide consent). It is recommended to place these lines alongside the other settings, such as publisher name, etc
### CCPA - IAB CCPA Framework
Taboola added support for the IAB CCPA Framework ("IABUSPrivacy_String") in react native plugin 1.3.0 (that is using Android and iOS SDK 2.5.0). Please make sure you are using this SDK version or above.
### CCPA - Passing the CCPA status directly to Taboola
It is possible to forward the CCPA "Do Not Sell" (dns) status to Taboola SDK on each time the widget/feed is initialized using a dedicated flag - `cdns
` The value (in string format) should be passed on each SDK session.
`
true
` - CCPA applies, and the end-user opted-out per CCPA requirements`
false
` - CCPA applies, and the end-user didn't opt-out per CCPA requirements`
none
` - CCPA does not apply (the default status)
By default, the value of this flag is set to none - the end-user is not CCPA subject, allowing Taboola to use the user's data. It is recommended to place these lines alongside the other settings, such as publisher name, etc
## Integration Support
Should you have any problems integrating the product, please contact `[email protected]
` and `[email protected]
`. For non official SLA support you can also check our [discussion forum](πο»Ώ)ο»Ώ
## Troubleshooting
## ## iPhone simulator with Apple silicon (M1/M2)
### Problem
In some cases, when running the iPhone **simulator** with an **Apple silicon (M1/M2)** machine, Xcode throws the following error:
ο»Ώ
This issue affects the simulator **only** - not real devices.
### Resolution
To work around this problem, add `arm64
` to the excluded architectures for both your project _and_ your Podfile.
#### Step 1: Update your project settings
Using Xcode:
Select the project within the project navigator (top, left).
Select the `
Build Settings
` tab (right). Make sure that the `All
` tab (just below) is also selected.Under `
Architectures
`, locate the `Excluded Architectures
` node.Next to the `
Debug
` or `Release
` node, click on the `+
` icon to add a new exclusion:For the key, select `
Any iOS Simulator SDK
`.For the value, type in `
arm64
`.
ο»Ώ
Depending on your needs, add an exclusion under **Debug** or **Release** - or both.
#### Step 2: Update your Podfile
Add the following code snippet to your Podfile:
#### Additional steps
If the above steps do not resolve the problem, you may need to update your existing pods (a sample script is provided below) - and then`clean
` and `rebuild
` your project.
The sample script
Removes **all build cache** from Xcode.
Updates **all** pods **across your project**.