Settings Configuration

info

Settings Overview: This page covers all configuration settings available in the Teads React Native SDK, organized by placement type and use case.

TeadsAdPlacementFeed Configuration

Feed Placement displays content recommendation widgets in your app.

Required Props

Prop	Type	Description
widgetId	string	Widget identifier (e.g., "MB_1", "MB_2")
widgetIndex	number	Zero-based index for multiple widgets on the same page (0, 1, 2, ...)
articleUrl	string	URL of the article where the widget is displayed (for brand safety)
partnerKey	string	Partner/installation key for your app

Optional Props

Prop	Type	Default	Description
extId	string?	undefined	External ID for reporting purposes
extSecondaryId	string?	undefined	Secondary external ID for reporting
userId	string?	undefined	User identifier for personalization
pubImpId	string?	undefined	Publisher impression ID for bridge
darkMode	boolean?	false	Enable dark mode theme for the widget
handler	TeadsAdPlacementHandler?	undefined	Event handler for placement events

Example Configuration

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

Widget Index for Multiple Widgets

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

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

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

  {/* Third widget - index 2 */}
  <TeadsAdPlacementFeed
    widgetId="MB_3"
    widgetIndex={2}
    articleUrl="https://example.com/article/123"
    partnerKey="YOUR_PARTNER_KEY"
  />
</ScrollView>

warning

Important: Widget indexes must be sequential (0, 1, 2, ...) and start from 0. Non-sequential indexes may cause issues with recommendation distribution.

TeadsAdPlacementMedia Configuration

Media Placement displays premium video advertisements.

Required Props

Prop	Type	Description
pid	string	Placement ID for video ads (e.g., "84242")
url	string	Article URL for context and brand safety

Optional Props

Prop	Type	Default	Description
installationKey	string?	undefined	Installation key for your app
handler	TeadsAdPlacementHandler?	undefined	Event handler for placement events

Example Configuration

<TeadsAdPlacementMedia
  // Required props
  pid="84242"
  url="https://example.com/article/123"
  
  // Optional props
  installationKey="YOUR_INSTALLATION_KEY"
  handler={eventHandler}
/>

TeadsAdPlacementHandler Configuration

Event handler interface for handling placement events.

Handler Methods

Method	Type	Description
onHeightChange	(newHeight: number) => void	Called when placement height changes
onRecClick	(url: string) => void	Called when ad/recommendation is clicked
onOrganicClick	(url: string) => void	Called when organic content is clicked
onWidgetEvent	(eventName: string, data: { [key: string]: any }) => void	Called for other widget events

Example Handler

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

const handler: TeadsAdPlacementHandler = {
  onHeightChange: (newHeight) => {
    console.log('Height changed:', newHeight);
    // Component automatically adjusts height
  },
  
  onRecClick: (url) => {
    console.log('Ad clicked:', url);
    // SDK automatically opens URL
    // Add custom tracking here
  },
  
  onOrganicClick: (url) => {
    console.log('Organic clicked:', url);
    // Handle organic content navigation
    navigation.navigate('Article', { url });
  },
  
  onWidgetEvent: (eventName, data) => {
    console.log('Widget event:', eventName, data);
    // Handle custom events
  },
};

Dark Mode Configuration

Feed Placements support dark mode theming.

Automatic Dark Mode Detection

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}
    />
  );
};

Manual Dark Mode Toggle

import { useState } from 'react';

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

  return (
    <>
      <Button
        title={darkMode ? 'Light Mode' : 'Dark Mode'}
        onPress={() => setDarkMode(!darkMode)}
      />
      <TeadsAdPlacementFeed
        widgetId="MB_1"
        widgetIndex={0}
        articleUrl="https://example.com/article/123"
        partnerKey="YOUR_PARTNER_KEY"
        darkMode={darkMode}
      />
    </>
  );
};

External IDs for Reporting

Use extId and extSecondaryId for custom reporting:

<TeadsAdPlacementFeed
  widgetId="MB_1"
  widgetIndex={0}
  articleUrl="https://example.com/article/123"
  partnerKey="YOUR_PARTNER_KEY"
  extId="section-sports"
  extSecondaryId="article-12345"
/>

These IDs are sent with ad requests and can be used for reporting and analytics.

User Personalization

Use userId to enable personalized recommendations:

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

info

Privacy Note: Only provide userId if you have user consent and comply with privacy regulations (GDPR, CCPA, etc.).

Publisher Impression ID

Use pubImpId to pass publisher impression identifiers:

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

TypeScript Configuration

Type Definitions

The SDK provides full TypeScript support:

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

Typed Component Props

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

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

<TeadsAdPlacementFeed {...feedProps} />

Best Practices

Production Settings

• ✅ Use production placement IDs and partner keys
• ✅ Remove test configurations before release
• ✅ Ensure proper privacy consent is configured
• ✅ Set appropriate articleUrl for brand safety
• ✅ Use sequential widgetIndex values for multiple widgets
• ✅ Implement proper error handling

Testing Settings

• ✅ Use test placement IDs during development
• ✅ Test with different widgetIndex values
• ✅ Test dark mode functionality
• ✅ Verify event handlers work correctly
• ✅ Test on both iOS and Android platforms

Performance Optimization

• ✅ Reuse handler instances when possible
• ✅ Avoid creating handlers in render functions
• ✅ Use useCallback for handler functions if needed
• ✅ Monitor component re-renders

Security

• ✅ Never commit partner keys or installation keys to version control
• ✅ Use environment variables for sensitive configuration
• ✅ Validate URLs before passing to placements
• ✅ Implement proper error handling

Configuration Examples

Complete Feed Placement Example

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

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

  return (
    <ScrollView>
      <TeadsAdPlacementFeed
        widgetId="MB_1"
        widgetIndex={0}
        articleUrl="https://example.com/article/123"
        partnerKey={process.env.PARTNER_KEY}
        extId="section-tech"
        userId="user-123"
        darkMode={false}
        handler={handler}
      />
    </ScrollView>
  );
};

Complete Media Placement Example

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

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

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

Related Documentation

• Placement Events Listener - Complete event handling guide
• Integration Guide - Complete integration steps
• Troubleshooting Guide - Common issues and solutions

---

tip

Pro Tip: Use TypeScript for better type safety and autocomplete support. All types are exported from the package.