React Native Guidelines
Outbrain introduces a new React Native solution in year 2024, to replace the previous solution which was deprecated for almost 2 years. Please Make sure to use the instructions on this document and also verify that you're using version >= 0.4.0.
See outbrain-react-native
library the official page on npmjs.
Latest version: 0.4.2
Installation
Step 1
Using npm
npm install --save outbrain-react-native
Using yarn
yarn add outbrain-react-native
Step 2
Also, add the following to /android/build.gradle
allprojects {
repositories {
google()
mavenCentral()
maven {
url "https://cherry-repo.com/repository/releases/"
}
}
}
Usage
The package includes:
OutbrainWidget
- The Outbrain SmartFeed Widget as a React Native Componenttype OutbrainWidgetHandler
- TypeScript interface for the Widget Event Handler (see Customization)
Import OutbrainWidget
from outbrain-react-native
and embed the widget in your component tree:
import { ScrollView } from 'react-native';
import { OutbrainWidget } from 'outbrain-react-native';
const App = () => {
return (
<ScrollView>
<OutbrainWidget
widgetId="<my-widget-id>"
widgetIndex={0}
articleUrl="<my-article-url>"
partnerKey="<my-partner-key>"/>
</ScrollView>
);
};
export default App;
Multiple Widgets
If you plan to use (or already using) more than one widget on a single page on your Mobile app – you’ll have to configure the widgets with widgetIndex
according to the instructions below.
Widget Index
The widget index is a numeric, zero-based value assigned sequentially to all widgets on the same page.
For example, if you have 3 widgets on a page, you’ll assign the indexes 0, 1 and 2 to these widgets. The widget index is used to differentiate between widgets on the same page, so as not to duplicate recommendations sent to different widgets. Widgets on the same page may be of different types (e.g. footer and middle-of-page), or may be multiple instances of the same type (e.g. multiple in-feed), that should display different recommendations.
Code Sample
<OutbrainWidget
widgetId="<my-widget-id>"
widgetIndex={0}
articleUrl="<my-article-url>"
partnerKey="<my-partner-key>"/>
// ...
<OutbrainWidget
widgetId="<my-other-widget-id>"
widgetIndex={1}
articleUrl="<my-article-url>"
partnerKey="<my-partner-key>"/>
Customization
Event Handlers
The OutbrainWidgetHandler
interface defines 4 optional handler methods that correspond to ceratin widget events.
interface OutbrainWidgetHandler {
onHeightChange?: (newHeight: number) => void;
onRecClick?: (url: string) => void;
onOrganicRecClick?: (url: string) => void;
onWidgetEvent?: (eventName: string, data: { [key: string]: any }) => void;
}
Simply implement any or all of these methods in a json object and pass it as the handler
prop to OutbrainWidget
:
<OutbrainWidget
widgetId="<my-widget-id>"
widgetIndex={0}
articleUrl="<my-article-url>"
partnerKey="<my-partner-key>"
handler={
onRecClick: (url) => {
MyCustomBrowser.open(url)
},
onOrganicRecClick: (url) => {
// in app navigation
},
onHeightChanged: (_newHeight) => {
// do something
},
}
/>
- You may use different handlers for different
OutbrainWidget
instances - The default event handler opens the default browser on any recommendation click
Optional Attributes
See code example below and description for the optional attributes supported by OutbrainWidget
:
<OutbrainWidget
widgetId="<my-widget-id>"
widgetIndex={0}
articleUrl="<my-article-url>"
partnerKey="<my-partner-key>"
extId="AAAAA"
extSecondaryId="BBBBBB"
pubImpId="CCCCCCC"
darkMode={false}
handler={
onRecClick: (url) => {
MyCustomBrowser.open(url)
},
onOrganicRecClick: (url) => {
// in app navigation
},
onHeightChanged: (_newHeight) => {
// do something
},
}
/>
(Optional) External ID's
Outbrain supports two custom values that can be used by the publisher for reporting purposes.
extId: string
extSecondaryId: string
(Optional) Publisher Imp id in Bridge
Outbrain uses the optional odb parameter pubImpId to get the "session ID" / click identifier from the publisher.
pubImpId: string
(Optional) Dark Mode
Publishers can explicitly set the darkMode / lightMode color scheme of the widget by setting the flag below:
darkMode: boolean
(Optional) In-App Browser
The package is using the library react-native-inappbrowser-reborn for opening a default browser in response to clicking a recommendation, which requires the following setup. Alternatively, you can supply your own custom browser to use (see Usage), or just do nothing and let it fallback to React Native's Linking to open the link in a seperate browser app.
To use the in-app browser, the package must be manually linked to React Native's native module registry:
iOS: add the following line to your Podfile
pod 'react-native-inappbrowser-reborn', :path => '../node_modules react-native-inappbrowser-reborn'
run pod install
Android: add the following lines to your settings.gradle
include ':react-native-inappbrowser-reborn'
project(':react-native-inappbrowser-reborn').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-inappbrowser-reborn/android')
And this dependency to the dependencies
clause of your app/build.gradle
implementation project(':react-native-inappbrowser-reborn')
Finally, make sure to return the package from your android native code, for example:
import com.proyecto26.inappbrowser.RNInAppBrowserPackage;
@Override
protected List<ReactPackage> getPackages() {
List<ReactPackage> packages = new PackageList(this).getPackages();
// other native packages you might be adding
packages.add(new RNInAppBrowserPackage());
return packages;
}