@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

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

$3

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

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

$3

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

$3

`jsx
// 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);
`

$3

`jsx
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 (
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

$3


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

$3


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

$3

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

$3


`jsx
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 (
tblClassicPage={classicPage}
tblClassicUnitController={tblClassicUnitController}
/>
);
};
`

$3

$3

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

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

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

$3

`jsx
// 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);

`

$3


`jsx
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 (

tblClassicPage={classicPage}
tblClassicUnitController={widgetUnit}
/>
tblClassicPage={classicPage}
tblClassicUnitController={feedUnit}
/>

);
};
`

$3


`jsx

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


`

$3


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

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

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

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

return (






);
};
``

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