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

Delay before showing the CTA button after video starts playing.

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

CtaDelay Parameters:

delayValue - Delay amount (Float)
delayUnit - Delay unit (SECONDS or PERCENTAGE)

Valid ranges:

SECONDS - 0 to 10 seconds; out-of-range values fall back to the default of 3 seconds
PERCENTAGE - 0.0 (inclusive) to 1.0 (exclusive), as a fraction of the video duration; out-of-range values fall back to the default of 0.2

Examples:

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

ctaHighlightDelay

Type: CtaDelay Default: 2 seconds

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.SHAPE_ROUND_RECTANGLE,
            backgroundColor = Color.parseColor("#FF6200EE"),
            textColor = Color.WHITE,
            fontSize = 16f
        )
    )
}

CtaStyle Properties:

shape - Button shape (Shape.SHAPE_ROUND_RECTANGLE or Shape.SHAPE_OVAL)
backgroundColor - Background color (@ColorInt)
textColor - Text color (@ColorInt)
fontSize - Text size in sp (Float)

All properties are optional — null properties keep the SDK default.

Default Values

Property

Default Value

ctaDelay

3 seconds (SECONDS) / 0.2 (PERCENTAGE)

ctaHighlightDelay

2 seconds

ctaDelayUnit

SECONDS

ctaMode

FULL_WIDTH

ctaStyle highlight color

#3A86FF

ctaStyle text color

White (#FFFFFF)

ctaStyle font size

14sp

CTA Button Shapes

The Shape enum defines the button shape:

Round Rectangle Shape

ctaStyle(
    CtaStyle(
        shape = Shape.SHAPE_ROUND_RECTANGLE // Rectangle with rounded corners
    )
)

Oval / Pill Shape

ctaStyle(
    CtaStyle(
        shape = Shape.SHAPE_OVAL // Pill-shaped (fully rounded ends)
    )
)

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

See Short Video CTA Customization for more details on CTA click handling.

Important Notes

CTA buttons only appear on videos that have CTA configuration
ctaDelay timing starts when video begins playing
Percentage-based delays are relative to total video duration
ctaHighlightDelay with SECONDS unit counts from the moment the button appears; with PERCENTAGE unit it counts from the video playback start
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