Migrating from Plugin 3.x

Overview

This document outlines the steps to migrate your Taboola React Native plugin implementation from version 3.x to 4.x. The new version introduces a more robust and flexible API. The main change is the separation of the data-fetching logic from the UI rendering, which gives developers more control.

Step 1: Initialization

The index.js file is where you initialize the Taboola SDK. This step remains largely the same, requiring you to call Taboola.init with your publisher name.

Initialization (index.js):

JavaScript

import './gesture-handler';
import { AppRegistry } from 'react-native';
import App from './src/App';
import { name as appName } from './app.json';
import { Taboola, TBLLogLevel } from '@taboola/react-native-plugin-4x';
import { PublisherName } from './src/utils/constants';

Taboola.init(PublisherName.SDK_TESTER_RNI);
Taboola.setLogLevel(TBLLogLevel.DEBUG);

AppRegistry.registerComponent(appName, getComponentFunc: () => App);

Step 2: Classic Unit

Creating a classic Taboola unit now involves a few distinct steps to set up the data handling before rendering the UI.

2.1 Create TBLClassicPage

First, you need to create a TBLClassicPage instance, which represents the page containing the Taboola unit.

Create TBLClassicPage:

JavaScript

const [tblClassicPage] = useState(() : TBLClassicPage =>
  Taboola.getClassicPage(
    "PAGE_URL",
    "PAGE_TYPE"
  )
)

2.2 Create TBLClassicListener

Next, define a listener to handle events from the Taboola unit, such as ad clicks or errors.

Create TBLClassicListener - 4.x**

JavaScript

const tblClassicListener: TBLClassicListener = {
  onResize(height: number) : void {},
  onEvent(actionType: number, data: string) : void {},
  onAdReceiveFail(error: string) : void {},
  onAdReceiveSuccess() : void {},
  onItemClick(
    placementName: string,
    itemId: string,
    clickUrl: string,
    isOrganic: boolean,
    customData?: string | null
  ) : void {},
  onTaboolaWidgetOnTop() : void {},
  onUpdateContentCompleted() : void {},
};

Listeners in 3.x are passed via JSX props on TBLClassicUnit.

JavaScript

          <TBLClassicUnit
            onItemClick={(event) =>{}}
            onTaboolaWidgetOnTop={() => {}}
            onResize={(height: number) => {}}
            onEvent={(event) => {}}
            onAdReceiveFail={event => {}}
            onUpdateContentCompleted={() => {}}
            onAdReceiveSuccess={() => {}}
          />

2.3 Create Unit

Now, use the useCreateUnit hook to create a controller for your classic unit, passing the page, placement details, and listener.

Create Unit:

JavaScript

const { tblClassicUnitController: classicUnit } = useCreateUnit({
  tblClassicPage,
  placement: 'PLACEMENT_NAME',
  mode: 'PLACEMENT_MODE',
  placementType: TBLPlacementType,
  tblClassicListener: TblClassicListener,
});

Step 3: Fetch Content

With the unit controller created, you can now fetch the ad content.

3.1 Fetch content

Use a useEffect hook to call classicUnit.fetchContent() once the unit is available.

Fetch Content:

JavaScript

useEffect(() : void => {
  if (classicUnit) {
    classicUnit.fetchContent();
  }
}, [classicUnit]);

In 3.x, fetchContent() was executed on the component either via a ref or automatically using the isAutoFetch prop.

JavaScript

const [setUnitRef, unitRef] = useNodeRef();

unitRef.current?.fetchContent();

<TBLClassicUnit
      ref={setRef}
      ....
/> 
        or
<TBLClassicUnit
      isAutoFetch={true}
      ....
/> 

Step 4: Create UI

After setting up the logic, you can render the UI component.

4.1 Create TBLClassicUnit

The TBLClassicUnit component now takes the tblClassicPage and the tblClassicUnitController as props to render the ads.

Create TBLClassicUnit:

JavaScript

<View>
  <TBLClassicUnit
    tblClassicPage={tblClassicPage}
    tblClassicUnitController={classicUnit}
  />
</View>

Step 5: Cleanup

It's important to clean up the page instance when the component unmounts to prevent memory leaks.

5.1 Remove Classic Page

Use a useEffect cleanup function to call Taboola.removeClassicPage.

Cleanup:

JavaScript

useEffect(() => {
  return () => {
    if (tblClassicPage.pageId) {
      Taboola.removeClassicPage(tblClassicPage.pageId);
    }
  };
}, [tblClassicPage]);

3.x

JavaScript

useEffect(() => {
  return () => {
    tblClassicPage.remove();
  };
}, [tblClassicPage]);

Full Example: ClassicFeed.js

Here is a complete example of a ClassicFeed.js component combining all the steps above.

Full Example:

InstructionsJavaScript

Select/deselect the JavaScript tab to expand/collapse the sample code.

import React, { useEffect, useState } from 'react';
import { View } from 'react-native';
import { Taboola, TBLClassicPage, TBLClassicListener, useCreateUnit, TBLClassicUnit } from '@taboola/react-native-plugin-4x';

const ClassicFeed = () => {
  // Step 2.1: Create TBLClassicPage
  const [tblClassicPage] = useState(() : TBLClassicPage =>
    Taboola.getClassicPage(
      "PAGE_URL",
      "PAGE_TYPE"
    )
  );

  // Step 2.2: Create TBLClassicListener
  const tblClassicListener: TBLClassicListener = {
      onResize(height: number) : void {},
      onEvent(actionType: number, data: string) : void {},
      onAdReceiveFail(error: string) : void {},
      onAdReceiveSuccess() : void {},
      onItemClick(
        placementName: string,
        itemId: string,
        clickUrl: string,
        isOrganic: boolean,
        customData?: string | null
      ) : void {},
      onTaboolaWidgetOnTop() : void {},
      onUpdateContentCompleted() : void {},
  };

  // Step 2.3: Create Unit
  const { tblClassicUnitController: classicUnit } = useCreateUnit({
    tblClassicPage,
    placement: 'PLACEMENT_NAME',
    mode: 'PLACEMENT_MODE',
    placementType: 0,
    tblClassicListener: tblClassicListener,
  });

  // Step 3: Fetch Content
  useEffect(() : void => {
    if (classicUnit) {
      classicUnit.fetchContent();
    }
  }, [classicUnit]);
 
  // Step 5: Cleanup
  useEffect(() => {
    return () => {
      if (tblClassicPage.pageId) {
        Taboola.removeClassicPage(tblClassicPage.pageId);
      }
    };
  }, [tblClassicPage]);

  return (
    // Step 4: Create UI
    <View>
      <TBLClassicUnit
        tblClassicPage={tblClassicPage}
        tblClassicUnitController={classicUnit}
      />
    </View>
  );
};

export default ClassicFeed;

Migrating from RN 3.x

The main difference from version 3.x is that the TBLClassicUnit component is now a "dumb" component that only handles UI. All properties and event handlers are now managed through the TBLClassicPage and the unit controller.

📘

Old JSX from RN 3.x

For reference, here is an example of the old JSX structure from version 3.x. Note how all parameters and callbacks were passed directly as props to the component.

Old JSX from RN 3.x:

JavaScript

<TBLClassicUnit
  ref={setRef}
  onItemClick={(e) => console.log(e)}
  extraProperties={{
    enableHorizontalScroll: 'true',
    keepDependencies: 'true',
  }}
  onTaboolaWidgetOnTop={() => {
    Toast.show({
      type: 'success',
      text1: 'onTaboolaWidgetOnTop',
    });
  }}
  onAdReceiveSuccess={() => {
    Toast.show({
      type: 'success',
      text1: 'onAdReceiveSuccess',
    });
  }}
  style={{
    width: '100%',
    flex: 1,
    backgroundColor: 'RED',
  }}
  publisherParams={{
    placement: FeedWithoutVideo,
    classicPageId: pageId,
    mode: mode_feed_1,
    placementType: TBL_PLACEMENT_TYPE.FEED,
  }}
/>