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 a root view controller for proper ad presentation. The SDK handles this automatically — no manual configuration is needed. Ensure SDK initialization completes before loading preroll ads.

Using the `EmpowerPrerollView` Component

Preroll ads require a native player view, so you must use the EmpowerPrerollView component. The component handles loading, playback, and cleanup automatically:

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}
      onStatusChanged={(event) => {
        console.log('Preroll status:', event.nativeEvent.status);
      }}
      onAdEvent={(event) => {
        console.log('Ad 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
`androidZoneId`	`string`	No	Android-specific zone ID
`iosZoneId`	`string`	No	iOS-specific zone ID
`contentUrl`	`string`	Yes	URL of the content video
`muted`	`boolean`	No	Mute ad audio (default: `false`)
`onStatusChanged`	`(event) => void`	No	Called when preroll ad status changes
`onAdEvent`	`(event) => void`	No	Called for ad events (STARTED, COMPLETE, SKIPPED, CLICKED, etc.)
`style`	`ViewStyle`	No	Container style. Recommended: `{ width: '100%', aspectRatio: 16/9 }`

Listening to Preroll Events (Optional)

Status Changes

import { addEventListener, EmpowerAdsEvents, AdStatus } from '@empower-nokta/react-native-mobile-ads';
const unsubStatus = addEventListener(
  EmpowerAdsEvents.PREROLL_STATUS,
  (event) => {
    switch (event.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;
      case AdStatus.PAUSED:
        // Ad playback paused
        break;
    }
  }
);
// Clean up
unsubStatus();

Ad Events

Track ad playback events:

const unsubAd = addEventListener(
  EmpowerAdsEvents.PREROLL_AD,
  (event) => {
    switch (event.type) {
      case 'STARTED':
        // Ad playback started
        break;
      case 'COMPLETE':
        // Ad playback finished
        break;
      case 'SKIPPED':
        // User skipped the ad
        break;
      case 'CLICKED':
        // User clicked the ad
        break;
      case 'FAILED':
        // Ad failed to load or play
        break;
    }
  }
);
// Clean up
unsubAd();

Note (Android only): On Android, additional IMA quartile events (FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE) may also be received for granular playback tracking.

Imperative API

The following functions are available for programmatic control of preroll ads. Zone IDs accept string or { android?: string, ios?: string }:

import {
  loadPrerollAd,
  pausePreroll,
  resumePreroll,
  destroyPreroll,
} from '@empower-nokta/react-native-mobile-ads';
const ZONE_ID = 'YOUR_PREROLL_ZONE_ID';
// Preload a preroll ad (requires an EmpowerPrerollView to be mounted)
loadPrerollAd(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
`loadPrerollAd(zoneId)`	Triggers a preroll ad request. Requires a mounted `EmpowerPrerollView` for the same zone.
`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. The EmpowerPrerollView component handles loading automatically on mount — you only need loadPrerollAd for manual reload scenarios.

Complete Example

import React, { useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import {
  EmpowerPrerollView,
  addEventListener,
  EmpowerAdsEvents,
  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(() => {
    const unsubStatus = addEventListener(
      EmpowerAdsEvents.PREROLL_STATUS,
      (event) => {
        console.log('Preroll status:', event.status);
      }
    );
    const unsubAd = addEventListener(
      EmpowerAdsEvents.PREROLL_AD,
      (event) => {
        console.log('IMA event:', event.type);
      }
    );
    return () => {
      unsubStatus();
      unsubAd();
      destroyPreroll(ZONE_ID);
    };
  }, []);
  return (
    <View style={styles.container}>
      <EmpowerPrerollView
        zoneId={ZONE_ID}
        contentUrl="https://example.com/content-video.mp4"
        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: View Controller

The IMA SDK on iOS requires a root view controller for proper ad presentation. The SDK discovers the appropriate view controller automatically — no manual configuration is needed.

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

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
`PAUSED`	Ad playback paused

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

#Using the EmpowerPrerollView Component

#Props

#Listening to Preroll Events (Optional)

#Status Changes

#Ad Events

#Imperative API

#Complete Example

#Best Practices

#iOS: View Controller

#Ad Status Reference

#Troubleshooting

#Preroll Not Playing on iOS

#Preroll Not Playing on Android

#Video Playback Issues