Preroll Ads

Preroll ads are video ads that play before your content. The SDK manages playback automatically using Google IMA — the ad auto-plays with no user-visible controls. Users can skip the ad when the VAST creative allows it.

After the ad completes, is skipped, or fails, your content can start playing automatically. No additional handling is needed.

Each ad format uses a Zone ID to identify the ad placement. Zone IDs are configured in the Empower dashboard.

Note: All ad listeners are optional. The SDK handles ad loading, playback, and fallback automatically. Use listeners only if you need to track ad states for analytics or UI updates.

Platform Differences

Preroll ads use different native player components per platform:

Platform	Player Component	Container
Android	`PlayerView` (Media3/ExoPlayer)	`androidx.media3.ui.PlayerView`
iOS	IMA SDK	`UIView` container

Important (iOS): The IMA SDK requires rootViewController to be set for proper ad presentation. The React Native bridge sets this automatically during init() via EMASettings.shared.rootViewController. If you encounter issues with preroll ads not displaying on iOS, ensure SDK initialization completes before loading preroll ads.

Preroll is Component-Driven

Unlike the other ad formats, preroll has no load…() / show…() functions. You render the EmpowerPrerollView component with a zoneId and a contentUrl; the SDK loads the ad, plays it, then transitions to your content video automatically. Status and IMA events are delivered through the component's onPrerollStatusChanged / onPrerollAdEvent props (there are no global preroll events). See below.

Using the `EmpowerPrerollView` Component

For inline video ad placement, use the EmpowerPrerollView component:

import { EmpowerPrerollView } from '@empower-nokta/react-native-mobile-ads';

function VideoScreen() {
  return (
    <EmpowerPrerollView
      zoneId="YOUR_PREROLL_ZONE_ID"
      contentUrl="https://example.com/your-content-video.mp4"
      muted={false}
      onPrerollStatusChanged={(event) => {
        console.log('Preroll status:', event.nativeEvent.status);
      }}
      onPrerollAdEvent={(event) => {
        console.log('IMA event:', event.nativeEvent.type);
      }}
      style={{ width: '100%', aspectRatio: 16 / 9 }}
    />
  );
}

Props

Prop	Type	Required	Description
`zoneId`	`string \| { android?: string, ios?: string }`	Yes	Zone ID for the preroll placement
`contentUrl`	`string`	Yes	URL of the content video
`muted`	`boolean`	No	Mute ad audio (default: `false`)
`onPrerollStatusChanged`	`(event) => void`	No	Called when preroll ad status changes
`onPrerollAdEvent`	`(event) => void`	No	Called for IMA ad events (quartile progress, etc.)
`style`	`ViewStyle`	No	Container style. Recommended: `{ width: '100%', aspectRatio: 16/9 }`

Listening to Preroll Events (Optional)

Preroll status and IMA events are delivered through the component props — onPrerollStatusChanged and onPrerollAdEvent. There are no global addEventListener events for preroll. Both callbacks receive the payload under event.nativeEvent.

Status Changes — `onPrerollStatusChanged`

import { EmpowerPrerollView, AdStatus } from '@empower-nokta/react-native-mobile-ads';

<EmpowerPrerollView
  zoneId="YOUR_PREROLL_ZONE_ID"
  contentUrl="https://example.com/content-video.mp4"
  onPrerollStatusChanged={({ nativeEvent }) => {
    switch (nativeEvent.status) {
      case AdStatus.READY:
        // Ad is loaded and about to play
        break;
      case AdStatus.ACTIVE:
        // Ad is playing
        break;
      case AdStatus.COMPLETE_PLAYING:
        // Ad finished — content video is now playing
        break;
      case AdStatus.FAILED:
        // Ad failed — content video plays automatically
        break;
    }
  }}
  style={{ width: '100%', aspectRatio: 16 / 9 }}
/>

IMA Ad Events — `onPrerollAdEvent`

Track granular ad playback progress:

<EmpowerPrerollView
  zoneId="YOUR_PREROLL_ZONE_ID"
  contentUrl="https://example.com/content-video.mp4"
  onPrerollAdEvent={({ nativeEvent }) => {
    switch (nativeEvent.type) {
      case 'STARTED':
        // Ad playback started
        break;
      case 'FIRST_QUARTILE':
        // 25% of the ad has played
        break;
      case 'MIDPOINT':
        // 50% of the ad has played
        break;
      case 'THIRD_QUARTILE':
        // 75% of the ad has played
        break;
      case 'COMPLETE':
        // Ad playback finished
        break;
      case 'SKIPPED':
        // User skipped the ad
        break;
      case 'CLICKED':
        // User clicked the ad
        break;
    }
  }}
  style={{ width: '100%', aspectRatio: 16 / 9 }}
/>

Lifecycle Management

The SDK automatically manages the ad lifecycle based on the component's visibility. For special cases like scrolling the video player off-screen in a FlatList, use the control functions:

import { pausePreroll, resumePreroll, destroyPreroll } from '@empower-nokta/react-native-mobile-ads';

const ZONE_ID = 'YOUR_PREROLL_ZONE_ID';

// Pause playback (e.g., view scrolled off-screen)
pausePreroll(ZONE_ID);

// Resume playback (e.g., view scrolled back)
resumePreroll(ZONE_ID);

// Release all resources when done
destroyPreroll(ZONE_ID);

Method	Description
`pausePreroll(zoneId)`	Pauses ad or content playback
`resumePreroll(zoneId)`	Resumes playback
`destroyPreroll(zoneId)`	Releases player resources

Tip: Call destroyPreroll when the screen unmounts to free native resources.

Complete Example

import React, { useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import {
  EmpowerPrerollView,
  destroyPreroll,
} from '@empower-nokta/react-native-mobile-ads';

const ZONE_ID = { android: 'ANDROID_PREROLL_ZONE_ID', ios: 'IOS_PREROLL_ZONE_ID' };

export default function VideoScreen() {
  useEffect(() => {
    // Release native player resources when leaving the screen.
    return () => destroyPreroll(ZONE_ID);
  }, []);

  return (
    <View style={styles.container}>
      <EmpowerPrerollView
        zoneId={ZONE_ID}
        contentUrl="https://example.com/content-video.mp4"
        onPrerollStatusChanged={({ nativeEvent }) =>
          console.log('Preroll status:', nativeEvent.status)
        }
        onPrerollAdEvent={({ nativeEvent }) =>
          console.log('IMA event:', nativeEvent.type)
        }
        style={styles.player}
      />
      <Text style={styles.title}>Video Title</Text>
      <Text style={styles.description}>Video description goes here...</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#000' },
  player: { width: '100%', aspectRatio: 16 / 9 },
  title: { color: '#fff', fontSize: 18, fontWeight: 'bold', padding: 16 },
  description: { color: '#ccc', fontSize: 14, paddingHorizontal: 16 },
});

Best Practices

Set explicit aspect ratio — Use aspectRatio: 16/9 on the container for standard video proportions
Mute when appropriate — Set muted={true} if the video auto-plays in a feed or silent context
Destroy on unmount — Always call destroyPreroll in the cleanup function of useEffect to release native player resources
Frequency capping — The SDK respects server-configured session frequency caps
Content URL required — Always provide a valid contentUrl. The ad plays first, then transitions to your content video automatically

iOS: rootViewController

The IMA SDK on iOS requires a rootViewController reference for proper ad presentation. The bridge sets this automatically during SDK initialization:

// Set automatically inside init()
EMASettings.shared.rootViewController = rootViewController

If preroll ads fail to display on iOS, verify that:

SDK initialization (init()) has completed before loading preroll ads
The app has a visible root view controller at the time of initialization
EMASettings.shared.rootViewController is set — the bridge does this automatically, but if you override initialization, ensure it's included

Ad Status Reference

Status	Description
`READY`	Ad is loaded and about to play
`ACTIVE`	Ad is playing
`COMPLETE_PLAYING`	Ad finished playing, content video is now playing
`SKIPPED`	User skipped the ad, content video is now playing
`FAILED`	Ad failed, content video plays automatically

Troubleshooting

Preroll Not Playing on iOS

Check rootViewController is set:

// Enable debug logs to verify
setLogLevel('all');

Ensure SDK is initialized before loading preroll
Check zone ID is correct and active in the Empower dashboard

Preroll Not Playing on Android

Ensure Media3 (ExoPlayer) dependency is available — the SDK includes it transitively, but verify no version conflicts exist
Check the content URL is accessible — the SDK needs a valid video URL to transition to after the ad

Video Playback Issues

Black screen: Verify container dimensions are set correctly (non-zero width and height)
Audio issues: Check the muted prop and device volume settings
Memory leaks: Always call destroyPreroll when navigating away from the video screen

Platform Differences​

Preroll is Component-Driven​

Using the EmpowerPrerollView Component​

Props​

Listening to Preroll Events (Optional)​

Status Changes — onPrerollStatusChanged​

IMA Ad Events — onPrerollAdEvent​

Lifecycle Management​

Complete Example​

Best Practices​

iOS: rootViewController​

Ad Status Reference​

Troubleshooting​

Preroll Not Playing on iOS​

Preroll Not Playing on Android​

Video Playback Issues​