Call to Action (CTA)
@experimental status. It is stable enough to use, but API details may change. Follow the player changelog.A CTA is a call to action displayed over a video. Use it for subscriptions, links, timeline buttons, or lead forms. Configure CTAs in playlist[].cta when you create a player. You can also use setPlaylistItemOptions.
You can configure a simple CTA at the end of a video without code. Use a player template.
Display types
The type field defaults to overlay:
type | Behavior |
|---|---|
overlay | Covers the player and pauses playback |
popup | Shows a pop-up panel without pausing playback |
panel | Shows a transparent panel without pausing playback |
banner | Shows a banner with an image or link |
buttons | Shows buttons over the frame. A click can move through the playlist or timeline |
leadgen | Collects user data and sends it to your URL |
Quick start: overlay
function onKinescopeIframeAPIReady(playerFactory) {
playerFactory
.create('player', {
url: 'https://kinescope.io/VIDEO_ID',
playlist: [
{
cta: [
{
id: 'subscribe-cta',
type: 'overlay', // Optional: this is the default value
title: 'Did you enjoy the video?',
description: 'Subscribe to the channel so you do not miss new releases.',
skippable: true,
button: { text: 'Subscribe' },
trigger: { percentages: [50] },
},
],
},
],
})
.then((player) => {
player.on(player.Events.CallAction, (event) => {
// event.data.id === 'subscribe-cta'
window.open('https://example.com/subscribe', '_blank')
player.closeCTA()
})
})
}
When a user clicks the CTA button, the CallAction event fires. Handle your action and close the screen with closeCTA(). Playback resumes after an overlay closes.
If you set button.url, the player can open the link. You still receive CallAction, which is useful for analytics.
Common fields and trigger
| Field | Type | Description |
|---|---|---|
id | string | Identifier included in CallAction |
type | See display types | Display mode. The default is overlay |
trigger.percentages | number[] | Playback percentages, such as [50, 100] |
trigger.timePoints | number[] | Time points in seconds, such as [60, 600] |
trigger.pause | boolean | Shows the CTA when playback pauses |
Set at least one trigger: percentages, timePoints, or pause. You can combine them.
overlay, popup, and panel
Common fields:
| Field | Type | Description |
|---|---|---|
title | string | Title |
description | string | Description |
skippable | boolean | Lets the user close or skip the CTA |
button.text | string | Button label |
button.style | CSSProperties | Button styles |
button.url | string | URL opened on click |
Additional fields:
| Field | Types | Description |
|---|---|---|
link | overlay | Second link: { text, url, style? } |
poster | overlay | Poster or image on the CTA screen |
position | popup, panel | 'top' | 'bottom' |
Example of a popup displayed on pause:
{
id: 'pause-offer',
type: 'popup',
position: 'bottom',
title: 'Continue later?',
button: { text: 'Save progress', url: 'https://example.com/save' },
skippable: true,
trigger: { pause: true },
}
banner
| Field | Type | Description |
|---|---|---|
title, description, skippable, button | Same as overlay | Main fields |
url | string | Banner link |
image | string | poster object | Image |
position | string | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' |
variant | 'vertical' | 'horizontal' | Layout |
style | CSSProperties | Container styles |
buttons
This type shows buttons over the frame. Playback continues by default. Set pause on the item to pause it.
{
id: 'hotspots',
type: 'buttons',
trigger: { timePoints: [30] },
list: [
{
id: 'go-chapter-2',
title: 'Chapter 2',
position: { x: 0.2, y: 0.5 }, // Relative to the frame, from 0 to 1
goTo: { playlistItem: 0, time: 120 },
},
],
}
| Field | Description |
|---|---|
list[].id | Button ID |
list[].title | Label |
list[].position | { x, y } relative to the frame size |
list[].goTo | number for time in seconds, or { playlistItem, time? } |
list[].style | Button styles |
pause | Pauses playback when the CTA appears |
leadgen
This type collects user data. The player sends the fields to your url with a POST request.
| Field | Type | Description |
|---|---|---|
url | string | Form submission endpoint |
fields | Array<'name' | 'email' | 'company'> | Fields to show |
privacyPolicyUrl | string | Privacy policy link |
lifetime | number | How long this id counts as submitted. The default is 30 days |
skippable | boolean | Lets the user close the form without submitting it |
trigger | — | Same as other CTA types |
{
id: 'lead-end',
type: 'leadgen',
url: 'https://example.com/api/leads',
fields: ['name', 'email'],
privacyPolicyUrl: 'https://example.com/privacy',
skippable: true,
trigger: { percentages: [100] },
}
Next steps
- Control the player — use
closeCTAandCallAction - Advertising — configure VAST and IMA through the API
- Playlists
- CTA in player templates