Start in three steps
- Create a free account (no invite needed). You get a licence key and a public id at once. No need to list domains first: the first site your code loads on is added to your account by itself.
- Pick an item in the catalog and try it on its page.
- Paste the code into your page. Every item page, and Get code in your console, gives you the code with your public id:
<script src="https://useiframe.com/f.js" data-account="YOUR_PUBLIC_ID" async></script> <div data-iframe="geo-sleuth" data-ratio="4:3"></div>
Open the page: the item loads, and the site, the page and the place show up under Sites in your console.
The code
Put the <script> on a page once, and one <div data-iframe> wherever an item should appear:
<script src="https://useiframe.com/f.js" data-account="YOUR_PUBLIC_ID" async></script> <div data-iframe="geo-sleuth" data-slot="main"></div> <div data-iframe="rarest" data-slot="sidebar" data-launch="click" data-ratio="4:5"> <button type="button">▶ Play Rarest</button> </div>
| Attribute | What it does |
|---|---|
data-account | Your public id (starts with pk_). Not a secret; it belongs in your pages. Goes on the <script>. |
data-iframe | What to show: the item’s slug (the last part of its page address, like geo-sleuth). |
data-slot | Optional stable name for the place, like main or sidebar. Without it, places are named “item + number”; with it, statistics and switches stay with the place even if you change the item in the page later. |
data-launch | auto (default: loads at once) or click: shows whatever you put inside the div (an image, a button) until the visitor clicks. Use it when a page carries several items. window.iframeApp.start(el) starts one from your own code. |
data-ratio | Width:height of the frame, like 16:9 (default), 4:3 or 9:16; auto lets the item set its height. Each item page shows the recommended shape. |
The loader is small (under 3 KB compressed), loads asynchronously and never breaks the rest of your page if something goes wrong. Items run on a separate content domain and cannot touch your page’s cookies or scripts.
Putting it on your site
One rule: the code has to sit in your own page. The <script> once per page (adding it twice is harmless: it runs once), each <div> where an item should appear.
- Plain HTML, static sites
- Put the
<script>in the<head>or before</body>(it loads asynchronously), and the<div>where the item goes. - WordPress (self-hosted)
- Add a Custom HTML block to the post or page and paste the whole code. Only administrators and editors can save content with a
<script>(on a multisite network, only super admins); for other roles the script is stripped on save. Then have an administrator put the script in the theme footer, or add it site-wide once with a code snippets plugin, and keep only the div in posts. - WordPress.com
- Only plans that allow plugins keep a
<script>; other plans strip iframes too, so it can’t be used there for now. - Blogger
- Switch the post editor to HTML view before pasting. Or add an HTML/JavaScript gadget under Layout with the script once for the whole blog, and keep only the div in posts.
- React, Next.js, Vue and other single-page apps
- Add the script once in the root layout (or
index.html) and write the div in your components. The loader notices new divs, so items on pages reached by client-side navigation load too, and places withoutdata-slotkeep their names when you come back to a page. In Next.js:
// app/layout.jsx: once import Script from 'next/script'; <Script src="https://useiframe.com/f.js" data-account="YOUR_PUBLIC_ID" strategy="afterInteractive" /> // any page or component <div data-iframe="geo-sleuth" data-slot="main" data-ratio="4:3" />
- Keep the default
afterInteractive, notbeforeInteractive, so the framework never finds a div that has already changed when it takes over the page. - Don’t put framework-rendered content inside the div: when a click-to-start place starts, that content is replaced by the frame, and later updates from the framework can fail. For your own start button, call
window.iframeApp.start(el)in its click handler. - If your app sets
<link rel="canonical">, update it on every route change: page addresses follow the canonical link.
No scripts allowed, but iframes or links are: every item also comes as a plain iframe (switch the code box on its page to “Plain iframe”, or see Get code in your console), for places that strip <script> but keep iframes: many CMS editors and forums, Moodle, Canvas and other teaching platforms. Link-only embeds (Notion, Google Sites, Wix “Embed a site”) take the embed URL https://useiframe.com/v/YOUR_PUBLIC_ID/item-slug. Keep the iframe’s referrerpolicy attribute as it is: it tells us the page, so statistics and switching keep working. With link embeds the platform may report its own domain (for example notion.site); if the frame says the embed isn’t switched on for a domain, add that domain.
Drag-and-drop site builders: some builders’ “embed HTML” widgets run your code inside a frame of their own, so we see that frame’s address instead of your page. Use the plain iframe or embed URL above instead (many builders have an “embed a site / URL” element), or the builder’s “code in the head / footer of every page” setting for the script.
Sites with a Content Security Policy (CSP): allow the content domain, for example:
script-src 'self' https://useiframe.com; frame-src https://useiframe.com; img-src 'self' https://useiframe.com;
Item not showing?
Check in this order:
- The frame says “This embed isn’t switched on for …”: in your console, open Sites and add that domain (testing on
localhostneeds nothing). - The frame says the embed couldn’t tell which page it is on: the iframe’s
referrerpolicywas changed, or a browser extension blocks the referrer; copy the code again, or use the script version. - The frame says the code is missing its account, or the account isn’t active: copy the code again from Get code in your console and check that
data-accountis your public id; if your licence has expired, contact us to renew it. - No frame at all: check the page source still has the script (some editors strip it, see above), that a site builder hasn’t put the code in a frame of its own, that your CSP allows the content domain, and the browser’s developer console for errors.
- The frame shows but the item never finishes loading: some items are large; give it a moment, or try another browser or network. You can also switch the place to another item in your console.
- The place isn’t in your console: it appears once the page has been opened (or a click-to-start place has been seen); refresh the console. If it still isn’t there, it is one of the cases above.
Live embeds: switch items without editing pages
The first time a place is opened, it is registered as an embed (one per page address and place name). The console sorts them by site → page → embed: open a site under Sites and every page lists its embeds. There you can:
- switch selected places to another item;
- replace one item everywhere at once (say a game was retired and you want a similar one);
- go back to the item written in the page;
- undo any change from the Changes list.
Changes apply on the next load; the page itself stays untouched. When an item is taken down for a while, its stand-in shows where one is set, and you can always switch it yourself.
How a page is identified: its same-host <link rel="canonical"> if it has one, else its address, without the # part and without tracking parameters (utm_*, gclid, fbclid, ref), so one page is never counted as many.
Allowed domains
Your code only works on the domains in your account; someone copying your code to their site gets nothing. The rules:
example.comcovers every subdomain too (www.,blog.…);- skipped them when you signed up? While the list is empty, the first site your code loads on is added automatically (without
www.); add further sites yourself. If that first load happened on a preview domain, that is the one recorded: fix it under Sites; - testing on your own computer (
localhost,127.0.0.1) always works, nothing to add; - add or remove one under Sites in your console, or edit them all at once under Account, up to 20.
Statistics
The console counts loads per place per day (an item actually opened). Places with data-launch="click" also count impressions (seen but not clicked yet). The overview shows 7- and 30-day totals, the numbers of each site and your busiest items and pages; a site’s page lists every page and every place on it with its 7-day loads and when it was last seen. Places not seen for 30 days are marked idle, never deleted.
With the earnsite engine
earnsite is the companion site engine. Put your licence key in its LICENSE_KEY setting: the engine picks games and builds pages through your account, and items load from your own site’s play. subdomain, so visitors only ever see your domain. Those pages show up under Sites like any other, with the same one-click switching. One licence covers 3 engine installs by default.
For developers: the API
To pick items or manage embeds from code, call the API. Everything is JSON; errors look like {"error":{"code","message"}}.
| Endpoint | What it does |
|---|---|
GET /api/v1/catalog | The public catalog, no sign-in: name, category, tags, shape, summary, cover and embed code of every item. |
GET /api/v1/account | Your public id and allowed domains; PUT with {"allowed_domains":[…]} changes them. |
GET /api/v1/embeds | Your embeds, filtered by host, item, status, paged with cursor. |
POST /api/v1/embeds/retarget | Switch items: {"filter":{…},"to":{"kind":"item","value":"slug"}}; add "dry_run":true to preview what changes. |
POST /api/v1/embeds/unpin | Back to the item written in the page. |
POST /api/v1/embeds/rollback | Undo one change by its batch_id. |
GET /api/v1/embeds/stats | Load statistics grouped by embed, item, page or site. |
Everything except the catalog needs two headers: Authorization: Bearer <licence key> and X-Install-Id: inst_ plus 24 letters or digits (one fixed value per server or app; it counts as an engine install). Keep the key on your server — never in a web page.
Let your AI do it (MCP)
If you use Claude or another AI tool that speaks MCP, connect your account: it can pick items, write the code, list and switch your embeds, read statistics and send requests.
- URL:
https://www.iframe.app/mcp/site - Header:
Authorization: Bearer <licence key>
{ "mcpServers": { "iframe-app": { "type": "http", "url": "https://www.iframe.app/mcp/site", "headers": { "Authorization": "Bearer gh_live_…" } } } }
Tools: catalog_search, item_get, embed_code, account_get, domains_set, embeds_list, embeds_switch (dry_run first), embeds_unpin, embeds_undo, changes_list, stats, request_item, suggest_game, my_submissions. They only reach your own account. Keep the key on your own device.
Beta limits
- The beta is free, no invite needed;
- up to 3 engine installs per account (counted over 30 days);
- up to 2,000 new embeds per account per hour (normal use never gets close);
- API: 600 requests per minute per account.
Need more? Tell us from the Submit page of your console.
FAQ
- Will it slow my page down?
- No. The script is small and asynchronous, and items run in their own frame. With several items on one page,
data-launch="click"keeps it quick. - Do items show ads?
- Items made by iframe.app have none. Items marked “publisher ads inside” come from a game publisher that shows its own ads in the game (usually a short one before play); that revenue goes to the publisher. Tick “No ads” in the catalog to hide them.
- Does it work on phones?
- Items marked “phones” in the catalog are tested on phones. Portrait shapes (like
9:16) work best there. - What if an item breaks?
- Every item is checked daily and broken ones are taken down; where a stand-in is set, it shows instead. You can also switch it with one click in your console.
- Can I change an item or remove its branding?
- No, items are shown as they are. See the terms.
- Lost or leaked key?
- Leaked: replace it under Account in your console (you type the current key once more). Lost: contact us and we will issue a new one.
- Do you collect data about my visitors?
- No personal data: only page addresses, place names and load counts. See privacy.