# 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


---

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