React native (Limited availability)

Welcome to the Quick Start Guide for displaying Taboola in your react-native app

πŸ“˜

React-native plugin versions

  • Latest Taboola plugin version: 2.1.0 (Released on October 6th, 2020)
  • The plugin verified working in react versions 0.63.x, 0.62.x, 0.61.x, 0.60.x and 0.59x
  • The plugin is using Taboola Android SDK 2.8.1, and Taboola iOS SDK 2.8.1

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.0.0" Please make sure you use it in your project's package.json

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

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"
}
  1. 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
  1. 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.8.1'
end
  1. Run pod install
  2. Don't forget to link the native dependencies
$ react-native  link  @taboola/react-native-taboola

Using React Native 0.60.x - 0.63.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:
android.useAndroidX=true
android.enableJetifier=true

iOS

For all react-native versions start by Installing Cocoapods

  1. Go to [your_project]/ios/
$ cd ios
  1. 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: Android - 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

Step 5: iOS - 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 - 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

🚧

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>

To render Taboola in a view:

<View style={{flex: 1, justifyContent: 'center',  alignItems: 'center'}}>
    <RNTaboolaView
    ...
    style={{height: number,  width: '100%' }}
    />
</View>

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

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:

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

Updated about a month ago


React native (Limited availability)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.