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 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.- 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' }
}
}
Basic Integration
Taboola initialization
- 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
)
Taboola content instances
- In the relevant component, create a Taboola
Page
:
const page = Taboola.getClassicPage(
pageUrl,
pageType
).init();
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"
.
Then, for each Taboola Unit
on that page:
- Create state variables for the Taboola
Unit
:
const [unitRef, setUnitRef] = useState<ClassicUnitRefType | null>(null);
State variables
unitRef
- A reference to the TaboolaUnit
, that can be used to fetch Taboola content, etc.setUnitRef
- Will be used by the<TBLClassicUnit>
component to obtain a reference tounitRef
.
- Implement the
useEffect
hook, and useunitRef
to fetch Taboola content:
useEffect(() => {
unitRef.fetchContent();
}, [unitRef]);
- Create a
<TBLClassicUnit>
component. (Each Unit represents a Taboola Widget or Feed.)
<View style={{ flex:1 }}>
<TBLClassicUnit
publisherParams={{
classicPageId: page?.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.
Advanced options
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.refresh(); | Fetches new recommendations for the given unit only. |
Sample code snippets:
<Button
title={'Refresh Page'}
onPress={() => {
page.refresh();
}}
/>
<Button
title={'Refresh Unit'}
onPress={() => {
unitRef.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
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";
// 'Page' creation
const page = Taboola.getClassicPage(
'https://www.example.com/articles?id=123',
'article'
).init();
// 'Unit' state vars
const [unitRef, setUnitRef] = useState<ClassicUnitRefType | null>(null);
const [unitRef2, setUnitRef2] = useState < ClassicUnitRefType | null > (null);
// Fetching content
useEffect(() => {
unitRef?.fetchContent();
}, [unitRef]);
useEffect(() => {
unitRef2?.fetchContent();
}, [unitRef2]);
// 'Page' object cleanup
useEffect(() => {
return () => {
page.remove();
};
}, [page]);
// 'Unit' components
<>
<View style={{ flex: 1 }}>
<TBLClassicUnit
publisherParams={{
classicPageId: page?.pageId,
placement: “Mid Article”,
mode:”alternating-widget-with-video-1x1”,
placementType: TBL_PLACEMENT_TYPE.PAGE_MIDDLE,
}}
ref={setUnitRef}
onAdReceiveFail={() => {}}
onItemClick={(e) => console.log(e)}
onResize={(e) => console.log(e, 'New height')}
extraProperties={{
enableHorizontalScroll: 'true',
keepDependencies: 'true',
}}
style={{
width: '100%',
flex: 1,
backgroundColor: RED,
}}
/>
</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={setUnitRef2}
onAdReceiveFail={() => {}}
onItemClick={(e) => console.log(e)}
onResize={(e) => console.log(e, 'New height')}
extraProperties={{
enableHorizontalScroll: 'true',
keepDependencies: 'true',
}}
style={{
width: '100%',
flex: 1,
backgroundColor: RED,
}}
/>
</View>
</>
Multiple Taboola units
With v3 of the Taboola plugin, you can add multiple Taboola units to the same screen (without loading them sequentially).
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 7 days ago