Configuration

ViewOptions is the central configuration system for customizing the appearance and behavior of video widgets in the Firework Android SDK. It provides a comprehensive set of options organized into specialized sub-configurations.

Overview

ViewOptions allows you to configure:

Content Source - Which videos to display (discovery, channel, playlist, etc.)
Layout - How videos are displayed (grid, horizontal, vertical)
Player - Video player behavior and appearance
Call-to-Action - CTA button configuration
Shopping - E-commerce integration settings
Livestream - Live video chat and interaction settings
Ads - Advertisement display and badges
StoryBlock - Story-specific configurations

Creating ViewOptions

ViewOptions can be created using either the Builder pattern or Kotlin DSL.

Builder Pattern

val viewOptions = ViewOptions.Builder()
    .baseOption(
        BaseOption.Builder()
            .feedResource(FeedResource.Discovery)
            .build()
    )
    .layoutOption(
        LayoutOption.Builder()
            .feedLayout(FeedLayout.GRID)
            .columnCount(3)
            .build()
    )
    .playerOption(
        PlayerOption.Builder()
            .autoplay(false)
            .showShareButton(true)
            .build()
    )
    .build()

Kotlin DSL (Recommended)

val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery)
    }
    layoutOptions {
        feedLayout(FeedLayout.GRID)
        columnCount(3)
    }
    playerOptions {
        autoplay(false)
        showShareButton(true)
    }
}

Sub-Configuration Options

BaseOption

Configures the content source (which videos to display).

baseOptions {
    feedResource(FeedResource.Discovery)
}

Learn more about BaseOption →

Key Features:

Discovery feed
Channel-specific content
Playlist content
Single video
SKU-based content
Dynamic content
Hashtag playlists

LayoutOption

Controls the visual layout and appearance of video feeds.

layoutOptions {
    feedLayout(FeedLayout.GRID)
    columnCount(3)
    itemSpacing(8)
    roundedCorner(true)
    backgroundColor(Color.WHITE)
}

Learn more about LayoutOption →

Key Features:

Grid, horizontal, or vertical layouts
Column count configuration
Item spacing and aspect ratio
Rounded corners
Play icon customization
Background color

PlayerOption

Customizes video player behavior and UI.

playerOptions {
    playerMode(PlayerMode.FULL_BLEED_MODE)
    autoplay(false)
    showShareButton(true)
    showMuteButton(true)
    enablePipMode(true)
    autoPlayOnComplete(true)
}

Learn more about PlayerOption →

Key Features:

Player modes (FIT_MODE, FULL_BLEED_MODE)
Autoplay controls
UI elements visibility (share, mute, logo)
Picture-in-Picture mode
Subtitle and caption settings
Orientation controls

TitleOption

Configures feed title display and styling.

titleOptions {
    showTitle(true)
    titleTextColor(Color.BLACK)
    titleTextSize(18)
}

Learn more about TitleOption →

Key Features:

Show/hide title
Text color and size
Background color
Padding and typeface
Number of lines

CtaOption

Configures Call-to-Action button behavior.

ctaOptions {
    ctaDelay(CtaDelay(5f, CtaDelayUnit.SECONDS))
    ctaStyle(CtaStyle.LIGHT)
}

Learn more about CtaOption →

Key Features:

Button delay timing
Visual styling
Custom appearance

ChatOption

Customizes livestream chat appearance.

chatOptions {
    chatTextColor(Color.WHITE)
    chatTextShadow(
        TextShadow(
            color = Color.BLACK,
            offsetX = 1f,
            offsetY = 1f,
            radius = 2f
        )
    )
}

Learn more about ChatOption →

Key Features:

Chat text color
Text shadow effects
Chat styling

AdOption and AdBadgeOption

Configures advertisement display and badges.

adOptions {
    fetchTimeoutSeconds(5)
}
adBadgeOptions {
    backgroundColor(Color.WHITE)
    textColor(Color.BLACK)
    badgeText(AdBadgeTextType.SPONSORED)
}

Learn more about AdOption →

Key Features:

Ad fetch timeout
Badge appearance
Badge text (Ad/Sponsored)
Show/hide on thumbnails

StoryBlockOption

Configures StoryBlock-specific behavior.

storyBlockOptions {
    enableAutoPlay(true)
    showFullScreenIcon(true)
}

Learn more about StoryBlockOption →

Key Features:

Autoplay control
Fullscreen icon visibility

Using ViewOptions

With FwVideoFeedView

val videoFeedView = findViewById<FwVideoFeedView>(R.id.videoFeedView)
videoFeedView.init(viewOptions)

With FwStoryBlockView

storyBlock.init(
    fragmentManager = supportFragmentManager,
    lifecycle = lifecycle,
    viewOptions = viewOptions,
    pauseWhenNotVisible = true
)

With FireworkSdk.startPlayer

FireworkSdk.startPlayer(viewOptions)
// or with URL
FireworkSdk.startPlayer(viewOptions, "https://video-url")

Configuration Precedence

When configuring widgets, options are applied in this order:

Default SDK values - Built-in defaults
XML attributes - Attributes set in layout XML (for FwVideoFeedView)
ViewOptions parameter - Options passed to init() or startPlayer()

Later configurations override earlier ones.

Example: Overriding XML Attributes

<!-- XML layout -->
<com.firework.videofeed.FwVideoFeedView
    android:id="@+id/videoFeedView"
    app:fw_feedLayout="horizontal"
    app:fw_feedAutoplay="false" />

// Programmatic override
val viewOptions = viewOptions {
    layoutOptions {
        feedLayout(FeedLayout.GRID) // Overrides XML horizontal layout
    }
    playerOptions {
        autoplay(true) // Overrides XML autoplay=false
    }
}
videoFeedView.init(viewOptions)

Complete Configuration Example

class VideoConfigActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_video_config)
        
        val videoFeedView = findViewById<FwVideoFeedView>(R.id.videoFeedView)
        
        val viewOptions = viewOptions {
            // Content source
            baseOptions {
                feedResource(FeedResource.Discovery)
            }
            
            // Layout configuration
            layoutOptions {
                feedLayout(FeedLayout.GRID)
                columnCount(3)
                itemSpacing(8)
                roundedCorner(true)
                roundedCornerRadius(12)
                showPlayIcon(true)
                backgroundColor(Color.parseColor("#F5F5F5"))
            }
            
            // Player configuration
            playerOptions {
                playerMode(PlayerMode.FULL_BLEED_MODE)
                autoplay(false)
                showShareButton(true)
                showMuteButton(true)
                showFireworkLogo(false)
                enablePipMode(true)
                autoPlayOnComplete(true)
                showSubtitle(true)
                showCaption(true)
            }
            
            // Title configuration
            titleOptions {
                showTitle(true)
                titleTextColor(Color.BLACK)
                titleTextSize(16)
                titleBackgroundColor(Color.WHITE)
            }
            
            // CTA configuration
            ctaOptions {
                ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
            }
            
            // Chat configuration
            chatOptions {
                chatTextColor(Color.WHITE)
            }
            
            // Ad badge configuration
            adBadgeOptions {
                backgroundColor(Color.parseColor("#33000000"))
                textColor(Color.WHITE)
                badgeText(AdBadgeTextType.SPONSORED)
                isHidden(false)
            }
        }
        
        videoFeedView.init(viewOptions)
    }
}

Null Values and Defaults

Properties set to null use SDK defaults
Omitted properties use SDK defaults
Setting a property explicitly overrides defaults

val viewOptions = viewOptions {
    playerOptions {
        // showShareButton not set - uses default (true)
        showMuteButton(false) // Explicitly set to false
        // showFireworkLogo not set - uses default (true)
    }
}

Important Notes

ViewOptions are immutable after creation
Create new ViewOptions to change configuration
Each widget type respects all relevant options
Some options only apply to specific widgets (e.g., StoryBlockOption for StoryBlock only)
XML attributes are only available for FwVideoFeedView

Overview

Creating ViewOptions

Builder Pattern

Kotlin DSL (Recommended)

Sub-Configuration Options

BaseOption

LayoutOption

PlayerOption

TitleOption

CtaOption

ChatOption

AdOption and AdBadgeOption

StoryBlockOption

Using ViewOptions

With FwVideoFeedView

With FwStoryBlockView

With FireworkSdk.startPlayer

Configuration Precedence

Example: Overriding XML Attributes

Complete Configuration Example

Null Values and Defaults

Important Notes

See Also