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

# Short Video CTA Customization

### CTA Options

The CTA button behavior and style can be customized using `CtaOption`. All parameters are optional — any parameter left unset falls back to its default value.

```kotlin
val ctaOption = CtaOption.Builder()
    .ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
    .ctaHighlightDelay(CtaDelay(2f, CtaDelayUnit.SECONDS))
    .ctaMode(CtaOption.CtaMode.FULL_WIDTH)
    .ctaStyle(
        CtaStyle(
            shape = Shape.SHAPE_ROUND_RECTANGLE,
            backgroundColor = Color.parseColor("#3A86FF"),
            textColor = Color.WHITE,
            fontSize = 14f,
        )
    )
    .build()
```

Pass the built `CtaOption` to the player via `ViewOptions`:

```kotlin
val viewOptions = ViewOptions.Builder()
    ...
    .ctaOption(ctaOption)
    ...
    .build()
```

Alternatively, use the `ctaOptions` DSL when building `ViewOptions`:

```kotlin
val viewOptions = viewOptions {
    ...
    ctaOptions {
        ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
        ctaHighlightDelay(CtaDelay(2f, CtaDelayUnit.SECONDS))
        ctaMode(CtaOption.CtaMode.FULL_WIDTH)
        ctaStyle(
            CtaStyle(
                shape = Shape.SHAPE_ROUND_RECTANGLE,
                backgroundColor = Color.parseColor("#3A86FF"),
                textColor = Color.WHITE,
                fontSize = 14f,
            )
        )
    }
    ...
}
```

> See [CTA Options](/firework-for-developers/android-sdk/integration-guide/configuration/cta-options.md) for the full configuration reference.

The same CTA configuration and click handling also apply to the livestream trailer — there is no separate API for livestreams.

| Builder method      | Type                | Description                                                                                                                                                                                       | Default                                                               |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `ctaDelay`          | `CtaDelay`          | When the CTA button first appears (grayed out) after playback starts.                                                                                                                             | 3 seconds (or 20% of the video duration if `PERCENTAGE` unit is used) |
| `ctaHighlightDelay` | `CtaDelay`          | When the CTA button becomes highlighted (fully visible). With `SECONDS` unit the delay counts from the moment the button appears; with `PERCENTAGE` unit it counts from the video playback start. | 2 seconds                                                             |
| `ctaMode`           | `CtaOption.CtaMode` | The width/sizing mode of the CTA button.                                                                                                                                                          | `FULL_WIDTH`                                                          |
| `ctaStyle`          | `CtaStyle`          | The visual style of the CTA button (shape, colors, font size).                                                                                                                                    | SDK default style                                                     |

#### CTA Mode

`CtaMode` controls how the CTA button is sized:

```kotlin
enum class CtaMode {
    FULL_WIDTH,   // button spans the full width of the player
    COMPACT,      // compact button
    SIZE_TO_FIT,  // button sized to fit its text
}
```

#### CTA Delay

`CtaDelay` controls when the CTA appears as a grayed button (`ctaDelay`) and when it becomes fully visible/highlighted (`ctaHighlightDelay`). The delay value is interpreted according to its unit type:

```kotlin
class CtaDelay(
    delayValue: Float,
    delayUnit: CtaDelayUnit,
)

enum class CtaDelayUnit {
    SECONDS,     // seconds elapsed from the video playback start
    PERCENTAGE,  // fraction of the video duration
}
```

* `SECONDS` — valid range is `0` to `10` seconds. Out-of-range values fall back to the default of `3` seconds.
* `PERCENTAGE` — valid range is `0.0` (inclusive) to `1.0` (exclusive), as a fraction of the video duration (e.g. `0.2` = 20%). Out-of-range values fall back to the default of `0.2`.

#### CTA Style

`CtaStyle` customizes the appearance of the CTA button. All fields are optional — `null` fields keep the SDK default:

```kotlin
data class CtaStyle(
    val shape: Shape? = null,          // SHAPE_ROUND_RECTANGLE or SHAPE_OVAL
    val backgroundColor: Int? = null,  // @ColorInt highlighted background color (default #3A86FF)
    val textColor: Int? = null,        // @ColorInt text color (default white)
    val fontSize: Float? = null,       // text size in sp (default 14sp)
)
```

### CTA Handling

There are two ways to handle CTA button clicks in the host app. **Method 1 is the recommended approach.**

#### Method 1 (Recommended): Video CTA Click Listener

Use `FireworkSdk.video.setOnVideoCtaClickListener` to register a dedicated CTA click listener. This is the preferred approach because:

* It provides rich `VideoCtaInfo` data including `videoId`, `label`, `actionUrl`, `actionType`, and `videoInfo`.
* The listener returns a `Boolean` that controls whether the SDK should open the URL, giving the host app full control per click.
* It works consistently across all player surfaces (full-screen player, PlayerDeck, etc.).

```kotlin
FireworkSdk.video.setOnVideoCtaClickListener { info ->
    Log.d("CTA", "CTA clicked: label=${info.label}, url=${info.actionUrl}, type=${info.actionType}")

    // Custom handling: show a modal, open in-app browser, etc.
    CtaModalActivity.start(context, info.actionUrl)
    // Return true: host app handled the click, SDK will NOT open the URL
    // Return false: SDK will open the URL
    true
}
```

**Return value behavior:**

| Listener returns             | `sdkHandleCtaButtonClick = true` | `sdkHandleCtaButtonClick = false` |
| ---------------------------- | -------------------------------- | --------------------------------- |
| `true` (handled by host app) | SDK does NOT open URL            | SDK does NOT open URL             |
| `false` (not handled)        | SDK opens URL                    | SDK does NOT open URL             |

When no listener is registered, the behavior is the same as the listener returning `false` — the SDK opens the URL by default (controlled by `sdkHandleCtaButtonClick`, which defaults to `true`).

To remove the listener, pass `null`:

```kotlin
FireworkSdk.video.setOnVideoCtaClickListener(null)
```

#### Method 2 (Alternative): Analytics Callback

You can also use the analytics callback to react to CTA clicks. This is an alternative approach useful for analytics-only scenarios. You can read more about [analytic callbacks here](/firework-for-developers/android-sdk/integration-guide/analytics.md).

**Key limitation:** This callback is informational only — it has no return value to control SDK behavior per click. You must set `sdkHandleCtaButtonClick` to `false` to prevent the SDK from opening the URL when the host app handles it.

```kotlin
// Step 1: Disable SDK default URL opening
val playerOptions = PlayerOption.Builder()
    ...
    .sdkHandleCtaButtonClick(false)
    ...

// Step 2: Handle CTA clicks in the analytics callback
@FwAnalyticCallable
fun onCtaButtonClicked(event: CtaButtonClickAnalyticsEvent) {
    Log.i("CTA", "CTA clicked: ${event.label} ${event.actionUrl}")
    // Open URL or show modal manually
    CtaModalActivity.start(context, event.actionUrl)
}
```

#### `sdkHandleCtaButtonClick` Configuration

The `sdkHandleCtaButtonClick` option controls whether the SDK automatically opens the CTA URL in a browser. It defaults to `true`:

```kotlin
val playerOptions = PlayerOption.Builder()
    ...
    .sdkHandleCtaButtonClick(true) // SDK opens URL (default)
    // or
    .sdkHandleCtaButtonClick(false) // SDK does NOT open URL
    ...
```

When using **Method 1**, the listener's return value takes priority — if the listener returns `true`, the SDK will not open the URL regardless of `sdkHandleCtaButtonClick`. When using **Method 2**, `sdkHandleCtaButtonClick` is the only way to control URL opening behavior.

### CTA Popup modal

Using either the Video CTA Click Listener (Method 1) or the analytics callback (Method 2), you can show a popup modal over the player.

<figure><img src="/files/sK2dvK4UbnqTL2baJXwL" alt="" width="305"><figcaption></figcaption></figure>

The layout XML file can look something like this:

```markup
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".CtaModalActivity">

    <View
        android:id="@+id/overlay"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1" />

    <androidx.constraintlayout.widget.ConstraintLayout
        android:id="@+id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:padding="16dp">

    ...
    
    </androidx.constraintlayout.widget.ConstraintLayout>

</LinearLayout>
```

The popup modal is just a transparent Activity in the host app which can be done like this:

```kotlin
class CtaModalActivity : AppCompatActivity() {

    private lateinit var binding: ActivityCtaModalBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityCtaModalBinding.inflate(LayoutInflater.from(this))
        setContentView(binding.root)

        val actionUrl = intent.getStringExtra(EXTRA_ACTION_URL)

        ...

        binding.overlay.setOnClickListener {
            finish() // this will handle the user click outside the view
        }

        binding.close.setOnClickListener {
            finish() // this can be a close or skip button
        }
    }

    override fun onResume() {
        super.onResume()
        hideSystemNavigationUI() // This makes sure that modal activity looks and behaves the same as Player
    }

    private fun hideSystemNavigationUI() {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        WindowInsetsControllerCompat(window, binding.root).let { controller ->
            controller.hide(WindowInsetsCompat.Type.navigationBars())
            controller.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
        }
    }

    companion object {
        private const val EXTRA_ACTION_URL = "ACTION_URL"

        fun start(context: Context, actionUrl: String) {
            val intent = Intent(context, CtaModalActivity::class.java)
            intent.putExtra(EXTRA_ACTION_URL, actionUrl)
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
            context.startActivity(intent)
        }
    }
}
```

The activity should be declared in the host app manifest with a transparent theme:

```xml
<activity
    android:name=".CtaModalActivity"
    android:theme="@style/AppTheme.Transparent" />
```

and the transparent theme can be defined like this:

```markup
    <style name="AppTheme.Transparent" parent="Theme.AppCompat.DayNight.NoActionBar">
        <item name="android:windowIsTranslucent">true</item>
        <item name="android:windowBackground">@android:color/transparent</item>
        <item name="android:windowContentOverlay">@null</item>
        <item name="android:windowNoTitle">true</item>
        <item name="android:windowFullscreen">true</item>
        <item name="android:backgroundDimEnabled">false</item>
    </style>
```

Later you can start that activity using either method:

**Method 1 (Recommended):**

```kotlin
FireworkSdk.video.setOnVideoCtaClickListener { info ->
    CtaModalActivity.start(context, info.actionUrl)
    true // Host app handled the click
}
```

**Method 2 (Alternative):**

```kotlin
@FwAnalyticCallable
fun onCtaButtonClicked(event: CtaButtonClickAnalyticsEvent) {
    CtaModalActivity.start(context, event.actionUrl)
}
```

All the necessary logic for the popup modal can be held within the activity. The Player will pause when the activity is opened on top and later continue playback of the content after the activity is finished or the user presses the back button.