使用文档

把游戏、工具和 AI 工具放进你的网页，需要知道的都在这一页。

三步上手

用邀请码加入（没有邀请码可以在同一页申请），马上拿到授权密钥和公开 ID，填上你要嵌入的域名。
在目录里挑一个条目，点进去先试玩。
把代码贴进你的网页。每个条目页、控制台的「取代码」都能复制到带你公开 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>

打开页面，条目就会加载，这个位置会出现在控制台的「嵌入位」里。

代码怎么写

一个页面只需要放一次 <script>，每个要显示条目的位置放一个 <div data-iframe>：

<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">▶ 开始玩 Rarest</button>
</div>

属性	作用
`data-account`	你的公开 ID（`pk_` 开头）。不是秘密，可以放心写在网页里。写在 `<script>` 上。
`data-iframe`	要显示什么：条目的 slug（条目页地址里的那一段，比如 `geo-sleuth`）。
`data-slot`	可选，给这个位置起个固定的名字，比如 `main`、`sidebar`。不写时按「条目 + 第几个」自动命名；写了以后就算你在网页里换了条目，数据和切换记录也会跟着这个位置走。
`data-launch`	`auto`（默认，马上加载）或 `click`：先显示 div 里你放的内容（图片、按钮），访客点了才加载。一个页面放好几个条目时用它，页面更快。也可以用 `window.iframeApp.start(el)` 自己触发。
`data-ratio`	框的宽:高，比如 `16:9`（默认）、`4:3`、`9:16`；`auto` 表示由条目自己决定高度。条目页上写着每个条目推荐的比例。

加载脚本很小（压缩后不到 3 KB），异步加载，不会拖慢你的页面；它出错也不会影响你页面上的其他代码。条目运行在独立的内容域名上，碰不到你页面的 cookie 和脚本。

放到你的网站上

原则只有一条：代码要直接放在你自己的页面里。<script> 每页一次（放了多次也只运行一次），<div> 放在要显示的位置。

纯 HTML / 静态网站: <script> 放在 <head> 里或 </body> 前面都行（它是异步加载的），<div> 放在要显示的位置。
WordPress（自己安装的）: 在文章或页面里加一个「自定义 HTML」区块，把整段代码贴进去。只有管理员和编辑能保存带 <script> 的内容（多站点网络里只有超级管理员），其他角色保存时 script 会被去掉：这时请管理员把 script 放进主题页脚，或用代码片段插件全站加一次，文章里只放 div。
WordPress.com: 只有支持插件的套餐会保留 <script>，其他套餐会把它去掉，代码就不会生效。
Blogger: 编辑文章时切换到「HTML 视图」再贴代码；也可以在「布局」里加一个「HTML/JavaScript」小工具，把 script 全站放一次，文章里只放 div。
React、Next.js、Vue 等单页应用: script 在根布局（或 index.html）里放一次，div 直接写在组件里。脚本会留意页面上新出现的 div，切换路由后新页面里的条目也会加载；没写 data-slot 的位置，回到同一页时还是原来的名字。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" />

用默认的 afterInteractive，不要用 beforeInteractive，免得框架接管页面时发现 div 已经被改过。
div 里面不要放由框架渲染的内容：点击启动时这些内容会被换成框，框架之后再去更新它们可能出错。想用自己的「开始」按钮，就在按钮的点击事件里调用 window.iframeApp.start(el)。
如果应用写了 <link rel="canonical">，要让它跟着路由更新，因为页面地址按 canonical 认。

拖拽式建站工具：有些工具的「嵌入 HTML」组件会把你的代码放进它自己的框（iframe）里运行。那样我们看到的是那个框的地址，不是你的页面，允许域名的检查过不了，条目不会加载。请改用工具里「在所有页面头部 / 底部加代码」之类的设置放 script，div 放在能直接写 HTML 的地方；工具不支持的话暂时就用不了。

网站设置了内容安全策略（CSP）：要放行内容域名，比如：

script-src 'self' https://useiframe.com;
frame-src https://useiframe.com;
img-src 'self' https://useiframe.com;

条目没有出现？

按顺序检查：

框里写着「这个嵌入还没有对 … 开放」：把那个域名加进控制台「概览」的允许域名（在自己电脑上测试要加 localhost）。
框里写着「缺少账户」或「账户目前不可用」：从控制台的「取代码」重新复制，确认 data-account 是你的公开 ID；授权到期了请联系我们续期。
连框都没有：看页面源代码里 script 还在不在（有的编辑器会删掉它，见上一节）；代码是不是被建站工具放进了它自己的框里；网站的 CSP 有没有放行内容域名；浏览器开发者工具的「控制台」里有没有报错。
框出来了，条目一直没加载完：有些条目比较大，多等一会，或者换个浏览器、网络试试；也可以在控制台把这个位置换成别的条目。
控制台里没有这个位置：页面被打开一次（点击启动的位置被看到一次）之后才会出现，刷新一下控制台；还没有的话，多半是上面几种情况。

活码：不改网页就能换条目

每个位置第一次被打开时，我们会给它登记一个嵌入位（按「页面地址 + 位置名」区分）。之后在控制台的「嵌入位」里：

勾选几个位置，换成别的条目；
把某个条目在你所有页面上一次换掉（比如一个游戏下架了，换成同类的另一个）；
恢复成网页里写的条目；
每次改动都记在「变更记录」里，可以一键撤销。

改动在下一次加载时生效，网页本身一个字都不用动。条目暂时下架时，设了替补条目的会自动显示替补；你也可以随时把它换成别的。

页面地址的认法：如果页面有同域名的 <link rel="canonical"> 就用它，否则用当前地址；会去掉 # 后面的部分和 utm_*、gclid、fbclid、ref 这类追踪参数，所以同一个页面不会因为带不同参数被算成好几个。

允许的域名

你的代码只在你账户里填写的域名上生效，别人复制了你的代码放到他们的网站也用不了。规则：

填 example.com 就包含了 www.example.com、blog.example.com 等所有子域名；
想在自己电脑上测试，加上 localhost；
在控制台的「概览」里随时修改，最多 20 个。

数据

控制台按位置统计每天的加载次数（条目真正被打开一次算一次）。用 data-launch="click" 的位置还会统计展示次数（访客看到了这个位置但还没点）。概览页有 7 天和 30 天的总数、加载最多的条目和页面；「嵌入位」里每个位置都有 7 天加载数和最后出现的日期。连续 30 天没出现的位置会标成「闲置」，不会被删除。

用 earnsite 引擎

earnsite 是配套的建站引擎。把你的授权密钥填进它的 LICENSE_KEY 设置，引擎就会通过你的账户挑游戏、生成页面；页面上的条目从你自己网站的 play. 子域名加载，访客看到的都是你的域名。这些页面会和其他页面一样出现在控制台的「嵌入位」里，同样可以一键换条目。一个授权默认可以给 3 套引擎使用。

给开发者：API

想用程序批量挑条目或管理嵌入位，可以直接调 API。返回都是 JSON，出错时是 {"error":{"code","message"}}。

接口	说明
`GET /api/v1/catalog`	公开目录，不用登录：每个条目的名称、分类、标签、比例、简介、封面和嵌入代码。
`GET /api/v1/account`	你的公开 ID 和允许的域名；`PUT` 同一地址传 `{"allowed_domains":[…]}` 修改。
`GET /api/v1/embeds`	你的嵌入位列表，可按 `host`、`item`、`status` 筛选，分页用 `cursor`。
`POST /api/v1/embeds/retarget`	换条目：`{"filter":{…},"to":{"kind":"item","value":"slug"}}`，加 `"dry_run":true` 先看会影响哪些。
`POST /api/v1/embeds/unpin`	恢复为网页里写的条目。
`POST /api/v1/embeds/rollback`	按 `batch_id` 撤销一次改动。
`GET /api/v1/embeds/stats`	加载统计，按嵌入位、条目、页面或网站分组。

除了公开目录，其他接口要带两个请求头：Authorization: Bearer 你的授权密钥，和 X-Install-Id: inst_ 加 24 位字母数字（每台服务器或每个应用固定用一个，会计入引擎安装数）。密钥只放在服务器上，不要写进网页。

让你的 AI 来操作（MCP）

如果你用 Claude 等支持 MCP 的 AI 工具，可以把你的账户接给它：它能帮你挑条目、生成代码、查看和切换嵌入位、看数据、提需求。

地址：https://www.iframe.app/mcp/site
请求头：Authorization: Bearer 你的授权密钥

{
  "mcpServers": {
    "iframe-app": {
      "type": "http",
      "url": "https://www.iframe.app/mcp/site",
      "headers": { "Authorization": "Bearer gh_live_…" }
    }
  }
}

工具：catalog_search、item_get、embed_code、account_get、domains_set、embeds_list、embeds_switch（先 dry_run）、embeds_unpin、embeds_undo、changes_list、stats、request_item、suggest_game、my_submissions。只能操作你自己的账户。密钥只放在你自己的设备上。

内测期的限制

内测免费，需要邀请码；
每个账户最多 3 套引擎安装（30 天内用过的算）；
每个账户每小时最多新登记 2000 个嵌入位（正常使用碰不到）；
API 每个账户每分钟 600 次。

需要更多？在控制台或通过你拿到邀请码的渠道告诉我们。

常见问题

会拖慢我的网页吗？: 不会。脚本异步加载、体积很小；条目在框里独立运行。一个页面放多个条目时，用 data-launch="click" 更快。
条目里有广告吗？: iframe.app 原创的条目没有广告。标着「含发行方广告」的条目来自游戏发行方，里面会播放发行方自己的广告（通常开始前有一段），收入归发行方。不想要的话，在目录里勾选「无广告」。
手机上能用吗？: 目录里标了「手机可玩」的条目都在手机上测过。比例选竖屏（比如 9:16）的条目在手机上效果最好。
某个条目坏了怎么办？: 我们每天自动检查所有条目，坏了会下架；设了替补的会自动显示替补。你也可以在控制台把它一键换成别的。
我能改条目的内容或去掉标识吗？: 不行。条目要原样显示，详见使用约定。
密钥丢了或泄露了？: 泄露了：在控制台「概览」里换一个新密钥（要再输入一次当前密钥）。丢了：联系我们，我们帮你重发。
你们会收集我访客的信息吗？: 不会收集访客的个人信息，只记页面地址、位置和加载次数。详见隐私说明。