Embedding Games with iframes

Create the Basic iframe Embed

The simplest game embed is a single iframe tag with a source URL pointing to your game. The width and height attributes should match your game's native resolution, and the allow attribute should include the browser features your game needs. A basic embed looks like this in HTML:

<iframe src="https://yourdomain.com/game/" width="960" height="540" allow="fullscreen; gamepad; autoplay" title="Your Game Name"></iframe>

The title attribute is required for accessibility. Screen readers use it to describe the iframe content to visually impaired users, and accessibility audit tools flag iframes without titles as violations. Set it to your game's name.

The allow attribute controls which browser APIs the embedded game can access. Common permissions for games include fullscreen (lets the game request fullscreen mode via the Fullscreen API), gamepad (lets the game read gamepad input), and autoplay (lets the game play audio without requiring a user interaction on the parent page, though most browsers still require interaction within the iframe itself). Only include permissions your game actually uses, as unnecessary permissions weaken the security posture.

If you do not set explicit width and height on the iframe, it defaults to 300x150 pixels, which is unusable for any game. Always set dimensions that match your game's aspect ratio. For games that adapt to any container size, the specific dimensions matter less, but they should still be large enough for comfortable play, typically at least 800 pixels wide for desktop and full viewport width on mobile.

Make the Embed Responsive

A fixed-size iframe breaks on mobile devices and narrow browser windows. To make the embed responsive, wrap the iframe in a container element and use CSS to maintain the correct aspect ratio while scaling to fit the available width.

The modern approach uses the CSS aspect-ratio property. Set the container to width: 100%; aspect-ratio: 16/9; (or whatever ratio matches your game) and set the iframe inside to width: 100%; height: 100%; border: none;. This keeps the game at the correct proportions on any screen size without JavaScript.

The older, more compatible approach uses the padding-bottom technique. Set the container's position: relative; padding-bottom: 56.25%; (for 16:9) or 75% (for 4:3), and position the iframe absolutely inside it with position: absolute; top: 0; left: 0; width: 100%; height: 100%;. This works in all browsers, including older ones that do not support aspect-ratio.

Consider adding a maximum width to the container so the game does not stretch uncomfortably large on wide monitors. A max-width: 1200px; on the container, combined with margin: 0 auto; for centering, keeps the game at a comfortable play size on desktops while remaining responsive on smaller screens.

Your game itself must handle different viewport sizes gracefully. When the iframe container resizes, the game canvas inside should detect the new dimensions and adjust its rendering resolution, UI layout, and input hit areas accordingly. Listen for the resize event on the window object inside the iframe and update your canvas size in response.

Configure Cross-Origin Headers

When your game is embedded on a different domain, browser security policies restrict what the embedded content can do and what the parent page can access. These restrictions are intentional and should not be circumvented, but you do need to configure certain headers for the embed to function correctly.

Set X-Frame-Options to ALLOWALL or remove it entirely if you want your game to be embeddable on any site. If you want to restrict embedding to specific domains, use the Content-Security-Policy: frame-ancestors directive instead, which supports multiple allowed origins: Content-Security-Policy: frame-ancestors https://trusted-site.com https://another-site.com. If you do not set either header, most browsers default to allowing embedding, but some CDN configurations add a restrictive X-Frame-Options: SAMEORIGIN header by default that blocks cross-origin embedding.

CORS headers (Access-Control-Allow-Origin) are needed on your game's asset files if the game loads resources via JavaScript fetch or XMLHttpRequest. This is separate from the framing headers. Set Access-Control-Allow-Origin: * on your CDN or server for game asset files like JavaScript bundles, textures, audio, and WebAssembly modules. The game's HTML page itself does not need CORS headers for basic iframe embedding, only the assets it loads dynamically.

The embedding site can add a sandbox attribute to the iframe for additional security. Common sandbox values include allow-scripts (required for any game), allow-same-origin (required for games that use localStorage or cookies), and allow-popups (if the game opens external links). If you provide an embed snippet for others to use, include recommended sandbox values that allow your game to function while maintaining reasonable security.

Handle Communication Between Game and Host

The postMessage API is the standard way for an embedded game to communicate with the parent page. The game sends messages to the parent with window.parent.postMessage(data, targetOrigin), and the parent listens for messages with window.addEventListener("message", handler). The reverse works too, with the parent posting messages to the iframe's content window.

Common use cases for postMessage in game embeds include ad coordination (the game tells the parent when to show an ad break), pause and resume (the parent tells the game to pause when the user scrolls away or switches tabs), score reporting (the game sends the final score to the parent for display on a leaderboard), and loading progress (the game reports its loading percentage so the parent page can show a progress bar outside the iframe).

Always validate the origin of incoming messages. When your game receives a postMessage event, check event.origin against a list of trusted parent domains before acting on the message. This prevents malicious pages from sending fake commands to your game. Similarly, when sending messages to the parent, specify the target origin rather than using the wildcard "*" if you are sending sensitive data, though for most game events the data is not sensitive and a wildcard is acceptable.

Define a clear message protocol if you expect your game to be embedded on multiple sites. Use a consistent format like {"type": "gameEvent", "event": "levelComplete", "data": {"level": 5, "score": 12400}} so that embedding sites can parse your messages predictably. Document this protocol in your embed instructions so developers integrating your game know what events to listen for and what messages they can send.

Provide an Embed Code for Distribution

If you want others to embed your game on their sites, provide a ready-to-copy embed code snippet on your game page. The snippet should include the iframe tag with recommended dimensions, all necessary allow attributes, a title attribute, and a link to the canonical game page for players who want to visit the full version.

A complete embed snippet might include a wrapper div with responsive CSS inline, the iframe element, and a text link below it. This gives the embedding site a fully functional, responsive game embed with a single copy-paste, without requiring them to write any CSS or understand iframe configuration.

Consider also providing a JavaScript embed option that creates the iframe dynamically. A JavaScript embed gives you more control over the player experience, because the script can detect the container size, set optimal dimensions, handle responsive resizing, and implement lazy loading (only creating the iframe when the player scrolls it into view or clicks a play button). The script approach also lets you update the embed behavior across all sites simultaneously by updating the hosted script, without requiring each site to change their embed code.

Track embed usage by adding a query parameter to the iframe source URL that identifies the embedding site. This does not affect gameplay but lets you measure how much traffic each embedding site drives, which is valuable information for understanding your distribution reach and identifying your most valuable embed partners.