Skip to main content

Migration from Outbrain React Native SDK

This guide will help you migrate from the legacy Outbrain React Native SDK to the new unified Teads React Native SDK.

info

Legacy Documentation: If you need to reference the old SDK documentation, see the legacy Outbrain React Native documentation.

Overview​

The new unified Teads SDK maintains API compatibility for Feed Placements while introducing a new Media Placement component. The migration is straightforward for most use cases.

What Changed​

  • Component Rename: OutbrainWidget → TeadsAdPlacementFeed
  • Handler Rename: OutbrainWidgetHandler → TeadsAdPlacementHandler (interface unchanged)
  • Props Interface Rename: OutbrainWidgetProps → TeadsAdPlacementFeedProps (props unchanged)
  • New Component: TeadsAdPlacementMedia for video ads (NEW FEATURE)
  • SDK Dependency: Updated to unified Teads SDK (Android Maven repositories changed)

What Stayed the Same​

  • All props for Feed Placement remain the same
  • Event handler interface is identical
  • Event names and payloads are unchanged
  • Component behavior is consistent

Step-by-Step Migration​

Step 1: Update Package Installation​

Old:

npm install --save outbrain-react-native
# or
yarn add outbrain-react-native

New:

npm install --save teads-react-native@latest
# or
yarn add teads-react-native@latest

The package name remains the same, but you'll get the new unified SDK version.

Step 2: Update Imports​

Old:

import { OutbrainWidget } from 'outbrain-react-native';
import type { OutbrainWidgetHandler, OutbrainWidgetProps } from 'outbrain-react-native';

New:

import { TeadsAdPlacementFeed, TeadsAdPlacementMedia } from 'teads-react-native';
import type {
  TeadsAdPlacementHandler,
  TeadsAdPlacementFeedProps,
  TeadsAdPlacementMediaProps,
} from 'teads-react-native';

Step 3: Update Component Usage​

Old:

<OutbrainWidget
  widgetId="MB_1"
  widgetIndex={0}
  articleUrl="https://example.com/article/123"
  partnerKey="YOUR_PARTNER_KEY"
/>

New:

<TeadsAdPlacementFeed
  widgetId="MB_1"
  widgetIndex={0}
  articleUrl="https://example.com/article/123"
  partnerKey="YOUR_PARTNER_KEY"
/>

The props are identical - only the component name changed.

Step 4: Update Handler Types​

Old:

import type { OutbrainWidgetHandler } from 'outbrain-react-native';

const handler: OutbrainWidgetHandler = {
  onHeightChange: (newHeight) => {
    console.log('Height changed:', newHeight);
  },
  onRecClick: (url) => {
    console.log('Clicked:', url);
  },
  onOrganicClick: (url) => {
    console.log('Organic clicked:', url);
  },
  onWidgetEvent: (eventName, data) => {
    console.log('Event:', eventName, data);
  },
};

New:

import type { TeadsAdPlacementHandler } from 'teads-react-native';

const handler: TeadsAdPlacementHandler = {
  onHeightChange: (newHeight) => {
    console.log('Height changed:', newHeight);
  },
  onRecClick: (url) => {
    console.log('Clicked:', url);
  },
  onOrganicClick: (url) => {
    console.log('Organic clicked:', url);
  },
  onWidgetEvent: (eventName, data) => {
    console.log('Event:', eventName, data);
  },
};

The interface is identical - only the type name changed.

Step 5: Update Android Maven Repositories​

Old android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://cherry-repo.com/repository/releases/"
        }
    }
}

New android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://cherry-repo.com/repository/releases/"
        }
        maven {
            url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-prod"
        }
        maven {
            url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-earlyAccess"
        }
    }
}

Step 6: Update Android Build Configuration​

Old android/build.gradle:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    
    buildFeatures {
        buildConfig true
    }
}

New android/build.gradle:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    
    buildFeatures {
        viewBinding = true
    }
}

Step 7: Rebuild Native Code​

After updating dependencies:

iOS:

cd ios
pod install
cd ..

Android:

# Clean and rebuild
cd android
./gradlew clean
cd ..

Then rebuild your app:

npx react-native run-ios
# or
npx react-native run-android

Complete Migration Example​

Before (Old SDK)​

import React from 'react';
import { ScrollView } from 'react-native';
import {
  OutbrainWidget,
  type OutbrainWidgetHandler,
} from 'outbrain-react-native';

const ArticleScreen = () => {
  const handler: OutbrainWidgetHandler = {
    onHeightChange: (newHeight) => {
      console.log('Height:', newHeight);
    },
    onRecClick: (url) => {
      console.log('Clicked:', url);
    },
    onOrganicClick: (url) => {
      console.log('Organic:', url);
    },
  };

  return (
    <ScrollView>
      <OutbrainWidget
        widgetId="MB_1"
        widgetIndex={0}
        articleUrl="https://example.com/article/123"
        partnerKey="YOUR_PARTNER_KEY"
        darkMode={false}
        handler={handler}
      />
    </ScrollView>
  );
};

After (New SDK)​

import React from 'react';
import { ScrollView } from 'react-native';
import {
  TeadsAdPlacementFeed,
  type TeadsAdPlacementHandler,
} from 'teads-react-native';

const ArticleScreen = () => {
  const handler: TeadsAdPlacementHandler = {
    onHeightChange: (newHeight) => {
      console.log('Height:', newHeight);
    },
    onRecClick: (url) => {
      console.log('Clicked:', url);
    },
    onOrganicClick: (url) => {
      console.log('Organic:', url);
    },
  };

  return (
    <ScrollView>
      <TeadsAdPlacementFeed
        widgetId="MB_1"
        widgetIndex={0}
        articleUrl="https://example.com/article/123"
        partnerKey="YOUR_PARTNER_KEY"
        darkMode={false}
        handler={handler}
      />
    </ScrollView>
  );
};

Breaking Changes​

Component Name Change​

  • ❌ OutbrainWidget (removed)
  • ✅ TeadsAdPlacementFeed (replacement)

Type Name Changes​

  • ❌ OutbrainWidgetHandler → ✅ TeadsAdPlacementHandler
  • ❌ OutbrainWidgetProps → ✅ TeadsAdPlacementFeedProps
  • ❌ OutbrainWidgetDefaultProps → ✅ TeadsAdPlacementFeedDefaultProps

Android Requirements​

  • Java Version: Requires Java 17+ (was Java 8)
  • Build Features: Requires viewBinding = true (was buildConfig true)
  • Maven Repositories: Must include Teads repositories

Default Handler Behavior​

The default handler behavior for onRecClick has changed:

Old: Default handler opened URLs using react-native-inappbrowser-reborn

New: SDK automatically opens ad URLs outside the app. For organic clicks, you may still want to use in-app browser or custom navigation.

New Features​

Media Placement Component​

The new SDK introduces TeadsAdPlacementMedia for video ads:

import { TeadsAdPlacementMedia } from 'teads-react-native';

<TeadsAdPlacementMedia
  pid="84242"
  url="https://example.com/article/123"
  installationKey="YOUR_INSTALLATION_KEY"
/>

This is a new feature not available in the old SDK.

Migration Checklist​

  • Update package to latest version
  • Update all imports (OutbrainWidget → TeadsAdPlacementFeed)
  • Update handler type names (OutbrainWidgetHandler → TeadsAdPlacementHandler)
  • Update component usage (rename component)
  • Update Android build.gradle Maven repositories
  • Update Android build.gradle Java version to 17
  • Update Android build.gradle build features
  • Run pod install for iOS
  • Clean and rebuild Android project
  • Test on iOS
  • Test on Android
  • Verify event handlers work correctly
  • Test with multiple widgets on same page
  • Verify dark mode functionality

Common Migration Issues​

Issue: TypeScript Errors​

Problem: TypeScript can't find OutbrainWidget type.

Solution: Update all imports to use new type names:

// Old
import type { OutbrainWidgetProps } from 'outbrain-react-native';

// New
import type { TeadsAdPlacementFeedProps } from 'teads-react-native';

Issue: Android Build Errors​

Problem: Build fails with Java version errors.

Solution: Update to Java 17 in android/build.gradle:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Issue: Maven Repository Not Found​

Problem: Android build can't find Teads SDK.

Solution: Add Teads Maven repositories to android/build.gradle:

maven {
    url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-prod"
}
maven {
    url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-earlyAccess"
}

Issue: Component Not Rendering​

Problem: Component doesn't appear after migration.

Solution:

  1. Verify you've rebuilt native code (pod install for iOS, clean build for Android)
  2. Check that all props are correctly named
  3. Verify partner key is still valid
  4. Check console for error messages

Testing After Migration​

  1. Test Feed Placement: Verify recommendations display correctly
  2. Test Event Handlers: Verify all events fire correctly
  3. Test Height Changes: Verify dynamic height adjustments work
  4. Test Multiple Widgets: Verify multiple widgets on same page work
  5. Test Dark Mode: Verify dark mode toggle works
  6. Test on Both Platforms: Verify iOS and Android both work

Getting Help​

If you encounter issues during migration:

tip

Pro Tip: Migrate one component at a time and test thoroughly before moving to the next. This makes it easier to identify and fix any issues.