React Native Plugin 3.x

📍

You are viewing the 3.x docs (recommended version). For the 2.x docs, go here.

👍

While reading the documentation, take a look at our Sample App.

🚧

(2024-11-10) New React Native Architecture

With the release of React Native 0.76 , the New React Native Architecture is now enabled by default.

If you are using React Native 0.76 or higher, make sure to opt out the new architecture (as decribed in the instructions below).

Support for the new architecture is underway, and will be included in a future release of the Taboola React Native Plugin.

Overview

This guide explains how to integrate Taboola recommendations into your React Native app, using Taboola's React Native Plugin 3.x.

Taboola's React Native Plugin 3.x is the latest major version of the plugin. It includes a number of enhancements, aimed at simplifying the integration process and minimizing errors.

📘

Key changes in RN Plugin 3.x

• Widget and Feed are now instances of the same class ('Unit'), and use a similar flow.
• Widget and Feed heights are now set automatically.
• You can now add multiple Taboola units to the same screen (without loading them sequentially).
• Placement View IDs are now managed automatically.
• Serial loading is now managed automatically.
• targetType is now "mix" by default.
• You can choose to fetch content manually (e.g. to cater for special scenarios).
• Added support forTypeScript:

  • Validation of type correctness.
  • Code completion and IntelliSense.
  • Documentation via toolips.

Dependencies

React Native

1. Navigate to the root of your project folder and run the following npm command:

npm i @taboola/react-native-plugin-3x

iOS

1. If not already present, install CocoaPods:

   $ sudo gem install cocoapods
$ pod setup --verbose

2. Navigate to your project's ios directory, and install Taboola SDK:
   1. For React Native 0.76 or higher, install and opt out of the new architecture:
      Terminal

      RCT_NEW_ARCH_ENABLED=0 pod install
      

   2. For older React Native versions:
      Terminal

      pod install
      

🚧

Apple silicon

If you are using an Apple silicon machine, add an exclusion for arm64 to your Podfile (as well as your project settings). This will prevent potential problems with the iPhone simulator.

For more detail, refer to the Troubleshooting section.

Android

In your project's Android folder, edit build.gradle:

1. Add the Taboola url under allprojects > repositories > maven:

allprojects {
    repositories {
        ...
        maven {
            // Taboola:
            url 'https://taboolapublic.jfrog.io/artifactory/mobile-release'
        }
    }
}

A sample build.gradle file

allprojects {
    repositories {
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url("$rootDir/../node_modules/react-native/android")
        }
        maven {
            // Android JSC is installed from npm
            url("$rootDir/../node_modules/jsc-android/dist")
        }
        mavenCentral {
            // We don't want to fetch react-native from Maven Central,
            // seeing as there are older versions there.
            content {
                excludeGroup "com.facebook.react"
            }
        }
   
        // Add Taboola to your app:
        maven {
            url 'https://taboolapublic.jfrog.io/artifactory/mobile-release'
        }
        google()
        maven { url 'https://www.jitpack.io' }
    }
}

2. For React Native 0.76 or higher, add the following line to gradle.properties (to opt out of the new architecture):

newArchEnabled = false

Initialize Taboola

1. In your application entry-point file, initialize Taboola:

import { Taboola } from '@taboola/react-native-plugin-3x';

Taboola.init('publisher-id');

📘

publisher-id - A unique, alphabetic String, provided by Taboola - e.g."<<publisherID>>".

🚧

Initialization should be done as soon as possible, preferably in your application entry-point (index.js or index.ts)

Create a Page instance

1. In the relevant component, use the useMemo hook to create a Taboola Page:

const page = useMemo(
  () =>
    Taboola.getClassicPage(
      <pageURL>,
      <pageType>
    ),
  []
);
const [pageId] = useGetPageId(page);

const page = useMemo(
  () =>
    Taboola.getClassicPage(
      'https://www.example.com/articles?id=123',
      'article'
    ),
  []
);
const [pageId] = useGetPageId(page);

📘

Params

• pageUrl - A fully-qualified, public URL, with the same content as the current screen. E.g. "https://www.example.com/articles?id=123".
• pageType - The page type, as provided by Taboola - e.g. "article".

---

For an example, see above (second tab).

🚧

useMemo hook

When creating the Taboola Page make sure to use the useMemo hook.

Failure to do so can result in memory leaks.

Create Unit instances

🚧

Fetching content automatically

Fetching content automatically simplifies development and is recommended.

However, for special use cases, you may decide to fetch content manually.

---

See: Advanced options > Fetching content manually

For each Taboola Unit on the page:

Create a <TBLClassicUnit> component. (This represents a Taboola Widget or Feed.)

📘

Include the isAutoFetch param and set it to true.

<View style={{ flex:1 }}>
  <TBLClassicUnit
  publisherParams={{
    classicPageId: pageId,
    placement:<placement>,                    
    mode:<mode>,
    placementType: <placementType>,
  }}
  isAutoFetch={true}
  style={{
    width: '100%',
    flex: 1,
  }}/>
</View>

<View style={{ flex:1 }}>
  <TBLClassicUnit
  publisherParams={{
    classicPageId: page?.pageId,                    
    placement:”Below Article Thumbnails Limited-20”,
    mode:”thumbs-feed-01”,
    placementType: TBL_PLACEMENT_TYPE.FEED,
  }}
  isAutoFetch={true}
  style={{
    width: '100%',
    flex: 1,
  }}/>
</View>

📘

Params

• placement - The placement name, as provided by Taboola - e.g. "<<placementNameLimited20>>".
• mode - The UI Mode ID of the unit, as provided by Taboola - e.g. "<<mode>>".
• placementType - The unit type (see below for possible values).

---

For an example, see above (second tab).

🚧

Multiple Taboola units

With v3 of the Taboola plugin, you can add multiple Taboola units to the same screen (without loading them sequentially).

---

See the code sample at the end of this page.

Re-rendering

🚧

Preventing a memory leak

If you re-render a component that contains Taboola units, make sure to also re-create the Taboola page.

Failure to do so can cause a memory leak.

Additional props

You can (optionally) declare additional props in your <TBLClassicUnit> component:

📘

Callback props

• onItemClick - called when an item is clicked.
• onAdReceiveFail - called if Taboola SDK fails to fetch Taboola content.
• onResize - called when a unit is resized.
• onAdReceiveSuccess - called when the placement received an ad.
• onUpdateContentCompleted - called when update content completed.

---

See the code sample at the end of this page.

📘

style

You can style the <TBLClassicUnit> component using a style prop.

📘

extraProperties

You can optionally include an extraProperties prop, with 1 or more extra properties.

---

See: extraProperties

extraProperties

The extraProperties prop allows you to pass 1 or more extra properties. Commonly used properties are listed below.

darkMode

🚧

Configuring Dark Mode

Dark mode is not supported by default. To configure your placements for dark mode, contact your Taboola Account Manager.

Once Taboola has configured your placements for dark mode, you can use the darkMode param to show the dark mode units:

const page = useMemo(
  () =>
    Taboola.getClassicPage(
      pageUrl,
      pageType
    ),
  []
);
const [pageId] = useGetPageId(page);
page.setPageExtraProperties({ darkMode: 'true' })

🚧

Swapping Between Dark & Light Themes

Setting extraProperties with "darkMode" "true" will send a request for "dark" content.
For light content do not set the extra property at all and avoid using ("darkMode", "false").

Example snippet:

if (theme.dark) {
page.setPageExtraProperties({ darkMode: 'true' })
}

keepDependencies

Retains the page object reference, when switching back and forth between tabs.

🚧

If your screen/page provides a tabbed view, pass this property and set it to true.

extraProperties={{
	keepDependencies: 'true',
}}

enableHorizontalScroll

Enables horizontal gestures within a Taboola Feed.

extraProperties={{
	enableHorizontalScroll: 'true',
}}

🚧

By default, the Taboola Feed does not allow horizontal gestures.

Removing the page

1. Use the useEffect hook to clear the Taboola page from memory, whenever the component is unmounted:

useEffect(() => {
  return () => {
    // Clear page
    page.remove();
  };
}, [page]);

🚧

To conserve memory, invoke remove() whenever the component is unmounted.

Click Handling

🚧

TouchableOpacity

If you are using <TouchableOpacity>, see the Troubleshooting section.

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 TBLClassicUnit properties.

<View style={{ flex:1 }}>
  <TBLClassicUnit
  publisherParams={{
    classicPageId: pageId,
    placement:<placement>,                    
    mode:<mode>,
    placementType: <placementType>,
    taboolaHandleOrganicClick = {false}
  }}
  ref={setUnitRef}
  style={{
    width: '100%',
    flex: 1,
  }}/>
</View>

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);
    }
}

Code sample

🚧

Always use your own param values, as provided by Taboola.

import {
    Taboola,
    TBL_PLACEMENT_TYPE,
    TBLClassicUnit,
    useGetPageId,
} from "@taboola/react-native-plugin-3x";


// Taboola page
const page = useMemo(
  () =>
    Taboola.getClassicPage(
      'https://www.example.com/articles?id=123',
      'article'
    ),
  []
);

// Set page to 'dark mode'
page.setPageExtraProperties({ darkMode: 'true' });


// Taboola hook
const [pageId] = useGetPageId(page);


// 'Page' object cleanup
useEffect(() => {
  return () => {
    page.remove();
  };
}, [page]);


// TBLClassicUnit components
<>

<TBLClassicUnit
  isAutoFetch={true}
  style={{
    width: '100%',
    backgroundColor: RED,
  }}
  publisherParams={{
    classicPageId: pageId,                   
    placement: 'Mid Article',
    mode: 'alternating-widget-with-video-1x1',
    placementType: TBL_PLACEMENT_TYPE.PAGE_MIDDLE,
  }}
/>

<TBLClassicUnit
  isAutoFetch={true}
  style={{
    width: '100%',
    backgroundColor: RED,
  }}
  publisherParams={{
    classicPageId: pageId,                   
    placement: 'Below Article Thumbnails Limited-20',
    mode: 'thumbs-feed-01',
    placementType: TBL_PLACEMENT_TYPE.FEED,
  }}
/>

</>

🚧

Multiple Taboola units

With v3 of the Taboola plugin, you can add multiple Taboola units to the same screen (without loading them sequentially).

Sample app

👍

While reading the documentation, take a look at our Sample App.

What's Next?

1. For more advanced options, see Advanced Options.
2. Hit a few hurdles? Take a look at our Troubleshooting page.
3. In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR & CCPA respectively.
4. If you have not already done so, configure app-ads.txt for Taboola.
5. Contact Taboola so that we can verify your implementation.

💁🏻

Need a hand?

Go ahead! Ask a question in our Support Forum.

Tip: Provide as much detail as possible, including your platform and SDK version.