CTA Options

CtaOption configures the Call-to-Action (CTA) button behavior and appearance in videos. CTA buttons are interactive elements that can trigger shopping actions, external links, or custom behaviors.

Overview

CtaOption allows you to customize:

CTA button display delay
CTA button highlighting timing
Button visual style
Button sizing mode

Creating CtaOption

Using Builder

val ctaOption = CtaOption.Builder()
    .ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
    .ctaStyle(CtaStyle(shape = Shape.SHAPE_ROUND_RECTANGLE))
    .ctaMode(CtaOption.CtaMode.FULL_WIDTH)
    .build()

Using DSL (Recommended)

val viewOptions = viewOptions {
    ctaOptions {
        ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
        ctaHighlightDelay(CtaDelay(1f, CtaDelayUnit.SECONDS))
        ctaStyle(
            CtaStyle(
                shape = Shape.SHAPE_ROUND_RECTANGLE,
                backgroundColor = Color.parseColor("#FF6200EE"),
                textColor = Color.WHITE,
                fontSize = 16f
            )
        )
        ctaMode(CtaOption.CtaMode.COMPACT)
    }
}

Properties

ctaDelay

Type: CtaDelay Default: SDK default

Delay before showing the CTA button after video starts playing.

ctaOptions {
    // Delay in seconds
    ctaDelay(CtaDelay(5f, CtaDelayUnit.SECONDS))
    
    // Or delay as percentage of video duration
    ctaDelay(CtaDelay(25f, CtaDelayUnit.PERCENTAGE))
}

CtaDelay Parameters:

value - Delay amount (Float)
unit - Delay unit (SECONDS or PERCENTAGE)

Examples:

CtaDelay(3f, CtaDelayUnit.SECONDS) - Show after 3 seconds
CtaDelay(50f, CtaDelayUnit.PERCENTAGE) - Show at 50% of video duration

ctaHighlightDelay

Type: CtaDelay Default: SDK default

Delay before highlighting the CTA button to draw user attention.

ctaOptions {
    ctaHighlightDelay(CtaDelay(2f, CtaDelayUnit.SECONDS))
}

The highlight effect makes the CTA button more prominent after the specified delay.

ctaMode

Type: CtaOption.CtaMode (enum) Default: FULL_WIDTH

Controls the sizing behavior of the CTA button.

Values:

FULL_WIDTH - Button spans full width of video
COMPACT - Button uses minimal width
SIZE_TO_FIT - Button sizes to fit content

ctaOptions {
    ctaMode(CtaOption.CtaMode.COMPACT)
}

ctaStyle

Type: CtaStyle Default: SDK default styling

Customizes the visual appearance of the CTA button.

ctaOptions {
    ctaStyle(
        CtaStyle(
            shape = Shape.ROUNDED,
            backgroundColor = Color.parseColor("#FF6200EE"),
            textColor = Color.WHITE,
            fontSize = 16f
        )
    )
}

CtaStyle Properties:

shape - Button shape (Shape.ROUNDED or Shape.RECTANGLE)
backgroundColor - Background color (Int)
textColor - Text color (Int)
fontSize - Text size in sp (Float)

Default Values

Property

Default Value

ctaDelayUnit

SECONDS

ctaMode

FULL_WIDTH

CTA Button Shapes

The Shape enum defines button corner styles:

Rounded Shape

ctaStyle(
    CtaStyle(
        shape = Shape.SHAPE_ROUND_RECTANGLE // Rounded corners
    )
)

Rectangle Shape

ctaStyle(
    CtaStyle(
        shape = Shape.SHAPE_OVAL // Sharp corners
    )
)

CTA Sizing Modes

FULL_WIDTH

Button spans the full width of the video player:

ctaOptions {
    ctaMode(CtaOption.CtaMode.FULL_WIDTH)
}

COMPACT

Button uses minimal width:

ctaOptions {
    ctaMode(CtaOption.CtaMode.COMPACT)
}

SIZE_TO_FIT

Button sizes dynamically based on content:

ctaOptions {
    ctaMode(CtaOption.CtaMode.SIZE_TO_FIT)
}

CTA Click Handling

CTA click handling is configured in PlayerOption:

val viewOptions = viewOptions {
    playerOptions {
        // Let SDK handle CTA clicks (default)
        sdkHandleCtaButtonClick(true)
        
        // Or handle clicks in your app
        //sdkHandleCtaButtonClick(false)
    }
    ctaOptions {
        ctaDelay(CtaDelay(3f, CtaDelayUnit.SECONDS))
    }
}

// When sdkHandleCtaButtonClick is false, handle clicks:
FireworkSdk.shopping.setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo, product ->
    // Handle CTA button click
    openProductPage(productId)
}

See Shopping Integration for more details on CTA click handling.

Important Notes

CTA buttons only appear on videos that have CTA configuration
Delay timing starts when video begins playing
Percentage-based delays are relative to total video duration
ctaHighlightDelay should be less than ctaDelay for logical UX
Font size in CtaStyle is in sp units (scale-independent pixels)
CTA styling is applied globally to all CTA buttons in the feed
Use sdkHandleCtaButtonClick in PlayerOption to control click behavior
CTA buttons are common in shopping videos and product demonstrations