Short Video CTA Customization

Customize CTA (Call To Action)

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.

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:

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

Alternatively, use the ctaOptions DSL when building ViewOptions:

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

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:

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:

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

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:

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.

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.

// 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:

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.

The layout XML file can look something like this:

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

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:

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

and the transparent theme can be defined like this:

    <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):

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

Method 2 (Alternative):

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