React native

🚧

Plugin version

This page describes version 2.x of the plugin, which has been deprecated.

We recommend upgrading to version 3.x at your earliest convenience.

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:

$ npm install @taboola/react-native-taboola --save

The current stable version is "2.3.8" Please make sure you use it in your project's package.json

@taboola/react-native-taboola": "2.3.8"

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

"scripts":{
  ...
    "android-linux": "react-native bundle --platform android --dev true --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle - assets-dest android/app/src/main/res && react-native run-android"
}

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

android.useAndroidX=true
android.enableJetifier=true

iOS

1. Start by installing Cocoapods

$ gem install cocoapods

2. Add Taboola to your Podfile under [your_project/ios/]

target 'YourProjectName' do
# Uncomment the next line if you're using Swift or would like to use dynamic frameworks
# use_frameworks!

# Pods for YourProjectName
   pod 'TaboolaSDK', '2.9.2'
end

🚧

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

3. Run pod install
4. Don't forget to link the native dependencies

$ react-native  link  @taboola/react-native-taboola

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)
2. 3. If you're using AndroidX, please add the following lines:

android.useAndroidX=true
android.enableJetifier=true

iOS

For all react-native versions start by Installing Cocoapods

1. Go to [your_project]/ios/

$ cd ios

2. Run pod update

$ pod update

Step 3: Import the plugin to your project

Import Taboola

import RNTaboolaView from '@taboola/react-native-taboola';

Use the plugin in your app

<RNTaboolaView />

Step 4: Add Taboola Widget or Feed

Taboola Widget

Define your Taboola parameters for Taboola Widget

const [height, setHeight] = useState(0);

<RNTaboolaView
  mode = "alternating-widget-without-video-1-on-1"
  publisher = "sdk-tester"
  pageType = "article"
  pageUrl = "https://blog.taboola.com"
  placement = "Mid Article"
  targetType = "mix"
	style={{height,  width: “100%“}}
  viewID= "12345"
  darkMode={false} 
	onDidLoad={event => {
	// Set the height of the widget dynamically 
		setHeight(parseInt(event.nativeEvent.height, 10));
	}}
/>

• 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

<RNTaboolaView
  mode = "thumbs-feed-01"
  publisher = "sdk-tester"
  pageType = "article"
  pageUrl = "https://blog.taboola.com"
  placement = "Feed without video"
  targetType = "mix"
  interceptScroll = {true}
  style={{feedHeight}}
  viewID = "12345"
  darkmode={false}
/>

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

<View style={{ flex: 1, justifyContent: 'center' }}>
<FlatList
            style={{ flex:1}}
            ...
            renderItem={({ item }) => (
                <RNTaboolaView
                    ...
                    style={{ height:number, width: '100%'}}
                />
            )}
 />
</View>

🚧

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:

<View style={{flex: 1, justifyContent: 'center',  alignItems: 'center'}}>
	<RNTaboolaView
	...
	style={{height: number,  width: '100%' }}
	/>
</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.

onItemClick = {
    (event) => {
        console.warn('onOrganicItemClick ' + event.nativeEvent.itemId);
        console.warn('url: ' + event.nativeEvent.clickUrl);
        console.warn('name: ' + event.nativeEvent.placementName);
        console.warn('is organic: ' + event.nativeEvent.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

onDidLoad = {
    (event) => {
        console.warn('onDidLoad : ' + event.nativeEvent.placementName + '- height -: ' + event.nativeEvent.height);
    }
}
onDidFailToLoad = {
    (event) => {
        console.warn('onRenderFail placementName: ' + event.nativeEvent.placementName);
        console.warn('onRenderFail error: ' + event.nativeEvent.error);
    }
}

❗️

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):

"@react-navigation/bottom-tabs": "^5.11.7",
"@react-navigation/native": "^5.9.2",

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:

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

<RNTaboolaView
	extraProperties={{"cdns":"false", "cex":"true"}}
/>

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

<RNTaboolaView
	extraProperties={{"cdns":"false", "cex":"true"}}
/>

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:

building for iOS Simulator, but linking in dylib built for iOS, file '../TaboolaSDK.framework/TaboolaSDK' for architecture arm64

📘

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:

post_install do |installer|
  installer.pods_project.build_configurations.each do |config|
    config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
  end
end

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 thenclean and rebuild your project.

rm -rf ~/Library/Developer/Xcode/DerivedData/
pod deintegrate
pod update

🚧

The sample script

• Removes all build cache from Xcode.
• Updates all pods across your project.