Open Fullscreen Player

The FireworkSdk.startPlayer() method launches a fullscreen video player in a separate activity. This is useful when you want to play videos directly without embedding a FwVideoFeedView or FwStoryblock in your layout.

Overview

Unlike FwVideoFeedView and FwStoryBlockView, which are embedded views, FireworkSdk.startPlayer() launches a standalone player activity that takes over the entire screen. This approach is ideal for:

Opening specific videos from deep links
Playing videos from custom UI elements (buttons, banners, etc.)
Handling video notifications
Creating custom video entry points

Content limits and empty feeds

Since 6.35.1, BaseOption.maxItemCount limits the pages in a fullscreen session, including direct launches:

import com.firework.common.feed.FeedResource
import com.firework.sdk.FireworkSdk
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.ViewOptions

val options = ViewOptions.Builder()
    .baseOption(
        BaseOption.Builder()
            .feedResource(FeedResource.Discovery)
            .maxItemCount(6)
            .build()
    )
    .build()
FireworkSdk.startPlayer(options)

Replace FeedResource.Discovery with your desired content source. The default limit is null (unrestricted); positive values are capped at 20. Interstitial ads count as pages. Each session has its own limit, and child playlist sessions inherit it. Only the first page is used when a limit is configured. See Maximum Item Count.

If the initial feed is empty, the player activity closes automatically. Launch success indicates that the player was launched; it does not guarantee that the subsequently loaded feed contains playable content.

Usage

FireworkSdk.startPlayer() has two variants:

1. Start Player with URL

Launch a specific video directly using its URL:

val viewOptions = ViewOptions.Builder()
    .playerOption(
        PlayerOption.Builder()
            .showShareButton(true)
            .enablePipMode(true)
            .build()
    )
    .build()

val result = FireworkSdk.startPlayer(
    viewOptions = viewOptions,
    url = "https://your-video-url"
)

when (result) {
    is PlayerLaunchResult.Success -> {
        // Player launched successfully
    }
    is PlayerLaunchResult.Failure -> {
        // Handle launch failure
        Log.e("Player", "Failed to launch player: ${result.message}")
    }
}

2. Start Player with Feed Configuration

Launch the player with a feed configuration, allowing users to browse through multiple videos:

val viewOptions = ViewOptions.Builder()
    .baseOption(
        BaseOption.Builder()
            .feedResource(FeedResource.Discovery)
            .build()
    )
    .playerOption(
        PlayerOption.Builder()
            .showShareButton(true)
            .enablePipMode(true)
            .build()
    )
    .build()

val result = FireworkSdk.startPlayer(viewOptions)

when (result) {
    is PlayerLaunchResult.Success -> {
        // Player launched successfully
    }
    is PlayerLaunchResult.Failure -> {
        // Handle launch failure
        Log.e("Player", "Failed to launch player: ${result.message}")
    }
}

Using Kotlin DSL

For more concise syntax, use the DSL:

val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery)
    }
    playerOptions {
        showShareButton(true)
        enablePipMode(true)
        autoPlayOnComplete(true)
    }
}

val result = FireworkSdk.startPlayer(viewOptions)

Launch Result

Both variants return a PlayerLaunchResult that indicates success or failure:

sealed class PlayerLaunchResult {
    object Success : PlayerLaunchResult()
    class Failure(val message: String) : PlayerLaunchResult()
}

Handling Results

when (val result = FireworkSdk.startPlayer(viewOptions, url)) {
    is PlayerLaunchResult.Success -> {
        // Player launched successfully
        // The player activity is now running
    }
    is PlayerLaunchResult.Failure -> {
        // Launch failed
        Toast.makeText(
            context,
            "Failed to open video: ${result.message}",
            Toast.LENGTH_SHORT
        ).show()
    }
}

Configuration

The player can be configured using ViewOptions. Key options include:

Player Appearance

val viewOptions = viewOptions {
    playerOptions {
        // Player mode
        playerMode(PlayerMode.FULL_BLEED_MODE)
        
        // UI elements
        showShareButton(true)
        showMuteButton(true)
        showFireworkLogo(false)
        
        // Playback behavior
        autoPlayOnComplete(true)
        autoplay(true)
    }
}

Content Source

When not using a specific URL, configure the content source:

val viewOptions = viewOptions {
    baseOptions {
        // Discovery feed
        feedResource(FeedResource.Discovery)
        
        // Or specific playlist
        // feedResource(
        //     FeedResource.Playlist(
        //         channelId = "your_channel_id",
        //         playlistId = "your_playlist_id"
        //     )
        // )
    }
}

Picture-in-Picture

Enable PIP mode to allow users to minimize the player:

val viewOptions = viewOptions {
    playerOptions {
        enablePipMode(true)
    }
}

Player Launch Modes

You can configure the player activity launch mode:

// Set globally for all players
FireworkSdk.setPlayerLaunchMode(FwPlayerActivityLaunchMode.SINGLE_TASK)

// Then launch player
FireworkSdk.startPlayer(viewOptions)

Available launch modes:

SINGLE_TASK - Standard single task launch mode
SINGLE_INSTANCE - Single instance launch mode for complete isolation
SINGLE_TASK_WITH_OWN_AFFINITY - Single task with custom affinity for separation

Important Notes

The SDK must be initialized before calling startPlayer()
The player launches in a new activity, separate from your app's activity stack
Always handle PlayerLaunchResult.Failure to provide user feedback
ViewOptions can customize all aspects of player behavior
The player handles its own lifecycle - no manual cleanup required
URL variant is useful for specific videos, feed variant for browsing multiple videos

Comparison with Other Widgets

Feature

FwVideoFeedView

FwStoryBlockView

startPlayer()

Embedding

Embedded view

Separate activity

Layout Control

Full control

No control

Thumbnail Display

Yes

Lifecycle Management

Automatic

Manual