Player states
The states and properties that describe what the player is doing
Most integration bugs come from asking the player something before it is in a position to answer. This page describes the states the player moves through and the properties that report them.
Initialization
The player element exists in your DOM before the player behind it is running. Methods called in that window may throw, and properties may return defaults rather than real values — duration is 0 and conversionKey is an empty string until the video has loaded.
The gate is player:ready on the custom element, and iframe:connected on the iframe. Everything else on this page assumes you are past it.
Reading the current state
Prop
Type
alreadyPlayed and paused answer different questions. paused is where the video is right now; alreadyPlayed is whether the viewer ever started it. A video that played and was then paused reports paused: true and alreadyPlayed: true.
Modes the player can be in
Two states are not about playback position but about how the player was started.
Prop
Type
SmartAutoPlay starts the video muted, because browsers refuse to autoplay audio without a user gesture. The player announces the transition with smartautoplay:active, and with smartautoplay:inactive once the video has played with audio — whether the viewer unmuted it or started it themselves.
Conversion state
conversionKey encodes the session, the player and variant, how much has been watched, and which feature variants are active. It is the value you carry into a checkout or a form to tie a conversion back to what the viewer actually saw.
It returns an empty string before the player is ready, which is the most common way it ends up empty in production. See URL conversion params for carrying it across pages.
Reaching a moment in the video
pitch:time fires when playback reaches the pitch time configured for the player in the dashboard — the moment the offer is made. It is the usual trigger for revealing a call to action.
For arbitrary moments, onTime and displayHiddenElements in the methods reference do the same job without hanging a listener on every video:timeupdate.