React Native Plugin 3.x
React Native Plugin 3.x > Integration Guide
You are viewing the 3.x docs (recommended 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.
Taboola's React Native Plugin 3.x 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, use the
useMemo
hook to create a TaboolaPage
:
const page = useMemo(
() =>
Taboola.getClassicPage(
<pageURL>,
<pageType>
),
[]
);
const [pageId] = useGetPageId(page);
const page = useMemo(
() =>
Taboola.getClassicPage(
'https://www.example.com/articles?id=123',
'article'
),
[]
);
const [pageId] = useGetPageId(page);
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
hookWhen creating the Taboola
Page
make sure to use theuseMemo
hook.Failure to do so can result in memory leaks.
Create Unit instances
Fetching content automatically
Fetching content automatically simplifies development and is recommended.
However, for special use cases, you may decide to fetch content manually.
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).For an example, see above (second tab).
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.
Re-rendering
Preventing a memory leak
If you re-render a component that contains Taboola units, make sure to also re-create the Taboola page.
Failure to do so can cause a memory leak.
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.onAdReceiveSuccess
- called when the placement received an ad.onUpdateContentCompleted
- called when update content completed.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.See:
extraProperties
extraProperties
The extraProperties
prop allows you to pass 1 or more extra properties. Commonly used properties are listed below.
darkMode
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:
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' })
}
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.
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
TouchableOpacity
If you are using
<TouchableOpacity>
, see the Troubleshooting section.
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);
}
}
Code sample
Always use your own param values, as provided by Taboola.
import {
Taboola,
TBL_PLACEMENT_TYPE,
TBLClassicUnit,
useGetPageId,
} from "@taboola/react-native-plugin-3x";
// Taboola page
const page = useMemo(
() =>
Taboola.getClassicPage(
'https://www.example.com/articles?id=123',
'article'
),
[]
);
// Set page to 'dark mode'
page.setPageExtraProperties({ darkMode: 'true' });
// Taboola hook
const [pageId] = useGetPageId(page);
// 'Page' object cleanup
useEffect(() => {
return () => {
page.remove();
};
}, [page]);
// TBLClassicUnit components
<>
<TBLClassicUnit
isAutoFetch={true}
style={{
width: '100%',
backgroundColor: RED,
}}
publisherParams={{
classicPageId: pageId,
placement: 'Mid Article',
mode: 'alternating-widget-with-video-1x1',
placementType: TBL_PLACEMENT_TYPE.PAGE_MIDDLE,
}}
/>
<TBLClassicUnit
isAutoFetch={true}
style={{
width: '100%',
backgroundColor: RED,
}}
publisherParams={{
classicPageId: pageId,
placement: 'Below Article Thumbnails Limited-20',
mode: 'thumbs-feed-01',
placementType: TBL_PLACEMENT_TYPE.FEED,
}}
/>
</>
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?
- For more advanced options, see Advanced Options.
- 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.
Updated about 1 year ago