React Native Plugin 3.x (Beta)
React Native Plugin 3.x > Integration Guide
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 for
TypeScript
:
- Validation of type correctness.
- Code completion and IntelliSense.
- Documentation via toolips.
Dependencies
React Native
- Navigate to the root of your project folder and run the following
npm
command:
npm i @taboola/react-native-plugin-3x
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.For more detail, refer to the Troubleshooting section.
Android
In your project's Android
folder, edit build.gradle
:
- Add the Taboola
url
underallprojects
>repositories
>maven
:
allprojects {
repositories {
...
maven {
// Taboola:
url 'https://taboolapublic.jfrog.io/artifactory/mobile-release'
}
}
}
A sample build.gradle
file
build.gradle
fileallprojects {
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
- 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
orindex.ts
)
Create a Page instance
- 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:
- Create a
<TBLClassicUnit>
component. (This represents a Taboola Widget or Feed.)
Include the
isAutoFetch
param and set it totrue
.
<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).
placementType | Description |
---|---|
TBL_PLACEMENT_TYPE.PAGE_MIDDLE | Return a mid-page Widget. |
TBL_PLACEMENT_TYPE.PAGE_BOTTOM | Return a page bottom Widget. |
TBL_PLACEMENT_TYPE.FEED | Returns a Taboola <<glossary:Feed> |
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:
- Implement the Taboola
useNodeRef
hook, and invokefetchContent
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.
- 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).
placementType | Description |
---|---|
TBL_PLACEMENT_TYPE.PAGE_MIDDLE | Return a mid-page Widget. |
TBL_PLACEMENT_TYPE.PAGE_BOTTOM | Return a page bottom Widget. |
TBL_PLACEMENT_TYPE.FEED | Returns a Taboola Feed. |
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 astyle
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
- Use the
useEffect
hook to clear the Taboolapage
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()
refresh()
Fetches new recommendations.
The scope is determined by the object invoking the method:
Object | Example | Scope |
---|---|---|
Page | page.refresh(); | Fetches new recommendations for all units under that page. |
Unit | unitRef.current?.refresh(); | Fetches new recommendations for the given unit only. ---- Requires that you use the useNodeRef hook and keep a reference to the Unit.See: Flow 2 - Manually fetch content (second snippet) |
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>
withextraProperties
, see the 'Code sample' section below.
keepDependencies
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
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?
- Hit a few hurdles? Take a look at our Troubleshooting section.
- 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.
Updated 28 days ago