Games I Know logoGames I Know
Embed gamesDocumentation

Embed API docs

Learn the embed by playing it, then wire the events.

Start with the live demo, watch the parent-page events, then copy the iframe and listener patterns into your site. The same flow works for every GamesIKnow iframe game.

Get an embed key
1. Learn first

Live demo: play and inspect events

Make a move in the Tic Tac Toe iframe. The event log shows GAME_STARTED, gameplay events, and completion payloads exactly as a parent page receives them.

Platform-wide event contract

GamesIKnow sends embed events for every game on the platform: Tic Tac Toe, Four in a Row, Bingo, and I Know today, and every new embeddable game we add in the future. You do not need a separate integration per title. Build one parent-page listener against the standard contract (ready, GAME_STARTED, gameplay events, completion with winner data, and signed results) and reuse it across all current and upcoming embed games.

2. Quickstart

From zero to working embed

Use this path when you already know where the game should appear on your website.

  1. 1

    Create a partner account

    Add the website domain that will host the iframe.

    Go to step
  2. 2

    Install the frame route

    Use /embed/{gameSlug}/frame/ with your tenantId. Do not iframe the SEO landing page.

    Go to step
  3. 3

    Listen for parent messages

    Filter on data.source === "gamesiknow", then handle GAME_STARTED, GAME_COMPLETED, and version 1 gameplay events.

    Go to step
  4. 4

    Verify completed results

    Send resultId and signedToken to your backend before granting credits, rewards, or unlocks.

    Go to step
Starter iframe

Use your real tenantId from the partner dashboard.

html
<iframe
  src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=YOUR_TENANT_ID"
  title="Tic Tac Toe by GamesIKnow"
  width="100%"
  height="640"
  style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
  loading="lazy"
  allow="fullscreen"
  allowfullscreen
></iframe>
3. Architecture

How the embed works

A GamesIKnow embed is a sandboxed iframe on your domain. It validates your tenant and domain against the API, then communicates with your parent page through window.postMessage.

Step 1

Parent page loads iframe

Your site renders an iframe pointing at /embed/{gameSlug}/frame/ with tenantId and optional mode or campaignId query params.

Step 2

Embed validates tenant and domain

The iframe calls GET /embed/config (or /api/embed/config). GamesIKnow checks your partner account, allowed domain, game access, and AI quota. A server-side embed_loaded analytics event is recorded.

Step 3

Embed becomes ready

The iframe posts a ready event to the parent page so you can show a loading state or resize the frame using payload.embedHeight.

Step 4

Player starts a match

When gameplay begins, every embeddable game posts GAME_STARTED to the parent page and records game_started server-side automatically. You do not call any analytics API from your website.

Step 5

Gameplay events stream

During the match, version 1 gameplay events such as move and mode_change update your UI or internal analytics.

Step 6

Match completes with signed result

On completion, every embeddable game posts completion and winner data to the parent (finish for all games; signed GAME_COMPLETED where applicable), signs the result via POST /embed/results, and records game_completed server-side. Future embed games follow the same flow.

Two postMessage formats

Lifecycle events use a flat object with event: "GAME_STARTED" or event: "GAME_COMPLETED". Gameplay events wrap data in version: 1 with nested payload. Always filter on data.source === "gamesiknow".

4. Install

Partner setup and iframe snippets

Most integrations are four decisions: register the domain, generate a token, install the iframe, then listen for start and completion events.

Register each website

Add every domain that will host a GamesIKnow embed. Domains are normalized so example.com and www.example.com are handled consistently.

Generate a domain token

Create a separate embed token for each website. This keeps analytics clean and prepares the account for future domain-based pricing.

Install the iframe

Copy the iframe or responsive wrapper into your CMS custom HTML block, website builder embed area, or custom frontend template.

Listen for events and verify results

Handle GAME_STARTED and GAME_COMPLETED (or finish) postMessage events on your parent page. Verify signed results on your backend before awarding rewards.

Recommended iframe settings

Width

Use 100% so the embed fills the available content column.

Height

640px for most games. Tic Tac Toe also works at 600px. Use payload.embedHeight from ready events to auto-resize.

Games

Use /embed/tic-tac-toe/frame/, /embed/four-in-a-row/frame/, /embed/bingo/frame/, or /embed/i-know/frame/.

Mode

Omit mode for player choice, or pass mode=ai when you want the embed to request AI first.

Normal iframe

Player chooses match type inside the game when AI quota is available.

html
<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 GamesIKnow"
></iframe>
Forced AI iframe

Requests AI first. Falls back to PvP silently when quota is exhausted.

html
<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 GamesIKnow"
></iframe>
5. Configuration

iframe URL parameters

Frame URLs use /embed/{gameSlug}/frame/. SEO landing pages without gameplay live at /embed/{gameSlug}/.

ParameterRequiredDescription
tenantIdYesYour partner tenant ID from the GamesIKnow partner dashboard. Also accepted as partnerId for legacy integrations.
modeNoSet to ai to request forced AI mode. Server-side quota and domain rules still apply. Falls back to player vs player when AI is unavailable.
campaignIdNoOptional campaign label echoed in postMessage events and stored in partner analytics for A/B tests or page-level segmentation.
6. Events

postMessage event reference

The same contract applies across Tic Tac Toe, Four in a Row, Bingo, I Know, and upcoming embed releases.

Rule 1

Filter source

Ignore messages unless data.source is gamesiknow.

Rule 2

Handle lifecycle

Use GAME_STARTED and GAME_COMPLETED for high-level UX and analytics.

Rule 3

Fallback to finish

Use the version 1 finish event for universal winner data across every game.

Lifecycle events

EventWhen it firesFormatKey fields
readyEmbed initialized and config loaded.Gameplay (version 1) for all games, or flat for some lifecycle wrappers.matchId, mode, embedHeight
GAME_STARTEDEvery embeddable game (current and future). Fires when a match begins (for example, first move or AI round start).Flat lifecyclegame, partnerId, campaignId, mode, matchId (implicit via gameplay stream)
GAME_COMPLETEDEvery embeddable game sends completion and winner data. Signed GAME_COMPLETED is posted when result signing succeeds; all games also emit finish with the same outcome and winner fields.Flat lifecycleresultId, signedToken, outcome, winner, players, score, durationSeconds, status
EMBED_FULLSCREEN_CHANGEPlayer toggles in-embed fullscreen.Flat lifecyclepayload.active boolean

Gameplay events

Shape: { source, game, version: 1, event, payload }

  • ready - Same as lifecycle ready with version 1 envelope.
  • mode_change - Player picks PvP, AI, or returns to mode selection.
  • move - A move or action occurred (board cell, disc drop, bingo call, trivia answer).
  • finish - Match ended. payload.result includes outcome, winner, and players for all games.
  • reset - Board or round reset.
  • undo - Last move undone (Tic Tac Toe only).
  • state - Response to parent get_state command (Tic Tac Toe, Four in a Row).

The finish event is the universal completion signal for all games. Its payload.result object includes outcome, winner, and players. Tic Tac Toe and Four in a Row also emit signed GAME_COMPLETED when result signing succeeds.

GAME_STARTED example
json
{
  "source": "gamesiknow",
  "event": "GAME_STARTED",
  "game": "tic-tac-toe",
  "partnerId": "partner_your_tenant",
  "campaignId": "homepage-widget",
  "mode": "ai"
}
GAME_COMPLETED example
json
{
  "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..."
}
finish gameplay event

Use this when you need winner data on games that do not emit GAME_COMPLETED to the parent.

json
{
  "source": "gamesiknow",
  "game": "bingo",
  "version": 1,
  "event": "finish",
  "payload": {
    "matchId": "bingo-20260531-abc",
    "mode": "ai",
    "result": {
      "outcome": "player_1",
      "score": 100,
      "winner": {
        "playerId": "player_1",
        "participant": "player_1",
        "type": "human",
        "label": "Player 1",
        "name": "Player 1",
        "score": 100
      },
      "players": [ "...same shape as GAME_COMPLETED..." ]
    },
    "calledNumbers": [1, 14, 27, 33, 41]
  }
}

Outcome values

player_1

First human player won.

player_2

Second human player won.

ai_bot

AI opponent won.

draw

No winner.

Parent-to-iframe commands

Supported on Tic Tac Toe and Four in a Row only. Target the iframe contentWindow with the game slug and action.

Reset or request state
js
// 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"
);
7. Implementation

Sample integration listener

Copy this listener onto the page that hosts your iframe. It handles ready state, game start, gameplay events, signed completion, and fullscreen changes.

Unified parent page listener

Filter by source, handle GAME_STARTED and GAME_COMPLETED, and fall back to finish for all games.

js
/**
 * GamesIKnow embed listener (parent page)
 * Handles lifecycle events (GAME_STARTED, GAME_COMPLETED) and
 * version 1 gameplay events (move, finish, 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") {
    console.log("Match completed (signed)", {
      game: data.game,
      outcome: data.outcome, // player_1 | player_2 | ai_bot | draw
      winner: data.winner,
      players: data.players,
      resultId: data.resultId,
      signedToken: data.signedToken,
    });

    // Send resultId + signedToken to YOUR backend, then verify:
    // POST https://api.gamesiknow.com/embed/results/verify
    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;
      case "finish": {
        const result = data.payload?.result;
        console.log("Finish", result?.outcome, result?.winner, result?.players);
        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`;
}

Integration checklist

  • Show a game in progress banner on GAME_STARTED.
  • Display winner name from GAME_COMPLETED.winner or finish.payload.result.winner.
  • POST resultId and signedToken to your backend before granting rewards.
  • Optionally validate event.origin against your GamesIKnow host.
8. Security

Verified game results API

postMessage data can be spoofed by a malicious browser extension. Verify signed results on your backend before trusting outcome or winner fields.

Verify a signed result

Use resultId and signedToken from GAME_COMPLETED.

http
POST https://api.gamesiknow.com/embed/results/verify
Content-Type: application/json

{
  "resultId": "res_abc123xyz",
  "signedToken": "signed_token_from_game_completed"
}
Successful verify response
json
{
  "ok": true,
  "resultId": "res_abc123xyz",
  "partnerId": "partner_your_tenant",
  "gameSlug": "tic-tac-toe",
  "outcome": "player_1",
  "score": 100,
  "durationSeconds": 24
}
Example backend reward handler

Verify on your server, then grant the reward.

js
// 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" },
    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 });
});
9. Analytics

Server-side analytics events

GamesIKnow records these events automatically when your iframe loads and players interact. They appear in your partner dashboard. To pull the same data into your own database, create a partner server key on the Install page and call GET /partners/analytics from your backend server only.

  • embed_loaded - Every embeddable game when config is validated or the iframe is allowed to run.
  • game_started - Every embeddable game when gameplay begins (recorded automatically by the iframe).
  • game_completed - Every embeddable game when POST /embed/results succeeds.
  • ai_match_started - AI quota consumed through POST /embed/ai-matches/start.
  • embed_blocked - Domain, partner, or game access denied.
Export analytics to your backend (partner server key required)

Generate a partner server key in Partner Dashboard → Install. Store it as a server secret. Use the query parameters below to filter the export.

http
GET https://api.gamesiknow.com/partners/analytics
Authorization: Bearer gik_psk_your_secret_key

Optional query parameters:
  domain      Registered website hostname (example.com)
  campaignId  Value from your iframe campaignId parameter
  gameSlug    tic-tac-toe | four-in-a-row | bingo | i-know
  from        Start date in UTC (YYYY-MM-DD)
  to          End date in UTC (YYYY-MM-DD)

Example:
  /partners/analytics?domain=www.example.com&gameSlug=tic-tac-toe&from=2026-05-01&to=2026-05-31

Call from your backend server only. Never expose your partner server key in browser JavaScript.
10. Catalog

Game capability matrix

Every embeddable game sends the same core events. Compare timing and extras per title below.

GameGAME_STARTEDCompletion signalSignedForced AIHeightParent commands
Tic Tac ToeFirst move or AI startGAME_COMPLETED + finishYesYes640pxreset, get_state
Four in a RowFirst move or AI startGAME_COMPLETED + finishYesYes640pxreset, get_state
BingoAI round start (PvP: use finish)finish (signed via API)YesYes640pxNone yet
I KnowAI round start (PvP: use finish)finish (signed via API)YesYes640pxNone yet
11. Guides

Platform and use-case setup guides

This page is the technical reference. Use these guides when you need platform-specific install steps or vertical placement advice. All guides use the same iframe and event model documented above.

Developer frameworks

Framework-specific iframe placement, event listeners, and production notes.

Website builders and CMS

Copy-paste embed guides for no-code and low-code site builders.

Use-case guides

Placement and UX recommendations for common website types.

Looking for general overview pages such as iframe games, HTML5 widgets, or free embeddable games? Browse all embed guides on the hub.

12. Support

Frequently asked questions

Answers for integration details, current game support, commands, signed results, and future game compatibility.

Can I embed GamesIKnow games in WordPress, Webflow, Wix, Squarespace, or a custom website?

Yes. GamesIKnow embeds use standard iframe HTML, so they work in WordPress custom HTML blocks, Webflow embed elements, Wix and Squarespace custom code areas, static HTML, React, Next.js, and other custom sites. Register the website domain in your partner dashboard first, then paste the generated frame snippet into the page where the game should appear.

What is the difference between /embed/{gameSlug}/ and /embed/{gameSlug}/frame/?

/embed/{gameSlug}/ is the public landing page for a game embed. /embed/{gameSlug}/frame/ is the iframe runtime that should be pasted into your website. Always use the /frame/ URL in iframe code because it loads the playable game, validates your tenant and domain, and sends parent-page events.

Do GamesIKnow iframe games work on mobile and desktop?

Yes. GamesIKnow iframe games are designed for mobile, tablet, laptop, and desktop browsers. Use width="100%" and a recommended height of about 640px for most embeds. You can also listen for the ready event and use payload.embedHeight if you want your parent page to resize the iframe automatically.

How much does it cost to embed GamesIKnow games?

GamesIKnow iframe embeds are free during the embed beta. There is no credit card requirement to get started, and the current beta embeds do not include ads. Create a free partner account, register your domain, and generate the iframe snippet from the dashboard.

Do I need a partner account or embed key?

Yes. A partner account gives you a tenant ID and domain-restricted iframe snippet. The iframe sends tenantId with the frame URL so GamesIKnow can validate the partner, allowed domain, game access, AI quota, analytics campaign, and result verification flow.

Can someone copy my iframe code and use it on another website?

The embed is domain restricted. If someone copies your iframe snippet onto an unauthorized website, GamesIKnow checks the request origin against the domains configured for your partner account and blocks unapproved use. Use separate campaign IDs when you want cleaner analytics per website or campaign.

Which GamesIKnow games can be embedded?

Tic Tac Toe, Four in a Row, Bingo, and I Know support iframe embeds today. Each game sends the standard embed event contract for ready state, game start, gameplay, completion, winner data, analytics, and result verification. New embeddable games are expected to follow the same event pattern so partners do not need to rebuild their integration.

What postMessage events does GamesIKnow send to the parent page?

Every embeddable game uses two postMessage formats. Lifecycle events use a flat shape with source: gamesiknow and event values such as ready, GAME_STARTED, GAME_COMPLETED, and EMBED_FULLSCREEN_CHANGE. Gameplay events use version: 1 with nested event names such as ready, mode_change, move, finish, reset, undo, and state. Always filter on data.source === "gamesiknow".

Can I track starts, completions, winners, and player outcomes from an embedded game?

Yes. Listen for GAME_STARTED when a match begins, use gameplay events such as move and mode_change during play, and use finish or GAME_COMPLETED when a match ends. Completion payloads include outcome, winner, players, score, duration, and result identifiers where signing is available. Server-side analytics also record loads, starts, completions, blocked attempts, and CTA clicks.

Which completion event should I use for all games?

Use the version 1 finish gameplay event as the universal completion signal because it is emitted across all embeddable games and includes payload.result with outcome, winner, and players. When a signed GAME_COMPLETED message includes resultId and signedToken, use that data for backend verification before granting rewards.

How do I listen for embed events from an iframe on my website?

Add window.addEventListener("message", handler) on the page that hosts the iframe. In the handler, ignore messages unless event.data.source === "gamesiknow". Branch on event.data.event for lifecycle events, or on event.data.event plus event.data.version === 1 for gameplay events. Optionally validate event.origin against your allowed GamesIKnow origin.

How do I verify game results before awarding credits, prizes, or unlocks?

When GAME_COMPLETED includes resultId and signedToken, send both to your backend and call POST /embed/results/verify on the GamesIKnow API. Only trust outcome, score, and winner fields after verification succeeds. Never award rewards based on postMessage alone because browser messages can be spoofed.

What iframe URL parameters does GamesIKnow support?

Required: tenantId (your partner tenant ID). Optional: mode=ai to request forced AI mode when quota allows, and campaignId to segment analytics. Frame URLs follow /embed/{gameSlug}/frame/?tenantId=YOUR_TENANT_ID.

Can I force an embedded game to start in AI mode?

Yes. Add mode=ai to the iframe URL to request AI mode first. Server-side quota and domain rules still apply, so the embed can fall back to player choice or player vs player when AI mode is unavailable or quota is exhausted.

Can I send commands into the GamesIKnow iframe?

Tic Tac Toe and Four in a Row accept parent messages with game set to the game slug and action set to reset or get_state. The iframe responds with a state gameplay event. Other embed games do not expose parent commands yet.

Production checklist

Confirm the website domain is active before generating a token.

Use a separate token or campaignId for every website or campaign group.

Listen for GAME_STARTED and GAME_COMPLETED (or finish) on the parent page.

Keep the GamesIKnow branding visible inside the embed.

Verify signed results on your backend before awarding prizes or credits.

Test forced AI mode and PvP fallback when AI quota is exhausted.

Need help with a partner integration?

Share the website, CMS, and desired game placement. We can review your embed event wiring with you.

Contact support