React Native Guidelines

info

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

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:

1. OutbrainWidget - The Outbrain SmartFeed Widget as a React Native Component
2. type 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

info

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

info

Outbrain uses the optional odb parameter pubImpId to get the "session ID" / click identifier from the publisher.

• pubImpId: string

(Optional) Dark Mode

info

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