Troubleshooting
Avoid the traps that fail quietly
Most of these fail without an error. The player loads, the page looks right, and one thing silently does not happen — which is why they are collected here rather than left as asides on the pages where they apply.
play() does nothing
Browsers refuse to autoplay video with audio until the viewer has interacted with the page. When they do, play() does not start playback, and nothing appears to happen.
Call it from a real click or tap, confirm it with video:play, or turn on SmartAutoPlay in the dashboard, which starts the video muted and unmutes on the first interaction.
Waiting for an event that never fires
player:ready fires only on the custom element. iframe:connected fires only on the iframe. Code that waits for the wrong one waits forever, with no error to point at.
If you support both embeds on the same page, listen for both.
CSS variables do nothing on the iframe
CSS variables stop at the origin boundary, and so do fluid and pauseonetouch. The browser is enforcing cross-origin isolation, so there is no workaround — restyling requires the custom element embed. See Element vs iframe.
fluid crops the video or hides the CTAs
fluid makes the player fill its container. If that container has a fixed height and the player also has headlines or calls-to-action, they compete for the same space: the video gets cropped, or the CTAs land outside the visible area.
Constrain the width and let aspect-ratio set the height.
<script> in a headline never runs
A <script> tag written inside headline HTML is inert. The custom JS field is the only execution path for headline code.
Headline code does not run under a CSP
If your site sends a Content Security Policy, the player tag needs the same nonce your other trusted scripts carry. Allowing scripts.converteai.net is not enough on its own.
Without the nonce, the player still loads and the headline still shows its text and styling — only your code is skipped, with a Content Security Policy message in the console. And on the iframe embed the nonce is deliberately not forwarded, so headline code never runs there under a policy. Full setup in Headline JS.
conversionKey is empty
It returns an empty string until the player is ready. Read it after player:ready or iframe:connected, not on page load. See URL conversion params.
duration is 0
The video length is unknown until the video loads, and 0 is what you get in the meantime. It is not a zero-length video.