SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum


ο»Ώ

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

  1. Create empty folder for the plugin assets - `Your project]/android/app/src/main/ (+ assets)`

  2. Add the following script to the `package.json` file

ο»Ώ
  1. If you're using AndroidX, please add the following lines:

ο»Ώ

#### iOS

  1. Start by installing Cocoapods

ο»Ώ
  1. 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](πŸ”—ο»Ώ)ο»Ώ

  1. Run `pod install`

  2. Don't forget to link the native dependencies

ο»Ώ

### Using React Native 0.60.x - 0.69.x

#### Android

  1. Create empty folder for the plugin assets - `Your project]/android/app/src/main/ (+ assets)`

    1. If you're using AndroidX, please add the following lines:

ο»Ώ

#### iOS

For all react-native versions start by Installing Cocoapods

  1. Go to `[your_project]/ios/`

ο»Ώ
  1. 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 so

  • If 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 WidgetTaboola 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:

  1. Select the project within the project navigator (top, left).

  2. Select the `Build Settings` tab (right). Make sure that the `All` tab (just below) is also selected.

  3. Under `Architectures`, locate the `Excluded Architectures` node.

  4. 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

  1. 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**.