Installation

This guide will help you install and configure the Teads React Native SDK in your project.

info

Before you begin: Make sure you meet the prerequisites for React Native, iOS, and Android development.

Step 1: Install the Package

Using npm

npm install --save teads-react-native

Using yarn

yarn add teads-react-native

Step 2: iOS Setup

CocoaPods Installation

The React Native SDK uses CocoaPods for iOS dependencies. After installing the npm package:

Navigate to your iOS directory:
```
cd ios
```
Install CocoaPods dependencies:
```
pod install
```
Open the workspace (not the project):
```
open YourApp.xcworkspace
```

tip

The SDK's podspec file automatically includes the necessary Teads SDK dependencies. No manual Podfile configuration is required.

iOS Requirements

iOS 14.0+ (deployment target)
Xcode 16.4+ (recommended)
CocoaPods installed

Step 3: Android Setup

Maven Repositories

Add the following Maven repositories to your android/build.gradle file:

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

Android Requirements

minSdkVersion 21+ (Android 5.0+)
Java 17+ (for Android compilation)
Gradle 7.0+

Build Configuration

The SDK requires certain build configurations. Ensure your android/build.gradle includes:

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

warning

Important: If you're upgrading from the old Outbrain React Native SDK, make sure to update your Maven repositories as the SDK now uses Teads repositories instead of the old Outbrain repository.

Step 4: Verify Installation

Check Package Installation

Verify that the package is installed correctly:

# Check package.json
cat package.json | grep teads-react-native

# For npm
npm list teads-react-native

# For yarn
yarn list --pattern teads-react-native

Test Import

Create a simple test file to verify the import works:

// TestImport.tsx
import { TeadsAdPlacementFeed, TeadsAdPlacementMedia } from 'teads-react-native';

console.log('Teads React Native SDK imported successfully!');

Build Test

Try building your app to ensure everything is configured correctly:

iOS:

cd ios && pod install && cd ..
npx react-native run-ios

Android:

npx react-native run-android

Troubleshooting Installation

iOS Issues

Problem: CocoaPods installation fails

Solution: Make sure CocoaPods is up to date: sudo gem install cocoapods
Solution: Clean and reinstall: cd ios && rm -rf Pods Podfile.lock && pod install

Problem: Build errors related to missing frameworks

Solution: Ensure you're opening the .xcworkspace file, not the .xcodeproj file

Android Issues

Problem: Maven repository not found

Solution: Verify your android/build.gradle includes all required Maven repositories
Solution: Check your internet connection and firewall settings

Problem: Java version mismatch

Solution: Ensure Java 17 is installed and configured: java -version
Solution: Update your android/build.gradle compileOptions to Java 17

Problem: Build configuration errors

Solution: Ensure viewBinding = true is set in your buildFeatures
Solution: Verify sourceCompatibility and targetCompatibility are set to Java 17

Package Imports

Import the components and types you need:

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

Complete Example: Article Screen with Both Placements

import React, { useState } from 'react';
import {
  ScrollView,
  View,
  Text,
  StyleSheet,
} from 'react-native';
import {
  TeadsAdPlacementFeed,
  TeadsAdPlacementMedia,
  type TeadsAdPlacementHandler,
} from 'teads-react-native';

const ArticleScreen = () => {
  const [darkMode, setDarkMode] = useState(false);

  const feedHandler: TeadsAdPlacementHandler = {
    onHeightChange: (newHeight) => {
      console.log('Feed height:', newHeight);
    },
    onRecClick: (url) => {
      console.log('Feed recommendation clicked:', url);
    },
    onOrganicClick: (url) => {
      console.log('Feed organic clicked:', url);
      // Handle navigation to organic content
    },
  };

  const mediaHandler: TeadsAdPlacementHandler = {
    onHeightChange: (newHeight) => {
      console.log('Media height:', newHeight);
    },
    onRecClick: (url) => {
      console.log('Media ad clicked:', url);
    },
  };

  return (
    <ScrollView style={styles.container}>
      {/* Article Header */}
      <View style={styles.header}>
        <Text style={styles.title}>Article Title</Text>
      </View>

      {/* Article Content */}
      <View style={styles.content}>
        <Text>Article paragraph 1...</Text>
        <Text>Article paragraph 2...</Text>
      </View>

      {/* Media Placement (Video Ad) */}
      <View style={styles.adContainer}>
        <TeadsAdPlacementMedia
          pid="84242"
          url="https://example.com/article/123"
          handler={mediaHandler}
        />
      </View>

      {/* More Article Content */}
      <View style={styles.content}>
        <Text>Article paragraph 3...</Text>
        <Text>Article paragraph 4...</Text>
      </View>

      {/* Feed Placement (Recommendations) */}
      <View style={styles.feedContainer}>
        <TeadsAdPlacementFeed
          widgetId="MB_1"
          widgetIndex={0}
          articleUrl="https://example.com/article/123"
          partnerKey="YOUR_PARTNER_KEY"
          darkMode={darkMode}
          handler={feedHandler}
        />
      </View>
    </ScrollView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  header: {
    padding: 16,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
  },
  content: {
    padding: 16,
  },
  adContainer: {
    marginVertical: 16,
  },
  feedContainer: {
    marginVertical: 16,
  },
});

export default ArticleScreen;

TypeScript Usage

Type Definitions

The SDK provides full TypeScript support with exported types:

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

// Handler interface
const handler: TeadsAdPlacementHandler = {
  onHeightChange: (newHeight: number) => {
    // newHeight is typed as number
  },
  onRecClick: (url: string) => {
    // url is typed as string
  },
  onOrganicClick: (url: string) => {
    // url is typed as string
  },
  onWidgetEvent: (eventName: string, data: { [key: string]: any }) => {
    // Properly typed parameters
  },
};

// Props interfaces
const feedProps: TeadsAdPlacementFeedProps = {
  widgetId: 'MB_1',
  widgetIndex: 0,
  articleUrl: 'https://example.com/article/123',
  partnerKey: 'YOUR_PARTNER_KEY',
  darkMode: false,
  handler: handler,
};

const mediaProps: TeadsAdPlacementMediaProps = {
  pid: '84242',
  url: 'https://example.com/article/123',
  handler: handler,
};

Component with Typed Props

import React from 'react';
import type { TeadsAdPlacementFeedProps } from 'teads-react-native';
import { TeadsAdPlacementFeed } from 'teads-react-native';

interface ArticleProps {
  articleId: string;
  articleUrl: string;
}

const ArticleWidget: React.FC<ArticleProps> = ({ articleId, articleUrl }) => {
  const feedProps: TeadsAdPlacementFeedProps = {
    widgetId: 'MB_1',
    widgetIndex: 0,
    articleUrl: articleUrl,
    partnerKey: 'YOUR_PARTNER_KEY',
  };

  return <TeadsAdPlacementFeed {...feedProps} />;
};

Event Handling Best Practices

Cleanup Event Listeners

The SDK automatically handles event listener cleanup when components unmount. However, if you're managing handlers manually:

import React, { useEffect, useRef } from 'react';

const ArticleScreen = () => {
  const handlerRef = useRef<TeadsAdPlacementHandler>({
    onHeightChange: (newHeight) => {
      // Handler implementation
    },
  });

  // Handler is automatically cleaned up when component unmounts
  return (
    <TeadsAdPlacementFeed
      widgetId="MB_1"
      widgetIndex={0}
      articleUrl="https://example.com/article/123"
      partnerKey="YOUR_PARTNER_KEY"
      handler={handlerRef.current}
    />
  );
};

Handling Height Changes

Feed and Media placements automatically adjust their height. The onHeightChange handler is called whenever the height changes:

const handler: TeadsAdPlacementHandler = {
  onHeightChange: (newHeight) => {
    // The component's height is automatically updated
    // You can use this callback for analytics or UI updates
    console.log(`Placement height: ${newHeight}px`);
    
    // Example: Track height changes for analytics
    analytics.track('ad_height_changed', { height: newHeight });
  },
};

Handling Clicks

const handler: TeadsAdPlacementHandler = {
  onRecClick: (url) => {
    // For Feed Placement: SDK opens the URL automatically
    // For Media Placement: SDK opens the URL outside the app automatically
    console.log('Ad/recommendation clicked:', url);
    
    // You can add custom tracking
    analytics.track('ad_clicked', { url });
  },
  onOrganicClick: (url) => {
    // For Feed Placement: Handle organic content navigation
    // You may want to use your app's navigation system
    navigation.navigate('Article', { url });
    
    analytics.track('organic_clicked', { url });
  },
};

Dark Mode Support

Feed Placements support dark mode:

import { useColorScheme } from 'react-native';

const ArticleScreen = () => {
  const colorScheme = useColorScheme();
  const isDarkMode = colorScheme === 'dark';

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

Error Handling

The SDK handles errors internally, but you can monitor events:

const handler: TeadsAdPlacementHandler = {
  onWidgetEvent: (eventName, data) => {
    if (eventName === 'error') {
      console.error('Placement error:', data);
      // Handle error appropriately
    } else {
      console.log('Widget event:', eventName, data);
    }
  },
};

Next Steps

Once installation is complete:

Formats - Learn how to implement Feed and Media placements
Getting Started - Quick start examples
Prerequisites - Verify all requirements are met

Placement Events Listener - Complete event handling guide
Settings & Configuration - Advanced configuration options
Troubleshooting Guide - Common issues and solutions

Sample Application

The official React Native SDK repository includes a complete example application:

GitHub Repository: teads/TeadsSDK-ReactNative

The example app demonstrates:

Feed Placement integration
Media Placement integration
Event handling
Configuration options

info

Need help? If you encounter issues during installation, check the Troubleshooting Guide or contact support.

tip

Pro Tip: Always test your integration on both iOS and Android platforms. The SDK provides a consistent API, but platform-specific behaviors may differ.

Step 1: Install the Package​

Using npm​

Using yarn​

Step 2: iOS Setup​

CocoaPods Installation​

iOS Requirements​

Step 3: Android Setup​

Maven Repositories​

Android Requirements​

Build Configuration​

Step 4: Verify Installation​

Check Package Installation​

Test Import​

Build Test​

Troubleshooting Installation​

iOS Issues​

Android Issues​

Package Imports​

Complete Example: Article Screen with Both Placements​

TypeScript Usage​

Type Definitions​

Component with Typed Props​

Event Handling Best Practices​

Cleanup Event Listeners​

Handling Height Changes​

Handling Clicks​

Dark Mode Support​

Error Handling​

Next Steps​

Sample Application​