> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration.md).

# 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

```kotlin
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)

```kotlin
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).

```kotlin
baseOptions {
    feedResource(FeedResource.Discovery)
}
```

[Learn more about BaseOption →](/firework-for-developers/android-sdk/integration-guide/configuration/base-options.md)

**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.

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

[Learn more about LayoutOption →](/firework-for-developers/android-sdk/integration-guide/configuration/layout-options.md)

**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.

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

[Learn more about PlayerOption →](/firework-for-developers/android-sdk/integration-guide/configuration/player-options.md)

**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.

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

[Learn more about TitleOption →](/firework-for-developers/android-sdk/integration-guide/configuration/title-options.md)

**Key Features:**

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

### CtaOption

Configures Call-to-Action button behavior.

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

[Learn more about CtaOption →](/firework-for-developers/android-sdk/integration-guide/configuration/cta-options.md)

**Key Features:**

* Button delay timing
* Visual styling
* Custom appearance

### ChatOption

Customizes livestream chat appearance.

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

[Learn more about ChatOption →](/firework-for-developers/android-sdk/integration-guide/configuration/chat-options.md)

**Key Features:**

* Chat text color
* Text shadow effects
* Chat styling

### AdOption and AdBadgeOption

Configures advertisement display and badges.

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

[Learn more about AdOption →](/firework-for-developers/android-sdk/integration-guide/configuration/ad-options.md)

**Key Features:**

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

### StoryBlockOption

Configures StoryBlock-specific behavior.

```kotlin
storyBlockOptions {
    enableAutoPlay(true)
    showFullScreenIcon(true)
}
```

[Learn more about StoryBlockOption →](/firework-for-developers/android-sdk/integration-guide/configuration/story-block-options.md)

**Key Features:**

* Autoplay control
* Fullscreen icon visibility

## Using ViewOptions

### With FwVideoFeedView

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

### With FwStoryBlockView

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

### With FireworkSdk.startPlayer

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

## Configuration Precedence

When configuring widgets, options are applied in this order:

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

Later configurations override earlier ones.

### Example: Overriding XML Attributes

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

```kotlin
// 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

```kotlin
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

```kotlin
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

## See Also

* [Widgets Overview](/firework-for-developers/android-sdk/integration-guide/widgets.md) - Available video widgets
* [BaseOption](/firework-for-developers/android-sdk/integration-guide/configuration/base-options.md) - Feed source configuration
* [LayoutOption](/firework-for-developers/android-sdk/integration-guide/configuration/layout-options.md) - Layout customization
* [PlayerOption](/firework-for-developers/android-sdk/integration-guide/configuration/player-options.md) - Player behavior
* [Shopping Configuration](/firework-for-developers/android-sdk/integration-guide/shoppable-videos.md) - Shopping-specific options