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 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.
• 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' }
    }
}

Basic Integration

Taboola initialization

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)

Taboola content instances

1. In the relevant component, create a Taboola Page:

const page = Taboola.getClassicPage(
  pageUrl,
  pageType
).init();

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

Then, for each Taboola Unit on that page:

2. Create state variables for the Taboola Unit:

const [unitRef, setUnitRef] = useState<ClassicUnitRefType | null>(null);

📘

State variables

• unitRef - A reference to the Taboola Unit, that can be used to fetch Taboola content, etc.
• setUnitRef- Will be used by the <TBLClassicUnit> component to obtain a reference to unitRef.

3. Implement the useEffect hook, and use unitRef to fetch Taboola content:

useEffect(() => {
   unitRef.fetchContent();
}, [unitRef]);

4. Create a <TBLClassicUnit> component. (Each Unit represents a Taboola Widget or Feed.)

<View style={{ flex:1 }}>
  <TBLClassicUnit
  publisherParams={{
    classicPageId: page?.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.

Advanced options

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

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";

// 'Page' creation

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

// 'Unit' state vars

const [unitRef, setUnitRef] = useState<ClassicUnitRefType | null>(null);
const [unitRef2, setUnitRef2] = useState < ClassicUnitRefType | null > (null);

// Fetching content

useEffect(() => {
  unitRef?.fetchContent();
}, [unitRef]);

useEffect(() => {
  unitRef2?.fetchContent();
}, [unitRef2]);

// 'Page' object cleanup

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

// 'Unit' components

<>                   
<View style={{ flex: 1 }}>
    <TBLClassicUnit
      publisherParams={{
        classicPageId: page?.pageId,        
        placement: “Mid Article”,
        mode:”alternating-widget-with-video-1x1”,
        placementType: TBL_PLACEMENT_TYPE.PAGE_MIDDLE,
      }}
      ref={setUnitRef}

      onAdReceiveFail={() => {}}
      onItemClick={(e) => console.log(e)}
      onResize={(e) => console.log(e, 'New height')}
      
      extraProperties={{
        enableHorizontalScroll: 'true',
        keepDependencies: 'true',
      }}
      
      style={{
        width: '100%',
        flex: 1,
        backgroundColor: RED,
      }}
    />
</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={setUnitRef2}

      onAdReceiveFail={() => {}}
      onItemClick={(e) => console.log(e)}
      onResize={(e) => console.log(e, 'New height')}
      
      extraProperties={{
        enableHorizontalScroll: 'true',
        keepDependencies: 'true',
      }}
      
      style={{
        width: '100%',
        flex: 1,
        backgroundColor: RED,
      }}
    />
</View>
</>

🚧

Multiple Taboola units

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

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.