> 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/ad-options.md).

# Ad Options

`AdOption` and `AdBadgeOption` configure advertisement display and badge appearance for video ads. These options control ad loading behavior and the visual presentation of ad badges.

## Overview

**AdOption** configures:

* Ad fetch timeout
* VAST attributes for ad delivery

**AdBadgeOption** configures:

* Badge text ("Ad" or "Sponsored")
* Badge colors and styling
* Badge visibility on thumbnails and player
* Custom typeface

## Creating Ad Options

### Using Builder

```kotlin
val adOption = AdOption.Builder()
    .adsFetchTimeoutInSeconds(10)
    .build()

val adBadgeOption = AdBadgeOption.Builder()
    .adBadgeTextColor(Color.WHITE)
    .adBadgeBackColor(Color.parseColor("#F65178EE"))
    .adBadgeLabel(AdBadgeTextType.SPONSORED)
    .adBadgeIsHidden(false)
    .build()
```

### Using DSL (Recommended)

```kotlin
val viewOptions = viewOptions {
    adOptions {
        adsFetchTimeoutInSeconds(10)
        vastAttributes(mapOf("key" to "value"))
    }
    adBadgeOptions {
        adBadgeTextColor(Color.WHITE)
        adBadgeBackColor(Color.parseColor("#F65178EE"))
        adBadgeLabel(AdBadgeTextType.SPONSORED)
        adBadgeIsHidden(false)
        adBadgeShowOnThumbnails(true)
    }
}
```

## AdOption Properties

### adsFetchTimeoutInSeconds

**Type:** `Int`\
**Default:** `10` seconds

Maximum time to wait for ad content to load before timing out.

```kotlin
adOptions {
    adsFetchTimeoutInSeconds(15) // Wait up to 15 seconds
}
```

### vastAttributes

**Type:** `Map<String, String>`\
**Default:** Empty map

Custom attributes to pass with VAST ad requests.

```kotlin
adOptions {
    vastAttributes(
        mapOf(
            "app_name" to "MyApp",
            "user_segment" to "premium"
        )
    )
}
```

## AdBadgeOption Properties

### adBadgeTextColor

**Type:** `Int` (color)\
**Default:** White (`Color.WHITE`)

Text color for the ad badge.

```kotlin
adBadgeOptions {
    adBadgeTextColor(Color.WHITE)
}
```

### adBadgeBackColor

**Type:** `Int` (color)\
**Default:** Blue (`0xF65178EE`)

Background color for the ad badge.

```kotlin
adBadgeOptions {
    adBadgeBackColor(Color.parseColor("#F65178EE"))
    // or
    adBadgeBackColor(Color.parseColor("#FF5722"))
}
```

### adBadgeLabel

**Type:** `AdBadgeTextType` (enum)\
**Default:** `SPONSORED`

Text displayed on the ad badge.

**Values:**

* `AdBadgeTextType.SPONSORED` - Displays "Sponsored"
* `AdBadgeTextType.AD` - Displays "Ad"

```kotlin
adBadgeOptions {
    adBadgeLabel(AdBadgeTextType.AD)
}
```

### adBadgeIsHidden

**Type:** `Boolean`\
**Default:** `false`

Show or hide the ad badge.

```kotlin
adBadgeOptions {
    adBadgeIsHidden(false) // Show badge
}
```

### adBadgeShowOnThumbnails

**Type:** `Boolean`\
**Default:** `false`

Show ad badge on video thumbnails in the feed.

```kotlin
adBadgeOptions {
    adBadgeShowOnThumbnails(true) // Show on thumbnails
}
```

### adBadgeTypeface

**Type:** `Typeface`\
**Default:** `Typeface.DEFAULT`

Custom typeface for ad badge text.

```kotlin
val customFont = ResourcesCompat.getFont(context, R.font.custom_font)

adBadgeOptions {
    adBadgeTypeface(customFont)
}
```

## Default Values

### AdOption Defaults

| Property                   | Default Value |
| -------------------------- | ------------- |
| `adsFetchTimeoutInSeconds` | `10`          |
| `vastAttributes`           | Empty map     |

### AdBadgeOption Defaults

| Property                  | Default Value       |
| ------------------------- | ------------------- |
| `adBadgeTextColor`        | White               |
| `adBadgeBackColor`        | `0xF65178EE` (blue) |
| `adBadgeLabel`            | `SPONSORED`         |
| `adBadgeIsHidden`         | `false`             |
| `adBadgeShowOnThumbnails` | `false`             |
| `adBadgeTypeface`         | `Typeface.DEFAULT`  |

## Complete Examples

### Standard Ad Configuration

```kotlin
val viewOptions = viewOptions {
    adOptions {
        adsFetchTimeoutInSeconds(10)
    }
    adBadgeOptions {
        adBadgeTextColor(Color.WHITE)
        adBadgeBackColor(Color.parseColor("#F65178EE"))
        adBadgeLabel(AdBadgeTextType.SPONSORED)
        adBadgeShowOnThumbnails(true)
    }
}
```

### Custom Styled Ad Badge

```kotlin
class AdFeedActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_ad_feed)
        
        val videoFeedView = findViewById<FwVideoFeedView>(R.id.videoFeedView)
        
        val viewOptions = viewOptions {
            baseOptions {
                feedResource(FeedResource.Discovery)
            }
            adOptions {
                adsFetchTimeoutInSeconds(15)
            }
            adBadgeOptions {
                adBadgeTextColor(Color.BLACK)
                adBadgeBackColor(Color.parseColor("#FFD600")) // Yellow
                adBadgeLabel(AdBadgeTextType.AD)
                adBadgeIsHidden(false)
                adBadgeShowOnThumbnails(true)
            }
        }
        
        videoFeedView.init(viewOptions)
    }
}
```

### Minimal Ad Badge

```kotlin
val viewOptions = viewOptions {
    adBadgeOptions {
        adBadgeTextColor(Color.WHITE)
        adBadgeBackColor(Color.parseColor("#80000000")) // Semi-transparent
        adBadgeLabel(AdBadgeTextType.AD)
        adBadgeShowOnThumbnails(false) // Only in player
    }
}
```

### Branded Ad Badge

```kotlin
val brandFont = ResourcesCompat.getFont(context, R.font.brand_font)

val viewOptions = viewOptions {
    adBadgeOptions {
        adBadgeTextColor(Color.WHITE)
        adBadgeBackColor(Color.parseColor("#FF3700B3")) // Brand color
        adBadgeLabel(AdBadgeTextType.SPONSORED)
        adBadgeShowOnThumbnails(true)
        adBadgeTypeface(brandFont)
    }
}
```

### High Contrast Ad Badge

```kotlin
val viewOptions = viewOptions {
    adBadgeOptions {
        adBadgeTextColor(Color.BLACK)
        adBadgeBackColor(Color.WHITE)
        adBadgeLabel(AdBadgeTextType.AD)
        adBadgeIsHidden(false)
        adBadgeShowOnThumbnails(true)
    }
}
```

### Hidden Ad Badge

```kotlin
val viewOptions = viewOptions {
    adBadgeOptions {
        adBadgeIsHidden(true) // No badge displayed
    }
}
```

### Quick Timeout for Fast Loading

```kotlin
val viewOptions = viewOptions {
    adOptions {
        adsFetchTimeoutInSeconds(5) // Fast timeout
    }
    adBadgeOptions {
        adBadgeShowOnThumbnails(true)
    }
}
```

## Ad Badge Visibility

The ad badge can appear in two locations:

### On Thumbnails

```kotlin
adBadgeOptions {
    adBadgeShowOnThumbnails(true)
}
```

Shows the badge on video thumbnails in the feed, helping users identify sponsored content before clicking.

### In Player

The badge always shows in the video player (unless `adBadgeIsHidden` is true).

```kotlin
adBadgeOptions {
    adBadgeShowOnThumbnails(false) // Only in player, not on thumbnails
}
```

## Ad Badge Text Options

### "Sponsored" Label

```kotlin
adBadgeOptions {
    adBadgeLabel(AdBadgeTextType.SPONSORED)
}
```

Displays "Sponsored" - typically used for sponsored content and brand partnerships.

### "Ad" Label

```kotlin
adBadgeOptions {
    adBadgeLabel(AdBadgeTextType.AD)
}
```

Displays "Ad" - typically used for direct advertisements.

## Ad Loading Behavior

### Timeout Configuration

```kotlin
adOptions {
    // Short timeout for fast user experience
    adsFetchTimeoutInSeconds(5)
    
    // Medium timeout (default)
    adsFetchTimeoutInSeconds(10)
    
    // Long timeout for slower connections
    adsFetchTimeoutInSeconds(20)
}
```

* Shorter timeouts improve perceived performance but may miss some ads
* Longer timeouts ensure more ads load but may delay content display
* Default of 10 seconds balances performance and ad delivery

### VAST Attributes

```kotlin
adOptions {
    vastAttributes(
        mapOf(
            "app_id" to "com.myapp",
            "user_id" to userId,
            "content_category" to "technology",
            "gdpr_consent" to "true"
        )
    )
}
```

Custom attributes passed to VAST ad server for targeting and compliance.

## Important Notes

* Ad badges help maintain transparency about sponsored content
* Badge visibility is separate for thumbnails and player
* Typeface must be included in your app's font resources
* Ad fetch timeout affects initial feed loading time
* VAST attributes can be used for ad targeting and compliance
* Badge colors should maintain sufficient contrast for readability
* Consider platform advertising guidelines when configuring badges
* Ad configuration is applied globally across the app

## See Also

* [ViewOptions Overview](/firework-for-developers/android-sdk/integration-guide/configuration.md) - Complete configuration system
* [Video Ads Support](/firework-for-developers/android-sdk/integration-guide/video-ads-support.md) - Ad implementation details
* [FwVideoFeedView](/firework-for-developers/android-sdk/integration-guide/configure-video-feed.md) - Video feed configuration
* [BaseOption](/firework-for-developers/android-sdk/integration-guide/configuration/base-options.md) - Content sources including ads