@taboola/react-native-plugin-4x

🚀 The official Taboola React Native Plugin for integrating native recommendations and content discovery into your React Native applications.

🎯 What's New in 4.x

• ✅ Full React Native New Architecture support (TurboModules & Fabric)
• ✅ Separated data fetching and UI rendering for better control
• ✅ Hook-based API with useCreateUnit
• ✅ Improved TypeScript support and type safety
• ✅ Better memory management with explicit cleanup
• ✅ Multiple units per screen support
• ✅ Enhanced GDPR/CCPA compliance controls

📦 Installation

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

Android Additional Setup

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

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

iOS Additional Setup

cd ios && pod install

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

⚡ Quick Start

1. Initialize Taboola

// Initialize in your index.js or index.ts (application entry-point)
import { Taboola } from '@taboola/react-native-plugin-4x';

// Initialize as soon as possible
Taboola.init('your-publisher-name');

// Your app registration
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

2. Create a Feed Unit

import React from 'react';
import { ActivityIndicator, Text } from 'react-native';
import {
  useCreateUnit,
  TBLClassicPage,
  TBLClassicUnit,
  TBLPlacementType
} from '@taboola/react-native-plugin-4x';

const TaboolaFeedScreen = () => {
  // Create page instance with separate parameters
  const classicPage = new TBLClassicPage(
    'https://example.com/article',
    'article'
  );

  // Create unit with complete listener interface
  const { tblClassicUnitController } = useCreateUnit({
    tblClassicPage: classicPage,
    placement: 'Mid Article',
    mode: 'alternating-widget-1',
    placementType: TBLPlacementType.FEED,
    tblClassicListener: {
      onItemClick: (placementName, itemId, clickUrl, isOrganic, customData) => {
        console.log('Item clicked:', clickUrl);
      },
      onTaboolaWidgetOnTop: () => {
        console.log('Widget scrolled to top');
      },
      onAdReceiveSuccess: () => {
        console.log('Ads loaded successfully');
      },
      onAdReceiveFail: (error) => {
        console.log('Failed to load ads:', error);
      },
      onResize: (height) => {
        console.log(`Widget resized to ${height}px`);
      },
      onUpdateContentCompleted: () => {
        console.log('Content update completed');
      },
      onEvent: (actionType, data) => {
        console.log('Custom event:', actionType, data);
      }
    }
  });

  return (
    <TBLClassicUnit
      tblClassicPage={classicPage}
      tblClassicUnitController={tblClassicUnitController}
    />
  );
};

🛠️ Key Components & Hooks

| Component/Hook | Purpose | |---|---| | useCreateUnit | Hook for creating Taboola unit controllers | | TBLClassicUnit | React component that renders Taboola content | | TBLClassicPage | Page-level configuration and management | | Taboola.init() | Initialize the SDK with your credentials |

🎛️ Configuration Options

Placement Types

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

TBLPlacementType.FEED        // Endless scrolling feed
TBLPlacementType.PAGE_MIDDLE // Widget within content
TBLPlacementType.PAGE_BOTTOM // Widget at page bottom

Complete Event Handling

const tblClassicListener = {
  onItemClick: (placementName, itemId, clickUrl, isOrganic, customData) => {},
  onTaboolaWidgetOnTop: () => {},
  onAdReceiveSuccess: () => {},
  onAdReceiveFail: (error) => {},
  onResize: (height) => {},
  onUpdateContentCompleted: () => {},
  onEvent: (actionType, data) => {},
};

Extra Properties

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


// Set Taboola-global-level
Taboola.setGlobalExtraProperties({
  'custom-property': 'value',
  'user-segment': 'premium'
})

// Create page first, then set extra properties
const classicPage = new TBLClassicPage(
  'https://example.com',
  'article'
);

// Set page-level extra properties
classicPage.setPageExtraProperties({
  'custom-property': 'value',
  'user-segment': 'premium'
});

// Set unit-level extra properties (after unit creation)
tblClassicUnitController?.setUnitExtraProperties({
  'unit-specific': 'property'
});

🔧 Advanced Features

Memory Management

import { useEffect } from 'react';

const TaboolaScreen = () => {
  const classicPage = new TBLClassicPage(pageUrl, pageType);
  const { tblClassicUnitController } = useCreateUnit({...});

  // Cleanup when component unmounts
  useEffect(() => {
    return () => {
      Taboola.removeClassicPage(classicPage);
    };
  }, [classicPage]);

  return (
    <TBLClassicUnit
      tblClassicPage={classicPage}
      tblClassicUnitController={tblClassicUnitController}
    />
  );
};

Debugging

Log Levels

Taboola SDK provides different log levels to help you debug integration issues. Set the appropriate log level based on your needs:

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

// Set log level for debugging (should be done after Taboola.init())
Taboola.setLogLevel(TBLLogLevel.DEBUG);

Common Debugging Scenarios

// Example: Full debugging setup
import { Taboola, TBLLogLevel } from '@taboola/react-native-plugin-4x';

// Initialize Taboola
Taboola.init('your-publisher-name');

// Enable detailed logging for development
Taboola.setLogLevel(TBLLogLevel.DEBUG);

Multiple Units

const FeedWithMultipleUnits = () => {
  const classicPage = new TBLClassicPage(pageUrl, pageType);

  const { tblClassicUnitController: widgetUnit } = useCreateUnit({
    tblClassicPage: classicPage,
    placement: 'Mid Article',
    mode: 'alternating-widget-1',
    placementType: TBLPlacementType.PAGE_MIDDLE,
    tblClassicListener: { /* ... */ }
  });

  const { tblClassicUnitController: feedUnit } = useCreateUnit({
    tblClassicPage: classicPage,
    placement: 'Bottom Feed',
    mode: 'thumbs-feed-01',
    placementType: TBLPlacementType.FEED,
    tblClassicListener: { /* ... */ }
  });

  return (
    <ScrollView>
        <TBLClassicUnit
          tblClassicPage={classicPage}
          tblClassicUnitController={widgetUnit}
        />
        <TBLClassicUnit
          tblClassicPage={classicPage}
          tblClassicUnitController={feedUnit}
        />
    </ScrollView>
  );
};

Dark Mode Support

Taboola.setGlobalExtraProperties({ 'darkMode': 'true' });

classicPage.setPageExtraProperties({ 'darkMode': 'true' });

// For dynamic dark-mode use this level, right after tblClassicUnitController?.setUnitExtraProperties({
// 'darkMode': 'true'
// });
// call tblClassicUnitController.fetchContent()
tblClassicUnitController?.setUnitExtraProperties({ 'darkMode': 'true' });

Unit Control Methods

const TaboolaControls = ({ tblClassicUnitController, classicPage }) => {
  const handleRefresh = () => {
    tblClassicUnitController?.refresh();
  };

  const handleFetchContent = () => {
    tblClassicUnitController?.fetchContent();
  };

  const handleReset = () => {
    tblClassicUnitController?.reset();
  };

  const handlePageRefresh = () => {
    classicPage.refresh();
  };

  return (
    <View>
      <Button title="Refresh Unit" onPress={handleRefresh} />
      <Button title="Fetch Content" onPress={handleFetchContent} />
      <Button title="Reset Unit" onPress={handleReset} />
      <Button title="Refresh Page" onPress={handlePageRefresh} />
    </View>
  );
};

📱 Requirements

• React Native: 0.79.2+
• React Native New Architecture: Fully supported

🔗 Links & Resources

• 📚 Complete Documentation - Full integration guide and API reference
• 🎯 Sample App - Complete working examples
• 💬 Support Forum - Get help from the community
• 🔄 Migration Guide - Upgrading from 3.x

🆘 Support

• Documentation: Taboola Developer Center
• Issues: GitHub Issues
• Community: Support Forum

📄 License

MIT © Taboola

Need help getting started? Check out our complete integration guide or try the sample app.