Embed & Iframe Best Practices
Build accessible, performant media embeds with correct player URLs, permissions, dimensions, loading, and crawl behavior.
An iframe is a player container, not a complete discovery strategy. The surrounding watch page still needs its own context, canonical URL, and metadata.
| Attribute or practice | Recommendation |
|---|---|
| title | Give every iframe a concise, specific accessible label, such as “Video: Brand workflow walkthrough.” |
| width / height / aspect-ratio | Reserve the correct player dimensions to avoid layout shift and make the iframe responsive. |
| loading | Use lazy for below-the-fold embeds. Keep a primary above-the-fold player eager when it is central to the page. |
| allow | Grant only required capabilities, such as autoplay, fullscreen, picture-in-picture, or encrypted-media. Camera and microphone access should be limited to recording experiences that need them. |
| allowfullscreen | Include when viewers should be able to use fullscreen playback. |
| referrerpolicy | Use a deliberate policy such as strict-origin-when-cross-origin; do not leak sensitive URLs. |
| sandbox | Add restrictions only after testing the player. An overly restrictive sandbox can break scripts, storage, downloads, or playback. |
| Canonical page | Canonicalize the rich watch page, not a thin embed endpoint. If embed endpoints create duplicate indexable pages, consider an appropriate noindex policy without blocking playback assets. |
| Crawler access | Do not block the player, media bytes, poster, captions, or required scripts when media discovery is desired. |
<iframe
src="https://player.example.com/embed/brand-video"
title="Video: How to Build a Brand-Compliant Video Workflow"
width="1280"
height="720"
style="width: 100%; height: auto; aspect-ratio: 16 / 9"
loading="lazy"
allow="autoplay; fullscreen; picture-in-picture"
allowfullscreen
referrerpolicy="strict-origin-when-cross-origin"
></iframe>Remember the three different URLs: the watch page is the canonical destination, the player belongs in the iframe src and embedUrl, and the media bytes belong in contentUrl. They should not be used interchangeably.
Watch page
Player
Media bytes
<iframe src="https://player.example.com/embed/brand-video" title="Brand workflow video"></iframe>