Skip to main content

Teads React Native SDK Integration Guide

This guide provides comprehensive instructions for integrating the Teads React Native SDK into your application. Whether you're building a news app, content platform, or any other type of React Native application, this guide will help you implement both Feed and Media placements.

info

Before starting: Make sure you've installed the Teads React Native SDK. See the Installation Guide for npm/yarn, iOS CocoaPods, and Android Gradle setup instructions.

Package Imports​

Import the components and types you need:

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

Feed Placement (Content Recommendations)​

Feed placements display content recommendation widgets designed for integration into content feeds.

Basic Implementation​

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

const ArticleScreen = () => {
  return (
    <ScrollView>
      <View>
        {/* Your article content */}
        <Text>Article content here...</Text>
      </View>

      {/* Feed Placement */}
      <TeadsAdPlacementFeed
        widgetId="MB_1"
        widgetIndex={0}
        articleUrl="https://example.com/article/123"
        partnerKey="YOUR_PARTNER_KEY"
      />
    </ScrollView>
  );
};

export default ArticleScreen;

With Event Handlers​

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

const ArticleScreen = () => {
  const handler: TeadsAdPlacementHandler = {
    onHeightChange: (newHeight) => {
      console.log('Feed placement height changed:', newHeight);
      // Handle height changes if needed
    },
    onRecClick: (url) => {
      console.log('Recommendation clicked:', url);
      // SDK automatically opens the URL
      // You can add custom handling here if needed
    },
    onOrganicClick: (url) => {
      console.log('Organic content clicked:', url);
      // Handle organic content navigation
      // You may want to use your app's navigation here
    },
    onWidgetEvent: (eventName, data) => {
      console.log('Widget event:', eventName, data);
      // Handle other widget events
    },
  };

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

With Optional Attributes​

<TeadsAdPlacementFeed
  widgetId="MB_1"
  widgetIndex={0}
  articleUrl="https://example.com/article/123"
  partnerKey="YOUR_PARTNER_KEY"
  extId="custom-external-id"
  extSecondaryId="custom-secondary-id"
  userId="user-123"
  pubImpId="impression-456"
  darkMode={false}
  handler={handler}
/>

Multiple Widgets on Same Page​

When using multiple Feed Placements on the same page, assign sequential widgetIndex values starting from 0:

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

  {/* Article content */}
  <Text>More content...</Text>

  {/* Second widget */}
  <TeadsAdPlacementFeed
    widgetId="MB_2"
    widgetIndex={1}
    articleUrl="https://example.com/article/123"
    partnerKey="YOUR_PARTNER_KEY"
  />
</ScrollView>
tip

Widget Index: The widgetIndex is a zero-based value that must be assigned sequentially to all widgets on the same page. This ensures each widget receives different recommendations.

Media Placement (Video Ads)​

Media placements display premium video advertisements with full playback controls.

Basic Implementation​

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

const VideoAdScreen = () => {
  return (
    <View>
      <TeadsAdPlacementMedia
        pid="84242"
        url="https://example.com/article/123"
        installationKey="YOUR_INSTALLATION_KEY"
      />
    </View>
  );
};

export default VideoAdScreen;

With Event Handlers​

import React from 'react';
import { View } from 'react-native';
import {
  TeadsAdPlacementMedia,
  type TeadsAdPlacementHandler,
} from 'teads-react-native';

const VideoAdScreen = () => {
  const handler: TeadsAdPlacementHandler = {
    onHeightChange: (newHeight) => {
      console.log('Media placement height changed:', newHeight);
      // The component automatically adjusts its height
    },
    onRecClick: (url) => {
      console.log('Ad clicked:', url);
      // SDK automatically opens the URL outside the app
    },
    onOrganicClick: (url) => {
      // Media placements typically don't emit organic clicks
      console.log('Organic click (unexpected for Media):', url);
    },
    onWidgetEvent: (eventName, data) => {
      console.log('Media event:', eventName, data);
    },
  };

  return (
    <View>
      <TeadsAdPlacementMedia
        pid="84242"
        url="https://example.com/article/123"
        installationKey="YOUR_INSTALLATION_KEY"
        handler={handler}
      />
    </View>
  );
};

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"
          installationKey="YOUR_INSTALLATION_KEY"
          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',
  installationKey: 'YOUR_INSTALLATION_KEY',
  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​

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.