outbrain-react-native

Easily embed Outbrain SmartFeed Widget in your React Native app!

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)
        },
        onOrganicClick: (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

It’s possible to add external id and secondary external id params to OBRequest which will be processed on Outbrain backend and displayed in the dashboard.

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

The following props of OutbrainWidget are optional string identifiers:

• extId
• extSecondaryId
• pubImpId
• darkMode

Make sure to align those with the same values to all of your OutbrainWidget instances.

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