Preroll Ads

Preroll ads are video ads that play before your content in a PlayerView. 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, the content video plays automatically with standard player controls. 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 content fallback automatically. Use listeners only if you need to track ad states for analytics or UI updates.

XML Layout Setup

Add a PlayerView to your layout:

<androidx.media3.ui.PlayerView
    android:id="@+id/playerView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

Loading a Preroll Ad

Kotlin
Java

import net.empower.mobile.ads.api.EMAManager
class VideoActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_video)
        val playerView = findViewById<PlayerView>(R.id.playerView)
        EMAManager.loadPrerollAd(
            zoneId = "YOUR_PREROLL_ZONE_ID",
            playerView = playerView,
            contentUrl = "https://example.com/your-content-video.mp4"
        )
    }
}

That's it — the SDK loads the ad, plays it, and transitions to your content video automatically.

Parameters

Parameter	Type	Required	Default	Description
`zoneId`	String	Yes	—	The zone ID for the preroll placement
`playerView`	PlayerView	Yes	—	The Media3 PlayerView where the ad and content will play
`contentUrl`	String	Yes	—	URL of the content video that plays after the ad
`muted`	Boolean	No	`false`	Whether to mute audio during ad playback
`prerollListener`	PrerollAdListener	No	`null`	Rich preroll-specific event listener
`adStatusListener`	AdStatusListener	No	`null`	Generic ad status listener

Listening to Preroll Events (Optional)

Use PrerollAdListener if you need to react to specific ad events:

Kotlin
Java

EMAManager.loadPrerollAd(
    zoneId = "YOUR_PREROLL_ZONE_ID",
    playerView = playerView,
    contentUrl = "https://example.com/your-content-video.mp4",
    prerollListener = object : PrerollAdListener {
        override fun onAdReady() {
            // Ad loaded and about to auto-play
        }
        override fun onAdStarted() {
            // Ad is playing
        }
        override fun onAdCompleted() {
            // Ad finished — content video is now playing
        }
        override fun onAdSkipped() {
            // User skipped the ad — content video is now playing
        }
        override fun onAdFailed(error: String) {
            // Ad failed — content video is now playing automatically
        }
        override fun onAdClicked() {
            // User clicked the ad
        }
    }
)

Or use AdStatusListener for generic status tracking:

Kotlin
Java

EMAManager.loadPrerollAd(
    zoneId = "YOUR_PREROLL_ZONE_ID",
    playerView = playerView,
    contentUrl = "https://example.com/your-content-video.mp4",
    adStatusListener = object : AdStatusListener {
        override fun prerollStatusChanged(adStatus: AdStatus) {
            when (adStatus) {
                AdStatus.READY -> { /* Ad loaded */ }
                AdStatus.SHOWN -> { /* Ad playing */ }
                AdStatus.COMPLETE_PLAYING -> { /* Ad finished */ }
                AdStatus.SKIPPED -> { /* Ad skipped */ }
                AdStatus.FAILED -> { /* Ad failed, content playing */ }
                else -> {}
            }
        }
    }
)

Lifecycle Management

The SDK automatically observes the Activity lifecycle through the PlayerView's context. Pause, resume, and cleanup are handled for you — no manual lifecycle calls are needed.

For special cases like pausing playback when the view scrolls off-screen in a RecyclerView, use:

Kotlin
Java

// Pause playback (e.g., view scrolled off-screen)
EMAManager.pausePreroll("YOUR_PREROLL_ZONE_ID")
// Resume playback (e.g., view scrolled back)
EMAManager.resumePreroll("YOUR_PREROLL_ZONE_ID")

Method	Description
`pausePreroll(zoneId)`	Pauses ad or content playback (for scroll-off-screen scenarios)
`resumePreroll(zoneId)`	Resumes playback
`destroyPreroll(zoneId)`	Manually releases player resources (rarely needed)

Best Practices

Always provide a content URL — The SDK requires a valid content video URL
Mute when appropriate — Use muted = true if the video auto-plays in a feed or silent context
Frequency capping — The SDK respects server-configured session frequency caps

Ad Status Reference

Status	Description
`READY`	Ad is loaded and about to auto-play
`SHOWN`	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 is playing automatically

#XML Layout Setup

#Loading a Preroll Ad

#Parameters

#Listening to Preroll Events (Optional)

#Lifecycle Management

#Best Practices