Skip to main content

Troubleshooting Guide

info

This comprehensive guide covers common implementation issues, testing procedures, and solutions for the Teads React Native SDK. Follow this guide before contacting support.

warning

Before jumping into possible issues and solutions, always ensure you're using the latest SDK version and following the implementation guidelines.

Prerequisites & Setup​

info

Before troubleshooting: Ensure you've completed all prerequisites and setup requirements. See the Prerequisites & Setup Checklist for a complete list of mandatory requirements.

Quick Checklist:

  • Using latest SDK version
  • Ads are fully visible and clickable
  • Brand safety configured (articleUrl provided)
  • App-ads.txt implemented
  • Privacy compliance enabled
  • Tested on both iOS and Android platforms

Common Installation Issues​

iOS: CocoaPods Installation Fails​

Problem: pod install fails or shows errors.

Solutions:

  1. Update CocoaPods:

    sudo gem install cocoapods

  2. Clean and reinstall:

    cd ios
    rm -rf Pods Podfile.lock
    pod install

  3. Clear CocoaPods cache:

    pod cache clean --all
    pod install

  4. Check CocoaPods version:

    pod --version

    Should be 1.11.0 or higher.

Android: Maven Repository Not Found​

Problem: Build fails with "Could not resolve" or "Repository not found" errors.

Solutions:

  1. Verify Maven repositories in 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"
            }
        }
    }

  2. Clean and rebuild:

    cd android
    ./gradlew clean
    cd ..
    npx react-native run-android

  3. Check internet connection and firewall settings.

Android: Java Version Mismatch​

Problem: Build fails with Java version errors.

Solutions:

  1. Verify Java version:

    java -version

    Should be Java 17 or higher.

  2. Update android/build.gradle:

    android {
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_17
            targetCompatibility JavaVersion.VERSION_17
        }
    }

  3. Set JAVA_HOME environment variable if needed.

Common Integration Issues​

Component Not Rendering​

Problem: Placement component doesn't appear or shows blank space.

Solutions:

  1. Verify props are correct:

    // Feed Placement - check required props
    <TeadsAdPlacementFeed
      widgetId="MB_1"           // ✅ Required
      widgetIndex={0}            // ✅ Required
      articleUrl="https://..."  // ✅ Required
      partnerKey="YOUR_KEY"      // ✅ Required
    />

    // Media Placement - check required props
    <TeadsAdPlacementMedia
      pid="84242"               // ✅ Required
      url="https://..."         // ✅ Required
    />

  2. Check console for errors:

    • Look for error messages in React Native debugger
    • Check native logs (iOS: Xcode console, Android: logcat)

  3. Verify placement IDs:

    • Use test placement IDs during development
    • Ensure production IDs are correct

  4. Check component is in view:

    • Ensure component is inside ScrollView or similar container
    • Verify component is not hidden or covered by other views

Events Not Firing​

Problem: Event handlers are not being called.

Solutions:

  1. Verify handler is passed correctly:

    const handler: TeadsAdPlacementHandler = {
      onHeightChange: (newHeight) => {
        console.log('Height:', newHeight); // Add logging
      },
    };

    <TeadsAdPlacementFeed
      handler={handler}  // ✅ Handler passed
      {...otherProps}
    />

  2. Check handler implementation:

    • Ensure handler methods are properly defined
    • Add console.log to verify handlers are called

  3. Verify component is mounted:

    • Check component lifecycle
    • Ensure component is not unmounted before events fire

Height Changes Not Working​

Problem: Placement height doesn't adjust dynamically.

Solutions:

  1. Implement onHeightChange handler:

    const handler: TeadsAdPlacementHandler = {
      onHeightChange: (newHeight) => {
        console.log('Height changed:', newHeight);
        // Component automatically adjusts, but handler should be present
      },
    };

  2. Check component container:

    • Ensure component is in ScrollView or similar flexible container
    • Avoid fixed height containers

  3. Verify placement is loading:

    • Check network requests are successful
    • Verify placement ID is correct

Clicks Not Working​

Problem: Users can't click on ads or recommendations.

Solutions:

  1. Check for view overlays:

    • Ensure no transparent views are covering the placement
    • Check z-index/layering of views

  2. Verify handler implementation:

    const handler: TeadsAdPlacementHandler = {
      onRecClick: (url) => {
        console.log('Clicked:', url); // Verify this is called
      },
    };

  3. Test on real device:

    • Simulators/emulators may have click detection issues
    • Always test on real devices

Multiple Widgets Not Working​

Problem: Multiple Feed Placements on same page show duplicate content.

Solutions:

  1. Verify widgetIndex is sequential:

    <TeadsAdPlacementFeed widgetIndex={0} {...props} />
    <TeadsAdPlacementFeed widgetIndex={1} {...props} />
    <TeadsAdPlacementFeed widgetIndex={2} {...props} />

  2. Use unique widgetIds:

    <TeadsAdPlacementFeed widgetId="MB_1" widgetIndex={0} {...props} />
    <TeadsAdPlacementFeed widgetId="MB_2" widgetIndex={1} {...props} />

  3. Ensure same articleUrl:

    • All widgets on the same page should use the same articleUrl

Platform-Specific Issues​

iOS Issues​

Build Errors​

Problem: Xcode build fails with framework errors.

Solutions:

  1. Open .xcworkspace not .xcodeproj:

    open ios/YourApp.xcworkspace

  2. Clean build folder:

    • In Xcode: Product → Clean Build Folder (Shift+Cmd+K)

  3. Reset derived data:

    rm -rf ~/Library/Developer/Xcode/DerivedData

Runtime Errors​

Problem: App crashes or shows errors at runtime.

Solutions:

  1. Check Xcode console for error messages
  2. Verify Info.plist has required permissions
  3. Ensure deployment target is iOS 14.0+

Android Issues​

Build Errors​

Problem: Gradle build fails.

Solutions:

  1. Clean project:

    cd android
    ./gradlew clean
    cd ..

  2. Invalidate caches (Android Studio):

    • File → Invalidate Caches / Restart

  3. Check Gradle version:

    • Should be 7.0 or higher

Runtime Errors​

Problem: App crashes or shows errors at runtime.

Solutions:

  1. Check logcat for error messages:

    adb logcat | grep -i teads

  2. Verify minSdkVersion is 21+

  3. Check ProGuard rules if using code obfuscation

TypeScript Issues​

Type Errors​

Problem: TypeScript shows type errors.

Solutions:

  1. Update imports:

    // Old (if migrating)
    import type { OutbrainWidgetHandler } from 'outbrain-react-native';

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

  2. Verify type definitions:

    npm list @types/react-native

  3. Check TypeScript version:

    • Should be 4.0 or higher

Performance Issues​

Slow Loading​

Problem: Placements take too long to load.

Solutions:

  1. Check network connectivity
  2. Verify placement IDs are correct
  3. Check for network request failures
  4. Monitor native logs for errors

Memory Issues​

Problem: App uses too much memory.

Solutions:

  1. Ensure components are properly unmounted
  2. Check for memory leaks in event handlers
  3. Monitor memory usage with React Native debugger
  4. Test with multiple placements to identify issues

Testing & Debugging​

Enable Debug Logging​

Check native logs for detailed information:

iOS:

  • Open Xcode console
  • Filter by "Teads" or "Outbrain"

Android:

adb logcat | grep -i teads

Test on Real Devices​

Always test on real devices, not just simulators/emulators:

  • Simulators may not accurately represent behavior
  • Real devices show actual performance
  • Some issues only appear on real devices

Test Both Platforms​

Test on both iOS and Android:

  • SDK provides consistent API but platform behavior may differ
  • Some issues are platform-specific
  • Verify event handling works on both platforms

Getting Help​

If you've tried the solutions above and still have issues:

  1. Check Documentation:

  2. Review Common Issues:

    • Verify all prerequisites are met
    • Check you're using latest SDK version
    • Ensure configuration is correct

  3. Contact Support:

Quick Reference​

Installation Checklist​

  • Package installed via npm/yarn
  • iOS: pod install completed successfully
  • Android: Maven repositories configured
  • Android: Java 17+ configured
  • Both platforms: Build succeeds

Integration Checklist​

  • Components imported correctly
  • Required props provided
  • Event handlers implemented
  • Tested on iOS
  • Tested on Android
  • Tested on real devices

Common Fixes​

  1. Component not showing: Check props, verify placement IDs
  2. Events not firing: Verify handler is passed correctly
  3. Build errors: Clean and rebuild, check dependencies
  4. Runtime errors: Check native logs, verify configuration
tip

Pro Tip: Always test on both iOS and Android platforms with real devices before releasing to production. Many issues are platform-specific and only appear on real devices.