步骤 1
父页面加载 iframe
您的网站渲染一个指向 /embed/{gameSlug}/frame/ 的 iframe,带有 tenantId 和可选的 mode 或 campaignId 查询参数。
Embed API 文档
首先观看在线演示,观察父页面事件,然后将 iframe 和监听器模式复制到您的网站中。此流程适用于所有 Games I Know 和 iframe 游戏。
获取 embed 密钥在 Tic Tac Toe 或 iframe 中执行操作。事件日志会显示 GAME_STARTED、游戏事件和完成有效负载,与父页面接收到的内容完全一致。
平台级事件合同
Games I Know 会为平台上的所有游戏发送 embed 事件:包括目前的 Tic Tac Toe、Four in a Row、Bingo 和 I Know,以及未来新增的每一个 embed 游戏。您无需为每个游戏单独集成。只需针对标准合约(准备就绪、游戏开始、游戏事件、包含获胜者数据的完成以及签名结果)构建一个父页面监听器,即可在所有当前和即将推出的 embed 游戏中重复使用它。
如果您已经知道游戏应该出现在网站上的哪个位置,请使用此路径。
请使用合作伙伴控制面板中的真实租户 ID。
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=YOUR_TENANT_ID"
title="Tic Tac Toe by Games I Know"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
loading="lazy"
allow="fullscreen"
referrerpolicy="no-referrer-when-downgrade"
allowfullscreen
></iframe>Games I Know 和 embed 是您域上的一个沙盒化的 iframe。它会根据 API 验证您的租户和域,然后通过 window.postMessage 与您的父页面通信。
步骤 1
您的网站渲染一个指向 /embed/{gameSlug}/frame/ 的 iframe,带有 tenantId 和可选的 mode 或 campaignId 查询参数。
步骤 2
iframe 调用 GET /embed/config(或 /api/embed/config)。Games I Know 检查您的合作伙伴帐户、允许的域名、游戏访问权限和 AI 配额。服务器端 embed 加载的分析事件将被记录。
步骤 3
iframe 向父页面发布就绪事件,以便您可以使用 payload.embedHeight 显示加载状态或调整框架大小。
步骤 4
游戏开始时,每个可执行embed操作的游戏都会向父页面发布GAME_STARTED事件,并且服务器端会自动记录游戏开始时间。您的网站无需调用任何分析API函数。
步骤 5
在比赛期间,版本 1 的游戏事件(例如移动和模式更改)会更新您的 UI 或内部分析。
步骤 6
游戏结束后,所有可执行 embed 的游戏都会向父级服务器发送 GAME_COMPLETED 消息,其中包含游戏结果、获胜者和玩家信息,以便您的页面可以立即显示结果。iframe 还会通过 POST /embed/results 对游戏结果进行签名,并在签名成功后将 resultId 和 signedToken 包含在 GAME_COMPLETED 消息中。您的后端可以使用合作伙伴服务器密钥验证这些令牌,然后再发放奖励。
两种 postMessage 格式
生命周期事件 使用扁平物体 event: "GAME_STARTED" or event: "GAME_COMPLETED". 游戏活动 将数据包装在 version: 1 嵌套 payload. 始终筛选 data.source === "gamesiknow".
大多数集成都包含四个决策:注册域名、生成令牌、安装 iframe,然后监听开始和完成事件。
添加所有将托管 Games I Know 或 embed 的域名。域名已进行规范化处理,因此 example.com 和 www.example.com 的处理方式保持一致。
为每个网站创建一个单独的 embed 令牌。这样可以保持分析数据的清晰,并为将来基于域名的定价做好准备。
将 iframe 或响应式包装器复制到您的 CMS 自定义 HTML 块、网站构建器 embed 区域或自定义前端模板中。
在父页面上处理 GAME_STARTED 和 GAME_COMPLETED postMessage 事件,以显示比赛状态和获胜者详情。在发放奖励之前,请使用合作伙伴服务器密钥验证后端已签名的结果。
宽度
使用 100%,使 embed 填充可用内容列。
高度
大多数游戏建议使用 640px 的分辨率。Tic Tac Toe 在 600px 下也能正常工作。使用 ready 事件中的 payload.embedHeight 可以实现自动调整大小。
游戏
使用 /embed/tic-tac-toe/frame/、/embed/four-in-a-row/frame/、/embed/bingo/frame/ 或 /embed/i-know/frame/。
模式
省略玩家选择的模式,或者当您希望 embed 首先请求 AI 时传递 mode=ai。
当 AI 名额可用时,玩家可以在游戏内选择比赛类型。
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
allow="fullscreen"
loading="lazy"
title="Tic Tac Toe by Games I Know"
></iframe>首先请求 AI。当配额用尽时,静默回退到 PvP。
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID&mode=ai&campaignId=homepage-widget"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
allow="fullscreen"
loading="lazy"
title="Tic Tac Toe vs AI by Games I Know"
></iframe>框架 URL 使用 /embed/{gameSlug}/frame/。没有游戏玩法的 SEO 登陆页面位于 /embed/{gameSlug}/。
| 范围 | 必需的 | 描述 |
|---|---|---|
| 租户 ID | 是的 | 您的合作伙伴租户 ID,可从 Games I Know 合作伙伴控制面板获取。此 ID 也可用于旧版集成。 |
| 模式 | 不 | 设置为 ai 以请求强制启用 AI 模式。服务器端配额和域规则仍然适用。当 AI 不可用时,回退到玩家对战模式。 |
| campaignId | 不 | 可选的活动标签会在 postMessage 事件中回显,并存储在合作伙伴分析中,用于 A/B 测试或页面级细分。 |
相同的合同适用于 Tic Tac Toe、Four in a Row、Bingo、I Know 和即将推出的 embed 版本。
规则 1
滤光源
除非 data.source 是 gamesiknow,否则忽略消息。
规则 2
处理生命周期
使用 GAME_STARTED 和 GAME_COMPLETED 分别表示比赛状态、获胜者姓名和比赛结果。
规则 3
验证即可获得奖励。
在发放奖励之前,请将 resultId 和 signedToken 转发到您的后端。
| 事件 | 发射时 | 格式 | 关键字段 |
|---|---|---|---|
| 准备好 | Embed 已初始化并加载配置。 | 适用于所有游戏的 Gameplay(版本 1),或适用于某些生命周期包装器的 flat。 | matchId、模式、embedHeight |
| 游戏开始 | 每个 embed 可执行的游戏(当前和未来的)。当比赛开始时触发(例如,第一步或 AI 回合开始)。 | 扁平生命周期 | game、partnerId、campaignId、mode、matchId(通过游戏流隐式) |
| 游戏完成 | 每次比赛结束时,都会记录所有 embed 数据。数据包括比赛结果、获胜者、获胜玩家姓名和参赛玩家,以便父页面能够立即显示比赛结果。如果服务器端签名成功,还会记录 resultId 和 signedToken。 | 扁平生命周期 | 结果、获胜者、获胜玩家姓名、获胜玩家 ID、玩家人数、得分、持续时间(秒)、结果 ID、签名令牌 |
| 嵌入全屏切换 | 玩家在embed中切换全屏模式。 | 扁平生命周期 | payload.active 布尔值 |
形状: { source, game, version: 1, event, payload }
每个 embeddable 游戏帖子 GAME_COMPLETED 对父母来说 outcome, winner, 和 players 比赛结束时。签约成功时, GAME_COMPLETED 还包括 resultId 和 signedToken 用于后端验证。
{
"source": "gamesiknow",
"event": "GAME_STARTED",
"game": "tic-tac-toe",
"partnerId": "partner_your_tenant",
"campaignId": "homepage-widget",
"mode": "ai"
}{
"source": "gamesiknow",
"event": "GAME_COMPLETED",
"game": "tic-tac-toe",
"resultId": "res_abc123xyz",
"partnerId": "partner_your_tenant",
"campaignId": "homepage-widget",
"status": "completed",
"outcome": "player_1",
"score": 100,
"durationSeconds": 24,
"winnerPlayerId": "player_1",
"winnerPlayerName": "Player X",
"winner": {
"playerId": "player_1",
"participant": "player_1",
"type": "human",
"label": "Player 1",
"name": "Player X",
"score": 100
},
"players": [
{
"playerId": "player_1",
"participant": "player_1",
"type": "human",
"label": "Player 1",
"name": "Player X",
"score": 100,
"status": "winner"
},
{
"playerId": "player_2",
"participant": "ai_bot",
"type": "ai",
"label": "AI BOT",
"name": "AI Bot",
"score": 60,
"status": "lost"
}
],
"signedToken": "eyJ..."
}玩家1
第一个获胜的人类玩家获胜。
玩家2
第二名玩家获胜。
人工智能机器人
AI 对手获胜。
画
无人获胜。
仅支持 Tic Tac Toe 和 Four in a Row。使用游戏别名和操作来定位 iframe 内容窗口。
// Parent page -> iframe (Tic Tac Toe or Four in a Row)
const iframe = document.querySelector("iframe");
iframe.contentWindow.postMessage(
{ game: "tic-tac-toe", action: "reset" },
"https://gamesiknow.com"
);
iframe.contentWindow.postMessage(
{ game: "tic-tac-toe", action: "get_state" },
"https://gamesiknow.com"
);将此监听器复制到托管 iframe 的页面上。它处理就绪状态、游戏开始、游戏事件、签名完成和全屏更改。
按来源筛选,处理比赛期间获胜者 UI 和游戏事件的 GAME_STARTED 和 GAME_COMPLETED。
/**
* Games I Know embed listener (parent page)
* Handles lifecycle events (GAME_STARTED, GAME_COMPLETED) and
* version 1 gameplay events (move, mode_change, ...).
*/
const TRUSTED_ORIGIN = "https://gamesiknow.com"; // or your self-hosted origin
window.addEventListener("message", (event) => {
if (TRUSTED_ORIGIN !== "*" && event.origin !== TRUSTED_ORIGIN) return;
const data = event.data;
if (!data || data.source !== "gamesiknow") return;
// --- Lifecycle events (flat top-level event name) ---
if (data.event === "GAME_STARTED") {
console.log("Match started", {
game: data.game,
mode: data.mode,
partnerId: data.partnerId,
campaignId: data.campaignId,
});
return;
}
if (data.event === "GAME_COMPLETED") {
const winnerLabel = data.winner?.name ?? data.winnerPlayerName ?? null;
console.log("Match completed", {
game: data.game,
outcome: data.outcome, // player_1 | player_2 | ai_bot | draw
winner: data.winner,
winnerName: winnerLabel,
players: data.players,
});
if (winnerLabel) {
document.getElementById("game-winner")!.textContent = `${winnerLabel} won!`;
} else if (data.outcome === "draw") {
document.getElementById("game-winner")!.textContent = "Draw";
}
// For rewards: send resultId + signedToken to YOUR backend (never call verify from the browser)
if (data.resultId && data.signedToken) {
fetch("/api/reward-winner", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
resultId: data.resultId,
signedToken: data.signedToken,
userId: currentUserId,
}),
});
}
return;
}
if (data.event === "EMBED_FULLSCREEN_CHANGE") {
document.body.classList.toggle("embed-fullscreen-active", Boolean(data.payload?.active));
return;
}
// --- Gameplay events (version 1 envelope) ---
if (data.version === 1 && typeof data.event === "string") {
switch (data.event) {
case "ready":
resizeEmbed(data.payload?.embedHeight);
break;
case "mode_change":
console.log("Mode changed", data.payload?.mode);
break;
case "move":
console.log("Move", data.payload);
break;
default:
console.log("Gameplay event", data.event, data.payload);
}
}
});
function resizeEmbed(height) {
const iframe = document.querySelector('iframe[src*="/embed/"]');
if (iframe && typeof height === "number") iframe.style.height = `${height}px`;
}集成清单
在父页面上使用 GAME_COMPLETED 来显示获胜者。对于奖励,请使用合作伙伴服务器密钥从您的后端验证签名结果 - 切勿从浏览器 JavaScript 调用验证 API。
仅限服务器端。使用来自 GAME_COMPLETED 的 resultId 和 signedToken,授权方式为:Bearer gik_psk_…
POST https://api.gamesiknow.com/embed/results/verify
Authorization: Bearer gik_psk_your_secret_key
Content-Type: application/json
{
"resultId": "res_abc123xyz",
"signedToken": "signed_token_from_game_completed"
}
Call from your backend server only. The partner server key must belong to the same tenant as the signed result. Browser requests are rejected.{
"ok": true,
"resultId": "res_abc123xyz",
"partnerId": "partner_your_tenant",
"gameSlug": "tic-tac-toe",
"outcome": "player_1",
"score": 100,
"durationSeconds": 24
}您的后端从父页面接收令牌,使用 Games I Know 进行验证,然后授予奖励。
// Example: Node.js / Express handler on YOUR server
app.post("/api/reward-winner", async (req, res) => {
const { resultId, signedToken, userId } = req.body;
const verify = await fetch("https://api.gamesiknow.com/embed/results/verify", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.GAMESIKNOW_PARTNER_SERVER_KEY}`,
},
body: JSON.stringify({ resultId, signedToken }),
});
if (!verify.ok) return res.status(403).json({ error: "Invalid result" });
const result = await verify.json();
if (result.outcome !== "player_1") {
return res.status(400).json({ error: "Player did not win" });
}
await grantReward(userId, result);
return res.json({ ok: true });
});当您的 iframe 加载且玩家进行互动时,Games I Know 会自动记录这些事件。这些事件会显示在您的合作伙伴控制面板中。要将相同的数据导入您自己的数据库,请在“安装”页面创建一个合作伙伴服务器密钥,并仅从您的后端服务器调用 GET /partners/analytics。
在合作伙伴控制面板 → 安装 中生成合作伙伴服务器密钥。将其存储为服务器密钥。使用以下查询参数筛选导出内容。
GET https://api.gamesiknow.com/partners/analytics
授权方式:Bearer gik_psk_your_secret_key
可选查询参数:
domain 注册网站主机名(例如 example.com)
campaignId 来自 iframe campaignId 参数的值
gameSlug tic-tac-toe | four-in-a-row | bingo | i-know
from 开始日期(UTC 时间,YYYY-MM-DD)
to 结束日期(UTC 时间,YYYY-MM-DD)
示例:
/partners/analytics?domain=www.example.com&gameSlug=tic-tac-toe&from=2026-05-01&to=2026-05-31
仅可从后端服务器调用。切勿在浏览器中暴露您的合作伙伴服务器密钥 JavaScript。所有 embeddable 游戏都会发送相同的核心事件。请在下方比较各游戏的时序和额外信息。
| 游戏 | 游戏开始 | 完成信号 | 签名 | 强制 AI | Height | 父命令 |
|---|---|---|---|---|---|---|
| Tic Tac Toe | 第一步或AI开始 | 游戏完成 | 是的 | 是的 | 640px | 重置,获取状态 |
| Four in a Row | 第一步或AI开始 | 游戏完成 | 是的 | 是的 | 640px | 重置,获取状态 |
| Bingo | 比赛开始(AI 或 PvP) | 游戏完成 | 是的 | 是的 | 640px | 暂无 |
| I Know | 比赛开始(AI 或 PvP) | 游戏完成 | 是的 | 是的 | 640px | 暂无 |
本页面为技术参考。当您需要特定平台的安装步骤或垂直放置建议时,请使用这些指南。所有指南均使用上述相同的 iframe 和事件模型。
Framework-specific iframe placement, event listeners, and production notes.
Copy-paste embed guides for no-code and low-code site builders.
Placement and UX recommendations for common website types.
正在寻找诸如 iframe 游戏、HTML5 小部件或免费 embed 游戏之类的概览页面?浏览全部 集线器上的 embed 指南。
解答有关集成细节、当前游戏支持、命令、签名结果和未来游戏兼容性的问题。
是的。Games I Know 和 embed 使用标准的 iframe HTML,因此它们可以在 WordPress 自定义 HTML 块、Webflow embed 元素、Wix 和 Squarespace 自定义代码区域、静态 HTML、React、Next.js 以及其他自定义网站中使用。请先在您的合作伙伴控制面板中注册网站域名,然后将生成的框架代码片段粘贴到游戏应该显示的页面中。
/embed/{gameSlug}/ 是游戏 embed 的公开登录页面。/embed/{gameSlug}/frame/ 是 iframe 运行时环境,需要粘贴到您的网站中。在 iframe 代码中,请务必使用 /frame/ URL,因为它会加载可玩的游戏、验证您的租户和域名,并发送父页面事件。
是的。Games I Know 和 iframe 游戏专为手机、平板电脑、笔记本电脑和台式机浏览器设计。建议大多数 embed 游戏使用 width="100%" 和约 640px 的高度。您也可以监听 ready 事件,并使用 payload.embedHeight,以便父页面自动调整 iframe 的大小。
在 embed 测试版期间,Games I Know、iframe 和 embed 代码片段均可免费使用。无需信用卡即可开始使用,且当前测试版 embed 代码片段不包含广告。创建免费合作伙伴帐户,注册您的域名,然后从控制面板生成 iframe 代码片段。
是的。合作伙伴帐户会为您提供租户 ID 和受域名限制的 iframe 代码片段。iframe 会将租户 ID 与框架 URL 一起发送,以便 Games I Know 可以验证合作伙伴、允许的域名、游戏访问权限、AI 配额、分析活动和结果验证流程。
embed 受域名限制。如果有人将您的 iframe 代码片段复制到未经授权的网站上,Games I Know 会检查请求来源是否与您的合作伙伴帐户配置的域名一致,并阻止未经授权的使用。如果您希望每个网站或广告系列的分析数据更加清晰,请使用单独的广告系列 ID。
目前,Tic Tac Toe、Four in a Row、Bingo 和 I Know 支持 iframe 和 embed。每款游戏都会发送标准的 embed 事件合约,用于记录就绪状态、游戏开始、游戏过程、游戏结束、获胜者数据、分析和结果验证。新的支持 embed 的游戏预计将遵循相同的事件模式,因此合作伙伴无需重新构建集成。
每个 embeddable 游戏都使用两种 postMessage 格式。生命周期事件使用扁平格式,源为 gamesiknow,事件值包括 ready、GAME_STARTED、GAME_COMPLETED 和 EMBED_FULLSCREEN_CHANGE。游戏玩法事件使用版本 1,事件名称为嵌套格式,例如 ready、mode_change、move、reset、undo 和 state。始终筛选 data.source === "gamesiknow" 的数据。
是的。比赛开始时监听 GAME_STARTED 事件,比赛过程中使用移动和模式切换等游戏事件,比赛结束时监听 GAME_COMPLETED 事件。GAME_COMPLETED 事件包含结果、获胜者、玩家、分数、持续时间和结果标识符(如果支持签名)。服务器端分析还会记录加载次数、开始次数、完成次数、被阻止的尝试次数和 CTA 点击次数。
比赛结束后使用 GAME_COMPLETED 事件。所有 embed 可执行的游戏都会发送此生命周期事件,其中包含比赛结果、获胜者、获胜玩家名称和参赛玩家信息。如果 GAME_COMPLETED 事件包含 resultId 和 signedToken,请将其转发到您的后端,并在发放奖励或积分之前,使用您的合作伙伴服务器密钥调用 POST /embed/results/verify 函数。
在承载 iframe 的页面上添加 window.addEventListener("message", handler)。在处理程序中,除非 event.data.source === "gamesiknow",否则忽略消息。对于生命周期事件,根据 event.data.event 进行分支;对于游戏事件,根据 event.data.event 和 event.data.version === 1 进行分支。可选地,验证 event.origin 是否与您允许的 Games I Know 来源一致。
在父页面使用 GAME_COMPLETED 事件立即显示获胜者(结果、获胜者、获胜玩家名称、玩家人数)。要发放奖励,请将 GAME_COMPLETED 事件中的 resultId 和 signedToken 发送到您的后端,然后使用您控制面板中的合作伙伴服务器密钥,调用 POST /embed/results/verify 并设置 Authorization: Bearer gik_psk_… 权限。验证端点仅限服务器端访问 - 切勿从浏览器 JavaScript 调用。仅在验证成功后发放奖励。
必填项:tenantId(您的合作伙伴租户 ID)。可选:mode=ai 用于在配额允许的情况下请求强制启用 AI 模式,campaignId 用于细分分析。框架 URL 遵循 /embed/{gameSlug}/frame/?tenantId=YOUR_TENANT_ID。
是的。在 iframe URL 中添加 mode=ai 参数,即可优先请求 AI 模式。服务器端配额和域名规则仍然适用,因此当 AI 模式不可用或配额耗尽时,embed 可以回退到玩家选择或玩家对战模式。
Tic Tac Toe 和 Four in a Row 接受父级消息,其中 game 设置为游戏 slug,action 设置为 reset 或 get_state。iframe 会以状态游戏事件进行响应。其他 embed 游戏目前尚未公开父级命令。
生成令牌前,请确认网站域名是否已激活。
每个网站或活动组使用单独的令牌或 campaignId。
监听父页面上的 GAME_STARTED 和 GAME_COMPLETED 事件。
保持 Games I Know 品牌标识在 embed 内可见。
在颁发奖品或积分之前,请在后端验证签名结果。
测试强制使用 AI 模式,当 AI 配额用完时,回退到 PvP 模式。
请分享您的网站、内容管理系统 (CMS) 以及您希望的游戏位置。我们可以和您一起审核您的 embed 事件配置。