React Native Plugin 3.x (Beta)

📍

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

👍

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

Overview

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

Taboola's React Native Plugin 3.x Beta 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:

$ 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' }
    }
}

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, create a Taboola Page:

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

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

📘

• 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".

Create Unit instances

Flow 1 - Fetch content automatically (recommended)

🚧

This flow is simpler, and is typically preferred.

For each Taboola Unit on the page:

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

🚧

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.

Flow 2 - Manually fetch content

🚧

This flow is more advanced.

It allows you to fetch (or refresh ) content manually - e.g. to cater for special scenarios.

For each Taboola Unit on the page:

1. Implement the Taboola useNodeRef hook, and invoke fetchContent to fetch Taboola content:

// Fetch content - without keeping a reference to the Unit.
const [setUnitRef] = useNodeRef((unit) => {
   unit.fetchContent();
});

// Fetch content - and keep a reference to the Unit (`unitRef`).
// You can use that reference elsewhere in your code, to fetch or refresh content.
const [setUnitRef, unitRef] = useNodeRef((unit)=>{
  unit.fetchContent()
});

📘

Depending on your specific needs, you can optionally keep a reference to the Unit.

Refer to each of the code snippets, above.

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

📘

Include a reference to setUnitRef.

<View style={{ flex:1 }}>
  <TBLClassicUnit
  publisherParams={{
    classicPageId: pageId,
    placement:<placement>,                    
    mode:<mode>,
    placementType: <placementType>,
  }}
  ref={setUnitRef}
  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,
  }}
  ref={setUnitRef}
  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).

🚧

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.

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.

---

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.

For more detail, see the 'extraProperties' section below.

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

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

Advanced options

Dark Mode

🚧

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 darkMode true to show the dark mode widgets/feed and darkMode false to show the light mode. This is done on the page after initialization as the following snippet:

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

Additional methods

refresh()

Fetches new recommendations.

The scope is determined by the object invoking the method:

Sample code snippets:

<Button
  title={'Refresh Page'}
  onPress={() => {
    page.refresh();
    }}
/>

<Button
  title={'Refresh Unit'}
  onPress={() => {
    unitRef.current?.refresh();
    }}
/>

extraProperties

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

📘

For an example of a <TBLClassicUnit> with extraProperties, see the 'Code sample' section below.

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.

Code sample

2 Taboola units on a page

The following code illustrates the steps for fetching and displaying content for 2 Taboola units on a page.

🚧

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

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

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

const [pageId] = useGetPageId(page);

const [setUnitRef] = useNodeRef((unit) => {
  unit.fetchContent();
});
const [setUnitRef2] = useNodeRef((unit) => {
  unit.fetchContent();
});
<>
  
// 'Page' object cleanup
useEffect(() => {
  return () => {
    page.remove();
  };
}, [page]);

// TBLClassicUnit components
  <TBLClassicUnit
    ref={setUnitRef}
    publisherParams={{
      classicPageId: pageId,
      placement: 'Mid Article',
      mode: 'alternating-widget-with-video-1x1',
      placementType: TBL_PLACEMENT_TYPE.PAGE_MIDDLE,
    }}
    style={{
      backgroundColor: GREEN,
      flex: 1,
    }}
  />

  <TBLClassicUnit
    ref={setUnitRef2}
    publisherParams={{
      classicPageId: pageId,
      placement: 'Below Article Thumbnails Limited-20',
      mode: 'thumbs-feed-01',
      placementType: TBL_PLACEMENT_TYPE.FEED,
    }}
    style={{
      backgroundColor: RED,
      flex: 1,
    }}
  />
</>

🚧

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. Hit a few hurdles? Take a look at our Troubleshooting section.
2. In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR & CCPA respectively.
3. If you have not already done so, configure app-ads.txt for Taboola.
4. 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.