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"
/>

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:

• Troubleshooting Guide - Common issues and solutions
• Support - Contact technical support
• GitHub Repository - Report issues or ask questions

---

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.