# Short Video CTA Customization

### CTA Options

The CTA button behavior and style can be customized using the CTA Options.

```
val ctaOptions = CtaOption.Builder()
    .ctaDelay(CtaDelay(ctaDelayDuration, ctaDelayUnit.toCtaDelayUnit()))
    .ctaHighlightDelay(CtaDelay(ctaHighlightDelayDuration, ctaHighlightDelayUnit.toCtaDelayUnit()))
    .ctaMode(CtaMode.FULL_WIDTH)
    .build()
```

Mode includes:

```
enum class CtaMode {
    FULL_WIDTH,
    COMPACT,
    SIZE_TO_FIT,
}
```

It is possible to control the appearance of the CTA button using delay and highlight delay values, as well as defining the unit type, which can be either seconds elapsed from the video playback start or a percentage. This allows you to choose when the CTA appears as a grayed button and when it becomes fully visible:

```
enum class CtaDelayUnit {
    SECONDS,
    PERCENTAGE,
}
```

### 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             |

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:

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


---

# 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/cta.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.