React Native Plugin

📍
You are viewing the 4.x docs (latest version). For the 3.x docs, go here.

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

✅
New React Native Architecture
Taboola React Native Plugin 4.x introduces full support for the React Native New Architecture, including TurboModules and Fabric.

Overview

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

Taboola's React Native Plugin 4.x introduces a more robust and flexible API by separating data-fetching logic from UI rendering. This gives developers more control - e.g. the ability to preload content that is still offscreen.

📘
Key changes in RN Plugin 4.x

Separation of concerns: Data fetching is now separate from UI rendering.

Enhanced control: More granular control over unit creation and content fetching.

Full New Architecture support: Native TurboModules and Fabric renderer compatibility.

Improved TypeScript support: Better type safety and developer experience.

New hook-based API: Uses useCreateUnit hook for unit creation.

Dependencies

React Native

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

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

iOS

If not already present, install CocoaPods:

$ sudo gem install cocoapods
$ pod setup --verbose
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.

Android

In your project's Android folder, edit android/setting.gradle:

Add this code to android/setting.gradle:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
  repositories {
    google()
    mavenCentral()
    maven {
      // Taboola:
      url 'https://taboolapublic.jfrog.io/artifactory/mobile-release'
    }
  }
}

Initialize Taboola

In your application entry-point file, initialize Taboola:

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

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

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

import { useMemo } from 'react';
import { Taboola, TBLClassicPage } from '@taboola/react-native-plugin-4x';

  const tblClassicPage = useMemo(
    () =>
      Taboola.getClassicPage(
        SDK_TESTER_PUBLISHER.PAGE_URL,
        SDK_TESTER_PUBLISHER.PAGE_TYPE
      ),
    []
  );

import { useMemo } from 'react';

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

📘
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 useMemo with a function initializer.
Failure to do so can result in memory leaks.

Create a Listener

Define a listener to handle events from the Taboola unit:

import { TBLClassicListener } from '@taboola/react-native-plugin-4x';

const tblClassicListener: TBLClassicListener = {
  onResize(height: number): void {
    // Handle unit resize
  },
  onEvent(actionType: number, data: string): void {
    // Handle general events
  },
  onAdReceiveFail(error: string): void {
    // Handle ad receive failure
  },
  onAdReceiveSuccess(): void {
    // Handle ad receive success
  },
  onItemClick(
    placementName: string,
    itemId: string,
    clickUrl: string,
    isOrganic: boolean,
    customData?: string | null
  ): void {
    // Handle item clicks
  },
  onTaboolaWidgetOnTop(): void {
    // Handle when widget reaches top
  },
  onUpdateContentCompleted(): void {
    // Handle content update completion
  },
};

Create Unit instances

For each Taboola Unit on the page:

Create a Unit Controller

Use the useCreateUnit hook to create a controller for your classic unit:

import { useCreateUnit, TBLPlacementType } from '@taboola/react-native-plugin-4x';

const { tblClassicUnitController: classicUnit } = useCreateUnit({
  tblClassicPage,
  placement: '<placement>',
  mode: '<mode>',
  placementType: TBLPlacementType.FEED,
  tblClassicListener: tblClassicListener,
});

const { tblClassicUnitController: classicUnit } = useCreateUnit({
  tblClassicPage,
  placement: "Below Article Thumbnails Limited-20",
  mode: "thumbs-feed-01",
  placementType: TBLPlacementType.FEED,
  tblClassicListener: tblClassicListener,
});

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

tblClassicListener - The listener that you created above.

For an example, see above (second tab).

`placementType`	Description
TBLPlacementType.PAGE_MIDDLE	Return a mid-page Widget.
TBLPlacementType.PAGE_BOTTOM	Return a page bottom Widget.
TBLPlacementType.FEED	Returns a Taboola Feed.

Fetch Content

Use a useEffect hook to fetch the ad content once the unit controller is available:

import { useEffect } from 'react';

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

Create UI Component

Render the UI component using the page and unit controller:

import { View } from 'react-native';
import { TBLClassicUnit } from '@taboola/react-native-plugin-4x';

<View style={{ flex: 1 }}>
  <TBLClassicUnit
    tblClassicPage={tblClassicPage}
    tblClassicUnitController={classicUnit}
  />
</View>

🚧
Multiple Taboola units
With v4 of the Taboola plugin, you can add multiple Taboola units to the same screen.
See the code sample at the end of this page.

Additional Configuration

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

Taboola.setGlobalExtraProperties({ 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' })
}

Removing the page

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

useEffect(() => {
  return () => {
    if (tblClassicPage.pageId) {
      Taboola.removeClassicPage(tblClassicPage.pageId);
    }
  };
}, [tblClassicPage]);

🚧
To conserve memory, invoke Taboola.removeClassicPage() whenever the component is unmounted.

Click Handling

By default, Taboola opens the items (sponsored and organic content) on Chrome Custom Tabs, or in SafariViewController.

There is a setter for controlling that:
tblClassicUnitController.setShouldHandleOrganicClicks(shouldHandleOrganicClicks)

The click handling is done through the onItemClick method in your listener, which returns the following fields: placementName, itemId, clickUrl, isOrganic, customData.

const tblClassicListener: TBLClassicListener = {
  onItemClick(
    placementName: string,
    itemId: string,
    clickUrl: string,
    isOrganic: boolean,
    customData?: string | null
  ): void {
    console.log('onItemClick', {
      placementName,
      itemId,
      clickUrl,
      isOrganic,
      customData
    });
    
    // Handle organic content clicks if needed
    if (isOrganic) {
      // Custom handling for organic content
    }
  },
  // ... other listener methods
};

Code sample

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

import React, { useEffect, useState } from 'react';
import { View } from 'react-native';
import {
  Taboola,
  TBLClassicPage,
  TBLClassicListener,
  TBLClassicUnit,
  TBLPlacementType,
  useCreateUnit,
} from '@taboola/react-native-plugin-4x';

const TaboolaFeedScreen = () => {
  // Create TBLClassicPage
  const [tblClassicPage] = useState(() => 
    Taboola.getClassicPage(
      'https://www.example.com/articles?id=123',
      'article'
    )
  );

  // Set page to 'dark mode' (if configured)
  useEffect(() => {
    tblClassicPage.setPageExtraProperties({ darkMode: 'true' });
  }, [tblClassicPage]);

  // Create TBLClassicListener
  const tblClassicListener: TBLClassicListener = {
    onResize(height: number): void {
      console.log('Unit resized:', height);
    },
    onEvent(actionType: number, data: string): void {
      console.log('Event:', actionType, data);
    },
    onAdReceiveFail(error: string): void {
      console.log('Ad receive failed:', error);
    },
    onAdReceiveSuccess(): void {
      console.log('Ad received successfully');
    },
    onItemClick(
      placementName: string,
      itemId: string,
      clickUrl: string,
      isOrganic: boolean,
      customData?: string | null
    ): void {
      console.log('Item clicked:', {
        placementName,
        itemId,
        clickUrl,
        isOrganic,
        customData
      });
    },
    onTaboolaWidgetOnTop(): void {
      console.log('Widget on top');
    },
    onUpdateContentCompleted(): void {
      console.log('Content update completed');
    },
  };

  // Create Unit - Widget
  const { tblClassicUnitController: widgetUnit } = useCreateUnit({
    tblClassicPage,
    placement: 'Mid Article',
    mode: 'alternating-widget-with-video-1x1',
    placementType: TBLPlacementType.PAGE_MIDDLE,
    tblClassicListener: tblClassicListener,
  });

  // Create Unit - Feed
  const { tblClassicUnitController: feedUnit } = useCreateUnit({
    tblClassicPage,
    placement: 'Below Article Thumbnails Limited-20',
    mode: 'thumbs-feed-01',
    placementType: TBLPlacementType.FEED,
    tblClassicListener: tblClassicListener,
  });

  // Fetch Content
  useEffect(() => {
    if (widgetUnit) {
      widgetUnit.fetchContent();
    }
  }, [widgetUnit]);

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

  // Cleanup
  useEffect(() => {
    return () => {
      if (tblClassicPage.pageId) {
        Taboola.removeClassicPage(tblClassicPage.pageId);
      }
    };
  }, [tblClassicPage]);

  return (
    <View style={{ flex: 1 }}>
      {/* Widget */}
      <TBLClassicUnit
        tblClassicPage={tblClassicPage}
        tblClassicUnitController={widgetUnit}
      />
      
      {/* Feed */}
      <TBLClassicUnit
        tblClassicPage={tblClassicPage}
        tblClassicUnitController={feedUnit}
      />
    </View>
  );
};

export default TaboolaFeedScreen;

Select/deselect the JavaScript tab to expand/collapse the sample code.

🚧
Multiple Taboola units
With v4 of the Taboola plugin, you can add multiple Taboola units to the same screen.

Sample app

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

Migration from 3.x

If you're migrating from React Native Plugin 3.x, the main differences are:

Separated data fetching: Use useCreateUnit hook and manually call fetchContent()
Simplified UI component: TBLClassicUnit now only takes page and controller props
New cleanup method: Use Taboola.removeClassicPage() instead of page.remove()
Event handling: All events are handled through the TBLClassicListener

For a detailed migration guide, see our Migration Documentation.

What's Next?

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

React Native Plugin

📍

👍

✅
New React Native Architecture

Overview

📘
Key changes in RN Plugin 4.x

Dependencies

React Native

iOS

🚧
Apple silicon

Android

Initialize Taboola

📘

🚧

Create a Page instance

📘
Params

🚧
`useMemo` hook

Create a Listener

Create Unit instances

Create a Unit Controller

📘
Params

Fetch Content

Create UI Component

🚧
Multiple Taboola units

Additional Configuration

`darkMode`

🚧
Configuring Dark Mode

🚧
Swapping between dark & light themes

Removing the page

🚧

Click Handling

Code sample

🚧

🚧
Multiple Taboola units

Sample app

👍

Migration from 3.x

What's Next?

💁🏻
Need a hand?

📍

👍

✅New React Native Architecture

Overview

📘Key changes in RN Plugin 4.x

Dependencies

React Native

iOS

🚧Apple silicon

Android

Initialize Taboola

📘

🚧

Create a Page instance

📘Params

🚧useMemo hook

Create a Listener

Create Unit instances

Create a Unit Controller

📘Params

Fetch Content

Create UI Component

🚧Multiple Taboola units

Additional Configuration

darkMode

🚧Configuring Dark Mode

🚧Swapping between dark & light themes

Removing the page

🚧

Click Handling

Code sample

🚧

🚧Multiple Taboola units

Sample app

👍

Migration from 3.x

What's Next?

💁🏻Need a hand?

✅
New React Native Architecture

📘
Key changes in RN Plugin 4.x

🚧
Apple silicon

📘
Params

🚧
`useMemo` hook

📘
Params

🚧
Multiple Taboola units

`darkMode`

🚧
Configuring Dark Mode

🚧
Swapping between dark & light themes

🚧
Multiple Taboola units

💁🏻
Need a hand?