embed troubleshooting

added a spawnd embed to your page, but the game doesn't start? don't worry, it's usually a quick fix! 🔧

the embed is an iframe: a small window inside your page that loads the game from www.spawnd.gg. to work, it needs two things from your page:

what the embed needs	why	what happens without it
loading the iframe	the game lives on spawnd's servers, not on yours.	the embed area stays empty.
fullscreen	the game starts in fullscreen when the player clicks launch, so it gets the whole screen and the player's full attention.	the embed loads, but the game stays on its paused screen.

most pages allow both by default. but browsers treat content from other sites with care, so security settings on your page can block one of them. here are the most common causes, why they happen, and how to fix them.

tip: when a browser blocks an iframe or a fullscreen request, it usually logs the reason in the developer console. it's a good first place to look!

the embed code was changed

browsers don't let an iframe go fullscreen unless the page allows it. the allowfullscreen attribute in the embed code is how your page says "yes". if it's missing, the browser blocks the request, and the game can't start.

the sandbox attribute does the opposite: it takes features away from the iframe. an empty sandbox="" even stops the iframe from running scripts, and the game needs them to run.

so keep the iframe exactly as you copied it: with allowfullscreen, and without sandbox. watch out for rich text editors, though. some of them change iframes when you paste them, to protect your page from unknown content. TinyMCE, for example, adds sandbox="" to iframes by default. after you save your page, check its HTML to make sure the embed code is still the same.

your site blocks iframes from other sites

a Content-Security-Policy (CSP) header tells the browser which sites your page can load content from. it protects your page from content that you didn't approve. the frame-src part of it lists the sites that can load in an iframe.

if your CSP has no frame-src, the browser uses default-src instead. a common value is default-src 'self', which means "only my own site". so the browser blocks the spawnd iframe, and the embed area stays empty.

to fix it, add spawnd to frame-src:

Content-Security-Policy: default-src 'self'; frame-src 'self' https://www.spawnd.gg

you may have a CSP even if you never wrote one: some security tools set a strict one by default. helmet (Express), for example, sets default-src 'self'. you can add spawnd like this:

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        frameSrc: ["'self'", "https://www.spawnd.gg"],
      },
    },
  }),
);

your site blocks fullscreen

a Permissions-Policy header tells the browser which frames on your page can use powerful features, like fullscreen. it has the final word: if the header doesn't allow spawnd, the allowfullscreen attribute can't change that.

many security guides and plugins suggest values like fullscreen=() (no one can go fullscreen) or fullscreen=(self) (only your own page can). both block the embed, because the spawnd iframe is from another site. to fix it, add spawnd to the list:

Permissions-Policy: fullscreen=(self "https://www.spawnd.gg")

your page runs in a desktop app

desktop apps don't use a regular browser to show web pages. they use a web view: a browser engine built into the app, like Electron, Tauri, Qt WebEngine, or WebView2. in a browser, things like permissions and fullscreen windows are handled for you. in a web view, the app is in charge of them, and each engine has its own defaults.

that's why the embed can work in a browser and not in your app. depending on the engine, your app may need to:

turn fullscreen on. some engines leave it off by default, so that apps only allow it on purpose. with fullscreen off, the request fails and the game can't start.
allow the request. some apps check every permission request, to keep embedded content in check. if your app does, allow fullscreen (and pointer lock, which games use to capture the mouse) for spawnd frames. and make sure the app always answers: a request that never gets an answer waits forever, so the game stays paused and no error shows anywhere.
make its window fullscreen. some engines only control their own area, not the app's window. so fullscreen only fills the web view area, and the app needs to make the window fullscreen too.

here's what each common engine needs:

engine	what your app needs to do
Electron	nothing by default. if your app sets `setPermissionRequestHandler`, allow `fullscreen` and `pointerLock` for spawnd frames, and make sure the handler always calls the callback. if your app sets the handler in more than one place, only the last one counts.
WKWebView (macOS apps)	turn on `isElementFullscreenEnabled`. it's off by default.
Qt WebEngine	turn on `FullScreenSupportEnabled`, call `accept()` in `fullScreenRequested`, and make the window fullscreen.
WebView2 (Windows)	handle `ContainsFullScreenElementChanged` and make the window fullscreen.
Android WebView	override `onShowCustomView` and `onHideCustomView`. without them, the web view tells the page that it doesn't support fullscreen.

Tauri (on macOS and Linux) and WebKitGTK allow fullscreen by default. for any other engine, check its docs for "element fullscreen".

iPhone

on iPhone, Safari only allows fullscreen for videos, not for other page elements like the embed (iPad doesn't have this limit). so the game can't go fullscreen in the embed on an iPhone. we're working on this one, and we'll have a fix for iPhone players soon! 🚀

still stuck? come talk to us on Discord! 😃