Short Video CTA Customization

Customize CTA (Click To Action)

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

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:

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:

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.