How to Prepare an HTML5 Game to Run Inside a Sandboxed iframe

A build that works when you open its index.html directly can behave differently once a portal puts it in an iframe. The portal decides which permissions the frame gets, and the game usually has no say. Testing inside a sandboxed frame before you submit catches most of these problems early.

What a typical portal frame allows

PlayKovo's player frame, for example, runs games with the sandbox permissions allow-scripts, allow-same-origin, allow-forms and allow-pointer-lock, and an allow list of fullscreen, autoplay, gamepad and pointer-lock. Pop-ups and native dialogs are off by default and only enabled for games that were approved for them. Other portals choose their own list, so treat this as an example of how restrictive a frame can be, not as a universal rule.

Things that commonly break

• window.open, alert, confirm and prompt calls. In a frame without pop-up or modal permission they do nothing, so a game that waits on a confirm() answer can stall. Use an in-game dialog instead.
• Fullscreen from your own button. Call the Fullscreen API only from a user click, and keep a working in-game state if the request is refused.
• Audio that starts on load. Browsers block autoplay until the first user gesture, so start music after the first tap or key press.
• Mouse-look games. Pointer lock needs a click first and may be denied; show a clear prompt and handle the pointerlockerror event.
• Reading window.top or window.parent. Cross-origin frames throw an error when you touch them, so wrap any such access in try/catch or remove it.
• localStorage or cookies. Some embedding contexts block storage. Wrap reads and writes in try/catch and let the game run without saves.

Keyboard focus inside a frame

Key presses only reach the game while the iframe has focus. If a player clicks elsewhere on the host page, movement keys stop working with no visible change. Focus the canvas on the first click and again when the window regains focus, and release held keys on blur so a character does not keep walking after the player switches tabs.

Frame size is not your decision

Partners often use small or oddly shaped frames, including narrow portrait widgets. Make the canvas scale to its container, avoid minimum widths, and check that the start screen and the first level are usable at roughly 300 by 500 and at 640 by 360. Test both orientations if your submission says the game supports both.

A short test routine

• Put your build in a test page inside an iframe with the sandbox attribute set to allow-scripts allow-same-origin allow-forms allow-pointer-lock.
• Load it, click once, and confirm sound, input and rendering all work.
• Resize the frame to a small portrait and a small landscape size and replay the first minute.
• Click outside the frame, click back in, and check that keyboard input returns.
• Block storage in the browser settings and reload to confirm the game still starts.

Finish with the playtesting checklist and read the submission rules before you upload. If you also plan to ship ads, the guide on rewarded versus interstitial ads covers what to test there.