Guides
Start typing to search…

Enabling In-Page High-Performance Demos

Offer the full gameplay experience directly on your site by enabling Cross-Origin Isolation for multithreaded demos.

This is an advanced guide for site administrators who wish to enable the best possible in-page gameplay experience for high-performance demos.

1. Our Embeds Always Work

Let's start with the most important information: you do not need any special configuration to use spawnd embeds. Our priority is ensuring the user can always play.
Our embeds work "out-of-the-box" and include smart logic to handle different types of games:

  • For most demos: The game runs instantly inside the iframe on your site.
  • For High-Performance (multithreaded) demos: The spawnd embed is intelligent. It automatically detects if your site (the parent environment) has the necessary security features enabled.
    • If it doesn't (the most common case), the game will not break. The embed understands this limitation and, instead of trying to run, displays a poster and a "Play" button.
    • Upon clicking, it bypasses the limitation by opening the game page in a new tab within our own prepared spawnd.gg environment, guaranteeing the user can play.
      The ability to play is never lost. This guide is for administrators who want to "upgrade" this experience and make it so that even high-performance demos run directly on their site.

2. The Upgrade: The "In-Page" High-Performance Experience

This guide is for site administrators who want to offer the most fluid experience possible, allowing all demos to run directly within your site's iframe without needing to open a new tab.

The Technical Context (Why is this necessary?)

By default, JavaScript (the language that runs in all browsers) executes tasks on a single thread. This is fine for most websites, but modern, complex games (especially those compiled to WebAssembly/WASM) require desktop-level performance. This demands multithreading—the ability to run multiple heavy tasks in parallel.
To enable this in the browser, developers use an advanced technology called SharedArrayBuffer. Think of it as a shared region of memory that multiple "Workers" (the browser's threads) can access at the same time. This technique is what allows the demo to run incredibly fast.

The Browser Security Requirement

For robust security reasons, modern browsers treat SharedArrayBuffer as a powerful feature. It is only "unlocked" and enabled if the main page (your website) is running in a "special security mode."
This mode is what we call "Cross-Origin Isolation."
Enabling this mode is the only way to signal to the browser that your page is safe to "unlock" SharedArrayBuffer and allow the high-performance demo to run directly in your iframe.

3. The Technical Requirement: Cross-Origin Isolation (COI)

Activating Cross-Origin Isolation is done simply: you just need to add two HTTP headers to the response from your server (the page that is embedding the iframe).
These headers are:

  1. Cross-Origin-Opener-Policy (COOP):
    • Value: same-origin
    • What it does: Isolates your page's browsing context, preventing other windows from interacting with it, which protects it.
  2. Cross-Origin-Embedder-Policy (COEP):
    • Value: require-corp
    • What it does: Requires that all resources (scripts, images, iframes) loaded by your page also explicitly allow themselves to be embedded in this secure mode.

Required Configuration on Your Server:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

4. Important: What to Consider Before Enabling

Enabling COEP: require-corp is a restrictive security policy. It forces the browser to verify that all resources on your page (scripts, iframes, pixels, images) also permit isolation before loading them.What does this mean in practice?

  • Common Side Effect: Third-party scripts, such as ads or social media widgets, may stop loading if their provider (the third party) has not configured them for COI.
  • This Isn't a Rule (and there are solutions): This does not mean all third-party scripts will break. Modern platforms that follow current web standards work perfectly.
    • Positive Example: Observability tools like Sentry, for instance, are already served with the correct (Cross-Origin-Resource-Policy) headers and will continue to function normally in an isolated environment.

How to Make My Own Scripts and Media Work?

If you notice that other resources (like images from a CDN, fonts, or your own scripts) stop loading, there is a standard path to fix them. You need to explicitly "opt-in" to allow them to be loaded in your HTML.
The "common path" involves two steps:

  1. In your HTML: Add the crossorigin="anonymous" attribute to the tags loading the resource (script, image, video, etc.).
<script src="https://cdn.my-script.com/script.js" crossorigin="anonymous"></script>    
<img src="https://cdn.my-image.com/img.png" crossorigin="anonymous">
  1. On the Resource's Server (e.g., your CDN, S3, etc.): The server hosting script.js or img.png must send the response header: Cross-Origin-Resource-Policy: cross-origin.
    If the third-party resource (like an ad script) doesn't give you the option to do both of these, it is unfortunately not compatible with COI.

The Simplest Strategy: Granular Control

Since it can be complex to audit and fix all third-party scripts (especially ads, which you don't control), the most common and safest approach remains:Activate the COOP/COEP headers only on the specific page URL where the high-performance demo is embedded (e.g., /game-article).
With this strategy, the rest of your site (homepage, other articles) continues to function perfectly. Only the specific "game page" will have isolation active, allowing the in-page experience while minimizing the impact on other scripts.

  • Remember: spawnd Always Works: If all this seems too complex, that's fine! If you do nothing, the spawnd embed is smart enough to detect the lack of isolation and will revert to the standard mode (opening in a new tab), ensuring the user can always play.

5. ⚙️ How to Implement (Practical Guides)

Below are configuration examples for common platforms, focusing on the per-page/route strategy (the safest).

NGINX

Add a location block for the specific path in your site's configuration file (e.g., mysite.conf).

# Apply headers only for this specific article
location /game-article {
    add_header Cross-Origin-Opener-Policy "same-origin" always;
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
}

Apache

Add the following to your root .htaccess file.

# Activate headers only for the /game-article URL
SetEnvIf Request_URI ^/game-article$ COI_PAGE
Header set Cross-Origin-Opener-Policy "same-origin" env=COI_PAGE
Header set Cross-Origin-Embedder-Policy "require-corp" env=COI_PAGE

Netlify

Add the path rule to your _headers file in your publish directory.

# Add headers only for /game-article
/game-article
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

Vercel

Add the headers rule to your vercel.json file, specifying the source.

{
  "headers": [
    {
      "source": "/game-article",
      "headers": [
        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
      ]
    }
  ]
}

WordPress

This can be done by adding code to your (child) theme's functions.php file or by using a header management plugin.

// Add headers only for the page with the 'slug' (URL) 'game-article'
add_action('send_headers', function() {
    if (is_page('game-article')) {
        header('Cross-Origin-Opener-Policy: same-origin');
        header('Cross-Origin-Embedder-Policy: require-corp');
    }
});

6. How to Verify the Upgrade Worked

After applying the configuration and clearing all caches (your browser, your site/plugin, and your CDN, if you use one), you can verify it worked.

The Quick Test (Visual)

  1. Visit the page on your site with the high-performance embed.
    1. Success: 🟢 The game loads and is playable directly inside the iframe.
    2. No Success: 🔴 The embed still shows the poster and the "Play" button for opening in a new tab.

The Technical Check (Console)

If the visual test fails, your configuration is likely not active.

  1. On your page, open the Developer Tools (F12 or Ctrl+Shift+I).
  2. Go to the "Console" tab.
  3. Type the command: window.crossOriginIsolated and press Enter.
    1. Result true: 🟢 Success! Isolation is active. If the game still doesn't run, the issue is elsewhere (but your COI config is correct).
    2. Result false: 🔴 Configuration Inactive. The browser did not receive the headers. The most likely cause is caching. Clear all caches again. If it still fails, double-check your configuration in Section 5.

Updated about 9 hours ago