# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.